Margin MCP 服务器端实现

使用说明（Markdown 格式）

• 项目简介

  • Margin 的 MCP 服务器实现是一个完整的后端服务，用于向 MCP 客户端（如 Claude Desktop 等）暴露 Margin 应用的数据、功能和提示模板。服务器核心通过 MCP 协议提供资源、工具和提示模板的标准化访问，并通过 JSON-RPC 与客户端通信，支持多种传输方式（如 STDIO、SSE、WebSocket 等）。此外，服务器还包含一个 HTTP 导出桥，用于接收来自 Claude 的导出数据并推送到 Margin。

• 主要功能点

  • 资源信息托管与访问：提供诸如最近文档、文档注解等资源的读取接口，便于 LLM 客户端在对话中上下文化地使用 Margin 的数据。
  • 工具注册与执行：注册多种工具（如文档查询、注释操作、 corrections/writing-rules 的增删改查等），LLM 客户端可通过 MCP 服务器执行外部功能并获得结构化返回。
  • Prompt 模板定义与渲染：包含用于注释评审、写作反馈、阅读摘要等场景的提示模板，支持对 LLM 交互模式的自定义。
  • JSON-RPC 通信：服务器以 MCP 规范的 JSON-RPC 形式接收请求并返回结果，便于与 LLM 客户端对等交互。
  • 会话管理与能力声明：实现资源/工具/模板的能力声明，以及会话状态管理。
  • 传输协议支持与导出桥：默认 stdio 传输，另可通过导出桥接入本地 Claude Desktop（HTTP 服务端口 24784），实现注释导出等协作工作流。

• 安装步骤

  • 1）获取代码：将 Margin 仓库克隆到本地，进入 mcp 目录。
  • 2）安装依赖：在包含 MCP 的工作区中执行依赖安装，确保构建所需的工具链就绪（如 Node、pnpm，以及相关的构建工具）。
  • 3）构建 MCP 服务器：在 mcp 子工程中执行构建命令，生成可执行的 dist/index.js（或等效入口点）以便独立运行。
  • 4）启动服务器：以生成的入口文件启动 MCP 服务器。对于开发环境，通常通过 Node 直接运行打包后的入口（如 node mcp/dist/index.js），或按项目提供的开发路径启动。

• 服务器配置（MCP 客户端所需的配置，JSON 格式，包含 server name、command、args 等） 注：以下为示例配置，务必使用实际部署时的路径与参数。MCP 客户端在连接时通常只需要这些字段来知道如何启动并与服务器通信，客户端本身不需要此配置执行。 { "serverName": "margin", "version": "0.1.0", "description": "Margin MCP 服务端，提供资源、工具与提示模板的 MCP 接口", "command": "node", "args": [ "path/to/your/mcp/dist/index.js" ], "transport": "stdio", "notes": "使用 stdio 传输，MCP 客户端通过该通道与服务器进行 JSON-RPC 交互。服务端同时提供导出桥（HTTP）用于 Claude Desktop 的注释导出等集成场景。" }

• 基本使用方法

  • 1）连接与初始化：在客户端配置好 MCP 服务器后，通过 MCP 客户端启动服务器进程，建立基于 JSON-RPC 的通信信道。
  • 2）发起请求：通过 MCP 的 JSON-RPC 接口，请求资源读取、工具调用、Prompts 获取等。服务器按 MCP 协议返回结果或通知。
  • 3）使用导出桥：如需将 Margin 的注释导出给 Claude Desktop，可以通过导出桥的 HTTP 服务端口进行交互， Margin 将注释推送到 Claude， Claude 可以通过特定工具进行高阶处理。
  • 4）开发与扩展：服务器实现具备可以注册新的工具、添加新的资源、或扩展 Prompt 模板的能力，按 MCP 模式对接新的 LLM 客户端时可无缝扩展。

• 运行与测试

  • 运行单元测试覆盖服务器核心能力、导出桥、工具、资源、Prompts 的集成点等；也可在 Margin 应用的开发环境中集成测试，确保与 Claude Desktop 等客户端互操作。

• 重要说明

  • MCP 服务器在 Margin 应用中作为后端服务存在，常与 Margin 的前端/桌面应用协同工作，提供统一的上下文服务。