MCP Tool Docs

mcp工具文档

独立的MCP服务器，适用于需要规范MCP协议和客户端布线文档的工具匠/客户端。它发布自己的语料库（在启动时获取，自动刷新）并公开一个工具， search_corpus，返回已排序的代码片段和源URL。

适用对象：MCP toolsmith代理、Codex/Continue用户，或任何需要可靠协议/配置引用而不依赖于本地存储库的MCP客户端。

它解决了什么：在单个MCP工具中快速、离线友好地查找MCP规范、SDK README模式、检查器使用和Codex/Continue MCP配置模式。

它暴露了什么

• 工具: search_corpus --在捆绑的语料库上进行关键字搜索（SQLite FTS5，前缀匹配），并可选择返回完整内容。
• 语料库 （启动时自动获取；即使缓存是新的，也会立即获取新源）：

- MCP合并文件： llms-full.txt - MCP协议README，参考服务器README - Python/TypeScript SDK自述文件 - MCP检查员自述 - Codex MCP指南、Codex CLI参考、Codex配置模式 - Continue.dev MCP深度学习和MCP工具页面

快速启动（stdio）

python -m venv .venv
source .venv/bin/activate
pip install -e .
# refresh corpus and start the server on stdio
python -m mcp_tool_docs.server

在不启动服务器的情况下运行一次性刷新

python -m mcp_tool_docs.corpus --refresh-only

配置

• MCP_TOOL_DOCS_DATA_DIR （可选）：语料库的存储位置。违约： ~/.local/share/mcp-tool-docs/corpus.
• MCP_TOOL_DOCS_REFRESH_HOURS （可选）：自动刷新前的最大年龄。违约： 24 小时。
• MCP_TOOL_DOCS_MAX_RESULTS （可选）：默认值 top_k 当客户端没有指定时。违约： 5.
• MCP_TOOL_DOCS_MAX_CONTENT_CHARS （可选）：截断帽 include_full_text=true默认值： 12000.

行为保证：

• 启动时和搜索前自动刷新（如果缓存早于 MCP_TOOL_DOCS_REFRESH_HOURS 或者如果添加了新的来源。
• 即使缓存是新的，也会立即获取新的源。
• 下载失败会退回到缓存副本（如果存在）；只有当源丢失且不存在缓存副本时，启动/搜索才会快速失败。
• 第一场比赛的片段长度约为240个字符；全文被截断为 MCP_TOOL_DOCS_MAX_CONTENT_CHARS.

工具合同

工具名称： search_corpus

输入架构：

• query （字符串，必填）：搜索词。
• top_k （整数，可选）：要返回的结果数（默认值来自env）。
• include_full_text （布尔值，可选）：在结果中包含完整的文档文本（可能很大）。默认 false.

输出架构：

{
  "results": [
    {
      "doc_id": "clients/codex/codex-mcp.txt",
      "title": "clients/codex/codex-mcp.txt",
      "source_url": "https://developers.openai.com/codex/mcp/",
      "score": 0.12,
      "snippet": "Text around the first hit...",
      "content": "Full text (truncated to MCP_TOOL_DOCS_MAX_CONTENT_CHARS) when include_full_text=true"
    }
  ]
}

示例通话

• 没有全文：

  {"tool": "search_corpus", "params": {"query": "Codex mcp_servers config", "top_k": 3}}

• 全文如下：

  {"tool": "search_corpus", "params": {"query": "streamable http transport", "top_k": 2, "include_full_text": true}}

搜索语义

• 通过SQLite FTS5进行关键字/前缀搜索（无嵌入，无短语匹配）。查询词为AND；每个术语被匹配为前缀（例如。， stream 火柴 streamable/streaming).
• 不区分大小写，子字符串友好；为了获得最佳结果，使用协议/配置关键短语（例如。， rmcp_client, stdio transport, mcpServers).
• 排名使用FTS5中的BM25；结果包括围绕第一个匹配项加上源URL的一个240个字符的片段。

语料库更新策略

• 源直接从中列出的第一方URL获取 mcp_tool_docs/sources.py.
• HTML源代码通过轻量级HTML解析器转换为纯文本（脚本/样式被剥离）；导航/样板可能会保留。
• 失败的下载会保留现有副本；missing+no缓存很快就会失败。使用 python -m mcp_tool_docs.corpus --refresh-only 检查健康状况。
• 语料库位于 MCP_TOOL_DOCS_DATA_DIR （默认值 ~/.local/share/mcp-tool-docs/corpus)，具有SQLite FTS索引。

扩展语料库

• 添加第一方 text 或 html 来源于 mcp_tool_docs/sources.py （保持权威网址）。
• 部署/重启：新源在首次启动或丢失时被拉取；强制刷新 python -m mcp_tool_docs.corpus --force.

食品法典配置（stdio）

[mcp_servers.mcp-tool-docs]
command = "python"
args = ["-m", "mcp_tool_docs.server"]
cwd = "/path/to/mcp-tool-docs" # optional if installed globally
startup_timeout_sec = 20
tool_timeout_sec = 60

[features]
rmcp_client = true  # only needed for OAuth/streamable-http targets; safe to leave on

CLI替代方案：

codex mcp add mcp-tool-docs -- python -m mcp_tool_docs.server

继续配置（stdio）

.continue/mcpServers/mcp-tool-docs.yaml

name: mcp-tool-docs
type: stdio
command: python
args:
  - -m
  - mcp_tool_docs.server
cwd: /path/to/mcp-tool-docs  # optional if installed globally
env: {}

操作和故障排除

• 健康/刷新检查： python -m mcp_tool_docs.corpus --refresh-only （报告下载问题）。
• 预期启动：初始获取是几个小文件；后续开始重用缓存，除非过时或源更改。
• 权限：确保 MCP_TOOL_DOCS_DATA_DIR 可写；下载失败时，过时的缓存会持续存在。
• 网络故障：服务器继续缓存文档；如果新源无法访问且未缓存，startup/search会在URL中引发错误。

开发说明

• 每个仓库只有一个工具，以保持最小的占用空间。
• 使用官方MCP Python SDK进行协议正确性。
• 仅使用标准库+ requests 尽量减少依赖性；SQLite FTS5处理排名。
• 自动刷新受到以下限制 MCP_TOOL_DOCS_REFRESH_HOURS 以避免对上游文件造成冲击。