pal-e-docs

Architecture: MCP Tools Layer

arch-mcp-tools Doc

architecture active
Project

What it covers

The MCP tools layer across all MCP servers — the tool definitions that Claude Code sessions and agents use to interact with external systems. Distinct from the MCP server infrastructure (arch:mcp) which covers the server process lifecycle.

Components

MCP Server Repo Tool Module
forgejo <code>ldraney/forgejo-mcp</code> <code>src/forgejo_mcp/tools/workflows.py</code>
pal-e-docs <code>ldraney/pal-e-docs</code> Django MCP app
woodpecker <code>ldraney/woodpecker-mcp</code> Woodpecker CI tools

Pattern

Each MCP tool follows the same shape: @mcp.tool() decorator, Annotated params with Field descriptions, JSON return, _error_response on exception. Tools are the agent-facing API — they determine what agents can and cannot do with external systems.

Why it matters

Missing tools force agents into unreliable fallbacks (e.g. curl with tokens from .mcp.json that aren't in the shell env). Every operation an agent needs must be exposed as an MCP tool.
  • arch-mcp — MCP server infrastructure (process lifecycle, not tools)
  • convention-architecture-ids — defines arch:mcp-tools label