How disler/aider-mcp-server works
Project type and purpose
• This is a backend micro-service (“Aider MCP Server”) implementing the Model Context Protocol (MCP) over stdio.
• Its purpose is to receive AI-coding requests from a client (Claude Code), offload them to the open-source Aider assistant, and return diffs or model lists.
File structure
• Top-level directories:
• ai_docs & specs: documentation and design notes (not part of runtime)
• src/aider_mcp_server: the main application
• .claude and .mcp.json: client config for integration
• Inside src/aider_mcp_server:
• __main__.py: CLI entrypoint (uv run aider-mcp-server …)
• server.py: MCP server orchestration (initialize, register tools, handle requests)
• atoms/: pure functional components split into:
– data_types.py: Pydantic models for requests & responses
– logging.py: centralized logger setup
– utils.py: shared constants (default models, etc.)
– tools/: individual tool implementations (aider_ai_code.py, aider_list_models.py)
• tests/: mirrors atoms/ for unit tests of each component
Key insights from the README
• The server receives MCP-formatted JSON, routes it to “tools” in the atoms layer, then returns JSON responses.
• Two core tools:
• aider_ai_code: invokes Aider to apply code changes, returns diff
• list_models: queries available AI models
• Environment-driven configuration (.env, .mcp.json) supplies API keys and working directories.
• Emphasis on layering: Server layer delegates to Atom layer (tools, utils, models).
a. Main Components
• MCP Client (Claude Code)
• a) CLI Entrypoint (__main__.py)
– Parses flags (editor model, working dir), launches server
• b) MCP Server Core (server.py)
– STDIO transport, request dispatcher, tool registry
• c) Atoms Layer
– Data Types (Pydantic schemas)
– Utils & Logging
– Tools:
· Aider AI Code tool
· List Models tool
• d) External Integrations
– Aider (CLI or Python API)
– AI Providers (e.g., Gemini, OpenAI, Anthropic)
• e) Configuration
– .env file, .mcp.json, pyproject.toml
b. Relationships & Interactions
1. Claude Code → STDIO → CLI Entrypoint
2. Entrypoint → instantiate MCP Server
3. MCP Server → parse JSON → dispatch to appropriate Atom tool
4. Tool Logic (in atoms/tools) → call out to Aider CLI or API → retrieve output
5. Server → wrap tool output into MCP-compliant JSON → STDIO → Claude Code
6. All layers log via atoms/logging and validate via atoms/data_types
c. Architectural Patterns & Principles
• Layered / Hexagonal architecture: server core is the “inside,” I/O (CLI, STDIO) is the “outside.”
• Pure functional components for tools; side effects confined to tool boundaries.
• Dependency injection of models and API keys via env vars.
• Use of Pydantic for schema validation enforces strong typing.
d. Key Technologies & Frameworks
• Python 3.x (via .python-version)
• uv (micro-frontend to run CLI and tests)
• Pydantic (data validation)
• pytest for tests
• Aider (external AI coding assistant)
• AI model providers: Gemini, OpenAI, Anthropic