Skip to main content
Glama
deenesjakoruzh
ZainUlAbideen02

StackBridge

by ZainUlAbideen02
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

🌉 StackBridge-MCP

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

PyPI version Python 3.10+ License: MIT CI Tests FastMCP Compatible

💡 Why StackBridge?

When AI coding agents (Cursor, Claude Code, Windsurf, Antigravity) edit backend models or API routes in full-stack codebases, backend unit tests frequently pass while the frontend silently breaks in production:

  1. An agent modifies an API parameter or Pydantic/SQLAlchemy field in backend/routes.py.

  2. Backend tests pass in isolation. Nothing warns the agent.

  3. The React/Next.js client calling that endpoint across the boundary fails with runtime errors.

StackBridge-MCP is an always-warm Model Context Protocol (MCP) server that parses full-stack AST relationships, discovers cross-stack blast radii in 0.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

Related MCP server: Carto MCP Server

⚡ Key Highlights

  • 🌲 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 ms traversal 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 CAUSE vs ⚠️ 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) on http://127.0.0.1:3456.

  • 🔄 Continuous Intelligence: Background file watcher daemon (stackbridge watch) and living AGENTS.md context generator.

📊 Real-World Benchmarks

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

Benchmark Metric

Raw Codebase Dump

StackBridge Compact Slice

Improvement / Latency

Context Window Size

19,705 tokens

51 tokens

📉 99.74% Token Reduction

Blast Radius Traversal

Full-repo search: ~150 ms

SQLite Recursive CTE: 0.75 ms

⚡ 200x Faster Traversal

Compiler Verification

Global linter: ~3,500 ms

Baseline-Diffed Engine: 312 ms

🛡️ Zero False Positives

Automated Test Suite

—

56 / 56 tests passing

✅ 100% Passing

See full benchmark methodology in docs/benchmarks.md and REAL_WORLD_BENCHMARK.md.

🚀 Quick Start

Option 1: Zero-Install Execution (Recommended via uvx)

uvx stackbridge serve

Option 2: Pip Installation

pip install stackbridge
stackbridge serve

⚙️ Client Configuration

Connect StackBridge to your AI pair programmer over standard JSON-RPC 2.0 stdio:

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

🤖 MCP Tools Reference

StackBridge exposes high-ergonomics tools to coding agents:

Tool Name

Arguments

Description

trace_fullstack_path

symbol_or_path: str

Traces the full-stack dependency chain: Frontend component ➔ API route ➔ Database model.

get_route_contract

route_path: str

Extracts HTTP methods, status codes, response models, and linked frontend fetch callers with confidence scores.

verify_schema_change

modified_files: dict

Runs in-memory compiler checks across impacted files, ranking root causes and proposing diff patches.

get_stack_health

repo_path: str

Returns real-time full-stack boundary stats, node counts, edge counts, and breakage drift status.

💻 CLI Reference

# 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

📁 Repository Structure

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

📄 License

This project is licensed under the MIT License.

Install Server
A
license - permissive license
B
quality
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Tools

Related MCP Servers

  • memtrace

    syncable-dev
    F
    license
    -
    quality
    A
    maintenance
    Memtrace is a persistent memory layer for coding agents, built as a bi‑temporal structural knowledge graph over your codebase (AST‑driven symbols and relationships, plus temporal evolution and cross‑service API topology)
    449

  • agenthelm

    jayasukuv11-beep
    A
    license
    A
    quality
    C
    maintenance
    Shared, versioned memory and governance control plane for AI coding agents. Compiler pipeline resolves architectural decision conflicts across Claude Code, Cursor, and custom agent fleets.
    3
    4
    MIT

View all related MCP servers

Related MCP Connectors

  • aethereum

    The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.

  • Hokmah

    AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).

  • AgentDrive

    Cross-agent artifact workspace with provenance across Claude Code, Codex, Cursor, LangGraph.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ZainUlAbideen02/StackBridge-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server