Metadata-Version: 2.4
Name: archai-mcp
Version: 0.4.5
Summary: Structural analysis engine for AI coding agents
Author-email: Cristian Chacha <cristianchachaleon@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/CristianChachaLeon/arch-ai
Project-URL: Repository, https://github.com/CristianChachaLeon/arch-ai
Project-URL: Documentation, https://github.com/CristianChachaLeon/arch-ai#readme
Project-URL: Issues, https://github.com/CristianChachaLeon/arch-ai/issues
Keywords: ai,coding-agent,architecture,middleware,mcp,opencode,cli
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=0.9
Requires-Dist: rich>=13.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: tree-sitter>=0.20.0
Requires-Dist: tree-sitter-c>=0.20
Requires-Dist: networkx>=3.0.0
Requires-Dist: mcp>=1.23.0
Provides-Extra: c
Provides-Extra: cpp
Requires-Dist: tree-sitter-cpp>=0.20; extra == "cpp"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: tree-sitter-cpp>=0.20; extra == "dev"
Dynamic: license-file

# archai-mcp

[![PyPI Version](https://img.shields.io/pypi/v/archai-mcp)](https://pypi.org/project/archai-mcp/)
[![Python Versions](https://img.shields.io/pypi/pyversions/archai-mcp)](https://pypi.org/project/archai-mcp/)
[![License](https://img.shields.io/pypi/l/archai-mcp)](https://github.com/CristianChachaLeon/arch-ai/blob/main/LICENSE)
[![Coverage](https://img.shields.io/badge/coverage-94%25-green)](https://github.com/CristianChachaLeon/arch-ai)

**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.

```bash
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

```bash
# 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
```

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

---

## CLI Commands

archai offers **12 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>` | Analyze the impact of changing a file |
| `archai validate <patch>` | Structural analysis of proposed code changes |
| `archai check` | Architecture design rule checks (cyclic deps, forbidden imports) |
| `archai ci` | Run archai checks for CI/CD pipelines (with exit code) |
| `archai mcp` | Alias for `archai serve` (deprecated) |

All analysis commands support `--json` for machine-readable 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`:

```json
{
  "$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
- **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

```bash
# 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
