StackBridge

Sub-1ms Cross-Stack AST Contract & Verification Layer for AI Coding Agents

Quick Start•Client Config•Benchmarks•MCP Tools•CLI Reference•Docs

StackBridge-MCPis an always-warmModel Context Protocol (MCP)server that parses full-stack AST relationships, discovers cross-stack blast radii in0.75 ms, and verifies changes using baseline-diffed compiler checks with zero false positives.

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

- 🌲 Tree-sitter AST Graph:Parses Next.js (fetch, Axios, React Query) ↔ FastAPI routes ↔ SQLAlchemy ORM models without heavy LSP sidecars or runtime imports.
- ⚡ Sub-1ms Traversal:Persistent SQLite WAL database with recursive Common Table Expressions (0.75 mstraversal query latency).
- 📉 99.74% Prompt Token Reduction:Replaces massive multi-file code dumps with compact, mathematically precise AST contract slices.
- 🛡️ Root-Cause Diagnostic Ranking:Graph-distance BFS ranks errors (🔴 PRIMARY ROOT CAUSEvs⚠️ CASCADING BREAKAGE) and outputs immediate Git diff patches.
- 🧪 Test Impact Selection:Isolates test suites impacted by a schema change and highlights untested blast-radius paths (0% coverage).
- 🌐 Interactive Canvas:Built-in localhost tripartite visualizer (stackbridge ui) onhttp://127.0.0.1:3456.
- 🔄 Continuous Intelligence:Background file watcher daemon (stackbridge watch) and livingAGENTS.mdcontext generator.

Empirical performance measured onfastapi-realworld-example-app(44 files, 23 AST dependency nodes, 10 cross-boundary edges):

See full benchmark methodology indocs/benchmarks.mdandREAL_WORLD_BENCHMARK.md.

pip install stackbridge stackbridge serve

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

StackBridge exposes high-ergonomics tools to coding agents:

# 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

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

This project is licensed under theMIT License.

An MCP server for offloading AI coding tasks to Aider, enhancing development efficiency and flexibility.