writing-extensions

Writing a gerrit-mcp-server Extension

Extensions register new MCP tools inside the running gerrit-mcp-server process via the gerrit_mcp_server.extensions entry-point group. They share the server's auth, config, and HTTP machinery through the stable ExtensionContext API.

1. Package layout

Each extension is a standalone Python package:

myext/
├── __init__.py          # empty
├── extension.py         # defines register(ctx)
└── pyproject.toml       # declares the entry point

This is a flat layout (package files alongside pyproject.toml rather than in a src/myext/ subdirectory). It requires an explicit package-dir in pyproject.toml — see section 8. Without it, setuptools looks for a ./myext/ subdirectory and the build fails with package directory 'myext' does not exist.

If the extension is a workspace member of a uv workspace, it lives at the repo root alongside other workspace members.

2. The register(ctx) contract

extension.py must export a top-level register(ctx: ExtensionContext) -> None. The server calls it once at startup.

from gerrit_mcp_server.extensions import ExtensionContext

def register(ctx: ExtensionContext) -> None:
    """Register all tools for this extension."""

    @ctx.mcp.tool()
    async def my_tool(change_id: str, gerrit_base_url: str = None) -> str:
        """One-line description shown in the MCP tool list."""
        base_url = ctx.get_base_url(gerrit_base_url)
        result = await ctx.run_curl([f"{base_url}/changes/{change_id}"], base_url)
        return result

All tools must be async def. ctx.mcp.tool() is a FastMCP decorator — register as many tools as needed.

3. Structured return types

All tools should declare a TypedDict return type rather than manually building [{"type": "text", "text": ...}] content blocks. The MCP SDK auto-generates a JSON output_schema from the annotation and produces both structured content (for clients that support it) and a text fallback (for those that don't).