mcp-a2a-documentation: Instructions file for Claude Code

Claude Code Instructions

This file contains instructions for Claude Code when working with the MCP A2A Documentation Server codebase.

Project Overview

This is an MCP (Model Context Protocol) server that provides search and retrieval tools for Agent2Agent (A2A) protocol documentation. It uses:

• FastMCP for the MCP server framework
• SQLite FTS5 for full-text search with BM25 ranking
• Python-frontmatter for parsing markdown files with YAML frontmatter
• Sparse Git checkout for efficient cloning of the documentation directory
• One upstream source:
  • a2aproject/A2A — the docs/ directory, which powers a2a-protocol.org

Code Principles

British English

• Use British English in all code, comments, and documentation
• Examples: "initialise" not "initialize", "colour" not "color"

Type Safety

• All functions must have type hints
• Use modern union syntax: str | None instead of Optional[str]
• Run mypy in strict mode before committing

Error Handling

• Use explicit error handling
• Raise appropriate exceptions with descriptive messages
• Never silently fail

Code Style

• Follow PEP 8 guidelines
• Maximum line length: 120 characters
• Use ruff for linting and formatting
• See CODESTYLE.md for detailed style guidelines

Development Workflow

Making Changes

1. Before starting:

   • Ensure development environment is initialised: make init
   • Understand the existing code structure

2. During development:

   • Write tests for new functionality
   • Update type hints as needed
   • Add docstrings following Google style

3. Before committing:

   • Format code: make format
   • Run linter: make lint
   • Run type checker: make typecheck
   • Run tests: make test
   • Or run all checks: make build

Testing

• Write tests using pytest
• Place tests in tests/ directory
• Mirror source structure in test files
• Test both success and failure cases
• Aim for high coverage (>80%)