StackBridge

---

💡 ¿Por qué StackBridge?

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

1. Un agente modifica un parámetro de API o un campo 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 de ejecución.

StackBridge-MCP es un servidor Model Context Protocol (MCP) siempre activo que analiza relaciones AST full-stack, descubre radios de impacto cross-stack en 0.75 ms y verifica cambios mediante comprobaciones del compilador 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

---

⚡ Características Destacadas

• 🌲 Grafo AST Tree-sitter: Analiza Next.js (fetch, Axios, React Query) ↔ rutas FastAPI ↔ modelos ORM SQLAlchemy sin sidecars LSP pesados ni importaciones en tiempo de ejecución.
• ⚡ Recorrido Sub-1ms: Base de datos SQLite WAL persistente con Expresiones de Tabla Común recursivas (0.75 ms de latencia de consulta de recorrido).
• 📉 Reducción del 99.74% de Tokens de Prompt: Reemplaza volcados masivos de código multi-archivo con fragmentos de contrato AST compactos y matemáticamente precisos.
• 🛡️ Clasificación de Diagnóstico de Causa Raíz: BFS por distancia de grafo clasifica errores (🔴 PRIMARY ROOT CAUSE vs ⚠️ CASCADING BREAKAGE) y genera parches Git diff inmediatos.
• 🧪 Selección de Impacto de Pruebas: Aísla suites de pruebas afectadas por un cambio de esquema y resalta rutas de radio de impacto sin probar (0% de cobertura).
• 🌐 Lienzo Interactivo: Visualizador tripartito localhost integrado (stackbridge ui) en http://127.0.0.1:3456.
• 🔄 Inteligencia Continua: Daemon de vigilancia de archivos en segundo plano (stackbridge watch) y generador de contexto vivo AGENTS.md.

---

📊 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):

Métrica de Benchmark	Volcado Crudo del Código Base	Fragmento Compacto de StackBridge	Mejora / Latencia
Tamaño de la Ventana de Contexto	19,705 tokens	51 tokens	📉 Reducción del 99.74% de Tokens
Recorrido del Radio de Impacto	Búsqueda en todo el repositorio: ~150 ms	CTE Recursivo SQLite: 0.75 ms	⚡ Recorrido 200x Más Rápido
Verificación del Compilador	Linter global: ~3,500 ms	Motor con Diff de Línea Base: 312 ms	🛡️ Cero Falsos Positivos
Suite de Pruebas Automatizadas	—	56 / 56 pruebas aprobadas	✅ 100% Aprobadas

Consulta 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 vía uvx)

uvx stackbridge serve

Opción 2: Instalación con Pip

pip install stackbridge
stackbridge serve

---

⚙️ Configuración del Cliente

Conecta StackBridge a tu programador en pareja de IA mediante stdio JSON-RPC 2.0 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 a los agentes de codificación:

Nombre de la Herramienta	Argumentos	Descripción
trace_fullstack_path	symbol_or_path: str	Rastrea la cadena de dependencias full-stack: Componente frontend ➔ Ruta de API ➔ Modelo de base de datos.
get_route_contract	route_path: str	Extrae métodos HTTP, códigos de estado, modelos de respuesta y llamadores fetch del frontend vinculados con puntuaciones de confianza.
verify_schema_change	modified_files: dict	Ejecuta verificaciones del compilador en memoria en los archivos afectados, clasificando causas raíz y proponiendo parches diff.
get_stack_health	repo_path: str	Devuelve estadísticas de límites full-stack en tiempo real, recuentos de nodos, recuentos de aristas y estado de deriva de rupturas.

---

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