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 для прямого запуска пакета:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123" \
  --transport http \
  --port 3000

Взаимодействие с сервером с помощью 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