How omniwaifu/pydantic-ai-docs-server works
Project type and purpose
• This is a backend MCP (Model Context Protocol) server written in Python.
• It exposes documentation‐retrieval tools over newline‐delimited JSON on stdio.
• It clones/updates a remote Pydantic‐AI docs repository, reads files, parses content, and serves results to any MCP client (e.g., Cursor).
File structure
• Top‐level:
• __main__.py – entry‐point CLI that starts the MCP server
• server.py – defines the MCP tool registry and request handlers
• repository_manager.py – handles Git clone/pull operations on the docs repo
• parser.py – reads/parses markdown files from the local clone
• models.py – Pydantic schemas for requests/responses
• Config files:
• pyproject.toml, uv.lock, .python-version – Python build/env setup
• .gitignore – excludes the cloned docs directory, virtual env, etc.
README for additional insights
• The server registers four main tools: update_documentation, get_document_by_path, list_topics, list_available_changelogs, get_changelog_content.
• It communicates over JSON‐RPC–style messages via stdin/stdout.
• Uses Pydantic models to validate inputs/outputs and uv (or pip) to install/run.
Main components & interactions (
A. External MCP Client
• e.g., Cursor or any LLM agent acting as a client
• Sends JSON messages (list-tools, call-tool) to the server on stdin
• Receives JSON responses on stdout
B. MCP Server Process
• Entry Point (__main__.py)
• Initializes environment, launches Server instance
• Server Module (server.py)
• Registers tools, dispatches incoming JSON to tool handlers
• Converts raw JSON → Pydantic models → business logic → JSON response
• Models (models.py)
• Defines request/response schemas using Pydantic
• Repository Manager (repository_manager.py)
• Checks if the local docs repo exists
• Runs git clone or git pull against the remote Pydantic-AI GitHub
• Stores or refreshes docs in a local folder (e.g., ./pydantic-ai-docs)
• Parser (parser.py)
• Loads markdown files from the local clone
• May parse headings or raw content for the MCP response
C. Local File System
• Holds the cloned Pydantic-AI docs (docs/)
• Used by Repo Manager and Parser
D. External Git Service
• Remote GitHub repository for Pydantic-AI docs
• Interacts only with repository_manager via Git commands
Architectural patterns & design principles
• Separation of concerns:
• Communication layer (Server) vs. Data‐access layer (Repository Manager) vs. Parsing logic
• Microservice‐style tool registry:
• Each “tool” is an independent RPC endpoint
• Model‐driven validation:
• Uses Pydantic to ensure request/response integrity
• Stateless request handlers:
• Each call fetches/reads as needed—no in‐memory session state beyond the local clone
Essential elements
• Annotations for key technologies: Python 3.12, Pydantic, MCP, Git