AI导哈

Markdown文档协议服务器

RefMD MCP Server是一个通过SSE端点托管RefMD文档的服务器，允许聊天机器人通过API浏览和编辑Markdown文档。

  • by refmdio
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 refmdio/mcp-server

使用说明

RefMD MCP服务器

模型上下文协议服务器，通过托管SSE端点公开RefMD文档，因此聊天机器人可以通过RefMD的API浏览和编辑Markdown。

特性

  • 与托管MCP客户端（如Claude、Cursor）兼容的流式HTTP/SSE传输
  • 资源模板 refmd://document/{id} 读取文档Markdown和元数据
  • 通过RefMD API列出、搜索、创建和更新文档的工具
  • 分块文档读取可选 offset/limit 参数（每次调用最多返回120000个字符）
  • 通过以下方式进行部分Markdown修补 refmd-patch-document-content （插入/删除/替换，而不重新上传整个文件）

先决条件

  • Node.js 18+
  • 访问现有的RefMD实例
  • 个人访问令牌（JWT）或可以通过登录的凭据 /api/auth/login

配置

服务器现在通过OAuth 2.1使用PKCE对用户进行身份验证。使用以下变量进行配置：

变量 描述
REFMD_API_BASE 必修的。 RefMD API的基本URL（例如。 https://refmd.example.com).
OAUTH_CLIENT_IDS 允许的逗号分隔列表 client_id 价值观。留空以允许任何。
OAUTH_ALLOWED_REDIRECTS 逗号分隔的允许重定向URI列表。默认为允许HTTPS URL和 http://localhost。包括ChatGPT的回调URL(https://chat.openai.com/aip/mcp/oauth/callback).
OAUTH_ISSUER 可选的公共颁发者URL（默认为当前请求源）。
ACCESS_TOKEN_TTL_SECONDS 可选访问令牌生存期（默认 3600).
REFRESH_TOKEN_TTL_SECONDS 可选刷新令牌生存期（默认 2592000即30天）。
MCP_DB_DRIVER 可选。设置为 sqlite, postgres，或 mysql 以持久化OAuth令牌。默认为内存存储。
MCP_DB_URL 配置的驱动程序的可选连接字符串（例如。 postgres://user:pass@host/db).对于SQLite，您可以省略此项并使用 MCP_DB_SQLITE_PATH.
MCP_DB_SQLITE_PATH SQLite存储的可选文件系统路径（默认为 ./data/refmd-mcp.sqlite).接受普通路径或 file:/// URL；使用SQLite时，确保路径解析为持久存储。
PORT / HOST 可选侦听端口/主机（默认值： 3334 / 0.0.0.0).

允许多个托管客户端：设置 OAUTH_CLIENT_IDS 以逗号分隔的列表（例如。 chatgpt-connector,Claude)并镜像同一组 OAUTH_ALLOWED_REDIRECTS。将任一变量留空将使其对任何HTTPS重定向保持开放，但一旦指定了一个值，您就必须列出要允许的每个连接器。

远程MCP客户端（包括Claude Web）需要OAuth保护资源元数据文档 https://<host>/.well-known/oauth-protected-resource 这样他们就可以跟随 resource_metadata 提示在 WWW-Authenticate 挑战。服务器自动提供该文档（包括镜像别名，如 /mcp/.well-known/...)，因此请确保您的反向代理转发这些路径。

如果在反向代理中终止TLS，请确保它转发标准 Forwarded 标题或 X-Forwarded-Proto / X-Forwarded-Host 因此OAuth元数据通告了正确的 https:// 起源。集 OAUTH_ISSUER=https://your-domain 如果你更喜欢显式覆盖。

ℹ️ 启用持久性时安装相应的数据库驱动程序：
npm install better-sqlite3 对于SQLite， npm install pg 对于PostgreSQL，或 npm install mysql2 适用于MySQL/MariaDB。

安装和构建

cd mcp-server
npm install
npm run build

跑

npm start
REFMD_API_BASE="https://refmd.example.com" \
OAUTH_CLIENT_IDS="chatgpt-connector" \
OAUTH_ALLOWED_REDIRECTS="https://chat.openai.com/aip/mcp/oauth/callback" \
npm start

服务器公开了两种传输方式：

  • http://<host>:<port>/sse --SSE传输（与Claude SSE等兼容）
  • http://<host>:<port>/mcp --可流式HTTP传输（每次交换一次POST）

OAuth流程

  1. 使用以下配置您的客户端（例如ChatGPT自定义连接器）：
    • 授权URL: https://your-domain.example.com/oauth/authorize
    • 令牌URL: https://your-domain.example.com/oauth/token
    • 吊销URL: https://your-domain.example.com/oauth/revoke
    • 范围： （留空）
    • PKCE： 已启用（ChatGPT自动使用S256）
  2. 出现提示时，浏览器显示RefMD MCP同意页面。粘贴从生成的RefMD API令牌 个人资料→ API令牌 并批准。
  3. 连接器接收访问令牌并可以调用 /sse 或 /mcp 随着 Authorization: Bearer <token>.

令牌可以从RefMD（配置文件页面）或通过以下方式撤销 POST /oauth/revoke.

使用Docker运行

# Build image
docker build -t refmd-mcp .

docker run -p 3334:3334 \
  -e REFMD_API_BASE="https://refmd.example.com" \
  -e OAUTH_CLIENT_IDS="chatgpt-connector" \
  -e OAUTH_ALLOWED_REDIRECTS="https://chat.openai.com/aip/mcp/oauth/callback" \
  -e MCP_DB_DRIVER="sqlite" \
  -e MCP_DB_SQLITE_PATH="/data/refmd-mcp.sqlite" \
  -v refmd-mcp-data:/data \
  refmd-mcp

装载一个持久卷（如上所示），以便SQLite数据库文件在容器重启后仍然存在。

连接聊天客户端

  • 克劳德（CLI）：
    claude mcp add --transport sse refmd https://your-domain.example.com/sse
  • 光标/VS代码/MCP检查器： 选择SSE传输并提供相同的URL。

连接后，资源显示在 refmd://document/{id}可用工具包括 refmd-list-documents, refmd-search-documents, refmd-create-document, refmd-read-document, refmd-update-document-content以及更多。

阅读大型文档

这 refmd-read-document 工具和 refmd://document/{id} 资源都支持可选的分页参数，因此大型Markdown文件保持在模型上下文协议有效载荷限制范围内：

  • offset （默认值 0)：起始字符位置（从零开始）。
  • limit （默认值 120000，上限为 120000)：响应中返回的最大字符数。

示例资源URI： refmd://document/123e4567-e89b-12d3-a456-426614174000?offset=60000&limit=60000.

每个响应都包含范围元数据和下一个偏移量，因此客户端可以发出后续调用，直到检索到完整文档。

修补文档内容

使用 refmd-patch-document-content 插入、删除或替换特定跨距的工具，而无需发送整个Markdown正文：

{
  "id": "document-uuid",
  "operations": [
    { "op": "insert", "offset": 120, "text": "New paragraph." },
    { "op": "delete", "offset": 42, "length": 5 }
  ]
}

偏移量/长度以Unicode码位计算，以匹配RefMD的编辑器行为。服务器在发出文档更改事件之前，会自动验证范围并应用操作，因此下游集成保持同步。

发布工作流程

GitHub操作工作流 CI MCP Server 运送集装箱图像。它在按下/PR时自动运行 mcp-server 并在以下情况下向GHCR发布：

  • 推送是一个标签匹配 mcp-server-v* （版本发布），或
  • 工作流是通过以下方式手动触发的 publish=true.

标签发布到 ghcr.io/<owner>/refmd-mcp 包括语义版本(1.2.0, 1.2, 1)，原始git标签，以及 latest.使用 extra-tag 手动调用工作流时输入其他标签。

发展

在TSX的监视模式下运行：

npm run dev

任何代码更改都需要重新生成(npm run build)在部署或运行之前 npm start.

相关 MCP