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-docsMCP客户端配置
添加到您的MCP设置中（例如。， cline_mcp_settings.json):
{
"mcpServers": {
"pydantic-docs": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/mcp_pydantic_docs",
"run",
"mcp-pydantic-docs"
]
}
}
}建筑
运作原理
- 源提取 (
source_extractor.py)-克隆Pydantic存储库，从markdown/docstring中提取文档→ JSONL - 建立索引 (
indexer.py)-处理JSONL文件→ BM25搜索索引 - MCP服务器 (
mcp.py)-通过MCP工具提供文档 - 共享公用设施 (
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 用于：
- 开发设置
- 代码风格
- 测试要求
- 拉取请求流程