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 onCLI替代方案：
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以避免对上游文件造成冲击。