OpenAPI MCP-сервер

Сервер Model Context Protocol (MCP), который выставляет конечные точки OpenAPI как ресурсы MCP. Этот сервер позволяет моделям больших языков обнаруживать и взаимодействовать с API REST, определенными спецификациями OpenAPI, через протокол MCP.

Обзор

Этот сервер MCP поддерживает два метода транспортировки:

Stdio Transport (по умолчанию): для прямой интеграции с системами ИИ, такими как Claude Desktop, которые управляют соединениями MCP через стандартный ввод/вывод.
Потоковый HTTP-транспорт : для подключения к серверу по протоколу HTTP, позволяющий веб-клиентам и другим системам с поддержкой HTTP использовать протокол MCP.

Related MCP server: File Context MCP

Быстрый старт для пользователей

Вариант 1: Использование с Claude Desktop (Stdio Transport)

Нет необходимости клонировать этот репозиторий. Просто настройте Claude Desktop для использования этого сервера MCP:

Найдите или создайте файл конфигурации Claude Desktop:
- В macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Добавьте следующую конфигурацию:

{ "mcpServers": { "openapi": { "command": "npx", "args": ["-y", "@ivotoby/openapi-mcp-server"], "env": { "API_BASE_URL": "https://api.example.com", "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json", "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key" } } } }

Замените переменные среды вашей фактической конфигурацией API:
- API_BASE_URL : базовый URL вашего API
- OPENAPI_SPEC_PATH : URL или путь к вашей спецификации OpenAPI
- API_HEADERS : пары ключ:значение, разделенные запятыми, для заголовков аутентификации API.

Вариант 2: использование с HTTP-клиентами (HTTP-транспорт)

Чтобы использовать сервер с HTTP-клиентами:

Установка не требуется! Используйте npx для прямого запуска пакета:

Взаимодействие с сервером с помощью HTTP-запросов:

# Initialize a session (first request) curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"client":{"name":"curl-client","version":"1.0.0"},"protocol":{"name":"mcp","version":"2025-03-26"}}}' # The response includes a Mcp-Session-Id header that you must use for subsequent requests # and the InitializeResult directly in the POST response body. # Send a request to list tools # This also receives its response directly on this POST request. curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: your-session-id" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' # Open a streaming connection for other server responses (e.g., tool execution results) # This uses Server-Sent Events (SSE). curl -N http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id" # Example: Execute a tool (response will arrive on the GET stream) # curl -X POST http://localhost:3000/mcp \ # -H "Content-Type: application/json" \ # -H "Mcp-Session-Id: your-session-id" \ # -d '{"jsonrpc":"2.0","id":2,"method":"tools/execute","params":{"name":"yourToolName", "arguments": {}}}' # Terminate the session when done curl -X DELETE http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

Виды транспорта

Stdio-транспорт (по умолчанию)

Транспорт stdio предназначен для прямой интеграции с системами ИИ, такими как Claude Desktop, которые управляют соединениями MCP через стандартный ввод/вывод. Это самая простая настройка, не требующая настройки сети.

Когда использовать : При интеграции с Claude Desktop или другими системами, поддерживающими связь MCP на основе stdio.

Потоковый HTTP-транспорт

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

Основные характеристики :

Управление сеансом с помощью заголовка Mcp-Session-Id
HTTP-ответы для запросов initialize и tools/list отправляются синхронно в POST.
Другие сообщения от сервера к клиенту (например, результаты tools/execute , уведомления) передаются по соединению GET с использованием событий, отправленных сервером (SSE).
Поддержка методов POST/GET/DELETE

Когда использовать : Когда вам нужно предоставить доступ к серверу MCP веб-клиентам или системам, которые взаимодействуют по протоколу HTTP, а не stdio.

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

Сервер можно настроить с помощью переменных среды или аргументов командной строки:

Переменные среды

API_BASE_URL — базовый URL для конечных точек API
OPENAPI_SPEC_PATH — Путь или URL к спецификации OpenAPI
API_HEADERS — пары ключ:значение, разделенные запятыми, для заголовков API.
SERVER_NAME — имя сервера MCP (по умолчанию: «mcp-openapi-server»)
SERVER_VERSION - Версия сервера (по умолчанию: "1.0.0")
TRANSPORT_TYPE — тип используемого транспорта: «stdio» или «http» (по умолчанию: «stdio»).
HTTP_PORT — порт для HTTP-транспорта (по умолчанию: 3000)
HTTP_HOST — Хост для HTTP-транспорта (по умолчанию: «127.0.0.1»)
ENDPOINT_PATH — путь к конечной точке для HTTP-транспорта (по умолчанию: "/mcp")

Аргументы командной строки

npx @ivotoby/openapi-mcp-server \ --api-base-url https://api.example.com \ --openapi-spec https://api.example.com/openapi.json \ --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \ --name "my-mcp-server" \ --version "1.0.0" \ --transport http \ --port 3000 \ --host 127.0.0.1 \ --path /mcp

Соображения безопасности

HTTP-транспорт проверяет заголовки Origin для предотвращения атак перепривязки DNS.
По умолчанию HTTP-транспорт привязывается только к localhost (127.0.0.1)
При предоставлении доступа другим хостам рассмотрите возможность внедрения дополнительной аутентификации.

Отладка

Чтобы просмотреть журналы отладки:

При использовании транспорта stdio с Claude Desktop:
- Журналы появляются в журналах Claude Desktop
При использовании HTTP-транспорта:
npx @ivotoby/openapi-mcp-server --transport http 2>debug.log

Для разработчиков

Инструменты разработки

npm run build — собирает исходный код TypeScript
npm run clean — удаляет артефакты сборки
npm run typecheck — запускает проверку типов TypeScript
npm run lint — запускает ESLint
npm run dev — отслеживает исходные файлы и выполняет пересборку при внесении изменений
npm run inspect-watch — запускает инспектор с автоматической перезагрузкой при изменениях

Рабочий процесс разработки

Клонировать репозиторий
Установить зависимости: npm install
Запустите среду разработки: npm run inspect-watch
Внесите изменения в файлы TypeScript в src/
Сервер автоматически перестроится и перезапустится.

Внося вклад

Форк репозитория
Создать ветку функций
Внесите изменения
Запуск тестов и линтинга: npm run typecheck && npm run lint
Отправить запрос на извлечение

Лицензия

Массачусетский технологический институт

OpenAPI MCP Server