StackBridge
🌉 StackBridge-MCP
AI 코딩 에이전트를 위한 Sub-1ms Cross-Stack AST 계약 및 검증 레이어
💡 StackBridge를 사용하는 이유?
AI 코딩 에이전트(Cursor, Claude Code, Windsurf, Antigravity)가 풀스택 코드베이스에서 백엔드 모델이나 API 라우트를 편집할 때, 백엔드 단위 테스트는 자주 통과하지만 프론트엔드는 프로덕션에서 조용히 깨집니다:
에이전트가
backend/routes.py에서 API 매개변수나 Pydantic/SQLAlchemy 필드를 수정합니다.백엔드 테스트는 격리된 상태에서 통과합니다. 에이전트에게 아무런 경고가 없습니다.
해당 엔드포인트를 호출하는 React/Next.js 클라이언트가 경계를 넘어 런타임 오류로 실패합니다.
StackBridge-MCP는 항상 준비된 Model Context Protocol (MCP) 서버로, 풀스택 AST 관계를 파싱하고, 0.75 ms 내에 크로스 스택 블래스트 반경을 발견하며, 베이스라인 차이 컴파일러 검사를 사용하여 변경 사항을 검증하여 거짓 양성(false positive)이 없습니다.
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 그래프: 무거운 LSP 사이드카나 런타임 임포트 없이 Next.js (
fetch, Axios, React Query) ↔ FastAPI 라우트 ↔ SQLAlchemy ORM 모델을 파싱합니다.⚡ 서브 1ms 순회: 재귀적 공통 테이블 표현식(0.75 ms 순회 쿼리 지연 시간)을 사용하는 영구 SQLite WAL 데이터베이스.
📉 99.74% 프롬프트 토큰 감소: 대규모 다중 파일 코드 덤프를 간결하고 수학적으로 정확한 AST 계약 조각으로 대체합니다.
🛡️ 근본 원인 진단 순위: 그래프 거리 BFS가 오류를 순위화합니다(
🔴 PRIMARY ROOT CAUSEvs⚠️ CASCADING BREAKAGE). 즉각적인 Git diff 패치를 출력합니다.🧪 테스트 영향 선택: 스키마 변경에 영향을 받는 테스트 스위트를 격리하고 테스트되지 않은 블래스트 반경 경로(0% 커버리지)를 강조합니다.
🌐 대화형 캔버스:
http://127.0.0.1:3456에서 내장된 localhost 삼자 시각화 도구(stackbridge ui).🔄 지속적 인텔리전스: 백그라운드 파일 감시 데몬(
stackbridge watch) 및 라이브AGENTS.md컨텍스트 생성기.
📊 실제 벤치마크
fastapi-realworld-example-app (44개 파일, 23개 AST 종속성 노드, 10개 교차 경계 엣지)에서 측정한 경험적 성능:
벤치마크 지표 | 원시 코드베이스 덤프 | StackBridge 컴팩트 슬라이스 | 개선 / 지연 시간 |
컨텍스트 윈도우 크기 |
|
| 📉 99.74% 토큰 감소 |
블래스트 반경 순회 | 전체 저장소 검색: | SQLite 재귀 CTE: | ⚡ 200배 빠른 순회 |
컴파일러 검증 | 글로벌 린터: | 베이스라인 차이 엔진: | 🛡️ 거짓 양성 제로 |
자동화된 테스트 스위트 | — | 56 / 56 테스트 통과 | ✅ 100% 통과 |
전체 벤치마크 방법론은 docs/benchmarks.md 및 REAL_WORLD_BENCHMARK.md를 참조하세요.
🚀 빠른 시작
옵션 1: 제로 설치 실행 (uvx 권장)
uvx stackbridge serve옵션 2: 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.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No | . | |
| route_path | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| repo_path | No | ||
| symbol_or_path | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No | . | |
| modified_files | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No | . | |
| modified_files | No | ||
| schema_changes | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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
Scored across 5 tools
Two tools (verify_schema_change and verify_breakage) have identical descriptions, making them indistinguishable. Other tools are distinct but the duplication severely harms disambiguation.
All tools follow a consistent snake_case verb_noun pattern (trace_, get_, verify_, get_). No mixing of conventions.
Five tools is a well-scoped, focused set for a StackBridge server that handles dependency tracing, contract extraction, verification, and health diagnostics.
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
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
- AlicenseNot gradedqualityBmaintenanceLocal-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
- 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