archai-mcp

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

Quick Start

# 1. Install
pip install archai-mcp

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

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

CLI Commands

archai offers 10 commands — one for every MCP tool plus utility commands:

All analysis commands support --json for machine-readable output. Use archai --version to check the installed version.

archai analyze flags

MCP Tools

archai exposes 7 structural analysis tools for AI agents:

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. get_file_detail("src/auth/handler.py")
     ← functions, classes, signatures in the auth module
     → Agent knows what already exists

  3. Writes code respecting inferred architecture

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

  5. validate_code_change(repo_path, changes=[...])
     ← structural context about the patch
     → Agent can self-validate before submitting

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:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "archai": {
      "type": "local",
      "command": ["archai", "serve"],
      "enabled": true
    }
  }
}

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

How It Works

                    ┌─────────────────────┐
                    │   archai serve       │
                    │  (MCP Server, no LLM)│
                    └──────────┬──────────┘
                               │
         ┌─────────────────────┼─────────────────────┐
         ▼                     ▼                     ▼
   Bootstrap              Analysis              Resolution
   ┌─────────────┐    ┌──────────────┐    ┌────────────────┐
   │ File        │    │ Clustering   │    │ Focus matching │
   │ discovery   │    │ • directory  │    │ Subsystem rank │
   │ AST parsing │    │ • dependency │    │ Test file      │
   │ Dependency  │    │ • call graph │    │ detection      │
   │ graph       │    │              │    │                │
   │ Var access  │    │ Shared state │    │ Trace flow     │
   │ extraction  │    │ analysis     │    │ Blast radius   │
   └─────────────┘    └──────────────┘    └────────────────┘

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

Key features

• Multi-language — Python, C, C++ via tree-sitter
• Intra-file clustering — function-level dependency resolution for C/C++
• Variable access tracking — shows which functions read/write each global variable
• Feature tracing — entry point → call chain → shared state → risk assessment
• Blast radius — transitive dependency impact analysis with configurable depth
• Disk caching — results cached in /tmp/archai_cache/ for faster repeated analysis
• No LLM — pure static analysis, runs offline, instant results

Why archai?

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/

License

MIT