docs2mcp

将包含 Markdown、HTML 或 TXT 文件的目录转换为远程、只读的 MCP 服务器，任何兼容的 MCP 客户端或代理都可以连接它来检索文档。这包括 AskMesh、Claude 集成、Codex 和自定义 MCP 客户端。

快速开始

uvx docs2mcp serve ./docs \
  --base-url https://docs.example.com/docs \
  --host 0.0.0.0 \
  --port 8765

uvx 会从 PyPI 创建隔离环境，并运行已发布的 docs2mcp CLI，无需手动安装步骤。若要从检出副本进行本地开发，请改用 python -m docs2mcp.runtime。

通过文件监视和定期对账启用增量同步：

uvx docs2mcp serve ./docs \
  --host 0.0.0.0 \
  --port 8765 \
  --watch \
  --sync-interval 30

首次启动会扫描整个目录。后续更改按文档应用：新文件会被插入，修改过的文件会被重新索引，删除的文件会被移除，未更改的文件会被跳过。监视器使用较短的防抖窗口，周期性扫描为无法可靠发出事件的文件系统提供回退方案。

当绑定到特定公共地址并启用 DNS 重新绑定保护时，请显式允许传入的 Host 头：

uvx docs2mcp serve ./docs \
  --host 0.0.0.0 \
  --port 8765 \
  --allowed-host 'docs.example.com:*'

安装和启动时请使用相同的 Python 解释器。docs2mcp 需要官方 MCP Python SDK mcp>=1.27.0,<2；名为 mcp 的较旧或不相关包不提供 mcp.server.fastmcp。

旧版 doc2mcp 命令仍可作为兼容别名使用。

进程在启动时会打印 MCP 连接配置。身份验证是可选的：传入 --token 以启用 Bearer 身份验证，或省略它以在无身份验证的情况下运行。

{
  "endpoint": "http://127.0.0.1:8765/mcp",
  "auth_type": "none",
  "token": null,
  "search_tool": "search_docs",
  "read_tool": "get_document",
  "contract_version": "agent-qa.docs/v1"
}

在 MCP 客户端配置中输入 endpoint、身份验证模式、search_docs 和 get_document 值。当 auth_type 为 none 时，选择无身份验证并将令牌留空。支持 Streamable HTTP 的客户端可以直接连接到同一端点，无需 AskMesh 专用适配器。

GET /readyz 报告文档数量和最新的同步计数器，包括新增、更新、删除、跳过、失败、耗时以及最后一条错误。

Related MCP server: Synapse

支持的格式

MVP 支持 .md、.markdown、.txt、.html 和 .htm。索引使用 SQLite FTS5，因此不需要单独的向量数据库。

MCP 契约

服务器实现了可互操作的 agent-qa.docs/v1 文档契约，并公开两个只读工具：

• search_docs(query, limit)：返回 route、title、url、snippet 和 score。

• get_document(route, max_characters)：返回文档内容、章节和引用 URL。

search_docs.query 使用 SQLite FTS5 语法。空白表示 AND 查询，OR 匹配任一术语，引号文本搜索精确短语，NOT 排除某个术语，* 启用前缀匹配。它不是语义自然语言搜索；客户端应向用户展示此语法。

从任何 MCP 客户端连接

在任何支持远程 MCP 连接的客户端中，使用 Streamable HTTP 端点和这两个工具名称。AskMesh 是受支持的集成之一；基于 Claude 的客户端、Codex 和自定义代理可以使用相同的端点和只读契约。

当前限制

此版本是单主机 MVP：文档从本地目录导入，索引存储在 SQLite 中。Git 同步、PDF 解析、对象存储、向量搜索和多租户控制平面计划在后续版本中提供。