openapi-md-mcp

MCP-сервер, передающий OpenAPI-спецификацию в Markdown через прогрессивное раскрытие (progressive disclosure).

Зачем

• Swagger UI (/docs) — это JS-оболочка, AI не может получить из неё содержимое

• Весь /openapi.json — это легко десятки K токенов, затаскивать его в контекст целиком слишком дорого

• Этот инструмент оставляет в постоянном контексте AI только таблицу конечных точек «ключ + сводка» (~1k токенов), по ключу можно углубиться и получить markdown-детали одной конечной точки / одной схемы — на практике экономит ~90% контекста

Related MCP server: OpenAPI MCP Server

Инструменты (прогрессивное раскрытие, выход всегда в markdown)

Ключ спуска = METHOD /path или имя схемы — берётся напрямую из вывода предыдущего уровня.

Пакетный режим (select + get_batch)

Спуск по одному ключу не отвечает на горизонтальные вопросы (для «всех аутентифицированных endpoint'ов» пришлось бы десятки раз дёргать get_endpoint по одному). Этот провал закрывает пакетный слой:

• select(patterns=["GET /v1/auth/*", "* /v1/scoring/*"], security="X-Service-Token", tag="scoring", schema_glob="Credit*")

  • элементы patterns имеют вид "METHOD /path/glob": метод может быть * (без учёта регистра); glob пути чувствителен к регистру

  • security — это имя схемы; между patterns действует OR, а с security/tag — AND

  • ноль совпадений возвращает успешный текст (доступные scheme / tag + подсказки по ослаблению фильтра), а не ошибку

• get_batch(["POST /v1/scoring/credit", "CreditBatchRequest"])

  • ключи дедуплятся и сохраняют порядок; лимит — 40; общий лимит символов рендера — 100k, при превышении рекомендуется include_refs=False или разбить на пакеты

  • include_refs=True автоматически объединяет упомянутые при рендере $ref в «общий appendix по схемам» (каждая схема рендерится только один раз)

Настройка (env)

• Спецификация поддерживает JSON и YAML; после загрузки кэшируется в процессе на 60 секунд

• Запросы идут напрямую (trust_env=False): цель — спецификация на localhost / внутренних адресах, системный прокси не используется (системный прокси macOS может перехватывать localhost и отдавать 502)

• Только чтение: никакой возможности вызывать API (заголовки аутентификации не попадают в слой MCP)

Подключение к любому репозиторию

Регистрация уровня пользователя Claude Code (одна регистрация — доступно во всех репозиториях):

claude mcp add openapi-md -s user -- \
  uv run --directory /path/to/openapi-md-mcp openapi-md-mcp

А для репозиториев, которым нужны разные источники данных, достаточно переопределить env в .mcp.json на уровне проекта.

Соответствие протоколу (MCP 2026-07-28, в просторечии 2.0)

• Имена инструментов / описания / входные схемы соответствуют §Tools спецификации (набор символов и длина имён, детерминированный порядок tools/list)

• Все пять инструментов объявляют annotations.readOnlyHint: true (только чтение)

• Семантика ошибок по §Tools Error Handling: сбой загрузки спецификации, неизвестный ключ (включая подсказки похожих ключей), недопустимые паттерны фильтрации и превышение пакетного лимита выбрасываются как tool execution error — ToolError, что на практике выглядит как CallToolResult(isError=true), и клиент закармливает подсказки модели для самокорректирующего ответа; ноль совпадений — это успешный текст, а не собственный; также не делается никакого call/API-вызова (инструмент только читает)

• Согласование версий: для stdio используется рукопожатие initialize (максимальная версия 2025-11-25); эпоха безстатных конвертов 2026-07-28 обрабатывается SDK на HTTP-транспорте (server/discover), в сценарии stdio не задействуется

Разработка

uv sync                 # 安装依赖
uv run pytest --cov=openapi_md_mcp   # 测试（fixture 为真实 OpenAPI 3.1 快照）