Skip to main content
Glama

🌉 StackBridge-MCP

Субмиллисекундный слой контрактов и верификации AST для AI-агентов кодирования

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


💡 Зачем нужен StackBridge?

Когда AI-агенты кодирования (Cursor, Claude Code, Windsurf, Antigravity) редактируют бэкенд-модели или API-маршруты в full-stack кодовых базах, юнит-тесты бэкенда часто проходят, в то время как фронтенд молча ломается в продакшене:

  1. Агент изменяет параметр API или поле Pydantic/SQLAlchemy в backend/routes.py.

  2. Бэкенд-тесты проходят изолированно. Ничто не предупреждает агента.

  3. 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()              BillingAccount

Related MCP server: Carto 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

Улучшение / Задержка

Размер окна контекста

19 705 токенов

51 токен

📉 Сокращение на 99.74%

Обход радиуса поражения

Полнорепозиторный поиск: ~150 мс

Рекурсивный CTE SQLite: 0.75 мс

Ускорение в 200 раз

Верификация компилятором

Глобальный линтер: ~3 500 мс

Движок на базовом диффе: 312 мс

🛡️ Ноль ложных срабатываний

Автоматизированный набор тестов

56 / 56 тестов проходят

100% прохождение

Полную методологию бенчмарков см. в docs/benchmarks.md и REAL_WORLD_BENCHMARK.md.


🚀 Быстрый старт

Вариант 1: Выполнение без установки (рекомендуется через uvx)

uvx stackbridge serve

Вариант 2: Установка через pip

pip install stackbridge
stackbridge serve

⚙️ Конфигурация клиента

Подключите StackBridge к вашему AI-программисту через стандартный 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-инструментов

StackBridge предоставляет агентам кодирования высокоэргономичные инструменты:

Имя инструмента

Аргументы

Описание

trace_fullstack_path

symbol_or_path: str

Прослеживает full-stack цепочку зависимостей: компонент фронтенда ➔ API-маршрут ➔ модель базы данных.

get_route_contract

route_path: str

Извлекает HTTP-методы, коды состояния, модели ответов и связанные вызовы fetch на фронтенде с оценкой уверенности.

verify_schema_change

modified_files: dict

Запускает компиляторные проверки в памяти по затронутым файлам, ранжируя первопричины и предлагая дифф-патчи.

get_stack_health

repo_path: str

Возвращает статистику границ full-stack в реальном времени: количество узлов, рёбер и статус дрейфа поломок.


💻 Справочник 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

Maintenance

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

Related MCP Servers

  • 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
  • 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

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

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

  • 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