OpenAPI Schema Explorer

MCP OpenAPI Обозреватель схем

Сервер MCP (Model Context Protocol), который обеспечивает эффективный доступ к спецификациям OpenAPI (v3.0) и Swagger (v2.0) через ресурсы MCP .

Цель проекта

Основная цель этого проекта — позволить клиентам MCP (например, Cline или Claude Desktop) исследовать структуру и детали больших спецификаций OpenAPI без необходимости загружать весь файл в контекстное окно LLM. Это достигается путем предоставления частей спецификации через ресурсы MCP, которые хорошо подходят для исследования данных только для чтения.

Этот сервер поддерживает загрузку спецификаций как из локальных путей файлов, так и из удаленных HTTP/HTTPS URL. Спецификации Swagger v2.0 автоматически преобразуются в OpenAPI v3.0 при загрузке.

Почему MCP Resources?

Протокол контекста модели определяет как ресурсы , так и инструменты .

• Ресурсы: представляют источники данных (например, файлы, ответы API). Они идеально подходят для доступа только для чтения и исследования клиентами MCP (например, просмотр путей API в Claude Desktop).
• Инструменты: представляют собой исполняемые действия или функции, часто используемые магистрами права для выполнения задач или взаимодействия с внешними системами.

Хотя существуют и другие серверы MCP, которые предоставляют доступ к спецификациям OpenAPI через Tools , этот проект специально фокусируется на предоставлении доступа через Resources . Это делает его особенно полезным для прямого исследования в клиентских приложениях MCP.

Более подробную информацию о клиентах MCP и их возможностях см. в документации по клиентам MCP .

Установка

Для рекомендуемых методов использования ( npx и Docker, описанных ниже) не требуется отдельного шага установки . Ваш клиент MCP загрузит пакет или извлечет образ Docker автоматически на основе предоставленной вами конфигурации.

Однако, если вы предпочитаете или вам необходимо установить сервер отдельно, у вас есть два варианта:

1. Глобальная установка: Вы можете установить пакет глобально с помощью npm:
   npm install -g mcp-openapi-schema-explorer
   См. Метод 3 ниже, чтобы узнать, как настроить клиент MCP для использования глобально установленного сервера.
2. Локальная разработка/установка: вы можете клонировать репозиторий и собрать его локально:
   git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git cd mcp-openapi-schema-explorer npm install npm run build
   См. Метод 4 ниже, чтобы узнать, как настроить клиент MCP для запуска сервера из локальной сборки с помощью node .

Добавление сервера к вашему MCP-клиенту

Этот сервер предназначен для запуска клиентами MCP (например, Claude Desktop, Windsurf, Cline и т. д.). Чтобы использовать его, вы добавляете запись конфигурации в файл настроек клиента (часто файл JSON). Эта запись сообщает клиенту, как выполнять процесс сервера (например, с помощью npx , docker или node ). Сам сервер не требует отдельной настройки, кроме аргументов командной строки, указанных в записи настроек клиента.

Ниже приведены распространенные методы добавления записи сервера в конфигурацию вашего клиента.

Метод 1: npx (рекомендуется)

Рекомендуется использовать npx , поскольку это позволяет избежать глобальной/локальной установки и гарантирует, что клиент использует последнюю опубликованную версию.

Пример записи конфигурации клиента (метод npx):

Добавьте следующий объект JSON в раздел mcpServers файла конфигурации вашего клиента MCP. Эта запись инструктирует клиента о том, как запустить сервер с помощью npx :

Примечания по конфигурации:

• Замените "My API Spec (npx)" на уникальное имя этого экземпляра сервера в вашем клиенте.
• Замените <path-or-url-to-spec> на абсолютный локальный путь к файлу или полный удаленный URL-адрес вашей спецификации.
• --output-format необязателен ( json , yaml , json-minified ), по умолчанию используется json .
• Чтобы изучить несколько спецификаций, добавьте отдельные записи в mcpServers , каждая из которых имеет уникальное имя и указывает на отдельную спецификацию.

Метод 2: Докер

Вы можете указать своему клиенту MCP запустить сервер, используя официальный образ Docker: kadykov/mcp-openapi-schema-explorer .

Примеры записей конфигурации клиента (метод Docker):

Добавьте один из следующих объектов JSON в раздел mcpServers файла конфигурации вашего клиента MCP. Эти записи инструктируют клиента о том, как запустить сервер с помощью docker run :

• Удаленный URL: Передайте URL-адрес непосредственно в docker run .
• Использование удаленного URL:
  { "mcpServers": { "My API Spec (Docker Remote)": { "command": "docker", "args": [ "run", "--rm", "-i", "kadykov/mcp-openapi-schema-explorer:latest", "<remote-url-to-spec>" ], "env": {} } } }
• Использование локального файла: (требуется монтирование файла в контейнер)
  { "mcpServers": { "My API Spec (Docker Local)": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/full/host/path/to/spec.yaml:/spec/api.yaml", "kadykov/mcp-openapi-schema-explorer:latest", "/spec/api.yaml", "--output-format", "yaml" ], "env": {} } } }
  Важно: замените /full/host/path/to/spec.yaml на правильный абсолютный путь на вашей хост-машине. Путь /spec/api.yaml — это соответствующий путь внутри контейнера.

Метод 3: Глобальная установка (менее распространённый)

Если вы установили пакет глобально с помощью npm install -g , вы можете настроить клиент для его непосредственного запуска.

Пример записи конфигурации клиента (метод глобальной установки):

Добавьте следующую запись в файл конфигурации вашего клиента MCP. Это предполагает, что команда mcp-openapi-schema-explorer доступна в среде выполнения PATH клиента.

• Убедитесь, что command ( mcp-openapi-schema-explorer ) доступна в переменной среды PATH, используемой вашим клиентом MCP.

Метод 4: Локальная разработка/установка

Этот метод полезен, если вы клонировали репозиторий локально для разработки или запуска измененной версии.

Шаги настройки (запустите один раз в терминале):

1. Клонируйте репозиторий: git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
2. Перейдите в каталог: cd mcp-openapi-schema-explorer
3. Установка зависимостей: npm install
4. Соберите проект: npm run build (или just build )

Пример записи конфигурации клиента (локальный метод разработки):

Добавьте следующую запись в файл конфигурации вашего клиента MCP. Это предписывает клиенту запустить локально созданный сервер с помощью node .

Важно: замените /full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js на правильный абсолютный путь к созданному файлу index.js в клонированном репозитории.

Функции

• Доступ к ресурсам MCP: изучите спецификации OpenAPI с помощью интуитивно понятных URI ( openapi://info , openapi://paths/... , openapi://components/... ).
• Поддержка OpenAPI v3.0 и Swagger v2.0: загружает оба формата, автоматически конвертируя v2.0 в v3.0.
• Локальные и удаленные файлы: загрузка спецификаций из локальных путей к файлам или URL-адресов HTTP/HTTPS.
• Эффективность токенов: разработан для минимизации использования токенов для LLM за счет предоставления структурированного доступа.
• Несколько форматов вывода: получайте подробные представления в формате JSON (по умолчанию), YAML или минифицированном JSON ( --output-format ).
• Динамическое имя сервера: имя сервера в клиентах MCP отражает info.title из загруженной спецификации.
• Преобразование ссылок: внутренние $ref ( #/components/... ) преобразуются в кликабельные URI MCP.

Доступные ресурсы MCP

Этот сервер предоставляет следующие шаблоны ресурсов MCP для изучения спецификации OpenAPI.

Понимание многозначных параметров ( * )

Некоторые шаблоны ресурсов включают параметры, заканчивающиеся звездочкой ( * ), например {method*} или {name*} . Это указывает на то, что параметр принимает несколько значений, разделенных запятыми . Например, чтобы запросить сведения для методов GET и POST пути, вы должны использовать URI типа openapi://paths/users/get,post . Это позволяет извлекать сведения для нескольких элементов в одном запросе.

Шаблоны ресурсов:

• openapi://{field}
  • Описание: Доступ к полям верхнего уровня документа OpenAPI (например, info , servers , tags ) или выводит список содержимого paths или components . Конкретные доступные поля зависят от загруженной спецификации.
  • Пример: openapi://info
  • Вывод: text/plain список для paths и components ; настроенный формат (JSON/YAML/минифицированный JSON) для других полей.
  • Дополнения: Предоставляет динамические предложения для {field} на основе фактических ключей верхнего уровня, найденных в загруженной спецификации.
• openapi://paths/{path}
  • Описание: Перечисляет доступные методы HTTP (операции) для определенного пути API.
  • Параметр: {path} — строка пути API. Должна быть закодирована в URL (например, /users/{id} становится users/{id} ).
  • Пример: openapi://paths/users/{id}
  • Вывод: text/plain список методов.
  • Дополнения: Предоставляет динамические предложения для {path} на основе путей, найденных в загруженной спецификации (в кодировке URL).
• openapi://paths/{path}/{method*}
  • Описание: Получает подробную спецификацию для одной или нескольких операций (методов HTTP) по определенному пути API.
  • Параметры:
    • {path} — строка пути API. Должна быть закодирована в URL .
    • {method*} — один или несколько методов HTTP (например, get , post , get,post ). Регистр не учитывается.
  • Пример (одиночный): openapi://paths/users/{id}/get
  • Пример (несколько): openapi://paths/users/{id}/get,post
  • Вывод: настроенный формат (JSON/YAML/минифицированный JSON).
  • Дополнения: Предоставляет динамические предложения для {path} . Предоставляет статические предложения для {method*} (общие HTTP-глаголы, такие как GET, POST, PUT, DELETE и т. д.).
• openapi://components/{type}
  • Описание: Перечисляет имена всех определенных компонентов определенного типа (например, schemas , responses , parameters ). Конкретные доступные типы зависят от загруженной спецификации. Также предоставляет краткое описание для каждого перечисленного типа.
  • Пример: openapi://components/schemas
  • Вывод: text/plain список названий компонентов с описаниями.
  • Дополнения: Предоставляет динамические предложения для {type} на основе типов компонентов, найденных в загруженной спецификации.
• openapi://components/{type}/{name*}
  • Описание: Получает подробную спецификацию для одного или нескольких именованных компонентов определенного типа.
  • Параметры:
    • {type} — Тип компонента.
    • {name*} — одно или несколько имен компонентов (например, User , Order , User,Order ). С учетом регистра.
  • Пример (одиночный): openapi://components/schemas/User
  • Пример (несколько): openapi://components/schemas/User,Order
  • Вывод: настроенный формат (JSON/YAML/минифицированный JSON).
  • Дополнения: Предоставляет динамические предложения для {type} . Предоставляет динамические предложения для {name*}только если загруженная спецификация содержит ровно один тип компонента в целом (например, только schemas ). Это ограничение существует, поскольку в настоящее время MCP SDK не поддерживает предоставление дополнений, ограниченных выбранным {type} ; предоставление всех имен по всем типам может ввести в заблуждение.

Внося вклад

Вклады приветствуются! Пожалуйста, ознакомьтесь с файлом CONTRIBUTING.md для получения инструкций по настройке среды разработки, запуску тестов и отправке изменений.

Релизы

В этом проекте используется semantic-release для автоматизированного управления версиями и публикации пакетов на основе Conventional Commits .

Планы на будущее

(Будущие планы будут определены)