SpecBridge MCP

SpecBridge MCP — это стартовый MCP-проект типа «клонируй и владей» для предоставления AI-агентам данных о контрактах OpenAPI/Huma. Он превращает спецификации OpenAPI/Huma в детерминированные метаданные эндпоинтов, схемы, факты валидации, ссылочные DTO и объявления TypeScript, которые агенты могут использовать перед внесением изменений в код фронтенда или клиента.

Этот проект намеренно ориентирован на использование в репозитории, а не на публикацию в npm: клонируйте его, адаптируйте реестр бэкендов под свои частные или публичные спецификации и зарегистрируйте локальный MCP-сервер в хосте вашего агента. Реализация сохраняет нейтральность ядра, избегая изменения файлов в downstream-проектах, используя нейтральный публичный демо-бэкенд, поддерживая несколько внедряемых бэкендов и рассматривая выведенные вспомогательные данные как «лучшую попытку», а не как гарантию.

Статус: экспериментальный. Поверхность инструментов полезна для локальной автоматизации, но репозиторий предназначен для того, чтобы каждая команда владела им и адаптировала под себя.

Краткая история

SpecBridge MCP начинался как личный внутренний инструмент в SesameLab для улучшения цикла разработки вокруг контрактов бэкенд-API. На практике предоставление AI-агентам структурированных данных контрактов OpenAPI/Huma через MCP уменьшило количество галлюцинаций по сравнению с тем, когда их просили читать страницы документации API напрямую.

Что он предоставляет

• Настраиваемый реестр бэкендов для одной или нескольких спецификаций, совместимых с OpenAPI/Huma

• Демо-бэкенд с нулевой настройкой, использующий реальный публичный URL OpenAPI

• Загрузка и обновление спецификаций с поддержкой JSON/YAML

• Список эндпоинтов и фильтрация

• Контрактные пакеты эндпоинтов с детерминированными фактами:

  • метаданные операции

  • параметры

  • схемы запросов и ответов

  • ссылочные схемы компонентов

  • объявления TypeScript DTO в области видимости эндпоинта

  • факты валидации, такие как required, nullable, enum, format, массивы, карты и композиция

• Генерация объявлений TypeScript DTO из схем компонентов

• Вспомогательные средства для предложений, которые явно вторичны по отношению к детерминированным фактам спецификации

Не является целью

• Публикация этого проекта в npm для v1

• Предоставление общей устанавливаемой CLI-абстракции

• Изменение downstream-репозиториев фронтенда/клиента

• Становление специфичным для фреймворка генератором клиентов или SDK

• Хостинг спецификаций или удаленное хранение данных API команды

Требования

• Node.js 18+

• pnpm 10+

Установка

git clone <your-fork-or-copy-url> specbridge-mcp
cd specbridge-mcp
pnpm install
pnpm build

Настройка бэкендов

SpecBridge поставляется с файлом openapi.backends.json, указывающим на публичный демо-API, чтобы инструменты работали сразу.

Чтобы использовать свои собственные API, отредактируйте openapi.backends.json или укажите OPENAPI_BACKENDS_FILE на другой JSON-файл.

[
  {
    "id": "public-demo",
    "name": "Public Demo API",
    "specUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "description": "Public OpenAPI demo backend",
    "domainHints": ["/pet", "/store", "/user"]
  },
  {
    "id": "local-service",
    "name": "Local Service API",
    "specUrl": "http://localhost:8080/openapi.json",
    "fallbackSpecUrls": ["http://localhost:8080/openapi.yaml"],
    "description": "Your local service contract"
  }
]

Приоритет конфигурации

Для вызова инструмента сначала проверяется явное переопределение specUrl для этого вызова.

Источники реестра бэкендов объединяются в следующем порядке, причем последующие источники переопределяют предыдущие по id:

1. Встроенный публичный демо-бэкенд

2. Локальный для репозитория openapi.backends.json (если присутствует)

3. OPENAPI_BACKENDS_FILE (если задан)

4. OPENAPI_BACKENDS (если задан)

DEFAULT_BACKEND_ID выбирает бэкенд по умолчанию. Если не задан, SpecBridge использует swagger-petstore.

Переменные окружения

• MCP_TRANSPORT: stdio или http

• MCP_HTTP_HOST: хост для привязки HTTP

• MCP_HTTP_PORT: HTTP-порт

• MCP_HTTP_PATH: путь к эндпоинту MCP, например /mcp

• MCP_HTTP_STATELESS: установите true для режима stateless HTTP

• DEFAULT_BACKEND_ID: ID бэкенда по умолчанию

• OPENAPI_BACKENDS: JSON-массив конфигураций бэкендов

• OPENAPI_BACKENDS_FILE: путь к JSON-файлу конфигурации бэкенда

• OPENAPI_FETCH_TIMEOUT_MS: таймаут получения для загрузки спецификации

• OPENAPI_CACHE_TTL_MS: TTL кэша спецификаций в памяти

• OPENAPI_ENABLE_SWAGGER_UI_SCRIPT_EXTRACTION: включение строгого извлечения JSON-объектов из статических скриптов Swagger UI; полученный JavaScript никогда не выполняется

Запуск

Режим stdio

pnpm mcp
# or
./mcp-server.sh

Режим HTTP

pnpm mcp:http

Режим stateless HTTP:

pnpm mcp:http:stateless

Настройка хоста MCP

Конфигурация stdio на основе команд

{
  "mcpServers": {
    "specbridge-mcp": {
      "command": "/absolute/path/to/specbridge-mcp/mcp-server.sh"
    }
  }
}

Пример config.toml для Codex

[mcp_servers.specbridge-mcp]
args = ["/absolute/path/to/specbridge-mcp/mcp-server.sh"]
command = "bash"

HTTP URL

Запустите сервер:

./mcp-server.sh --transport http --host 127.0.0.1 --port 3000 --path /mcp

Затем подключите ваш хост к:

• http://127.0.0.1:3000/mcp

Если у вашего хоста проблемы с состоянием сессии, повторите попытку с флагом --stateless.

Инструменты

Рекомендуемый порядок действий:

1. list_backends

2. load_openapi_spec

3. list_api_endpoints

4. get_endpoint_contract

5. generate_typescript_dto

list_backends

Выводит список настроенных целевых бэкендов, ID бэкенда по умолчанию и необязательные подсказки по доменам.

load_openapi_spec

Загружает или обновляет спецификацию, совместимую с OpenAPI/Huma, для бэкенда. Поддерживает прямые переопределения specUrl.

list_api_endpoints

Выводит список эндпоинтов из загруженной спецификации с необязательными фильтрами по тегу, методу, подстроке пути и лимиту.

get_endpoint_contract

Возвращает детерминированный контрактный пакет эндпоинта: метаданные операции, параметры, тело запроса, ответы, ссылочные схемы, объявления TypeScript DTO в области видимости эндпоинта, факты валидации и вспомогательные подсказки.

generate_typescript_dto

Генерирует объявления TypeScript DTO из имени схемы компонента и включает ссылочные вложенные типы DTO.

propose_new_endpoint

Возвращает предложение эндпоинта и DTO, основанное на лучших попытках, в соответствии с шаблонами, найденными в текущей спецификации. Рассматривайте это как помощь агенту, а не как детерминированную гарантию.

Разработка

pnpm install
pnpm check
pnpm build
pnpm test

Полезные скрипты:

• pnpm check: проверка Biome

• pnpm format: применение форматирования Biome

• pnpm lint: только линтинг Biome

• pnpm build: чистая сборка TypeScript

• pnpm test: сборка и запуск всех тестов

• pnpm test:e2e: сборка и запуск дымовых тестов MCP

Руководство «клонируй и владей»

SpecBridge намеренно ориентирован на репозиторий. Держите ядро маленьким, адаптируйте конфигурацию бэкенда локально и позвольте downstream-агентам решать, как редактировать ваш клиентский код. Если вашей команде нужна пользовательская аутентификация, внутренние правила именования или дополнительные факты о контрактах, добавьте их в свой клон, а не боритесь с глобальной абстракцией пакета.