How sengokudaikon/aider-mcp-server works
Project Type and Purpose
• This is an open‑source, Python‑based MCP (Model Context Protocol) server that acts as a protocol adapter between MCP clients (e.g., Claude Desktop, Cursor IDE) and the Aider CLI tool for file editing, code extraction, git status checks, and configuration inspection.
File Structure and Infer Architecture
• Top‑level files:
• Dockerfile, .env.example, example.aider.conf.yml – deployment/config artifacts
• pyproject.toml – Python packaging and dependencies
• src/aider_mcp/
• server.py – MCP protocol handler and main entrypoint
• services/ – modular implementations of individual tools: edit_files, create_files, git_status, extract_code, aider_status, aider_config
• utils/ – shared helpers: configuration loader (.env + YAML), subprocess wrappers (to invoke Aider and Git), logging, error handling
• tests/ – unit tests for the protocol handler and services
Pull Insights from the README
• The server communicates over stdio in MCP protocol mode
• It discovers configuration via .aider.conf.yml and .env files at multiple layers (home, repo root, working dir, custom path)
• It launches the Aider executable (default “aider”) and Git commands via subprocesses
• It can be invoked directly via uvx or installed as a pip package
Main Components
a. External Clients
• Claude Desktop, Cursor IDE, MCP Inspector
• Communicate via stdio (MCP JSON RPC)
b. MCP Server (aider_mcp) – container or process
1) Protocol Handler (server.py)
• Reads/Writes MCP frames over stdio
• Routes incoming requests to tool services
2) Services Layer (services/*.py)
• One module per tool (edit_files, create_files, git_status, extract_code, aider_status, aider_config)
• Each service defines a schema, input validation, business logic orchestration
3) Utils Layer (utils/*.py)
• Config loader: merges .aider.conf.yml and .env from multiple locations
• Subprocess manager: invokes Aider CLI and Git CLI, captures stdout/stderr
• File system helpers, logging, error handling
c. External Systems
• Aider CLI executable (invoked via subprocess)
• Git CLI (invoked via subprocess)
• File system (repository being edited)
• Configuration files (.aider.conf.yml, .env)
Relationships and Data Flow
• Clients → Protocol Handler: incoming MCP requests
• Protocol Handler → Services Layer: route to specific tool
• Services → Utils: load config, run subprocess (Aider/Git), read/write files
• Utils → External Systems: execute Aider CLI, Git CLI, access file system
• Utils results → Services → Protocol Handler → Clients: responses and tool outputs
• Optional branches for uvx/uv launcher layer and MCP Inspector for debugging
Architectural Patterns and Principles
• Layered architecture: Protocol → Services → Utils → External Systems
• Single Responsibility per service module
• Plugin‑style extensibility: adding new tools just means creating new services modules
• Configuration‑first design: multiple config sources with clear override hierarchy
• Process isolation: external Aider and Git run in separate subprocesses
Technologies and Frameworks to Call Out
• Python 3.8+, pyproject.toml (Poetry or PEP 621)
• Model Context Protocol (JSON‑RPC over stdio)
• uv / uvx launcher for zero‑install execution
• Subprocess module for CLI integration
• YAML (.aider.conf.yml) and dotenv for configuration
• Git command‑line integration
• pytest for tests