aida-mcp 0.4.1.dev4

AIDA MCP server - Developer actions (lint, test, typecheck) for monorepos

AIDA MCP

aida-mcp is the MCP server and CLI package for AIDA. It gives AI assistants a repository-owned workflow layer for guidance retrieval, validation, and Git/GitHub operations.

Use this package when you want assistant behavior controlled by versioned repository policy instead of large client-specific prompts.

Why This Package Exists

Most coding assistants are good at generating text and code, but weak at staying inside repository-specific workflow constraints. aida-mcp closes that gap by moving the control plane into repository-owned files under .aida/ and exposing the right operations through MCP and CLI.

That means teams can:

• keep rules, validation routing, and Git policy in version control
• share the same behavior across Cursor, Claude Code, OpenAI Codex, JetBrains AI Chat, and Junie — adding another MCP-compatible client is straightforward because AIDA builds on the open MCP standard
• evolve onboarding and workflow behavior without rewriting client prompts
• give less technical contributors safer defaults for validation, commits, PRs, and review follow-up

What You Get

• get_rules: hybrid retrieval over embedded and repository-owned rules, with compact responses, provenance, and session-aware delta mode
• validate_command: MCP planner for repository-defined validation routing across lint, format, types, tests, codegen, and other project-specific checks
• aida-mcp validate: CLI executor for the planned validation commands with streamed output
• commit_command: executes a policy-compliant git commit server-side and returns structured results (sha, subject, files changed)
• pr_command: executes a policy-compliant gh pr create server-side and returns structured results (PR URL, number)
• github_comments: lists, replies to, and resolves GitHub PR review threads
• CLI commands for bootstrap, migration, health checks, policy checks, template previews, alias installation, and policy-aware commits
• unified rule-selection controls for embedded and repo-owned rules, including shared defaults plus per-user local overrides

Design Principles

• Client-agnostic: package the workflow logic once and reuse it across MCP-capable assistants
• Repository-owned policy: keep operational behavior in .aida/ instead of hiding it in client prompts
• Extensible by default: add new validation domains, pipelines, commands, and rules without forking the package
• Workflow-oriented: support more than coding, including onboarding, validation, commit/PR policy, review response, and CI triage

Requirements

• Python >=3.12,<3.15
• An MCP-compatible client
• A repository where you want to enable AIDA

Install from PyPI

Recommended:

uv tool install aida-mcp

Pip fallback:

pip install aida-mcp

Prerelease/dev builds:

uv tool install --prerelease allow aida-mcp
pip install --pre aida-mcp

Quick Start

From the repository you want to onboard:

aida-mcp init

Then reload your MCP client and let it discover the aida server and tools.

To run the server manually:

aida-mcp

In most environments the client launches it for you, so manual startup is mainly for troubleshooting.

Experimental HTTP mode is also available:

aida-mcp serve-http --path /mcp

This is an opt-in alternative to stdio for local testing. Stdio remains the default and recommended setup.

Onboarding Flow

The practical onboarding path is:

1. Install aida-mcp.
2. Run aida-mcp init in the target repository root.
3. Reload the client so MCP tools are discovered.
4. Ask the assistant to call get_rules for a concrete task.
5. Ask it to call validate_command(...) for your current changes, then run the returned aida-mcp validate ... command.
6. Refine repository-owned rules and validation wiring under .aida/ as needed.

For repositories that already contain assistant-specific rules, bootstrap files, or older AIDA material:

• aida-mcp migrate is the onboarding normalization/upgrade path: it backs up old client/bootstrap files, updates repo config versions, reconciles missing/default config keys, and rewrites current stubs
• aida-mcp doctor is the onboarding health check and also works as a standalone repository audit before, during, or after onboarding
• aida-mcp doctor --auto-fix applies only safe semantic config fixes where supported, then re-runs the audit

Current AIDA config files are versioned. That gives you an upgrade path where doctor and migrate can distinguish outdated config from missing config instead of treating every repo the same.

If onboarding is still incomplete after deterministic setup, get_rules returns an onboarding_incomplete response for normal tasks. In that case, ask the assistant to call get_rules again with an onboarding-focused query such as finalize onboarding after aida-mcp migrate.

What init Writes

aida-mcp init bootstraps both repository policy files and client bootstrap files.

Repository-owned AIDA config:

• .aida/change_domains.yaml
• .aida/validation_policy.yaml
• .aida/validation_registry.yaml
• .aida/rules_selection.yaml
• .aida/.gitignore containing rules_selection.local.yaml
• .aida/rules/
• optional: .aida/git_policy.yaml
• optional: .aida/templates/commit-message.txt, .aida/templates/pr-title.txt, .aida/templates/pr-body.md

Minimal assistant bootstrap files:

• .cursor/rules/aida.mdc
• .claude/CLAUDE.md
• AGENTS.md
• .aiassistant/rules/aida.md
• .junie/guidelines.md

These bootstrap files stay intentionally small. Detailed task guidance should come from get_rules, not from copying large static instructions into every client file.

MCP Client Setup

init writes repository-local MCP config for clients that support it and merges with existing config where possible.

Project-local targets:

• Cursor: .cursor/mcp.json
• Claude Code: .mcp.json
• OpenAI Codex: .codex/config.toml

By default, these repository-local configs are root-agnostic and rely on native MCP roots from the client. That lets one installed AIDA server entry work across multiple repositories without pinning AIDA_WORKSPACE_ROOT in the generated config.

You can also install or refresh MCP wiring explicitly:

aida-mcp install-mcp --target cursor
aida-mcp install-mcp --target claude
aida-mcp install-mcp --target codex

Experimental HTTP wiring can be written explicitly with:

aida-mcp init --http
aida-mcp install-mcp --target codex --http

This writes URL-based MCP config instead of stdio command entries. It is intentionally experimental. The generated HTTP config uses http://localhost:9910/mcp by default. If you need a different port, pass --http-port, for example aida-mcp init --http --http-port 9911 or aida-mcp install-mcp --target codex --http --http-port 9911. The generated HTTP config does not inject AIDA_WORKSPACE_ROOT; workspace selection is expected to come from native MCP roots.

Recommended conventions:

• Use 9910 as the shared default for normal repository usage.
• If you are actively developing packages/aida-mcp and also using HTTP MCP in other repositories at the same time, use a dedicated override such as 9911 in this repository so AIDA changes do not disrupt the default server used elsewhere.
• Example for AIDA contributors:

aida-mcp init --http --http-port 9911
aida-mcp install-mcp --target codex --http --http-port 9911
aida-mcp serve-http --port 9911

Some clients currently require global MCP config:

aida-mcp install-mcp --global --target jetbrains
aida-mcp install-mcp --global --target junie

Current global locations:

• JetBrains AI Chat: ~/.ai/mcp/mcp.json
• Junie: ~/.junie/mcp/mcp.json

If you need to pin AIDA to one repository, use --workspace-root or set AIDA_WORKSPACE_ROOT manually. That override is optional and mainly useful for single-repo or non-standard client setups.

Rule Retrieval Model

get_rules is the central mechanism for dynamic guidance.

How it works:

• repository rules live in .aida/rules/**
• embedded defaults and profiles come from the package
• selection is controlled by .aida/rules_selection.yaml
• optional per-user opt-out lives in .aida/rules_selection.local.yaml
• assistants should call get_rules at task start and when task scope changes significantly
• commit/push-only flows should use commit_command / pr_command instead of refreshing get_rules

Important behavior:

• session_id is required and enables delta mode across the same chat
• normal responses are optimized for use, returning context plus concise reporting
• partially onboarded repositories block normal retrieval and return onboarding_incomplete
• warmup_embeddings exists only for one-time model download/index warmup when requested

Default rule-selection semantics:

• embedded rules: core/** enabled by default
• repository rules: .aida/rules/** enabled by default (repo: all)

That default keeps local rule authoring intuitive while still making embedded overlays opt-in.

Validation Model

Validation is split into an MCP planner and a CLI executor.

Repository-owned config still controls the routing:

• .aida/change_domains.yaml maps changed files to domains and roots
• .aida/validation_policy.yaml maps domains to pipelines
• .aida/validation_registry.yaml defines commands and processors

Common MCP planning calls:

validate_command(scope="pre_commit")
validate_command(scope="pre_push")
validate_command(scope="pre_commit", focus_paths=["path/to/component"])

Typical CLI execution:

aida-mcp validate --scope pre_commit
aida-mcp validate --scope pre_push --upstream-ref origin/main
aida-mcp validate --scope pre_commit --focus-path path/to/component

Useful characteristics:

• scope is high-level; routing details stay repo-owned
• focus_paths narrows validation to specific paths/components
• explain=True includes routing details in the planner response
• pre_commit can include commit_guidance that points assistants to commit_command
• pre_push can include commit-policy checks for the branch range being validated

The package does not hardcode project-specific validation logic. Instead, repositories own the external commands and decide whether those commands run in check mode, autofix mode, or a fix-then-validate flow.

Policy-Aware Git and PR Workflows

aida-mcp now covers more of the delivery workflow than validation alone.

Commit flow:

• CLI: aida-mcp commit
• MCP: commit_command
• shared source of truth: .aida/git_policy.yaml plus optional commit templates

Important behavior:

• pre-commit validation runs before the commit
• when validation modifies files, the commit flow continues with automatic staging of current changes
• the commit is executed server-side following repository footer and template policy
• the MCP tool returns structured results so assistants never need to run git commit themselves

Useful CLI commands:

aida-mcp commit --type feat --title "add policy-aware release workflow" --risk low
aida-mcp check-commit-policy --from-ref origin/main --to-ref HEAD
aida-mcp preview-commit-template --title "example" --type docs --risk low

PR flow:

• MCP: pr_command
• CLI: aida-mcp preview-pr-template, aida-mcp check-pr-policy
• shared source of truth: .aida/git_policy.yaml and .aida/templates/

The MCP tool executes gh pr create server-side and returns the PR URL and number, so assistants never need to construct or run the command themselves.

GitHub Workflow Tools

The package also exposes GitHub-focused MCP helpers:

• github_comments for listing review threads, replying in-thread, and resolving discussions

CI triage is handled through gh CLI workflow guidance returned by get_rules.

Typical Assistant Workflow

1. Run aida-mcp init once in the repository.
2. Ask the assistant to call get_rules for the concrete task.
3. Implement the change.
4. Ask the assistant to call validate_command(...) and run the returned aida-mcp validate ... command.
5. Use commit_command or aida-mcp commit for the final commit.
6. Use pr_command, github_comments, and gh CLI CI triage during PR preparation and review follow-up.

CLI Surface

Main lifecycle commands:

• aida-mcp init
• aida-mcp update-rules
• aida-mcp migrate
• aida-mcp doctor
• aida-mcp install-mcp
• aida-mcp serve-http
• aida-mcp validate
• aida-mcp validate-python

Git/policy commands:

• aida-mcp commit
• aida-mcp check-commit-policy
• aida-mcp check-pr-policy
• aida-mcp preview-commit-template
• aida-mcp preview-pr-template

Convenience commands:

• aida-mcp alias status
• aida-mcp alias install
• aida-mcp alias uninstall

Configure in Your Repository

To make AIDA fully operational in a repository:

1. Install aida-mcp.
2. Run aida-mcp init.
3. Review .aida/rules/** and .aida/*.yaml.
4. Reload your client.
5. Verify with:
   • aida-mcp doctor
   • an assistant call to get_rules
   • an assistant call to validate_command

If doctor passes and validate_command resolves repository-specific commands, onboarding is in good shape.

Minimal Repository Wiring Sketch

init gives you a starting point, but the core ownership model is:

# .aida/change_domains.yaml
domains:
  - id: python_service
    match_globs:
      - "services/*/**/*.py"
      - "services/*/pyproject.toml"
    root_depth: 2

# .aida/validation_policy.yaml
validation_policy:
  routes:
    - domain: python_service
      pipeline: python-default
  pipelines:
    python-default:
      steps:
        - command_id: python.validate.engine
          processor_id: external_json

# .aida/validation_registry.yaml
registry:
  commands:
    python.validate.engine:
      argv:
        - "bash"
        - "{workspace_root}/scripts/validate_python.sh"
        - "--project-path"
        - "{workspace_root}/{root}"
      cwd: "{workspace_root}"
      timeout_sec: 3600
  processors: {}

That is the main contract: the package owns orchestration and repositories own policy plus executable validation commands.

Source Repository Docs

If you are working from the source repository, additional long-form docs live in:

• CONTRIBUTING.md
• docs/validation-tools.md
• docs/external-validation-interface.md
• ../../docs/aida/configuring-a-repository.md
• ../../docs/aida/cli-usage.md

Roadmap: Adaptive Quality Loops

Auto-tuning for rule behavior is partially available and expected to expand. The target model is eval-driven improvement of retrieval and routing quality while preserving repository-owned controls.

Planned direction includes:

• evaluating assistant outcomes against explicit quality signals
• feeding observability and trace data into tuning workflows
• supporting optional telemetry backends such as Langfuse

The package is meant to keep those feedback loops repository-visible and reviewable rather than hidden inside the client.

Opt-Out

To opt out for a specific client:

1. disable or remove that client’s AIDA MCP wiring
2. remove the corresponding bootstrap instruction file for that client scope

That disables AIDA cleanly while leaving normal repository CI and rulesets untouched.