MCP pydantic docs

Pydantic文档MCP服务器

一个模型上下文协议（MCP）服务器，通过BM25支持的全文搜索提供对Pydantic和Pydantic AI文档的本地优先访问。

特性

• 当地第一建筑 -默认情况下为仅脱机模式
• BM25全文搜索 -跨所有文档的快速语义搜索
• 基于Git的提取 -直接从源代码库（无HTML抓取）
• 预处理数据 -包含用于即时设置的JSONL文件
• 自动初始化 -首次运行时自动构建索引
• 全覆盖 -Pydantic v2和Pydantic AI文档

需求

• Python 3.12+
• uv包管理器
• ~15MB磁盘空间（带索引）

快速开始

# Clone and install
git clone 
cd mcp_pydantic_docs
uv sync

# Server auto-builds indices on first run
uv run mcp-pydantic-docs

MCP客户端配置

添加到您的MCP设置中（例如。， cline_mcp_settings.json):

{
  "mcpServers": {
    "pydantic-docs": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp_pydantic_docs",
        "run",
        "mcp-pydantic-docs"
      ]
    }
  }
}

建筑

运作原理

1. 源提取 (source_extractor.py)-克隆Pydantic存储库，从markdown/docstring中提取文档→ JSONL
2. 建立索引 (indexer.py)-处理JSONL文件→ BM25搜索索引
3. MCP服务器 (mcp.py)-通过MCP工具提供文档
4. 共享公用设施 (utils.py)HTML/文本处理，规范化

目录结构

mcp_pydantic_docs/
├── mcp_pydantic_docs/          # Source code
│   ├── mcp.py                  # MCP server
│   ├── source_extractor.py     # Git-based doc extraction
│   ├── indexer.py              # BM25 index builder
│   ├── utils.py                # Shared utilities
│   └── setup.py                # Setup CLI
├── data/                       # Search data
│   ├── pydantic.jsonl          # Pydantic docs (2.9MB, in git)
│   ├── pydantic_ai.jsonl       # Pydantic AI docs (3.3MB, in git)
│   ├── *_bm25.pkl              # BM25 index (generated)
│   └── *_records.pkl           # Document records (generated)
└── docs_raw/                   # Source repos (not in git)
    ├── pydantic/               # Cloned from GitHub
    └── pydantic_ai/            # Cloned from GitHub

数据流

GitHub Repos → source_extractor.py → JSONL files → indexer.py → BM25 indices → mcp.py → MCP Client

可用工具

搜索与检索

• pydantic_search(query, k=10) -BM25排名的全文搜索
• pydantic_get(path_or_url, max_chars=None) -获取完整文档页面
• pydantic_section(path_or_url, anchor) -提取特定部分
• pydantic_api(symbol, anchor=None) -跳转到API文档

健康与行政

• health_ping() -服务器健康检查
• health_validate() -验证搜索索引
• pydantic_mode() -服务器配置
• admin_cache_status() -详细的缓存状态
• admin_rebuild_indices() -重建搜索索引

更新文档

从现有JSONL重建

uv run python -m mcp_pydantic_docs.indexer

提取新文档

# Check status
uv run python -m mcp_pydantic_docs.setup --status

# Download and extract from GitHub
uv run python -m mcp_pydantic_docs.setup --download --build-index

# Clean cache
uv run python -m mcp_pydantic_docs.setup --clean

配置

环境变量

• PDA_DOC_ROOT -Pydantic v2源路径
• PDA_DOC_ROOT_AI -Pydantic AI源路径
• PDA_DATA_DIR -数据目录路径

脱机模式

违约： 启用 (OFFLINE_ONLY = True 在 mcp.py)

• 阻止远程请求
• 验证文件路径
• 本地缓存中的所有内容

发展

运行测试

uv run pytest

代码质量

uv run black mcp_pydantic_docs/  # Format
uv run ruff check .              # Lint
uv run mypy mcp_pydantic_docs/   # Type check

故障排除

未找到搜索索引：

uv run python -m mcp_pydantic_docs.indexer

错误的Python版本：

uv python install 3.12

服务器无法启动：

# Test standalone
uv run mcp-pydantic-docs

# Check indices
uv run python -m mcp_pydantic_docs.setup --status

许可证

MIT许可证-请参阅 许可证 文件。

贡献

看 贡献.md 用于：

• 开发设置
• 代码风格
• 测试要求
• 拉取请求流程