Aider MCP Server

The project uses pytest for validation. Every atom must be tested. Run tests for a specific file using:

uv run pytest <path_to_test_file.py>

Note: Tests should not use mocks; they should perform real LLM calls and include failure path testing.

The aider_ai_code tool wraps the code_with_aider functionality.

Workflow:

1. The client sends a request with ai_coding_prompt and relative_editable_files.
2. The server resolves the model (using the request-provided model or the default editor_model).
3. The server executes the Aider command within the validated Git repository directory.
4. The tool returns a JSON object containing:
   • success (boolean): Whether the operation completed successfully.
   • diff (string): The code changes (diff) produced by Aider.

Note: If the tool fails to parse the result from Aider, it returns an error object: {"error": "Failed to process AI coding result"}.

The list_models function allows you to search for available LLM models supported by Aider using a substring match.

Signature: list_models(substring: str) -> List[str]

This function wraps aider.models.fuzzy_match_models(substr: str).

# Example usage concept
models = list_models("openai")
# Returns a list containing models like ['gpt-4o', ...]

The list_models tool returns a list of AI models supported by Aider that match a provided substring.

Parameters:

• substring (string, required): The text to search for within model names.

Returns:

• A list of model name strings (e.g., ["gemini/gemini-1.5-flash", "gemini/gemini-1.5-pro"]).

{
  "name": "list_models",
  "parameters": {
    "substring": "gemini"
  }
}

The serve function is the primary entry point for running the MCP server.

Signature: serve(editor_model: str = DEFAULT_EDITOR_MODEL, current_working_dir: str = ".", architect_model: str = None) -> None

Parameters:

• editor_model: The model used for editing. Defaults to DEFAULT_EDITOR_MODEL (gemini/gemini-2.5-pro-exp-03-25).
• current_working_dir: The directory from which the server operates. Defaults to ".".
• architect_model: The model used for architectural planning. If not provided, architect mode is not used.

from aider_mcp_server.server import serve

# Start the server with custom models
serve(editor_model="gemini/gemini-2.5-pro-exp-03-25", architect_model="gemini/gemini-2.5-pro-exp-03-25")

The code_with_aider function performs a single-shot execution using Aider based on the programmable Aider documentation. It is designed to run in 'no commit' mode to ensure no changes are automatically committed to the codebase.

Signature: code_with_aider(ai_coding_prompt: str, relative_editable_files: List[str], relative_readonly_files: List[str] = []) -> str

Returns:

• 'success'
• 'failure'

# Example usage concept
result = code_with_aider(
    ai_coding_prompt="Implement a new feature",
    relative_editable_files=["src/main.py"],
    relative_readonly_files=["docs/api.md"]
)

The project uses pytest for testing. Note that AI coding tests require a valid Gemini API key set in your .env file.

Run all tests:

uv run pytest

Run specific tests:

• List models tests:

  uv run pytest src/aider_mcp_server/tests/atoms/tools/test_aider_list_models.py

• AI coding tests:

  uv run pytest src/aider_mcp_server/tests/atoms/tools/test_aider_ai_code.py

To validate that the server is working correctly, run the server with the --help flag using uv.

uv run aider-mcp-server --help

The server uses the is_git_repository function to ensure that the provided current_working_dir is a valid Git work tree. It does this by executing git -C <directory> rev-parse --is-inside-work-tree.

If the directory does not exist or is not a Git repository, the server will return an error or raise a ValueError during startup.

# Signature for internal/utility use
tuple[bool, Union[str, None]] = is_git_repository(directory: str)