OpenNote MCP 后端服务器

关键词

语义检索文档管理Rust 服务端向量嵌入LLM 集成
  • 项目简介
    • 该仓库实现了一个基于 MCP 的服务端，用于向 LLM 客户端提供上下文信息和功能。后端整合了文档管理、语义检索、元数据管理、以及对嵌入向量服务的调用等能力，支持多用户场景和后台任务调度。
  • 主要功能点
    • MCP 服务端实现：实现 MCP 服务的核心能力，包括信息查询、任务初始化和工具/能力描述等，通过 RMCP/Actix-Web 提供流式 HTTP 的 MCP 接入点。
    • 资源与元数据管理：通过后端存储管理文档集合、文档元数据、以及文档 chunks，支持增删改查等操作。
    • 语义检索与向量化集成：通过向量化服务（本地 embedder/OpenAI 等提供商）对文档进行向量化，并基于向量对文档进行语义检索。
    • 任务调度与异步处理：对长时间操作（如导入文档、重新索引、备份/还原）使用异步任务和任务状态查询接口。
    • 安全与多用户：基本用户认证信息（Bearer token）在 MCP 初始化阶段获取并维护，结合资源访问控制实现多用户场景的隔离。
    • 容器化/热启动能力：后端使用 Actix-Web 与 RMCP 的组合，支持 SSE 保活、流式传输等 MCP 场景。
  • 安装步骤
    1. 确保开发环境具备 Rust（cargo）以及相关依赖库的编译环境。
    2. 在仓库根目录下构建后端服务（通常执行 cargo build 或 cargo run 进入后端目录后启动服务）。
    3. 配置嵌入向量向外部服务的参数（如本地 embedder、Qdrant 向量数据库、以及 OpenAI/其他提供商的向量服务）。
    4. 启动后端服务，监听端口（仓库实现中默认对外暴露 HTTP/... 端口，具体端口由配置决定）。
  • 服务器配置（MCP 客户端需要的配置信息）
    • 说明：MCP 客户端连接该 MCP 服务器以获取上下文、执行工具等。在本实现中，MCP 服务的地址通过 baseUrl 指定，其他连接参数如命令/参数用于描述服务的启动方式；实际客户端通常不需要执行服务器启动命令，但可以通过以下示例配置了解如何声明连接。
    • 配置示例（JSON 结构，描述 MCP 服务器连接信息；注释用于说明字段含义，不作为代码片段展示）： { "mcpServers": { "server-uuid-placeholder": { "name": "opennote", "description": "", "baseUrl": "http://localhost:8086/mcp", "command": "", "args": [], "env": {}, "isActive": true, "type": "streamableHttp", "headers": { "Authorization": "Bearer <your-username>" } } } }
    • 字段说明
      • server-uuid-placeholder：唯一标识该 MCP 服务器的键名称（客户端在连接时以此识别服务器）。
      • name：服务器名称，便于区分不同 MCP 服务端。
      • description：服务器描述信息，供客户端展示。
      • baseUrl：MCP 服务器的访问地址，需以 /mcp 结尾的服务入口。
      • command/args：用于描述服务器启动命令及参数的字段。对于本 MCP 服务器实现，实际启动通常由后端容器/进程执行，因此可留空。若需要客户端知道启动方式，可填写相应的启动命令及参数注释。
      • env：启动环境变量，若有需要可配置。
      • isActive：是否当前可用，启用后客户端可以连接。
      • type：传输类型，示例为 streamableHttp，表示通过可流式的 HTTP 通道进行 MCP 通信。
      • headers：连接所需的附加头部信息（如认证 Bearer token），客户端在请求 MCP 服务时可附带该头部。
  • 基本使用方法
    • 启动服务
      • 运行后端服务，确保后端所需的依赖（向量数据库、嵌入向量服务、模型服务等）已正确启动并可访问。
      • MCP 服务监听在配置中指定的 baseUrl（如 http://localhost:8086/mcp）。
    • 与 MCP 客户端对接
      • 在 MCP 客户端配置中填入上述 JSON，以声明该 MCP 服务器的连接信息、传输类型和认证头等。
      • 客户端通过 JSON-RPC 调用 MCP 提供的语义检索、元数据查询、文档内容获取等能力。
    • 运行后的常见流程
      • 客户端初始化时通过 initialize 请求获取服务器信息与能力描述。
      • 通过预定义的工具路由（如语义搜索、获取集合元数据、获取文档内容等）请求服务端的功能。
      • 服务端返回 JSON-RPC 风格的响应，或通过事件/任务机制返回异步结果。
  • 额外说明
    • 本实现的 MCP 服务端侧具备多用户会话管理、权限校验、以及对嵌入向量服务的整合能力，能够在多用户场景下提供文档上下文和检索能力。
    • MCP 服务端使用的基础栈包括 Rust、Actix-Web、RMCP（Model Context Protocol）以及向量数据库/嵌入服务的对接组件，适合在企业或研究场景中作为 LLM 的上下文提供端。

服务器信息

访问项目