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

```bash
uv tool install aida-mcp
```

Pip fallback:

```bash
pip install aida-mcp
```

Prerelease/dev builds:

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

## Quick Start

From the repository you want to onboard:

```bash
aida-mcp init
```

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

To run the server manually:

```bash
aida-mcp
```

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

Experimental HTTP mode is also available:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

Typical CLI execution:

```bash
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:

```bash
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:

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

```yaml
# .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
```

```yaml
# .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.
