archai-mcp 0.3.1

Cognitive Middleware for Architecture-Aware AI Coding Agents

archai-mcp

Structural analysis engine for AI coding agents. archai analyzes your repository's architecture and exposes it as MCP tools — no LLM needed, no API keys, zero configuration.

pip install archai-mcp
cd my-project
archai init
opencode .

The agent automatically uses archai's tools to understand your codebase before making changes.

---

Quick Start

# 1. Install
pip install archai-mcp

# 2. Configure in your project
cd /path/to/your/project
archai init
# → Creates .opencode.json with MCP config

# 3. Open in OpenCode
opencode .
# → The agent has archai tools available automatically

That's it. No API keys, no ARCHAI_LLM_MODEL, no .env file.

---

CLI Commands

Command	Description
archai init	Configure the project for OpenCode MCP integration
archai mcp	Start MCP server (stdio, for AI agents)

That's the entire surface. archai is designed to be used by AI agents through MCP, not by humans in a terminal.

---

MCP Tools

archai exposes 3 structural analysis tools for AI agents:

Tool	Description
get_architecture_context	Returns clusters, dependency edges, and file relationships for a query
get_blast_radius	Analyzes the impact of changing a file (dependents, subsystems)
validate_code_change	Returns structural data about proposed changes for the agent to evaluate

How agents use it

User: "Add a login endpoint in the auth module"

Agent:
  1. get_architecture_context("auth", repo_path)
     ← focus cluster, all clusters, dependency edges, file deps
     → Agent's LLM infers: "auth depends on db, API depends on auth"

  2. Writes code respecting inferred architecture

  3. get_blast_radius("src/auth/login.py", repo_path, depth=2)
     ← affected files and subsystems
     → Agent's LLM assesses: "safe change, expected impact"

archai returns raw structural data — the agent's own LLM interprets it. This means:

• No duplicated LLM calls
• Context-aware inference (the agent knows WHAT you're building)
• Zero LLM configuration for archai

Configuration for OpenCode

Generated by archai init:

{
  "mcp": {
    "archai": {
      "type": "local",
      "command": ["archai", "mcp"],
      "enabled": true
    }
  }
}

No environment passthrough. No API keys. archai needs nothing but your files.

---

How It Works

                     archai MCP Server
                     (no LLM, no API keys)
                            │
     ┌──────────────────────┼──────────────────────┐
     │                      │                      │
     ▼                      ▼                      ▼
  Bootstrap             Clustering           Focus Resolution
  • File discovery      • Directory prox.    • Query matching
  • AST parsing         • Shared imports     • Subsystem rank
  • Dependency graph    • Call density       • Test file detection
  • Cycle detection

archai is a pure structural analysis engine. It discovers files, builds a dependency graph, clusters them into logical subsystems, and exposes everything as structured data. No LLM involved.

---

Why archai?

Problem	Solution
Agents don't understand your codebase structure	archai provides clusters, dependencies, and focus resolution
Agents make changes without knowing the impact	get_blast_radius shows affected files and subsystems
LLM context windows fill with irrelevant files	archai finds the relevant subsystem (focus resolution)
Agents violate architecture constraints	Structural data enables the agent to self-validate
Configuring LLMs for tools is friction	archai needs no LLM config — the agent uses its own

---

Development

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=html

# Format code
uv run black src/
uv run ruff check src/

---

Architecture

See docs/003-sdd-agent-native-architecture.md for the current architecture spec.

---

License

MIT