archai-mcp 0.1.0__tar.gz

archai_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristian Chacha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

archai_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+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

archai_mcp-0.1.0/README.md

@@ -0,0 +1,116 @@
+# 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

archai_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[project]
+name = "archai-mcp"
+version = "0.1.0"
+description = "Cognitive Middleware for Architecture-Aware AI Coding Agents"
+readme = {file = "README.md", content-type = "text/markdown"}
+requires-python = ">=3.11"
+authors = [
+    {name = "Cristian Chacha", email = "cristianchachaleon@gmail.com"}
+]
+license = "MIT"
+keywords = ["ai", "coding-agent", "architecture", "middleware", "mcp", "opencode", "cli"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "typer[all]>=0.9",
+    "rich>=13.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "python-dotenv>=0.18.0",
+    "tree-sitter>=0.20.0",
+    "networkx>=3.0.0",
+    "litellm>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/CristianChachaLeon/arch-ai"
+Repository = "https://github.com/CristianChachaLeon/arch-ai"
+Documentation = "https://github.com/CristianChachaLeon/arch-ai#readme"
+Issues = "https://github.com/CristianChachaLeon/arch-ai/issues"
+
+[project.optional-dependencies]
+mcp = [
+    "mcp>=1.0",
+]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "httpx>=0.24.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+    "pre-commit>=3.0.0",
+]
+
+[project.scripts]
+archai = "archai.cli.app:app"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false

archai_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

archai_mcp-0.1.0/src/archai/__init__.py

@@ -0,0 +1,12 @@
+"""ArchAI - Cognitive Middleware for Architecture-Aware AI Coding Agents.
+
+Main entry point for the ArchAI library.
+"""
+
+from archai.middleware import ArchaiMiddleware
+from archai.middleware.pipeline import PipelineResult
+from archai.orchestrator import ArchaiOrchestrator
+
+__version__ = "0.1.0"
+
+__all__ = ["ArchaiMiddleware", "PipelineResult", "ArchaiOrchestrator"]

archai_mcp-0.1.0/src/archai/bootstrap/__init__.py

@@ -0,0 +1,44 @@
+"""ArchAI Bootstrap Module - File discovery and bootstrap utilities.
+
+Pipeline:
+    1. file_discovery - find all .py files
+    2. ast_parser - parse files and extract metadata
+    3. dependency_resolver - resolve imports to filenames
+    4. graph_builder - build NetworkX graph
+"""
+
+from archai.bootstrap.file_discovery import discover_python_files
+from archai.bootstrap.ast_parser import parse_python_file, get_imports, get_functions, get_classes
+from archai.bootstrap.dependency_resolver import resolve_imports, FileNode
+from archai.bootstrap.graph_builder import build_graph, FileGraph
+from archai.bootstrap.cache import (
+    compute_repo_hash,
+    save_cache,
+    load_cache,
+    cache_exists,
+    invalidate_cache,
+    get_cache_path,
+)
+
+__all__ = [
+    # Discovery
+    "discover_python_files",
+    # Parsing
+    "parse_python_file",
+    "get_imports",
+    "get_functions",
+    "get_classes",
+    # Resolution
+    "resolve_imports",
+    # Graph
+    "build_graph",
+    "FileNode",
+    "FileGraph",
+    # Cache
+    "compute_repo_hash",
+    "save_cache",
+    "load_cache",
+    "cache_exists",
+    "invalidate_cache",
+    "get_cache_path",
+]

archai_mcp-0.1.0/src/archai/bootstrap/ast_parser.py

@@ -0,0 +1,97 @@
+"""AST Parser - Parse Python files using standard library ast module.
+
+Note: This implementation uses Python's built-in ast module for reliability.
+Future versions can integrate tree-sitter for faster parsing and multi-language support.
+"""
+
+import ast
+import tokenize
+from pathlib import Path
+
+
+def parse_python_file(file_path: Path) -> ast.AST:
+    """
+    Parses a Python file and returns its AST using the standard library.
+
+    Args:
+        file_path: Path to the Python file.
+
+    Returns:
+        An ast.AST object representing the parsed file.
+
+    Raises:
+        SyntaxError: If the file contains invalid Python syntax.
+        FileNotFoundError: If the file does not exist.
+    """
+    with tokenize.open(file_path) as f:
+        code = f.read()
+    if not code.strip():
+        # Return an empty Module for empty files
+        return ast.Module(body=[], type_ignores=[])
+
+    return ast.parse(code, filename=str(file_path))
+
+
+def get_imports(tree: ast.AST) -> list[str]:
+    """
+    Extracts all import statements from an AST.
+
+    Args:
+        tree: The parsed AST tree.
+
+    Returns:
+        List of imported module/component names.
+    """
+    imports = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                imports.append(alias.name)
+        elif isinstance(node, ast.ImportFrom):
+            rel_prefix = "." * node.level
+            for alias in node.names:
+                if node.module:
+                    imports.append(f"{rel_prefix}{node.module}.{alias.name}")
+                else:
+                    imports.append(f"{rel_prefix}{alias.name}")
+
+    return imports
+
+
+def get_functions(tree: ast.AST) -> list[str]:
+    """
+    Extracts all function definitions from an AST.
+
+    Args:
+        tree: The parsed AST tree.
+
+    Returns:
+        List of function names.
+    """
+    functions = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            functions.append(node.name)
+
+    return functions
+
+
+def get_classes(tree: ast.AST) -> list[str]:
+    """
+    Extracts all class definitions from an AST.
+
+    Args:
+        tree: The parsed AST tree.
+
+    Returns:
+        List of class names.
+    """
+    classes = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            classes.append(node.name)
+
+    return classes