# AIDA MCP

AIDA gives your AI coding assistant repository-specific rules, validation, and Git workflow guardrails — across any MCP-compatible tool.

Instead of maintaining separate prompt files for each assistant, you configure behavior once in `.aida/` and every tool picks it up.

## What AIDA Does for You

**As a developer**, AIDA works in the background. Your AI assistant automatically:

- Receives project-specific coding rules and conventions when you start a task
- Runs the right linters, formatters, and tests for the files you changed — before you commit
- Creates commits and PRs that follow your team's message format, required trailers, and templates

You don't need to learn new commands. AIDA teaches your assistant your team's workflow.

**As a repo maintainer**, AIDA lets you:

- Define validation pipelines that run automatically on changed files
- Enforce commit message format, risk labels, ticket references
- Write project-specific rules your assistant will follow
- Configure all of this in version-controlled YAML files under `.aida/`

## Install

```bash
uv tool install aida-mcp    # recommended (uv is a fast Python package manager: brew install uv)
pip install aida-mcp         # alternative
```

## Quick Start

### If your repo already has AIDA configured

Just install `aida-mcp` and reload your AI tool. The `.mcp.json` / `.cursor/mcp.json` in the repo tells your tool to connect to AIDA. Everything works automatically.

### If you're setting up AIDA in a new repo

```bash
cd /path/to/your/repo
aida-mcp init
```

This creates `.aida/` config files, MCP wiring, and rule files. Commit the result and reload your AI tool.

For the full setup guide, see [Configuring a Repository](https://github.com/gooddata/gdc-aida/blob/master/docs/aida/configuring-a-repository.md).

## Supported Tools

Cursor, Claude Code, OpenAI Codex, JetBrains AI Chat, and Junie. Any MCP-compatible tool can be added.

## Customizing Behavior

### Preferences

Control how AIDA behaves per-developer via `.aida/preferences.local.yaml` (gitignored):

```yaml
preferences:
  validation:
    pre_commit: ask      # auto | ask | disabled
  commit:
    mode: ask            # auto | ask | disabled
```

Team defaults live in `.aida/preferences.yaml` (checked in).

### Native Mode (No MCP Server)

If you prefer not to run the MCP server, export rules as static files your AI tool reads directly:

```bash
aida-mcp rules export
```

This writes self-contained rule files with your project's conventions, validation commands, and commit templates. Re-run after config changes; `aida-mcp doctor` warns when stale.

## CLI Commands

| Command | Purpose |
|---------|---------|
| `aida-mcp init` | Bootstrap AIDA in a repository |
| `aida-mcp doctor` | Check repository health |
| `aida-mcp migrate` | Upgrade from older AIDA layout |
| `aida-mcp validate --scope pre_commit` | Run validation on changed files |
| `aida-mcp commit --type feat --title "..."` | Policy-compliant commit |
| `aida-mcp rules export` | Export static native rule files |
| `aida-mcp install-mcp --target claude` | Install/refresh MCP wiring |

Full CLI reference: [cli-reference.md](https://github.com/gooddata/gdc-aida/blob/master/docs/aida/cli-reference.md)

## Documentation

- [For Developers](https://github.com/gooddata/gdc-aida/blob/master/docs/aida/for-developers.md) — how AIDA works in your daily workflow
- [Configuring a Repository](https://github.com/gooddata/gdc-aida/blob/master/docs/aida/configuring-a-repository.md) — setup guide for repo maintainers
- [CLI Reference](https://github.com/gooddata/gdc-aida/blob/master/docs/aida/cli-reference.md) — all commands and flags
- [Rules Retrieval](docs/rules-retrieval.md) — how `get_rules` scoring and selection works
- [Validation Tools](docs/validation-tools.md) — planner + executor architecture
- [External Validation Interface](docs/external-validation-interface.md) — wiring custom scripts

## Requirements

- Python ≥3.12, <3.15
- An MCP-compatible AI tool
- A repository you want to configure
