aida-mcp 0.4.0

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

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:

uv tool install aida-mcp

Pip fallback:

pip install aida-mcp

Prerelease/dev builds (optional):

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

pip install --pre aida-mcp

Basic Usage

Initialize AIDA files in your repository root:

aida-mcp init

Run the MCP server:

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:

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:

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:

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:

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.