Субмиллисекундный слой контрактов и верификации AST для AI-агентов кодирования
Когда AI-агенты кодирования (Cursor, Claude Code, Windsurf, Antigravity) редактируют бэкенд-модели или API-маршруты в full-stack кодовых базах, юнит-тесты бэкенда часто проходят, в то время как фронтенд молча ломается в продакшене:
Агент изменяет параметр API или поле Pydantic/SQLAlchemy в backend/routes.py.
Бэкенд-тесты проходят изолированно. Ничто не предупреждает агента.
React/Next.js клиент, вызывающий эту конечную точку через границу, падает с ошибками времени выполнения.
StackBridge-MCP — это постоянно активный сервер Model Context Protocol (MCP), который анализирует full-stack 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: Stratum MCP Server
🌲 Tree-sitter AST-граф: Анализирует Next.js (fetch, Axios, React Query) ↔ FastAPI-маршруты ↔ SQLAlchemy ORM-модели без тяжёлых LSP-сайдкаров или импортов времени выполнения.
⚡ Обход менее чем за 1 мс: Постоянная база данных SQLite WAL с рекурсивными общими табличными выражениями (0.75 мс задержка запроса обхода).
📉 Сокращение токенов промпта на 99.74%: Заменяет массивные дампы кода из нескольких файлов компактными, математически точными срезами AST-контрактов.
🛡️ Ранжирование диагностики первопричин: BFS на основе расстояния в графе ранжирует ошибки (🔴 ПЕРВИЧНАЯ ПРИЧИНА vs ⚠️ КАСКАДНАЯ ПОЛОМКА) и выводит немедленные Git-дифф патчи.
🧪 Выбор тестов по влиянию: Изолирует наборы тестов, затронутые изменением схемы, и подсвечивает непроверенные пути радиуса поражения (0% покрытия).
🌐 Интерактивное полотно: Встроенный визуализатор трипартита на localhost (stackbridge ui) по адресу http://127.0.0.1:3456.
🔄 Непрерывный интеллект: Фоновый демон отслеживания файлов (stackbridge watch) и генератор живого контекста AGENTS.md.
Эмпирическая производительность, измеренная на fastapi-realworld-example-app (44 файла, 23 узла AST-зависимостей, 10 межграничных рёбер):
Показатель бенчмарка | Сырой дамп кодовой базы | Компактный срез StackBridge | Улучшение / Задержка |
Размер окна контекста |
|
| 📉 Сокращение на 99.74% |
Обход радиуса поражения | Полнорепозиторный поиск: | Рекурсивный CTE SQLite: | ⚡ Ускорение в 200 раз |
Верификация компилятором | Глобальный линтер: | Движок на базовом диффе: | 🛡️ Ноль ложных срабатываний |
Автоматизированный набор тестов | — | 56 / 56 тестов проходят | ✅ 100% прохождение |
Полную методологию бенчмарков см. в docs/benchmarks.md и REAL_WORLD_BENCHMARK.md.
uvx)uvx stackbridge servepip install stackbridge
stackbridge serveПодключите StackBridge к вашему AI-программисту через стандартный JSON-RPC 2.0 stdio:
.cursor/mcp.json){
"mcpServers": {
"stackbridge": {
"command": "uvx",
"args": ["stackbridge", "serve"]
}
}
}claude_desktop_config.json){
"mcpServers": {
"stackbridge": {
"command": "python",
"args": ["-m", "stackbridge.main", "serve", "--transport", "stdio"]
}
}
}StackBridge предоставляет агентам кодирования высокоэргономичные инструменты:
Имя инструмента | Аргументы | Описание |
|
| Прослеживает full-stack цепочку зависимостей: компонент фронтенда ➔ API-маршрут ➔ модель базы данных. |
|
| Извлекает HTTP-методы, коды состояния, модели ответов и связанные вызовы fetch на фронтенде с оценкой уверенности. |
|
| Запускает компиляторные проверки в памяти по затронутым файлам, ранжируя первопричины и предлагая дифф-патчи. |
|
| Возвращает статистику границ full-stack в реальном времени: количество узлов, рёбер и статус дрейфа поломок. |
# 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.mdStackBridge-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.
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 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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.
Returns stack health diagnostics, graph statistics, and verification metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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.
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 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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.
Runs compiler and schema verification across all files impacted by a change.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No | . | |
| modified_files | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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.
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 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_route_contractget_stack_healthtrace_fullstack_pathverify_breakageverify_schema_changeTwo 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.
Live React design-system APIs, patterns, and code validation so AI agents build real UI, not slop.
Architecture compiler for AI code. 11 tools, 92 actions, 872 Lean4 proofs, 100/100 self-cert.
AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).
Coding agents run multi-leg cross-chain DeFi. Legs re-derived from your sentence before signing.
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
