archai-mcp 0.4.6

Structural analysis engine for AI coding agents

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:

Command	Description
archai init	Configure the project for OpenCode MCP integration
archai serve	Start MCP server (stdio, for AI agents)
archai analyze	Show full architecture: clusters, dependencies, functions
archai context <query>	Get architecture context relevant to a query
archai file <path>	Detailed analysis of a single file
archai state [--var]	Shared global state map: writers + readers per variable
archai trace <feature>	Trace a feature's call flow through the codebase
archai blast <path>	Impact of changing a file (or a function with --function <name>)
archai validate <patch>	Structural analysis of proposed code changes

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

archai analyze flags

Flag	Description
--clusters / --no-clusters	Show or hide cluster analysis (default: True)
--deps / --no-deps	Show or hide dependency analysis (default: True)
--functions / --no-functions	Show or hide function-level analysis (default: True)
--sub-clusters / --no-sub-clusters	Show or hide intra-file sub-cluster analysis (default: True)
--force	Bypass disk cache and re-analyze from scratch
--json	Machine-readable JSON output

---

MCP Tools

archai exposes 7 structural analysis tools for AI agents:

Tool	CLI	Description
get_architecture_context	archai context	Focus cluster, cluster edges, file dependencies, test files for a query
get_file_detail	archai file	Per-file analysis: functions, classes, imports, dependents
get_shared_state	archai state	Global variable map showing which functions write/read each variable
trace_feature_flow	archai trace	Entry point → call chain → shared state → risks
get_blast_radius	archai blast	Impact analysis: dependents, transitive dependencies, affected subsystems
validate_code_change	archai validate	Structural context about proposed changes (no "valid/invalid" judgment)
propose_change	—	Given a change description, suggests affected files

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?

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/

---

License

MIT