# AIDA MCP

`aida-mcp` is the MCP server and CLI package for AIDA (**AI Developer Assistant**).
It provides repository-owned guidance retrieval and validation orchestration for AI-assisted software development.

Use this package when you want assistant behavior controlled by repository policy instead of tool-specific prompt configuration.

## What You Get

- `get_rules`: hybrid retrieval over repository-owned rules, with dependency-aware composition.
- `validate`: repository-defined validation routing across lint, tests, type checks, codegen, and related tasks.
- GitHub helpers: inspect CI failures and review-comment workflows.
- CLI commands for setup, MCP wiring, diagnostics, and policy-aware commit workflow.
- Unified rule-selection controls (shared + local) for embedded and repo-owned rules.

## Design Principles

- **Client-agnostic**: works with MCP-compatible assistants.
- **Repository-owned policy**: behavior is version-controlled in `.aida/`.
- **Extensible by default**: add domains, pipelines, commands, and rules without forking client prompts.
- **Workflow-oriented**: supports more than code generation (including validation and Git/GitHub operations).

## Roadmap: Adaptive Quality Loops

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

Planned direction includes:

- plugging in eval frameworks to score assistant outcomes (for example DSPy-style mechanisms)
- connecting observability traces and feedback signals into tuning workflows
- supporting production-grade telemetry backends (for example Langfuse) as optional integrations

In all cases, observability and tuning are intended to inform policy, not bypass it.

## Requirements

- Python `>=3.12,<3.15`
- An MCP-compatible client (for example Cursor, Claude Code, OpenAI Codex, or JetBrains AI)
- A target repository where you want to use AIDA

## Install from PyPI

Recommended:

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

Pip fallback:

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

Prerelease/dev builds (optional):

```bash
uv tool install --prerelease allow aida-mcp
# or pin an exact dev build:
uv tool install "aida-mcp==0.2.0.dev5"
```

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

## Basic Usage

Initialize AIDA files in your repository root:

```bash
aida-mcp init
```

Run the MCP server:

```bash
aida-mcp
```

For clients that support project-local config, `aida-mcp init` auto-wires MCP config and
merges into existing `mcp.json` files without removing other MCP servers.
In most cases, you only need to reload/restart the client.
`init` also writes minimal project guidance files:
- `.cursor/rules/aida.mdc`
- `.claude/CLAUDE.md`
- `AGENTS.md`
- `.aiassistant/rules/aida.md`
- `.junie/guidelines.md`

`init` also writes rule selection defaults:

- `.aida/rules_selection.yaml` (tracked)
- `.aida/.gitignore` containing `rules_selection.local.yaml`

## Typical Flow

1. Run `aida-mcp init` in a target repository.
2. Let assistants call `get_rules` at task start and on major workflow pivots.
3. Call `get_rules` again before commit/push workflow with query like `How to commit/push`.
4. Let assistants run `validate` before commit/push.
5. Evolve `.aida/rules/**` and `.aida/*.yaml` as team policy changes.
6. Use Git/GitHub helpers to support delivery workflows and less technical users.
7. Optionally add eval/observability loops to improve guidance quality over time.

## Rule Selection and Embedded Profiles

Embedded rules are now organized into:

- `core/**`: safe defaults enabled by default
- `profiles/**`: optional overlays (languages/build/framework/workflow)

Selection is repository-owned and layered:

1. Shared `.aida/rules_selection.yaml`
2. Optional local `.aida/rules_selection.local.yaml` (gitignored; user opt-out)

Default semantics:

- `defaults.embedded: core_only`
- `defaults.repo: all`

This keeps local authoring intuitive: new files under `.aida/rules/**` are active without extra allowlisting.

## Configure in Your Repository (Full Checklist)

To make AIDA fully operational in a repository, you need both MCP wiring and
repository-owned policy files.

1. Install `aida-mcp` (from PyPI).
2. In your target repository root, run:

```bash
aida-mcp init
```

3. Ensure the repository now contains the `.aida/` configuration files:
   - `.aida/change_domains.yaml`
   - `.aida/validation_policy.yaml`
   - `.aida/validation_registry.yaml`
   - `.aida/rules_selection.yaml` (shared rule-selection defaults)
   - `.aida/.gitignore` (contains `rules_selection.local.yaml` for local overrides)
   - `.aida/rules/` (rule files used by `get_rules`)
   - optional: `.aida/git_policy.yaml` (commit/PR policy)
4. Confirm project-local MCP config files exist:
   - `.cursor/mcp.json` (Cursor)
   - `.mcp.json` (Claude Code)
   - `.codex/config.toml` (OpenAI Codex)
   - `AGENTS.md` (shared project workflow instructions)
   - `.aiassistant/rules/aida.md` (IntelliJ AI Assistant / AI Chat rule file)
   - `.junie/guidelines.md` (Junie guideline file)
   - JetBrains AI Chat / Junie currently ignore repository-local `mcp.json`
     and use global files instead.
5. Reload/restart your client so the `aida` MCP tools are discovered.
6. To (re)apply project-local MCP config explicitly:

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

`init` and project-local `install-mcp` both merge with existing `mcpServers`
entries and preserve non-AIDA servers.

7. If your client does not use project-local MCP config, configure global MCP explicitly:

```bash
aida-mcp install-mcp --global --target <cursor|claude|codex|jetbrains|junie>
```

JetBrains AI Chat writes to `~/.ai/mcp/mcp.json`.
Junie writes to `~/.junie/mcp/mcp.json`.

### What each config area does

- `rules/`: task guidance used by `get_rules`
- `change_domains.yaml`: maps changed files to logical domains
- `validation_policy.yaml`: routes domains/scopes to validation pipelines
- `validation_registry.yaml`: defines executable validation commands
- `git_policy.yaml` (optional): commit/footer and workflow constraints

### Quick verification

After setup:

- run `aida-mcp doctor` in the repository root
- ask your AI client to call `get_rules` for a concrete coding task
- ask it to run `validate` for your current changes

If `doctor` passes and `validate` executes repository-specific commands (not just no-op placeholders), AIDA is configured correctly.

### Optional pre-commit guidance

To include commit workflow hints in `validate(scope="pre_commit")`, enable this in `.aida/git_policy.yaml`:

```yaml
git_policy:
  commit:
    pre_commit_guidance: true
```

When enabled, `validate(pre_commit)` includes `commit_guidance` that points assistants to `aida-mcp commit` with repo policy expectations.

## Opt-out

To opt out for a specific client:

1. Disable/remove that client's AIDA MCP wiring.
2. Remove the client bootstrap instruction file for that client scope.

Repository CI/rulesets still remain your shared safety net.

## Documentation and Support

For implementation and repository-level docs, see:

- repository overview: `../../README.md`
- configuration guide: `../../docs/aida/configuring-a-repository.md`
- CLI usage guide: `../../docs/aida/cli-usage.md`
- contributor guide: `../../docs/aida/contributor-guide.md`

## Onboarding Finalization (Client-Agnostic)

After running deterministic setup commands (`aida-mcp init`, optional
`aida-mcp migrate`, and `aida-mcp doctor`), ask your AI client to call
`get_rules` with an onboarding-focused query (for example:
"finalize onboarding after aida-mcp migrate").

`get_rules` can return an embedded onboarding-finalization rule that tells the AI how to:
- refactor/populate `.aida/rules/**`
- fill `.aida/*.yaml` with conservative defaults
- tune `.aida/rules_selection.yaml` with detected embedded profiles
- preserve user-local opt-out through `.aida/.gitignore` + `rules_selection.local.yaml`
- ask focused follow-up questions when details are missing
- run `validate(...)` before considering onboarding complete

If onboarding is incomplete (for example `.aida/rules/` is missing or empty),
normal `get_rules` calls return an `onboarding_incomplete` error and instruct
the AI to request onboarding guidance first.
