aida-mcp 0.1.2.dev1

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

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 "	The assistant calls the right tool automatically.

Need the full local setup (Node, uv, multi-repo tips, troubleshooting)? See 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 to keep this README short. If you only need the external command contract and config shape, start with docs/external-validation-interface.md. Rules retrieval details live in 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).
3. In the editor, ask: “run validation” or “validate microservices/gen-ai”. The assistant calls validate(scope=..., focus_paths=...).
4. Routing and the exact commands run are repo-owned via .aida/*.

From the terminal

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

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:

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: environment prep, Cursor integration, node/uv requirements, manual overrides, and how to add new tools/rules.
• 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.