What is Pydantic Ai Docs Server

The Pydantic AI Documentation Server is a Model Context Protocol (MCP) server that provides programmatic access to the Pydantic-AI documentation, allowing users to clone/update the documentation repository, retrieve specific documents, list documentation topics, and access changelog information.

Use cases

Use cases include maintaining up-to-date documentation for Pydantic-based applications, retrieving specific documentation files for reference, and managing changelogs for version tracking.

How to use

To use the Pydantic AI Documentation Server, clone the repository, create and activate a Python virtual environment, and utilize the provided tools to manage documentation and changelogs.

Key features

Key features include updating documentation with update_documentation, retrieving documents by path with get_document_by_path, listing topics with list_topics, and accessing changelogs with list_available_changelogs and get_changelog_content.

Where to use

The server can be used in software development environments, particularly for projects that utilize Pydantic for data validation and settings management, where documentation needs to be easily accessible and up-to-date.

Pydantic AI Documentation Server

Overview

This server provides programmatic access to the Pydantic-AI documentation, including cloning/updating the documentation repository, retrieving specific documents, listing documentation topics, and accessing changelog information. It operates as a Model Context Protocol (MCP) server, exposing its functionalities as tools.

Note: This is primarily for personal use and requires cloning the repository and using the update tool to keep the documentation up to date.

Features

The server exposes the following tools via MCP:

• update_documentation(force_clone: bool = False): Clones the Pydantic-AI repository (if not already present) or pulls the latest updates. If force_clone is true, it will delete any existing repository and clone fresh.
• get_document_by_path(path: str): Retrieves a specific documentation file by its path relative to the docs/ directory (e.g., usage/models.md).
• list_topics(path: Optional[str] = None): Lists files and directories within the Pydantic-AI docs/ directory. If a path is provided, it lists contents of that subdirectory.
• list_available_changelogs(): Lists all available changelog files found in the Pydantic-AI repository (typically under docs/history/).
• get_changelog_content(path: str): Retrieves the content of a specific changelog file (e.g., history/0.2.0.md).

Setup

1. Clone this repository:

   git clone <repository_url> # Replace <repository_url> with the actual URL of this server's repository
   cd pydantic-ai-docs-server
   

2. Create and activate a Python virtual environment:
   It’s recommended to use Python 3.12 or newer.
   Using python -m venv:

   python -m venv .venv
   source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
   

   Alternatively, using uv:

   uv venv .venv
   source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
   

3. Install dependencies:
   This project uses uv for fast package management, but pip can also be used.

   uv pip install -e .
   # Or, if you don't have uv:
   # pip install -e .
   

   This installs the package in editable mode along with its dependencies specified in pyproject.toml.

Running the Server

Once the setup is complete, you can run the server using the script installed by pip install -e ., or by running the module directly:

pydantic-ai-docs-server

Or:

python -m pydantic_ai_docs_server

The server will start and listen for MCP requests over standard input/output (stdio).

Using the Server

This application is an MCP server designed to communicate over standard input/output (stdio) using newline-delimited JSON messages. To interact with it, you would typically use an MCP client library or tool that can manage this communication channel. However, you can also interact with it directly by sending and receiving the raw JSON messages if you are developing a client or for testing purposes.

Interaction Protocol:

1. You send a JSON request object on a single line to the server’s stdin.
2. The server processes the request and sends a JSON response object on a single line to its stdout.

Common MCP Request Types:

1. Listing Available Tools (list-tools)

   To ask the server what tools it provides, send a JSON message like this:

   {
     "type": "list-tools"
   }
   

   The server will respond with a JSON object containing a list of available tools and their schemas.

2. Calling a Tool (call-tool)

   To execute a specific tool, send a JSON message like this:

   Example: Calling update_documentation

   {
     "type": "call-tool",
     "tool_name": "update_documentation",
     "tool_args": {
       "force_clone": false
     }
   }
   

   Example: Calling get_document_by_path

   {
     "type": "call-tool",
     "tool_name": "get_document_by_path",
     "tool_args": {
       "path": "usage/models.md"
     }
   }
   

   Example: Calling list_topics (no arguments)

   {
     "type": "call-tool",
     "tool_name": "list_topics",
     "tool_args": {}
   }
   

   The server will respond with a JSON object containing the result of the tool execution or an error if something went wrong.

Refer to the Model Context Protocol specification for more details on the message formats and protocol. The tools available on this server are defined in pydantic_ai_docs_server/server.py.

Integration with MCP Clients (e.g., Cursor)

To use this server with an MCP client application like Cursor, you need to configure it in the client’s MCP settings file. For Cursor, this is typically a file named .cursor/mcp.json located in your project root.

.cursor/mcp.json Configuration:

Add or update the mcpServers section in your .cursor/mcp.json as follows. This configuration uses uv to run the server module from the specified project directory.

{
  "mcpServers": {
    "pydantic-ai-docs": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/pydantic-ai-docs-server",
        "run",
        "-m",
        "pydantic_ai_docs_server"
      ]
    }
  }
}

Key points for this configuration:

• "pydantic-ai-docs": This is a name you assign to this server configuration. Your MCP client (e.g., Cursor) will use this name to identify and communicate with this server.
• "command": "uv": Specifies that uv should be used to launch the server.
• "args": Defines the arguments passed to uv:
  • "--directory": Instructs uv to operate as if it were launched from the specified directory. Replace /path/to/your/pydantic-ai-docs-server with the actual absolute path to the root of this pydantic-ai_docs_server project on your system. This is critical for the server to correctly locate its internal modules and the cloned documentation repository.
  • "run": The uv command to execute a project.
  • "-m", "pydantic_ai_docs_server": Tells uv run to execute the pydantic_ai_docs_server package as a module (which runs its __main__.py file).

Ensure your virtual environment (created with uv venv or python -m venv) is active, or that uv is installed globally and can find the project’s environment when the MCP client starts the server.

Once configured, your MCP client should be able to discover and call the tools provided by this server (e.g., PyDanticAIDocs.update_documentation).