# omniwaifu/pydantic-ai-docs-server architecture

> Architecture diagram of the GitHub repository omniwaifu/pydantic-ai-docs-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/omniwaifu/pydantic-ai-docs-server
- Repository: https://github.com/omniwaifu/pydantic-ai-docs-server

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["MCP Client\n(LLM Agent)"]:::client

    %% Entry Point
    EntryPoint["Entry Point\n__main__.py\n(Python CLI)"]:::process

    %% Server Module
    Server["MCP Server\nserver.py\n(JSON-RPC Dispatch)"]:::process

    %% Models
    Models["Pydantic Models\nmodels.py\n(Request/Response)"]:::process

    %% Repository Manager
    RepoManager["Repository Manager\nrepository_manager.py\n(Git Clone/Pull)"]:::process

    %% Parser
    Parser["Parser\nparser.py\n(Markdown Loader)"]:::process

    %% Local Clone
    LocalClone["Local Docs\n(pydantic-ai-docs)"]:::db

    %% Remote Git Service
    RemoteGit["Remote Git Service\n(Pydantic-AI Docs Repo)"]:::cloud

    %% Configuration & Docs
    Config["Config Files\n(pyproject.toml,\nuv.lock,\n.python-version,\n.gitignore)"]:::docs
    README["Documentation\nREADME.md"]:::docs

    %% Connections
    Client -->|"JSON/stdio"| EntryPoint
    EntryPoint -->|"init Server"| Server
    Server -->|"validate/convert JSON"| Models
    Server -->|"call update_documentation\nget_document_by_path\nlist_topics\nget_changelog_content"| RepoManager & Parser
    RepoManager -->|"git clone/pull"| RemoteGit
    RepoManager -->|"store docs in"| LocalClone
    Parser -->|"read markdown"| LocalClone
    Parser -->|"parsed content"| Server
    Server -->|"JSON/stdio"| Client

    %% Config & Docs linkage
    EntryPoint --- Config
    EntryPoint --- README

    %% Click Events
    click EntryPoint "https://github.com/omniwaifu/pydantic-ai-docs-server/blob/master/pydantic_ai_docs_server/__main__.py"
    click Server "https://github.com/omniwaifu/pydantic-ai-docs-server/blob/master/pydantic_ai_docs_server/server.py"
    click Models "https://github.com/omniwaifu/pydantic-ai-docs-server/blob/master/pydantic_ai_docs_server/models.py"
    click RepoManager "https://github.com/omniwaifu/pydantic-ai-docs-server/blob/master/pydantic_ai_docs_server/repository_manager.py"
    click Parser "https://github.com/omniwaifu/pydantic-ai-docs-server/blob/master/pydantic_ai_docs_server/parser.py"
    click Config "https://github.com/omniwaifu/pydantic-ai-docs-server/blob/master/pyproject.toml"
    click Config "https://github.com/omniwaifu/pydantic-ai-docs-server/blob/master/uv.lock"
    click Config "https://github.com/omniwaifu/pydantic-ai-docs-server/blob/master/.python-version"
    click Config "https://github.com/omniwaifu/pydantic-ai-docs-server/blob/master/.gitignore"
    click README "https://github.com/omniwaifu/pydantic-ai-docs-server/blob/master/README.md"

    %% Styles
    classDef client fill:#888888,stroke:#333,color:#fff;
    classDef process fill:#bbdefb,stroke:#1e88e5,color:#000;
    classDef db fill:#c8e6c9,stroke:#43a047,color:#000;
    classDef cloud fill:#ffe0b2,stroke:#fb8c00,color:#000;
    classDef docs fill:#e1bee7,stroke:#8e24aa,color:#000;
```
