🌉 StackBridge-MCP

Capa de Contrato y Verificación AST Multi-Stack Sub-ms para Agentes de Codificación con IA

💡 ¿Por qué StackBridge?

Cuando los agentes de codificación con IA (Cursor, Claude Code, Windsurf, Antigravity) editan modelos backend o rutas API en bases de código full-stack, las pruebas unitarias del backend suelen pasar mientras el frontend falla silenciosamente en producción:

1. Un agente modifica un parámetro de API o un campo de Pydantic/SQLAlchemy en backend/routes.py.

2. Las pruebas del backend pasan de forma aislada. Nada advierte al agente.

3. El cliente React/Next.js que llama a ese endpoint a través del límite falla con errores en tiempo de ejecución.

StackBridge-MCP es un servidor Model Context Protocol (MCP) siempre activo que analiza las relaciones AST de pila completa, descubre radios de explosión entre stacks en 0.75 ms y verifica los cambios mediante comprobaciones de compilación con diff de línea base y cero falsos positivos.

React / Next.js Client            FastAPI Routes            SQLAlchemy ORM Models
   (TypeScript AST)      ───►    (Python AST)     ───►          (Schema AST)
  UserProfile.tsx              get_user_billing()              BillingAccount

Related MCP server: Carto MCP Server

⚡ Aspectos Destacados

• 🌲 Grafo AST con Tree-sitter: Analiza Next.js (fetch, Axios, React Query) ↔ rutas FastAPI ↔ modelos ORM de SQLAlchemy sin necesidad de costosos sidecars LSP ni importaciones en tiempo de ejecución.

• ⚡ Recorrido Sub-ms: Base de datos persistente SQLite WAL con expresiones de tabla común recursivas (0.75 ms de latencia de consulta de recorrido).

• 📉 99.74% de Reducción de Tokens de Prompt: Reemplaza volcados masivos de código de múltiples archivos con fragmentos de contrato AST compactos y matemáticamente precisos.

• 🛡️ Clasificación de Diagnóstico de Causa Raíz: BFS basado en distancia de grafo clasifica errores (🔴 CAUSA RAÍZ PRIMARIA vs ⚠️ RUPTURA EN CADENA) y genera parches de diff Git inmediatos.

• 🧪 Selección de Impacto de Pruebas: Aísla los conjuntos de pruebas afectados por un cambio de esquema y resalta las rutas de radio de explosión no probadas (0% de cobertura).

• 🌐 Lienzo Interactivo: Visualizador tripartito localhost integrado (stackbridge ui) en http://127.0.0.1:3456.

• 🔄 Inteligencia Continua: Demonio de monitorización de archivos en segundo plano (stackbridge watch) y generador de contexto AGENTS.md vivo.

📊 Benchmarks del Mundo Real

Rendimiento empírico medido en fastapi-realworld-example-app (44 archivos, 23 nodos de dependencia AST, 10 aristas entre límites):

Consulte la metodología completa de benchmarks en docs/benchmarks.md y REAL_WORLD_BENCHMARK.md.

🚀 Inicio Rápido

Opción 1: Ejecución Sin Instalación (Recomendada mediante uvx)

uvx stackbridge serve

Opción 2: Instalación con Pip

pip install stackbridge
stackbridge serve

⚙️ Configuración del Cliente

Conecte StackBridge a su programador en pareja de IA mediante JSON-RPC 2.0 stdio estándar:

1. Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "stackbridge": {
      "command": "uvx",
      "args": ["stackbridge", "serve"]
    }
  }
}

2. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "stackbridge": {
      "command": "python",
      "args": ["-m", "stackbridge.main", "serve", "--transport", "stdio"]
    }
  }
}

🤖 Referencia de Herramientas MCP

StackBridge expone herramientas de alta ergonomía para los agentes de codificación:

💻 Referencia CLI

# Index a repository and export the dependency graph
stackbridge index --repo-path . --force

# Trace blast radius for a model or route
stackbridge trace --target BillingAccount

# Run pre-commit boundary verification guard
stackbridge guard --fail-on-error

# Launch interactive tripartite web visualizer
stackbridge ui --port 3456

# Start continuous background watcher daemon
stackbridge watch

# Generate living AGENTS.md boundary architecture guide
stackbridge init-agents

# Execute performance and token reduction benchmarks
stackbridge benchmark --runs 3 --output BENCHMARK.md

📁 Estructura del Repositorio

StackBridge-MCP/
├── .github/
│   ├── workflows/ci.yml         # CI pipeline (Python 3.10-3.13 on Ubuntu/Windows/macOS)
│   ├── ISSUE_TEMPLATE/          # Bug report and feature request issue templates
│   └── PULL_REQUEST_TEMPLATE.md # Standard PR checklist
├── docs/
│   ├── architecture.md          # Subsystem breakdown and Mermaid diagrams
│   ├── benchmarks.md            # Benchmark methodology and raw metrics
│   └── ast_extraction_spec.md   # Tree-sitter extractor grammar specifications
├── stackbridge/
│   ├── core/                    # Unified StackGraph, SQLite CTE store, watcher, route matcher
│   ├── parsers/                 # Tree-sitter parsers (TS fetch, Python routes, SQLAlchemy)
│   ├── verifier/                # Baseline-diffed verifier, root-cause ranker, test impact selector
│   ├── mcp_server/              # FastMCP stdio server and JSON-RPC tools
│   ├── benchmarks/              # Benchmark runner and markdown report generator
│   └── ui/                      # Localhost tripartite interactive canvas
├── tests/                       # 56 automated test suites (parsers, verifiers, MCP E2E, CTE)
├── AGENTS.md                    # Living agent architecture guide
├── CHANGELOG.md                 # Version release notes
├── CONTRIBUTING.md              # Contribution and development guidelines
├── LICENSE                      # MIT License
└── pyproject.toml               # Package metadata and tool configurations

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.