Skip to main content
Glama
deenesjakoruzh
The-Swarm-Corporation

openapi-to-mcp

by The-Swarm-Corporation
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

MCP Scribe

Преобразуйте любую схему OpenAPI в production-grade MCP-сервер.

PyPI Python License

Swarms GitHub Swarms website Discord Twitter

Related MCP server: Any API MCP Server

Обзор

Укажите MCP Scribe на схему OpenAPI — и получите MCP-сервер.

Каждая операция в спецификации становится инструментом, который может вызывать модель, — с уже настроенными JSON Schema, учётными данными, повторами, ограничением частоты запросов и формированием ответов. Нет сгенерированного кода, который нужно поддерживать, и нет слоя адаптера, который нужно синхронизировать — спецификация является источником истины, а сервер выводится из неё при запуске.

MCP Scribe создан для команд, которые предоставляют реальные API языковым моделям, где важнейшие сценарии отказов — это утечка учётных данных, бесконтрольные повторы запросов к платному эндпоинту и слишком большая поверхность инструментов, которую модель не может обойти.

Установка

pip install mcp-scribe

Из исходного кода, как глобальный CLI:

git clone https://github.com/kyegomez/mcp-scribe && cd mcp-scribe
uv tool install --editable ".[http]"

Дополнительный пакет http устанавливает uvicorn и starlette, которые требуются только для HTTP-транспорта. Серверу stdio не нужно ни то, ни другое.

Требования: Python 3.10 – 3.13.

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

Разверните общий сервер

Одна команда. Спецификация на входе — сервер на выходе.

mcp-scribe deploy https://api.swarms.world/openapi.json --port 8000

Вызов этого сервера

import asyncio
import os
import sys

from dotenv import load_dotenv
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
from mcp.shared._httpx_utils import create_mcp_http_client

load_dotenv()

# Streamable HTTP path defaults to /mcp (see transport.path).
MCP_URL = "http://127.0.0.1:8000/mcp"


async def main() -> None:
    api_key = os.environ.get("SWARMS_API_KEY")
    if not api_key:
        sys.exit(
            "set SWARMS_API_KEY first: export SWARMS_API_KEY=sk-..."
        )

    http = create_mcp_http_client(headers={"x-api-key": api_key})
    async with http, streamable_http_client(
        MCP_URL, http_client=http
    ) as (read, write), ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool(
            "get_available_models_v1_models_available_get",
            {},
        )
        print(result.content[0].text)


if __name__ == "__main__":
    asyncio.run(main())

Команды CLI

Usage: mcp-scribe [OPTIONS] COMMAND [ARGS]...

Turn any OpenAPI schema URL into a production-grade MCP server.

Options:
  --help          Show this message and exit.

Commands:
  serve     Run the MCP server.
  deploy    Serve over HTTP with production defaults. The short path to a shared server.
  inspect   Show the tools a spec produces — the fastest way to validate a setup.
  call      Invoke one tool from the terminal — the same code path the server uses.
  generate  Write a self-contained, deployable MCP server project for a spec.
  install   Build the server and register it with your MCP client in one step.
  version   Print the version.

Ключевые возможности

Возможность

Что она даёт

Универсальный приём спецификаций

OpenAPI 3.1, 3.0 и Swagger 2.0 из URL, файла или stdin — JSON или YAML. Swagger 2.0 конвертируется заранее; внешние и рекурсивные $ref предварительно загружаются и разрешаются.

Генерация инструментов без кода

Один MCP-инструмент на операцию, выдаваемый как JSON Schema 2020-12 с полной матрицей style/explode, $defs для рекурсивных моделей и автоматическим уплощением тела запроса для точности вызова инструментов.

Изоляция учётных данных

Параметры учётных данных, объявленные в спецификации, удаляются из схем инструментов и подставляются во время запроса. Модель никогда не просят предоставить секрет, которым она не располагает.

Корпоративная аутентификация

API-ключ (заголовок, query, cookie), bearer, HTTP basic, учётные данные клиента OAuth2 с автоматическим обновлением и произвольные статические заголовки — компонуемые, применяются к каждому запросу.

Изоляция мультитенантности

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

Устойчивость по умолчанию

Экспоненциальная задержка с полным джиттером с учётом Retry-After, автоматический выключатель на хост, токен-бакет, ограничение параллелизма и бюджет реального времени на каждый вызов инструмента.

Безопасные по умолчанию повторы

POST и PATCH никогда не повторяются, если это явно не включено. Повторная отправка платного запроса считается хуже, чем сбой.

Контроль поверхности атаки

Фильтрация по тегу, регулярному выражению пути, методу или operationId; --read-only одним флагом ограничивает сервер методами GET/HEAD/OPTIONS.

Управление контекстом

Ответы усекаются до настраиваемого бюджета с подсказкой, сообщающей модели, как сузить запрос.

Двойной транспорт

stdio для персональных серверов на пользователя; потоковый HTTP с проверкой /health и сеансами без сохранения состояния для общих развёртываний с горизонтальным масштабированием.

Гигиена секретов

Файлы .env, переменные окружения MCP_SCRIBE_* и интерполяция ${VAR} в конфигурации. Секреты хранятся в памяти как SecretStr и редактируются в выводе.

Эксплуатационные инструменты

inspect для проверки конфигурации без запуска, call --dry-run для просмотра точного исходящего запроса, структурированное JSON-логирование и горячая перезагрузка спецификации.

Развёртываемые артефакты

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

Документация

Документ

Содержание

docs/DOCS.md

Полное руководство пользователя — ментальная модель, транспорты, учётные данные, мультитенантность, фильтрация, формирование схем, надёжность, отладка, развёртывание и устранение неполадок.

docs/REFERENCE.md

Исчерпывающий справочник — каждая команда и флаг CLI, каждый ключ конфигурации с типами и значениями по умолчанию, полная таблица переменных окружения, Python API и иерархия исключений.

CLAUDE.md

Руководство для контрибьюторов и агентов — команды, архитектура по модулям, ключевые инварианты, соглашения и подводные камни.

MCP_SCRIBE_SKILL.md

Определение навыка агента — как автономный агент должен выбирать команды, проверять конфигурации и обращаться с учётными данными.

Лицензия

Apache-2.0. См. LICENSE.

Цитирование

@misc{mcpscribe2026,
    title   = {mcp-scribe: production-grade MCP servers from OpenAPI schemas},
    author  = {Gomez, Kye},
    year    = {2026},
    url     = {https://github.com/kyegomez/mcp-scribe}
}
@misc{mcp2024,
    title   = {Model Context Protocol},
    author  = {Anthropic},
    year    = {2024},
    url     = {https://modelcontextprotocol.io}
}

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivitySlowing
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers