Content
# 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:**
```bash
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`:
```bash
python -m venv .venv
source .venv/bin/activate # On Windows use: .venv\Scripts\activate
```
Alternatively, using `uv`:
```bash
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.
```bash
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:
```bash
pydantic-ai-docs-server
```
Or:
```bash
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:
```json
{"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:
```json
{"type": "call-tool", "tool_name": "<tool_name_here>", "tool_args": {"<arg_name>": "<value>", ...}}
```
**Example: Calling `update_documentation`**
```json
{"type": "call-tool", "tool_name": "update_documentation", "tool_args": {"force_clone": false}}
```
**Example: Calling `get_document_by_path`**
```json
{"type": "call-tool", "tool_name": "get_document_by_path", "tool_args": {"path": "usage/models.md"}}
```
**Example: Calling `list_topics` (no arguments)**
```json
{"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.
```json
{
"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`).
