StackBridge

---

💡 Por que StackBridge?

Quando agentes de codificação de IA (Cursor, Claude Code, Windsurf, Antigravity) editam modelos de backend ou rotas de API em codebases full-stack, os testes unitários de backend frequentemente passam enquanto o frontend quebra silenciosamente em produção:

1. Um agente modifica um parâmetro de API ou campo Pydantic/SQLAlchemy em backend/routes.py.
2. Os testes de backend passam isoladamente. Nada alerta o agente.
3. O cliente React/Next.js que chama esse endpoint através da fronteira falha com erros de runtime.

StackBridge-MCP é um servidor Model Context Protocol (MCP) sempre ativo que analisa relacionamentos AST full-stack, descobre raios de impacto entre stacks em 0,75 ms e verifica alterações usando verificações de compilador com diff de baseline, com zero falsos positivos.

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

---

⚡ Principais Destaques

• 🌲 Grafo AST Tree-sitter: Analisa Next.js (fetch, Axios, React Query) ↔ rotas FastAPI ↔ modelos ORM SQLAlchemy sem sidecars LSP pesados ou imports em runtime.
• ⚡ Travessia em menos de 1ms: Banco de dados SQLite WAL persistente com Common Table Expressions recursivas (0,75 ms de latência de consulta de travessia).
• 📉 Redução de 99,74% em Tokens de Prompt: Substitui despejos massivos de código multi-arquivo por fatias compactas e matematicamente precisas de contratos AST.
• 🛡️ Classificação Diagnóstica de Causa Raiz: BFS por distância de grafo classifica erros (🔴 PRIMARY ROOT CAUSE vs ⚠️ CASCADING BREAKAGE) e gera patches de diff Git imediatos.
• 🧪 Seleção de Impacto de Testes: Isola suítes de testes impactadas por uma mudança de schema e destaca caminhos de raio de impacto sem testes (0% de cobertura).
• 🌐 Canvas Interativo: Visualizador tripartite localhost integrado (stackbridge ui) em http://127.0.0.1:3456.
• 🔄 Inteligência Contínua: Daemon de monitoramento de arquivos em segundo plano (stackbridge watch) e gerador de contexto vivo AGENTS.md.

---

📊 Benchmarks do Mundo Real

Desempenho empírico medido em fastapi-realworld-example-app (44 arquivos, 23 nós de dependência AST, 10 arestas entre fronteiras):

Métrica de Benchmark	Despejo Bruto de Codebase	Fatia Compacta StackBridge	Melhoria / Latência
Tamanho da Janela de Contexto	19,705 tokens	51 tokens	📉 Redução de 99,74% em Tokens
Travessia do Raio de Impacto	Busca no repositório inteiro: ~150 ms	CTE Recursiva SQLite: 0.75 ms	⚡ Travessia 200x Mais Rápida
Verificação do Compilador	Linter global: ~3,500 ms	Mecanismo com Diff de Baseline: 312 ms	🛡️ Zero Falsos Positivos
Suíte de Testes Automatizados	—	56 / 56 testes passando	✅ 100% Aprovados

Veja a metodologia completa de benchmarks em docs/benchmarks.md e REAL_WORLD_BENCHMARK.md.

---

🚀 Início Rápido

Opção 1: Execução Sem Instalação (Recomendado via uvx)

uvx stackbridge serve

Opção 2: Instalação via Pip

pip install stackbridge
stackbridge serve

---

⚙️ Configuração do Cliente

Conecte o StackBridge ao seu programador parceiro de IA via stdio JSON-RPC 2.0 padrão:

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"]
    }
  }
}

---

🤖 Referência de Ferramentas MCP

O StackBridge expõe ferramentas de alta ergonomia para agentes de codificação:

Nome da Ferramenta	Argumentos	Descrição
trace_fullstack_path	symbol_or_path: str	Rastreia a cadeia de dependências full-stack: Componente frontend ➔ Rota de API ➔ Modelo de banco de dados.
get_route_contract	route_path: str	Extrai métodos HTTP, códigos de status, modelos de resposta e chamadores fetch de frontend vinculados com pontuações de confiança.
verify_schema_change	modified_files: dict	Executa verificações de compilador em memória nos arquivos impactados, classificando causas raiz e propondo patches de diff.
get_stack_health	repo_path: str	Retorna estatísticas de fronteira full-stack em tempo real, contagens de nós, contagens de arestas e status de desvio de quebras.

---

💻 Referência 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

---

📁 Estrutura do Repositório

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

---

📄 Licença

Este projeto é licenciado sob a Licença MIT.