Metadata-Version: 2.4
Name: archai-mcp
Version: 0.3.1
Summary: Cognitive Middleware for Architecture-Aware 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: python-dotenv>=0.18.0
Requires-Dist: tree-sitter>=0.20.0
Requires-Dist: networkx>=3.0.0
Requires-Dist: litellm>=1.0.0
Requires-Dist: mcp>=1.23.0
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"
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)

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

```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.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`:

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

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

---

## Architecture

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

---

## License

MIT
