# disler/aider-mcp-server architecture

> Architecture diagram of the GitHub repository disler/aider-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/disler/aider-mcp-server
- Repository: https://github.com/disler/aider-mcp-server

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Client["Claude Code (MCP Client)"]:::client
    end

    subgraph "Application Layer"
        CLI["CLI Entrypoint (__main__.py)"]:::application
        Server["MCP Server Core (server.py)"]:::application

        subgraph "Atoms Layer"
            DataTypes["Data Types (data_types.py)"]:::application
            Logging["Logging Setup (logging.py)"]:::application
            Utils["Utils & Constants (utils.py)"]:::application

            subgraph "Tools"
                AIcode["Aider AI Code Tool"]:::tools
                ListModels["List Models Tool"]:::tools
            end
        end

        Config["Configuration (.env, .mcp.json)"]:::application
    end

    subgraph "Infrastructure Layer"
        AiderProc["Aider Process/API"]:::infra
        AIProviders["AI Model Providers"]:::infra
    end

    Client -->|STDIO JSON-RPC| CLI
    CLI -->|instantiate MCP Server| Server
    Server -->|"validate/serialize JSON"| DataTypes
    Server -.->|"logging events"| Logging
    Server -.->|"shared constants"| Utils
    Server -->|dispatch to tool| AIcode
    Server -->|dispatch to tool| ListModels
    AIcode -->|invoke CLI/API| AiderProc
    ListModels -->|invoke API| AIProviders
    AiderProc -->|diffs/models output| Server
    AIProviders -->|model list output| Server
    Server -->|STDIO JSON-RPC| Client
    Config -.->|env vars & settings| CLI
    Config -.->|env vars & settings| Server

    %% Click Events
    click CLI "https://github.com/disler/aider-mcp-server/blob/main/src/aider_mcp_server/__main__.py"
    click Server "https://github.com/disler/aider-mcp-server/blob/main/src/aider_mcp_server/server.py"
    click DataTypes "https://github.com/disler/aider-mcp-server/blob/main/src/aider_mcp_server/atoms/data_types.py"
    click Logging "https://github.com/disler/aider-mcp-server/blob/main/src/aider_mcp_server/atoms/logging.py"
    click Utils "https://github.com/disler/aider-mcp-server/blob/main/src/aider_mcp_server/atoms/utils.py"
    click AIcode "https://github.com/disler/aider-mcp-server/blob/main/src/aider_mcp_server/atoms/tools/aider_ai_code.py"
    click ListModels "https://github.com/disler/aider-mcp-server/blob/main/src/aider_mcp_server/atoms/tools/aider_list_models.py"
    click Logging "https://github.com/disler/aider-mcp-server/blob/main/src/aider_mcp_server/tests/atoms/test_logging.py"
    click AIcode "https://github.com/disler/aider-mcp-server/blob/main/src/aider_mcp_server/tests/atoms/tools/test_aider_ai_code.py"
    click ListModels "https://github.com/disler/aider-mcp-server/blob/main/src/aider_mcp_server/tests/atoms/tools/test_aider_list_models.py"
    click Config "https://github.com/disler/aider-mcp-server/blob/main/.env.sample"
    click Config "https://github.com/disler/aider-mcp-server/blob/main/.mcp.json"
    click ai_docs "https://github.com/disler/aider-mcp-server/blob/main/ai_docs/just-prompt-example-mcp-server.xml"
    click ai_docs "https://github.com/disler/aider-mcp-server/blob/main/ai_docs/programmable-aider-documentation.md"
    click specs "https://github.com/disler/aider-mcp-server/blob/main/specs/init-aider-mcp-exp.md"

    %% Styles
    classDef client fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef application fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef infra fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef tools fill:#a5d6a7,stroke:#333,stroke-width:1px
```
