mcp-a2a-documentation
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
# MCP A2A Documentation Server
An MCP (Model Context Protocol) server that provides search and retrieval tools for the [Agent2Agent (A2A) protocol](https://a2a-protocol.org) documentation. This server enables AI assistants like Claude to search and read A2A documentation directly from the upstream repository.
## Source
This server indexes documentation from the [`a2aproject/A2A`](https://github.com/a2aproject/A2A) repository's `docs/` directory, which powers [a2a-protocol.org](https://a2a-protocol.org).
## Features
- **Full-text search** using SQLite FTS5 with BM25 ranking and Porter stemming
- **Section filtering** to narrow search results by documentation category (`root`, `topics`, `tutorials`, `sdk`)
- **Sparse checkout** for efficient cloning of only the required `docs/` directory
- **Docker support** for portable deployment across projects
- **STDIO transport** for seamless MCP client integration
## Quick Start
### Using the Container Image (Recommended)
The `martoc/mcp-a2a-documentation` container image is published to Docker Hub with the documentation index pre-built. Available for `linux/amd64` and `linux/arm64`.
```bash
# Pull and run the server
docker run -i --rm martoc/mcp-a2a-documentation:latest
```
### Building Locally with Docker
```bash
# Build the Docker image (includes pre-indexed documentation)
make docker-build
# Test the server
make docker-run
```
### Using uv (Local Development)
```bash
# Initialise the environment
make init
# Build the documentation index
make index
# Run the server
make run
```
## Container Image
The `martoc/mcp-a2a-documentation` container image is published to [Docker Hub](https://hub.docker.com/r/martoc/mcp-a2a-documentation). It includes the pre-built documentation index so the server is ready to use immediately.
| Property | Value |
|----------|-------|
| Registry | Docker Hub |
| Image | `martoc/mcp-a2a-documentation` |
| Platforms | `linux/amd64`, `linux/arm64` |
| Base image | `python:3.12-slim` |
| Index | Pre-built at image build time from the `main` branch of `a2aproject/A2A` |
```bash
# Pull the latest image
docker pull martoc/mcp-a2a-documentation:latest
# Run the MCP server
docker run -i --rm martoc/mcp-a2a-documentation:latest
```
## Configuration
### Claude Code / Claude Desktop
Add to your `.mcp.json` or global settings to use the published container image:
```json
{
"mcpServers": {
"a2a-documentation": {
"command": "docker",
"args": ["run", "-i", "--rm", "martoc/mcp-a2a-documentation:latest"]
}
}
}
```
For local development without Docker:
```json
{
"mcpServers": {
"a2a-documentation": {
"command": "uv",
"args": ["run", "mcp-a2a-documentation"],
"cwd": "/path/to/mcp-a2a-documentation"
}
}
}
```
## MCP Tools
| Tool | Description |
|------|-------------|
| `search_documentation` | Search A2A documentation by keyword query with optional section filter |
| `read_documentation` | Retrieve the full content of a specific documentation page |
### search_documentation
Search A2A protocol documentation using full-text search with stemming support.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | string | Yes | - | Search terms (supports stemming) |
| `section` | string | No | None | Filter by section (`root`, `topics`, `tutorials`, `sdk`) |
| `source` | string | No | None | Filter by source (`a2a`) |
| `limit` | integer | No | 10 | Maximum results (1-50) |
**Available sections:** `root` (specification, community, roadmap, partners, etc.), `topics` (core protocol concepts), `tutorials` (the Python quickstart), `sdk` (SDK overview).
### read_documentation
Retrieve the full content of a documentation page.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Source-prefixed path to the document (e.g., `a2a/topics/what-is-a2a.md`). This path is returned by `search_documentation`. |
## CLI Commands
```bash
# Build/rebuild the documentation index
uv run a2a-docs-index index
uv run a2a-docs-index index --rebuild
uv run a2a-docs-index index --branch main
# Show index statistics
uv run a2a-docs-index stats
```
## Development
```bash
make init # Initialise development environment
make build # Run full build (lint, typecheck, test)
make test # Run tests with coverage
make format # Format code
make lint # Run linter
make typecheck # Run type checker
```
## Documentation
- [USAGE.md](USAGE.md) - Detailed usage instructions
- [CODESTYLE.md](CODESTYLE.md) - Code style guidelines
- [CLAUDE.md](CLAUDE.md) - Claude Code instructions
## Licence
This project is licensed under the MIT Licence - see the [LICENSE](LICENSE) file for details.
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: search_documentation finds pages by keyword, while read_documentation retrieves a specific page's full content. There is no meaningful overlap that would cause an agent to select the wrong tool.
Both names follow a consistent snake_case verb_noun pattern: search_documentation and read_documentation. The naming is predictable and directly reflects each tool's action and target.
Two tools is a very thin surface, even for a focused documentation server. Search plus read covers the core flow, but the set feels minimal and could benefit from at least an index/listing operation.
Search and read cover the essential documentation workflow: discover relevant pages, then read full content. A listing or table-of-contents tool would improve browsing, but the current surface is workable for most agent needs.