Swagger MCP

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

Функции

• Загружает спецификацию Swagger и сохраняет ее локально для более быстрого использования.

• Возвращает список всех конечных точек, их HTTP-методов и описаний.

• Возвращает список всех моделей

• Возвращает модель

• Возвращает услугу для подключения к конечной точке

• Возвращает определения функций MCP

• Создает полные определения инструментов MCP с полной информацией о схеме

• Включает в описания инструментов инструкции, специфичные для ИИ

Related MCP server: Mcp-Swagger-Server

Предпосылки

• Node.js (v14 или выше)

• нпм или пряжа

Установка

1. Клонируйте репозиторий:

git clone https://github.com/readingdancer/swagger-mcp.git
cd swagger-mcp

2. Установите зависимости:

npm install

3. Создайте файл .env на основе файла .env.example :

cp .env.example .env

4. Обновите файл .env .

Конфигурация

Отредактируйте файл .env для настройки приложения:

• PORT : Порт, на котором будет работать сервер (по умолчанию: 3000)

• NODE_ENV : Среда (разработка, производство, тестирование)

• LOG_LEVEL : Уровень ведения журнала (информация, ошибка, отладка)

Использование

Создание приложения

Создайте приложение:

npm run build

Это скомпилирует код TypeScript, готовый к использованию в качестве сервера MCP.

Работает как сервер MCP

Для запуска в качестве сервера MCP для интеграции с Cursor и другими приложениями:

node build/index.js

Использование MCP-инспектора

Чтобы запустить MCP Inspector для отладки:

npm run inspector

Добавление к курсору

Чтобы добавить этот MCP-сервер в Cursor:

1. Откройте Настройки курсора > Функции > MCP

2. Нажмите «+ Добавить новый сервер MCP»

3. Введите имя сервера (например, «Swagger MCP»)

4. Выберите «stdio» в качестве типа транспорта.

5. Введите команду для запуска сервера: node path/to/swagger-mcp/build/index.js а затем, если необходимо, добавьте аргументы командной строки, как указано выше.

6. Нажмите «Добавить».

Инструменты Swagger MCP теперь будут доступны для Cursor Agent в Composer.

Доступные инструменты Swagger MCP

На сервере MCP доступны следующие инструменты:

• getSwaggerDefinition : загружает определение Swagger с URL-адреса

• listEndpoints : список всех конечных точек из определения Swagger

• listEndpointModels : список всех моделей, используемых определенной конечной точкой.

• generateModelCode : Генерирует код TypeScript для модели

• generateEndpointToolCode : генерирует код TypeScript для определения инструмента MCP

Доступные подсказки Swagger MCP

Сервер также предоставляет подсказки MCP, которые направляют помощников ИИ по общим рабочим процессам:

• add-endpoint : пошаговое руководство по добавлению новой конечной точки с использованием инструментов Swagger MCP

Чтобы использовать подсказку, клиенты могут сделать запрос prompts/get с именем подсказки и необязательными аргументами:

{
  "method": "prompts/get",
  "params": {
    "name": "add-endpoint",
    "arguments": {
      "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json",
      "endpointPath": "/pets/{id}",
      "httpMethod": "GET"
    }
  }
}

В ответ на запрос будет выведен ряд сообщений, которые проведут помощника на основе искусственного интеллекта через точный процесс, необходимый для добавления новой конечной точки.

Настройка вашего нового проекта

Сначала попросите агента получить файл Swagger, обязательно сообщите ему URL-адрес файла Swagger или, по крайней мере, способ его найти. Это позволит загрузить файл и сохранить его локально с хешированным именем файла. Это имя файла будет автоматически добавлено в файл настроек .swagger-mcp в корне вашего текущего решения.

Автоматически сгенерированный файл конфигурации .swagger-mcp

SWAGGER_FILENAME = TheFilenameOfTheLocallyStoredSwaggerFile

Этот простой файл конфигурации связывает ваш текущий проект с определенным API Swagger. В будущем мы можем использовать его для хранения дополнительных сведений.

После настройки MCP сможет найти ваше определение Swagger и связать его с вашим текущим решением, что сократит количество вызовов API, необходимых для получения проекта и задач, связанных с решением, над которым вы работаете.

Улучшенный генератор кода инструмента MCP

Генератор кода инструмента MCP был улучшен для предоставления более полных и удобных определений инструментов:

Ключевые улучшения

1. Полная информация о схеме : генератор теперь включает полную информацию о схеме для всех моделей, включая вложенные объекты, непосредственно в inputSchema.

2. Улучшенное именование параметров : имена параметров теперь более семантические и не содержат проблемных символов, таких как точки (например, taskRequest вместо task.Request ).

3. Семантические имена инструментов : имена инструментов теперь более описательные и соответствуют единым соглашениям об именовании, основанным на методе HTTP и пути к ресурсу.

4. Поддержка файлов YAML Swagger : генератор теперь поддерживает файлы определений Swagger как JSON, так и YAML.

5. Улучшенная документация : созданные определения инструментов включают в себя исчерпывающие описания всех параметров и свойств.

6. Отсутствие внешних зависимостей : сгенерированный код не требует импорта внешних файлов модели, что делает его более автономным и простым в использовании.

7. Инструкции, специальные для ИИ : описания инструментов теперь включают специальные инструкции для агентов ИИ, помогающие им понять, как эффективно использовать инструменты.

Пример использования

Чтобы создать определение инструмента MCP для конечной точки:

import generateEndpointToolCode from './services/generateEndpointToolCode.js';

const toolCode = await generateEndpointToolCode({
  path: '/pets',
  method: 'POST',
  swaggerFilePath: './petstore.json',
  singularizeResourceNames: true
});

console.log(toolCode);

Это позволит создать полное определение инструмента MCP с полной информацией о схеме для конечной точки POST /pets.

Лицензия

Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE .

MCP предлагает использовать помощников с искусственным интеллектом

Чтобы помочь помощникам ИИ эффективно использовать инструменты Swagger MCP, мы создали набор подсказок, которые направляют их через общие задачи. Эти подсказки предоставляют пошаговые инструкции для таких процессов, как добавление новых конечных точек, использование сгенерированных моделей и многое другое.

Полную коллекцию подсказок смотрите в файле PROMPTS.md .

Пример использования: когда вы просите помощника на основе искусственного интеллекта добавить новую конечную точку в ваш проект, вы можете сослаться на подсказку «Добавление новой конечной точки», чтобы убедиться, что помощник выполнит правильный процесс в правильном порядке.