Pydocs MCP

pydocs mcp

作为MCP服务器的离线Python文档。这反映了建筑 库比蒂诺存储库 但目标是Python官方文档（docs.Python.org）。

什么是pydocs-mcp？

Python的本地、结构化、AI就绪的文档系统。它

• 下载 来自docs.Python.org的官方Python文档
• 索引 将所有内容放入快速、可搜索的SQLite FTS5数据库中
• 供应 通过模型上下文协议向AI代理提供文档
• 提供 离线访问Python语言和标准库文档

为什么要建造这个？

• 不再有幻觉：AI代理获得准确、最新的Python文档
• 线下开发：在没有互联网接入的情况下使用完整的文档
• 确定性搜索：相同的查询总是返回相同的结果
• 本地控制：拥有您的文档，检查数据库，编写工作流程脚本
• AI优先设计：专为通过MCP集成AI代理而构建

快速开始

安装

git clone https://github.com/arsenylosev/pydocs-mcp.git
cd pydocs-mcp
uv sync

设置

一个命令安装程序下载并索引Python文档：

uv run pydocs-mcp setup

或者一步一步：

# Download documentation
uv run pydocs-mcp fetch

# Verify index
uv run pydocs-mcp stats

与Claude Desktop一起使用

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pydocs": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pydocs-mcp", "pydocs-mcp", "serve"]
    }
  }
}

与Claude Code一起使用

claude mcp add pydocs --scope user -- uv run --directory /path/to/pydocs-mcp pydocs-mcp serve

与VS代码一起使用（GitHub Copilot）

添加 .vscode/mcp.json:

{
  "servers": {
    "pydocs": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pydocs-mcp", "pydocs-mcp", "serve"]
    }
  }
}

命令

外部包装

默认情况下，pydocs-mcp只下载官方Python文档。您可以通过配置文件添加外部包（NumPy、Pandas等）。

初始化包配置

uv run pydocs-mcp packages init

这创造了 ~/.pydocs_mcp/pydocs-packages.yaml 样品包装。

示例包配置

packages:
  - name: numpy
    doc_url: https://numpy.org/doc/stable/
    doc_type: auto
    max_pages: 2000
    crawl_delay_seconds: 0.3

  - name: pandas
    doc_url: https://pandas.pydata.org/docs/
    doc_type: auto
    max_pages: 2000

  - name: requests
    doc_url: https://requests.readthedocs.io/en/latest/
    doc_type: readthedocs
    max_pages: 500

获取外部包

# Fetch all configured sources + external packages
uv run pydocs-mcp fetch

# Fetch only a specific package
uv run pydocs-mcp fetch --source numpy

从CLI添加包

uv run pydocs-mcp packages add --name flask --url https://flask.palletsprojects.com/

配置

环境变量

自定义源

对于高级用例，您可以提供自定义源配置：

uv run pydocs-mcp fetch --config /path/to/custom-sources.yaml

搜索示例

# Search for list comprehensions
uv run pydocs-mcp search "list comprehension"

# Search with text output
uv run pydocs-mcp search "context manager" --format text

# Search within specific source
uv run pydocs-mcp search "asyncio" --source python-library

# Read a specific document
uv run pydocs-mcp read --url "https://docs.python.org/3/library/asyncio.html"

建筑

该项目遵循库比蒂诺架构模式：

Foundation Layer:
  ├─ config.py          # Configuration management
  ├─ log.py             # Logging infrastructure
  └─ parser.py          # HTML to Markdown conversion

Infrastructure Layer:
  ├─ crawler.py         # Web crawling
  ├─ storage.py         # SQLite FTS5 storage
  └─ indexer.py         # Document indexing

Application Layer:
  ├─ search.py          # Search API
  └─ mcp_server.py      # MCP server implementation

Interface Layer:
  └─ cli.py             # CLI commands

默认来源

内置源代码（仅限Python官方文档）：

• python -Python 3主要文档
• python-tutorial -Python教程
• python-library -Python标准库
• python-reference -Python语言参考
• python-howto -Python教程

MCP工具

• search_docs(query, limit=10, source=None) -全文搜索
• read_doc(doc_id=None, url=None) -按ID或URL读取文档
• list_sources() -列出可用来源
• get_stats() -获取数据库统计信息

发展

# Install dependencies
uv sync

# Run tests
uv run pytest

# Format code
uv run ruff format .
uv run ruff check . --fix

与原始pydocs-mcp的差异

原始项目默认下载了许多ML库（NumPy、Pandas、PyTorch等）。此版本：

1. 关注Python官方文档 -默认情况下只有docs.python.org
2. 可选外部包 -ML库可以通过配置添加
3. 库比蒂诺风格CLI -命令组织为设置、获取、保存、服务
4. 更好的源代码管理 -按来源筛选，列出来源等。

许可证

MIT许可证

致谢

• 受启发于 库比蒂诺 Apple文档
• 建于 FastMCP