Skip to main content
Glama
deenesjakoruzh
ZainUlAbideen02

StackBridge

by ZainUlAbideen02
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

🌉 StackBridge-MCP

面向 AI 编码智能体的亚毫秒级跨栈 AST 契约与验证层

PyPI 版本 Python 3.10+ 许可证: MIT CI 测试 FastMCP 兼容

💡 为什么选择 StackBridge？

当 AI 编码智能体（Cursor、Claude Code、Windsurf、Antigravity）在全栈代码库中编辑后端模型或 API 路由时，后端单元测试通常能通过，而前端却会在生产环境中静默崩溃：

  1. 智能体在 backend/routes.py 中修改了 API 参数或 Pydantic/SQLAlchemy 字段。

  2. 后端测试在隔离环境下通过。没有任何机制向智能体发出警告。

  3. 调用该端点的 React/Next.js 客户端在跨栈边界处因运行时错误而失败。

StackBridge-MCP 是一个始终热就绪的模型上下文协议 (MCP) 服务器，它能解析全栈 AST 关系，在 0.75 毫秒内发现跨栈影响范围，并通过基于基线差异的编译器检查验证变更，实现零误报。

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

⚡ 核心亮点

  • 🌲 Tree-sitter AST 图： 解析 Next.js（fetch、Axios、React Query）↔ FastAPI 路由 ↔ SQLAlchemy ORM 模型，无需笨重的 LSP 侧车进程或运行时导入。

  • ⚡ 亚毫秒级遍历： 基于持久化 SQLite WAL 数据库，使用递归公共表表达式（遍历查询延迟 0.75 毫秒）。

  • 📉 减少 99.74% 的提示词 Token： 将大量多文件代码转储替换为紧凑、数学上精确的 AST 契约片段。

  • 🛡️ 根本原因诊断排序： 基于图距离的 BFS 对错误进行排序（🔴 主要根本原因 与 ⚠️ 级联故障），并输出即用型 Git diff 补丁。

  • 🧪 测试影响选择： 隔离受模式变更影响的测试套件，并高亮未测试的影响范围路径（0% 覆盖率）。

  • 🌐 交互式画布： 内置本地主机三方可视化工具（stackbridge ui），访问地址 http://127.0.0.1:3456。

  • 🔄 持续智能： 后台文件监听守护进程（stackbridge watch）和可动态更新的 AGENTS.md 上下文生成器。

📊 真实世界基准测试

在 fastapi-realworld-example-app（44 个文件，23 个 AST 依赖节点，10 条跨边界边）上测得实证性能：

基准指标

原始代码库转储

StackBridge 紧凑片段

提升 / 延迟

上下文窗口大小

19,705 个 token

51 个 token

📉 减少 99.74% 的 Token

影响范围遍历

全仓库搜索：~150 毫秒

SQLite 递归 CTE：0.75 毫秒

⚡ 遍历速度快 200 倍

编译器验证

全局 linter：~3,500 毫秒

基于基线差异引擎：312 毫秒

🛡️ 零误报

自动化测试套件

—

56 / 56 个测试通过

✅ 100% 通过

完整基准测试方法论请参阅 docs/benchmarks.md 和 REAL_WORLD_BENCHMARK.md。

🚀 快速开始

方式一：零安装执行（推荐使用 uvx）

uvx stackbridge serve

方式二：通过 pip 安装

pip install stackbridge
stackbridge serve

⚙️ 客户端配置

通过标准 JSON-RPC 2.0 stdio 将 StackBridge 连接到您的 AI 编程搭档：

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 工具参考

StackBridge 向编码智能体提供高易用性工具：

工具名称

参数

描述

trace_fullstack_path

symbol_or_path: str

追溯全栈依赖链：前端组件 ➔ API 路由 ➔ 数据库模型。

get_route_contract

route_path: str

提取 HTTP 方法、状态码、响应模型以及关联的前端 fetch 调用者及其置信度评分。

verify_schema_change

modified_files: dict

对受影响的文件执行内存内的编译器检查，对根本原因进行排序并提出 diff 补丁。

get_stack_health

repo_path: str

返回实时的全栈边界统计信息，包括节点数、边数以及故障偏离状态。

💻 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

📁 仓库结构

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

📄 许可证

本项目基于 MIT 许可证 授权。

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