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
面向 AI 编码智能体的亚毫秒级跨栈 AST 契约与验证层
💡 为什么选择 StackBridge？
当 AI 编码智能体（Cursor、Claude Code、Windsurf、Antigravity）在全栈代码库中编辑后端模型或 API 路由时，后端单元测试通常能通过，而前端却会在生产环境中静默崩溃：
智能体在
backend/routes.py中修改了 API 参数或 Pydantic/SQLAlchemy 字段。后端测试在隔离环境下通过。没有任何机制向智能体发出警告。
调用该端点的 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() BillingAccountRelated MCP server: repocontext
⚡ 核心亮点
🌲 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 紧凑片段 | 提升 / 延迟 |
上下文窗口大小 |
|
| 📉 减少 99.74% 的 Token |
影响范围遍历 | 全仓库搜索： | SQLite 递归 CTE： | ⚡ 遍历速度快 200 倍 |
编译器验证 | 全局 linter： | 基于基线差异引擎： | 🛡️ 零误报 |
自动化测试套件 | — | 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 向编码智能体提供高易用性工具：
工具名称 | 参数 | 描述 |
|
| 追溯全栈依赖链：前端组件 ➔ API 路由 ➔ 数据库模型。 |
|
| 提取 HTTP 方法、状态码、响应模型以及关联的前端 fetch 调用者及其置信度评分。 |
|
| 对受影响的文件执行内存内的编译器检查，对根本原因进行排序并提出 diff 补丁。 |
|
| 返回实时的全栈边界统计信息，包括节点数、边数以及故障偏离状态。 |
💻 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 许可证 授权。
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