Metadata-Version: 2.4
Name: archai-mcp
Version: 0.1.0
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
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
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)

Cognitive Middleware for Architecture-Aware AI Coding Agents.

## Overview

ArchAI is a middleware layer that governs how AI coding agents perceive and reason about software systems. It provides architecture-aware context to agents, reducing context pollution and architectural drift.

## Installation

```bash
# Install from PyPI
pip install archai-mcp

# Or install with uv
uv tool install archai-mcp
```

After installation, the `archai` CLI is available globally.

For MCP integration, add `uvx archai-mcp mcp` to your `.opencode/mcp.json` (see [MCP Integration](#mcp-integration-agents)).

## Quick Start

```bash
# Install
uv sync

# Process a repository
uv run archai start .

# Ask about the architecture
uv run archai ask "how does the login work"
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `archai start [repo_path]` | Process a repository (bootstrap + inference pipeline) |
| `archai ask "query"` | Ask a question about the architecture |
| `archai mcp` | Start MCP server (stdio, for agent integration) |

### Examples

```bash
# Process current directory
archai start

# Process another repo
archai start /path/to/repo

# Ask questions
archai ask "how does the orchestrator work"
archai ask "what constraints does the auth module have"

# JSON output for scripting
archai ask "orchestrator" --json | jq '.focus'
```

### Auto-Cache

`archai ask` automatically runs `archai start` if no cache exists. You never need to run `archai start` manually — but can if you want to pre-process.

## MCP Integration (Agents)

ArchAI exposes 3 MCP tools for AI agents:

| Tool | Description |
|------|-------------|
| `get_architecture_context` | Get context packet for a query |
| `validate_code_change` | Validate changes against constraints |
| `get_blast_radius` | Analyze impact of changing a file |

### Agent Configuration

```json
// .opencode/mcp.json
{
  "mcpServers": {
    "archai": {
      "command": "uvx",
      "args": ["archai-mcp", "mcp"],
      "description": "Architecture-aware context for AI coding agents"
    }
  }
}
```

## 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/002-sdd-cli-mcp-architecture.md` for the current architecture spec.

See `docs/001-sdd-mvp-architecture.md` for the original MVP spec (superseded by 002 for CLI/MCP sections).

## License

MIT
