python-docs-mcp-server 是一个只读的 MCP（Model Context Protocol）服务器，专为编写 Python 代码的 AI 编程代理设计，提供对 Python 官方标准库文档的本地、精确检索。它被定位为“Python 标准库的权威预言机”：精确符号、精确章节、精确版本，离线可用、始终免费、MIT 许可、节省 token。
用途
该工具解决 AI 编码代理在查询 Python 标准库时遇到的常见问题：通用文档检索容易返回模糊的页面命中，而 Python 版本差异（如 3.12 与 3.13）会导致文档内容不同；直接抓取整个页面会浪费 token，且官方文档本身并不以 MCP 服务器形式提供。python-docs-mcp-server 在本地索引官方文档，并通过一组小型 MCP 工具暴露查找和章节检索能力，让代理获得精确的符号、章节和版本信息，而不是整页转储或向量存储产生的幻觉锚点。
主要能力
- 通过 Python 的 objects.inv 进行精确符号查找。
- 支持页面和章节检索，具备截断和分页功能。
- 使用本地 SQLite + FTS5 索引，运行时无需网络抓取。
- 为每个已索引的 Python 版本提供结果，覆盖 Python 3.10 至 3.14 的文档版本。
- 提供七个只读 MCP 工具。
- 无需管理 API 密钥，查询针对本地索引运行，而非托管文档 API。
- 结果来自官方 Python 文档，运行时只读，依赖较少，便于严格环境审查。
- 通过 lookup_package_docs 查询 PyPI 声明的文档、主页和源码链接。
使用方式
运行方式：可直接使用 uvx 运行，或使用 pipx 安装一次。若已安装 uv 但 uv 命令不在 PATH 中，可重新打开 shell 或使用 python -m uv ... 作为本地贡献者命令的回退。
构建本地文档索引：首次构建会下载 Python 的 objects.inv 文件、克隆 CPython 文档源码、运行 sphinx-build -b json，并将 SQLite 索引写入本地缓存。该过程可能需要数分钟。若已持久安装包，可去掉 uvx 前缀。
配置 MCP 客户端：仓库包含项目级 .mcp.json，适用于支持签入 MCP 服务器配置的客户端，指向已发布的包。在期望文档查询返回基于语料库的结果之前，需先运行首次构建命令。
Claude Desktop 配置：将配置添加到 Claude Desktop 配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json；Linux: ~/.config/Claude/claude_desktop_config.json；Windows: %APPDATA%\Claude\claude_desktop_config.json），编辑后重启 Claude Desktop。
Cursor 配置：添加到 Cursor MCP 设置（项目中的 .cursor/mcp.json 或全局设置）。
Codex 配置：添加到 .codex/config.toml。
使用示例：询问 MCP 客户端“在 Python 3.13 中，如何使用 asyncio.TaskGroup，与旧版 asyncio 模式相比有何变化？”若设置正常，客户端应使用 search_docs 查找精确符号，然后使用 get_docs 获取匹配章节，从而获得针对所请求 Python 版本的官方标准库文本，并裁剪到相关章节。
搜索行为：对于 kind="auto" 且指定显式版本的情况，非空搜索若有剩余结果槽位，当提示包含该版本中一个已知的限定标识符时，可能追加一个精确的清单目标。原始命中、片段、分数、顺序和注释均保留。完整结果、歧义标识符、其他 kind 和无版本查询保持不变；现有的空结果回退保持不变。规范位置会去重，包括清单别名。仅当 Pydantic 的紧凑 model_dump_json() 序列化后的完整拟议响应不超过 8000 UTF-8 字节时，才允许追加。这不是全局搜索上限：过大的原始响应保持不变。这与 get_docs(max_chars=8000) 不同，后者限制内容字符数。
对于 search_docs 且 kind="auto" 并指定显式索引版本的情况，原始查找和全文搜索先运行。若两者均无命中，服务器会在提示中查找带点的 Python 标识符。恰好一个在该版本中注册的不同标识符会启用符号查找回退；重复提及只计一次，未知标识符不计。多个已知标识符则结果为空。结果注释会标识回退匹配，这些是符号文档，而非对完整提示的回答。显式 kind、无版本搜索、非空结果和结果预算保持不变。
适用场景
- AI 编码代理需要查询 Python 标准库的精确符号签名、语义或版本变更时。
- 需要针对特定 Python 版本（3.10 至 3.14）获取官方文档章节，而非整页内容时。
- 在严格环境中需要只读、无 API 密钥、依赖较少的本地文档检索工具时。
- 需要查询 PyPI 包声明的文档、主页和源码链接时。
限制
- 该服务器不是通用文档搜索引擎，而是专注于标准库检索的工具。对于第三方库、任意网页或框架研究，应使用 Context7 或通用文档获取器。
- 服务器运行时需要 Python 3.12+。
- 生成的文档语料库覆盖 Python 文档版本 3.10 至 3.14。
- 首次构建索引可能需要数分钟。
- 在 macOS 和 Linux 上已测试；Windows 应可运行，但并非每个版本都经过验证。
- 若 Python 构建不包含 SQLite FTS5，需要额外处理。
- 在 Debian/Ubuntu 上若缺少 pythonX.Y-venv，build-index 无法创建用于构建 JSON 文档内容的一次性 Sphinx 环境。
- 从旧 CLI 迁移时，若 MCP 客户端配置仍通过 uvx 引用旧 PyPI 名称 mcp-server-python-docs，会出现 Package not found 错误。
- 重建索引后需重启 MCP 客户端以加载新数据库文件；服务器启动时以只读方式打开索引，运行期间不会重新加载。在 Windows 上，若索引文件被锁定，重建前需关闭 MCP 客户端。
- uvx 缓存可能过期，导致运行旧版本。
- Windows 上 MSIX 打包的 Claude Desktop 可能限制 PATH 访问，若找不到 uvx，需在配置中指定完整路径。
其他信息
检索到的文档缓存：get_docs 响应会跨 MCP 客户端/服务器重启缓存在平台缓存目录中。缓存存储已完成的 get_docs 结果，针对解析后的 Python 文档版本以及请求身份（slug、可选 anchor、max_chars 和 start_index）。缓存未命中时使用正常的本地索引检索路径，然后写入结果。缓存条目还限定于本地 index.db 文件的指纹（路径、大小和修改时间戳）。若重建或替换本地文档索引，旧条目会自动忽略。删除 retrieved-docs-cache.sqlite3 是安全的；它移除缓存的检索结果，而非文档索引。
PyPI 包文档查询：lookup_package_docs 查询官方 PyPI JSON API（GET /pypi/<project>/json），仅返回该包 PyPI 元数据中声明的来源：PyPI 项目 URL、docs_url、home_page，以及允许列表中的 project_urls 标签，如 Documentation、Homepage、Source 和 Repository。该工具通过 trust_boundary="pypi-declared-metadata" 明确信任边界。它不抓取页面、不执行网络搜索，也不会静默回退到非官方社区镜像。
环境检查与索引验证：可检查本地环境（运行时 Python 版本、SQLite FTS5、缓存/索引路径、磁盘空间，以及 build-index 所需的 venv/ensurepip 支持），并验证现有索引。
贡献者工作流：CI 在 macOS 和 Linux 上针对 Python 3.12 和 3.13 运行 ruff、pyright 和 pytest；基于 subprocess 的 stdio 和冒烟测试覆盖 MCP 协议管道；打包测试检查 wheel 内容和 CLI 入口点；检索回归测试覆盖精确符号命中、版本行为、缺失符号、截断和本地版本默认值。手动 MCP QA 位于 .github/INTEGRATION-TEST.md，使用 MCP Inspector 进行本地检查，使用 Claude/Cursor 进行真实客户端检查。贡献者命令和验证步骤位于 CONTRIBUTING.md。
