# AIDA (AI Developer Assistant)

FastMCP server (`aida-mcp`) that exposes GoodData's **unified validation** workflow (plus GitHub helpers and rules retrieval) over the MCP protocol. Use it from Cursor, Claude Code, JetBrains AI, or the CLI to run repo-configured lint/type/test/codegen pipelines without memorizing each project's workflow.

---

## TL;DR – Getting Started

### Cursor / Claude Code / JetBrains AI
| Step | Command | Notes |
| --- | --- | --- |
| 1 | `cd packages/aida-mcp && make install` | Installs/updates the **packaged** MCP server (wheel) only. |
| 2 | `aida-mcp init` (run in your repo root) | Writes **repo-local** MCP config stubs (e.g. `.cursor/mcp.json`, `.mcp.json`) and onboarding files. Add `--vendor-rules` to enable vendor/example embedded rules. |
| 3 | Restart IDE / Agent | Tools appear as `aida` in the MCP panel. |
| 4 | Ask your assistant to "validate <service>" | The assistant calls the right tool automatically. |

Need the full local setup (Node, uv, multi-repo tips, troubleshooting)? See [CONTRIBUTING.md](CONTRIBUTING.md).

---

## Repo Config Files

AIDA reads repo-owned policy and routing from `.aida/`:
- `change_domains.yaml`
- `validation_policy.yaml`
- `validation_registry.yaml`
- `git_policy.yaml` (commit/PR/workflow knobs for git-related tools)
- `rules/**/*.mdc`

`aida-mcp init` bootstraps these files when missing.

---

## Tool Overview

| Tool | Highlights |
| --- | --- |
| `validate` | Unified validation tool. Computes scope (`pre_commit` / `pre_push`), routes via `.aida/*`, executes registry-defined commands with streaming progress. |
| `get_rules` | Retrieves relevant rules for the current task (hybrid lexical + embeddings), with transparent scoring/debug output. |
| `github_ci_errors` | Fetch size-capped CI failures for a PR (errors-only by default). |
| `github_comments` | List/reply/resolve PR review threads (non-interactive). |

**Progress Tracking**: `validate` streams real-time progress updates to Cursor using combined `ctx.report_progress()` + `ctx.info()` events. External validators can emit `AIDA_EVENT {json}` lines for richer progress while keeping full logs in artifacts.

Detailed behavior (step descriptions, parameters, and usage snippets) now lives in [docs/validation-tools.md](docs/validation-tools.md) to keep this README short.
If you only need the external command contract and config shape, start with [docs/external-validation-interface.md](docs/external-validation-interface.md).
Rules retrieval details live in [docs/rules-retrieval.md](docs/rules-retrieval.md).

---

## Architecture at a Glance

```
packages/aida-mcp/
├── src/
│   └── app/
│       ├── server/              # FastMCP entrypoint + tool registration
│       ├── tools/
│       │   ├── core/            # shared primitives (registry, change classifier, external tool helpers)
│       │   └── validate/        # unified validate engine (policy + external command execution)
│       └── utils/               # command runner, config loader, junit parsing, progress, timing, etc.
├── config/                      # bundled defaults (registry, tool configs)
├── docs/                        # detailed validation tool documentation
├── tests/                       # unit + integration suites
└── CONTRIBUTING.md              # setup, workflows, troubleshooting
```

Validation design:
- AIDA is language-agnostic for validation command execution.
- Validation commands are repo-owned external executables configured in `.aida/validation_registry.yaml`.
- Output processors remain built-in and reusable inside `packages/aida-mcp`.

---

## Using the Tools

### From Cursor / Claude
1. Install/update the MCP server via `cd packages/aida-mcp && make install`.
2. Onboard the repo you want to use AIDA in via `aida-mcp init` (run in the repo root).
2. In the editor, ask: “run validation” or “validate `microservices/gen-ai`”. The assistant calls `validate(scope=..., focus_paths=...)`.
3. Routing and the exact commands run are repo-owned via `.aida/*`.

### From the terminal

```bash
cd packages/aida-mcp
aida-mcp  # launches stdio server manually (once installed via uv tool)
```

Commit helper (enforces footer policy and 70-char subject limit):

```bash
aida-mcp commit \
  --type chore \
  --scope aida \
  --title "add commit helper command" \
  --body "Enforce risk footer ordering and metadata trailers." \
  --jira DX-123 \
  --risk nonprod
```

Prefer running the command directly in this shape; do not probe with `aida-mcp commit --help` unless troubleshooting.

Optional metadata in the footer block:
- `--co-authored-by "Name <email>"` (repeatable)
- `--ai-share actor=percent` (repeatable, must sum to 100)
- `--ai-share-auto <actor>` for deterministic `<actor>=100` without guessing (policy-gated)
- multiline body support:
  - `--body-file /path/to/body.txt`
  - `--body-stdin` (pipe or heredoc)
  - `--body-line ...` (repeatable)

`aida-mcp commit` policy values (for example title length, allowed `risk:` values, and optional required trailers) are configurable via `.aida/git_policy.yaml`.
`Co-authored-by` is explicit-only: pass `--co-authored-by` when available; if omitted, no co-author trailer is added.

Validation CLI shortcuts still live in the repo root:

```bash
make format-fix lint-fix
make types
make test
make validate       # fast default (format/lint/types + unit tests)
make validate-all   # includes integration tests (slow)
```

---

## Troubleshooting & Workflow Guides

Rather than duplicating multiple pages of instructions here, refer to:
- [CONTRIBUTING.md](CONTRIBUTING.md): environment prep, Cursor integration, node/uv requirements, manual overrides, and how to add new tools/rules.
- [docs/validation-tools.md](docs/validation-tools.md): deep dive into each tool’s steps, parameters, and best practices.
- Developer onboarding docs under `docs/developer/` for broader GoodData setup.

---

## FAQ

**Why a single `validate` tool?**
Repo-owned routing (`.aida/*`) lets `aida-mcp` live in a separate repo while still executing GoodData-specific validations (often via external wrappers) with streaming progress.

**Can I add custom output processors as external commands?**
Not in unified validate today. Processors are built-in only; for custom behavior, either emit JSON consumed by `external_json` or add a new reusable built-in processor in `packages/aida-mcp`.

**Can I run Docker/OpenAPI without rewriting commands?**
Yes—when the repo’s `.aida/validation_policy.yaml` routes those steps. Add dedicated pipelines/commands for `docker`/`openapi` when needed.

**What happens if the MCP client disconnects during validation?**
The server gracefully handles invalid or closed MCP contexts. Progress updates are silently skipped if the context becomes unavailable, preventing server crashes. Validation continues to completion and returns results normally.

**What if Python tests fail with "duplicate file name metadata.proto"?**
The Python validator automatically detects this common issue (stale protobuf artifacts in `.venv`) and runs `make ultra-clean` + `make dev` to rebuild the environment, then retries the test step. This recovery is transparent and only triggers when needed.

**How do I extend validation routing?**
Update `.aida/change_domains.yaml` + `.aida/validation_policy.yaml`, and add commands in `.aida/validation_registry.yaml` as needed.

---

## Upgrading / breaking changes

When AIDA source changes in a way that affects the MCP server executable, the installed tool set, or the MCP tool schema, you must **reinstall/refresh the MCP server setup** in your client.

- **Action**: rerun `cd packages/aida-mcp && make install`, then restart/reload your client.
- **Why**: clients cache the MCP server command + environment from MCP config files. Reinstall ensures the client points at the current `aida-mcp` executable and tool definitions.

---

## Repository setup

This repository is AIDA-ready (repo-owned `.aida/` and repo-local MCP stubs are committed), so you can install the tool and start using it immediately.

---

Happy validating! Let the assistants run the noisy commands so you can stay focused on the code. For contributions, open an issue or follow the checklist in [CONTRIBUTING.md](CONTRIBUTING.md).
