AILSS MCP 服务器

关键词

Obsidian本地索引向量检索工具执行OpenAI 集成

使用说明（简要、可操作的指南）

  • 项目简介

    • 该仓库实现了一个基于 MCP 的后端服务器，负责管理和暴露“资源与数据、可调用工具、以及可渲染的 Prompt 模板”等能力，供 LLM 客户端以标准的 JSON-RPC 方式访问。
    • 服务器与 Obsidian 插件协同工作，能够在本地建立和维护一个索引数据库（包括文件、笔记元数据、分块内容及嵌入向量），并提供高效的向量检索能力，从而为大模型提供结构化的上下文信息。

  • 主要功能点

    • 资源与数据管理：维护 vault 的文件/笔记元数据、跨笔记的 typed-links、标签、关键词、来源等，支持向量化嵌入与向量检索。
    • 工具集成与执行：内置多种工具，例如读取笔记、读取 vault 树、解析/解析 frontmatter、读取上下文、查找/解析笔记、读写/修改笔记等，并支持对外部工具的安全控制（写工具需要显式开启）。
    • Prompt 模板定义与渲染：提供与 Vault 结构相符的 Prompt 模板组合，便于向 LLM 客户端渲染和自定义对话模式。
    • MCP 传输与会话：实现基于 STDIO 的服务器传输和本地 HTTP 服务，可通过 Codex/Claude Code 等客户端连接，支持会话管理、并发连接限制以及端口/令牌等鉴权机制。
    • 本地索引与向量检索：与 Obsidian 插件紧密集成，建立 SQLite + sqlite-vec 的向量库，支持语义检索、结果去重、预览文本截断等。
    • 多传输协议支持：除了 STDIO，还实现本地 HTTP 服务器作为暴露接口，方便远程客户端接入。

  • 安装与运行步骤

      1. 运行环境准备
      • 安装 Node.js 环境，并确保 OpenAI API Key 可用（用于 Embedding 与模型调用）。
      • 设置本地 Vault 路径（用于 Obsidian 插件的本地索引与笔记读取）。
      1. 构建与部署 MCP 服务器
      • 构建或直接使用仓库中的 MCP 服务端实现（包括 STDIO 和 HTTP 传输实现）。
      1. 启动 MCP HTTP 服务（便于局域网内的客户端连接）
      • 将所需的环境变量设置好，例如 OPENAI_API_KEY、OPENAI_EMBEDDING_MODEL、AILSS_VAULT_PATH、端口及 token。
      • 启动 HTTP 服务脚本，HTTP 服务将监听指定的主机/端口与路径，并通过 Bearer Token 进行鉴权。
      1. 启动 MCP STDIO 服务（用于本地嵌入式客户端）
      • 指定 Node 可执行路径与脚本路径，例如 node /path/to/ailss/packages/mcp/dist/stdio.js，以 STDIO 形式暴露 MCP 服务。
      1. 配置 MCP 客户端
      • 参考仓库文档中的示例，将服务器地址、端点、鉴权方式等配置到客户端（如 Codex、Claude Code 等支持的 MCP 配置）。
      • 客户端通常需要提供：
        • 服务器名称
        • 启动命令（command）及参数（args）来启动 MCP 服务
        • 访问令牌/鉴权信息（HTTP 访问或环境变量注入）
      1. 使用与测试
      • 使用 MCP 客户端执行工具、获取上下文、执行可写工具等，观察返回的 JSON-RPC 结果与 structuredContent。

  • 服务器配置（示例说明） 下面给出一份描述性配置，便于 MCP 客户端理解如何启动/连接该服务器。请注意：实际客户端使用时，请参考各自的配置格式进行配置，以下为信息性描述，非代码块形式呈现。

    • serverName: "ailss"
    • transport: "stdio" 或 "http"（选择使用 STDIO 传输或本地 HTTP 服务）
    • startCommand: "/usr/bin/node"（Node.js 的绝对路径，按你的系统实际路径填写）
    • startArgs: [ "/path/to/your/project/packages/mcp/dist/stdio.js" // 入口脚本，用于 STDIO 传输 ] 注释：这是用于启动 MCP 服务端的命令及参数。若使用本地 HTTP 传输，请相应使用 http.js 的入口。
    • env（启动时注入的环境变量，示例）:
      • OPENAI_API_KEY: "<你的 OpenAI API Key>"
      • OPENAI_EMBEDDING_MODEL: "text-embedding-3-large" // 常用模型，可按实际选择
      • AILSS_VAULT_PATH: "<你的 vault 路径>"
      • AILSS_MCP_HTTP_HOST: "127.0.0.1" // 仅当使用 HTTP 传输时需要
      • AILSS_MCP_HTTP_PORT: "31415"
      • AILSS_MCP_HTTP_PATH: "/mcp"
      • AILSS_MCP_HTTP_TOKEN: "<你的访问令牌>"
      • AILSS_GET_CONTEXT_DEFAULT_TOP_K: "10" // get_context 的默认 top_k，按需设置
    • 备注：不同客户端实现对配置的格式可能不同，上述字段主要描述服务器端的启动参数和运行环境，具体客户端需要的配置要依据客户端的 MCP 客户端实现来决定。

  • 基本使用方法

    • 通过 STDIO 启动的服务器，客户端将通过进程的标准输入输出建立 RPC 通道，按 MCP 约定进行请求/响应。 通过本地 HTTP 启动的服务器，客户端通过 HTTP 接口进行 JSON-RPC 通信，支持会话管理、鉴权和多路复用连接。
    • 客户端常用操作包括：
      • 初始化会话（initialize）
      • 获取工具列表和调用工具（tools/list、tools/call）
      • 读取笔记、读取 vault 树、获取 TypedLinks、执行 frontmatter 验证等工具
      • 根据返回的 structuredContent 进行后续的笔记存储、聚合、或向量检索
    • 具体使用方式请参阅仓库内提供的工具/示例测试，以了解每个工具的输入输出格式与数据结构。

  • 其他注意事项

    • 安全性：HTTP 传输需使用 Bearer Token 进行鉴权，关闭未授权访问。
    • 多会话与并发：服务端对会话数、空闲会话、以及写操作有控制，确保在本地环境中的稳定性。

  • 参考要点

    • MCP 功能实现范围包括：资源管理、工具注册/执行、Prompts 定义与渲染、JSON-RPC 风格的请求/响应、以及多传输协议支持。
    • 系统设计强调与 Obsidian 本地索引、向量化检索的紧密整合，以及对前端（Obsidian 插件）和后端（MCP 客户端）之间的协同工作能力。

服务器信息

访问项目