A
licenseNot graded
qualityB
maintenanceLocal-first cross-service code intelligence engine for AI agents, connecting frontend, gateways, backend services, and databases to enable impact analysis and change planning.
Apache 2.0
StackBridge
🌉 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:
Un agente modifica un parámetro de API o un campo de Pydantic/SQLAlchemy en
backend/routes.py.Las pruebas del backend pasan de forma aislada. Nada advierte al agente.
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() BillingAccountRelated MCP server: repocontext
⚡ 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 PRIMARIAvs⚠️ 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) enhttp://127.0.0.1:3456.🔄 Inteligencia Continua: Demonio de monitorización de archivos en segundo plano (
stackbridge watch) y generador de contextoAGENTS.mdvivo.
📊 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 de Código Base Sin Procesar | Fragmento Compacto de StackBridge | Mejora / Latencia |
Tamaño de Ventana de Contexto |
|
| 📉 99.74% de Reducción de Tokens |
Recorrido del Radio de Explosión | Búsqueda en repositorio completo: | CTE Recursivo de SQLite: | ⚡ 200x más rápido |
Verificación del Compilador | Linter global: | Motor con Diff de Línea Base: | 🛡️ Cero Falsos Positivos |
Suite de Pruebas Automatizadas | — | 56 / 56 pruebas pasan | ✅ 100% Exitoso |
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 serveOpció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:
Nombre de la Herramienta | Argumentos | Descripción |
|
| Traza la cadena de dependencias de pila completa: Componente Frontend ➔ Ruta API ➔ Modelo de Base de Datos. |
|
| Extrae métodos HTTP, códigos de estado, modelos de respuesta y llamadas fetch del frontend vinculadas con puntuaciones de confianza. |
|
| Ejecuta comprobaciones de compilación en memoria en los archivos afectados, clasificando causas raíz y proponiendo parches diff. |
|
| Devuelve estadísticas de límites entre stacks en tiempo real, conteo de nodos, conteo de aristas y estado de desviación por roturas. |
💻 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.
Available Tools
5 toolsget_route_contractB
Extracts the API contract for a route, including HTTP method, status codes, response model, and all linked frontend fetch callers with confidence scores.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No | . | |
| route_path | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the transparency burden. It discloses the output contents and implies a read-only extraction operation, but it does not mention edge cases, external dependencies, or any side effects beyond the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence that front-loads the primary action and lists the key output categories without any wasted words. It is appropriately concise and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description names the main outputs and an output schema exists, but parameter semantics are severely under-documented (0% schema coverage). The tool needs at least a brief note on how route_path should be specified and what repo_path controls to be fully actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter-level meaning. It does not explain the expected format of route_path or the purpose of repo_path, leaving both parameters semantically under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Extracts' and identifies the resource as 'API contract for a route'. It lists concrete deliverables (HTTP method, status codes, response model, callers with confidence scores), which clearly distinguishes it from sibling tools like trace_fullstack_path and get_stack_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when one needs a route's API contract, but it does not explicitly state when to use it versus alternatives. No exclusions or contrast with sibling tools are provided, leaving some selection inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_stack_healthC
Returns stack health diagnostics, graph statistics, and verification metrics.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral transparency. It does not disclose any side effects, access requirements, performance implications, or what 'health diagnostics' entails (e.g., whether it mutates state or is read-only).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that lists the types of results. It is front-loaded and efficient, though it could be improved by adding brief usage context without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the complexity of a diagnostic tool, the description lacks sufficient context. It does not explain the tool's role relative to siblings, what 'stack health' includes, or how to interpret the results beyond what the output schema provides.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the purpose or default behavior of the 'repo_path' parameter. The schema shows it is optional with a null default, but without context, the agent cannot infer what happens when it is omitted or provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states what the tool does (returns diagnostics, statistics, metrics), but it is vague about the specific resource or domain. 'Stack health' is not clearly defined, and the description does not distinguish this tool from siblings like 'trace_fullstack_path' or 'verify_breakage'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus its siblings. For example, it does not clarify whether this is a general health check or a debugging step, and no exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
trace_fullstack_pathB
Traces fullstack dependency chain across Frontend, API Routes, and SQLAlchemy ORM models.
Returns the complete path: Frontend component -> API Route handler -> Database Model.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| repo_path | No | ||
| symbol_or_path | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It explains what the tool returns but does not mention whether it modifies state, requires authentication, handles large repos, or what happens if targets are not found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. Every sentence adds value without repetition or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic return structure but lacks guidance on parameter usage, error handling, or performance implications. Given the complexity of tracing fullstack dependencies and having zero annotation coverage, more detail is needed to be complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should clarify parameter meanings. The description mentions a 'target' concept but does not explain the roles of target, repo_path, or symbol_or_path, nor how they interact. With multiple optional parameters, the semantics are ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool traces a fullstack dependency chain across Frontend, API Routes, and SQLAlchemy ORM models, specifying the resources involved and the return path format. This distinguishes it well from siblings like get_route_contract or get_stack_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_route_contract or verify_schema_change. The description does not indicate what input is needed or prerequisites like a valid repo path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
verify_breakageA
Runs compiler and schema verification across all files impacted by a change.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No | . | |
| modified_files | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explains what the tool does (runs compiler and schema verification) and the scope (across all files impacted by a change), but it does not disclose behavioral traits such as whether it modifies files, requires specific permissions, has side effects, or what the output schema represents. This is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently conveys the tool's purpose without unnecessary words. It is front-loaded and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two optional parameters and an output schema, the description provides a solid overview of the tool's function. It could benefit from noting that both parameters are optional, but the context signals help there. The description is complete enough for an agent to understand the tool's core purpose and scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the two parameters. It does not explain the meaning of 'repo_path' or 'modified_files' beyond their names in the schema. However, the description of the tool's action (running verification across impacted files) gives implicit context that 'modified_files' likely lists changed files and 'repo_path' is the repository root. This is minimal value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Runs' and the resource 'compiler and schema verification across all files impacted by a change', which is specific and distinguishes it from siblings like 'verify_schema_change' (which focuses only on schema) and 'get_stack_health' (which checks overall health).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a change has been made and needs verification, but it does not explicitly state when to use this tool versus alternatives like 'verify_schema_change' or 'trace_fullstack_path', nor does it mention when not to use it or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
verify_schema_changeC
Runs compiler and schema verification across all files impacted by a change.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No | . | |
| modified_files | No | ||
| schema_changes | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.6/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavioral traits. The description does not mention what happens upon failure (e.g., error messages, warnings), whether the tool modifies any state, or if it requires network access or specific permissions. The behavior is presented too abstractly for safe agent invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 10 words, which is concise. It front-loads the key verbs (runs compiler and schema verification). However, it omits essential details, crossing the line from concise to underspecified. Still, brevity is maintained.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero annotations, no output schema explanation (but an output schema exists), and 3 parameters with no description, the tool description fails to provide enough context. The agent needs to know the output format (what success/failure looks like), the expected data format for parameters, and how this relates to sibling tools. The description is incomplete for a tool of moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters with 0% description coverage, meaning the schema itself provides no descriptions. The tool description does not clarify the parameters either—'repo_path', 'modified_files', and 'schema_changes' are not explained in terms of format or semantics. Since there are no enums, the agent cannot guess valid values. A score of 3 is generous because the schema's structure hints at purpose, but the lack of any explanation makes selection difficult.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool runs compiler and schema verification across impacted files, which gives a clear verb+resource combination. However, it does not distinguish this tool from its siblings like 'verify_breakage' or 'trace_fullstack_path', which might have overlapping purposes. The purpose is adequate but lacks differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like 'verify_breakage' or 'get_route_contract'. The description does not indicate prerequisites, such as needing a git diff or pre-identified list of modified files. Without any usage context, an AI agent may misuse or underuse the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.0- First observed
get_route_contract - First observed
get_stack_health - First observed
trace_fullstack_path - First observed
verify_breakage - First observed
verify_schema_change
TDQS
B3.1/5.0
Scored across 5 tools
Disambiguation2/5
Two tools (verify_schema_change and verify_breakage) have identical descriptions, making them indistinguishable. Other tools are distinct but the duplication severely harms disambiguation.
Naming Consistency5/5
All tools follow a consistent snake_case verb_noun pattern (trace_, get_, verify_, get_). No mixing of conventions.
Tool Count5/5
Five tools is a well-scoped, focused set for a StackBridge server that handles dependency tracing, contract extraction, verification, and health diagnostics.
Completeness3/5
Core analysis features are present, but the duplicate verify tools indicate poor domain modeling. Missing a tool to list all routes or contracts, and it's unclear if schema verification and breakage verification are truly separate concepts.
Maintenance
ActivitySlowing
ResponsivenessNo issues
Related MCP Connectors
Design domain models and generate deterministic multi-stack code, driven by your coding agent.
Coding agents in multi-service codebases routinely rebuild existing helpers, trust stale type definitions, and modify API contracts without knowing who consumes them. Carrick solves this by indexing your entire TypeScript ecosystem across service and repository boundaries. By integrating deeply with the TypeScript compiler, Carrick traces every route, type, and cross-service call while recording function behaviour so agents search by intent rather than name. Delivered via MCP for AI agents and LSP for IDEs, Carrick ensures models see existing endpoints and utilities before generating new code. The scanner is source-available and runs from your CLI or CI pipeline.
Live React design-system APIs, patterns, and code validation so AI agents build real UI, not slop.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Related MCP Servers
- AlicenseAqualityAmaintenanceNext-gen AST codebase map, token compression (70%~85% savings), and context packaging engine for AI coding agents & IDEs.43MIT
- AlicenseNot gradedqualityCmaintenanceEnables cross-repository architecture discovery and dependency routing across multi-service codebases, with automated scanning and batch AST indexing for AI agents to trace request lifecycles and navigate service boundaries.15 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables autonomous frontend and backend AI agents to asynchronously coordinate development by registering and discovering OpenAPI-compatible route contracts, tracking integration issues, and managing route groups for efficient LLM context.MIT