MCPGen

Генерируйте безопасные MCP-серверы с поддержкой политик на основе спецификаций OpenAPI.

MCPGen — это MVP-фреймворк на Python, ориентированный на промышленное использование, который превращает спецификации OpenAPI в безопасные по умолчанию серверы инструментов. Он может генерировать демонстрационный сервер FastAPI или сервер MCP в стиле stdio, при этом операции записи остаются заблокированными, пока будущие политики явно не разрешат их использование.

Проблема

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

MCP-серверы делают инструменты доступными для систем ИИ, но быстрые прототипы могут случайно открыть доступ к опасным операциям, таким как DELETE, POST, PATCH или PUT, без предварительной проверки.

Related MCP server: openapi-mcp

Решение

MCPGen считывает YAML- или JSON-файл OpenAPI и генерирует:

• структурированные дескрипторы инструментов

• списки безопасных доступных инструментов

• отчеты об исключенных инструментах

• схемы входных данных

• сервер FastAPI или MCP с поддержкой политик

• предварительный просмотр (dry-run)

• безопасное выполнение GET

• журналы аудита в формате JSONL

• семантическую маршрутизацию инструментов с резервным поиском по ключевым словам

Поведение по умолчанию намеренно консервативно: доступны только низкорисковые инструменты GET.

Функции

• Парсинг OpenAPI YAML/JSON

• Генерация инструментов на основе эндпоинтов

• Классификация рисков:

  • GET = низкий

  • POST, PUT, PATCH = средний

  • DELETE = высокий

• Фильтрация «безопасно по умолчанию»

• Генерация схемы входных данных на основе параметров пути/запроса и тел запросов JSON

• Семантическая маршрутизация инструментов с резервным поиском по ключевым словам

• Режим FastAPI

• Режим MCP stdio с tools/list и tools/call

• Предварительный просмотр запросов (dry-run)

• Безопасное реальное выполнение только для низкорисковых инструментов GET

• Центральный механизм политик

• Журналирование аудита в формате JSONL

• CLI-команды: generate, inspect

• Конфигурация через mcpgen.yaml

Поток архитектуры

OpenAPI spec
  -> parser
  -> tool generator
  -> risk classifier
  -> safety filter
  -> tools.json / tools.all.json / tools.embeddings.json / safety_report.json
  -> generated FastAPI or MCP server
  -> policy engine
  -> semantic/keyword router
  -> dry-run or safe GET execution
  -> audit log

Быстрый старт

Установите локально:

pip install -e .[dev]

Изучите спецификацию:

mcpgen inspect --from examples/jsonplaceholder.openapi.yaml

Сгенерируйте сервер FastAPI:

mcpgen generate --from examples/jsonplaceholder.openapi.yaml --mode fastapi --output generated_jsonplaceholder

Запустите его:

cd generated_jsonplaceholder
export API_BASE_URL=https://jsonplaceholder.typicode.com
uvicorn server:app --reload --port 8001

PowerShell:

cd generated_jsonplaceholder
$env:API_BASE_URL = "https://jsonplaceholder.typicode.com"
uvicorn server:app --reload --port 8001

Откройте:

http://127.0.0.1:8001/
http://127.0.0.1:8001/docs
http://127.0.0.1:8001/tools
http://127.0.0.1:8001/safety

Пример входных данных OpenAPI

Демо-спецификация:

examples/jsonplaceholder.openapi.yaml

Она включает:

• GET /users

• GET /users/{id}

• GET /posts

• GET /posts/{id}

• POST /posts

• DELETE /posts/{id}

Фрагмент:

paths:
  /users/{id}:
    get:
      operationId: getUserById
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer

Пример сгенерированного инструмента

Сгенерированный безопасный инструмент:

{
  "name": "get_user_by_id",
  "description": "Get user by ID",
  "method": "GET",
  "path": "/users/{id}",
  "risk_level": "low",
  "enabled": true,
  "operation_id": "getUserById",
  "input_schema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "description": "User ID",
        "x-mcpgen-location": "path"
      }
    },
    "required": ["id"]
  }
}

Исключенные инструменты, такие как create_post и delete_post, остаются в tools.all.json и описаны в safety_report.json.

Демо-команды FastAPI

Из корня проекта:

mcpgen generate --from examples/jsonplaceholder.openapi.yaml --mode fastapi --output generated_jsonplaceholder
cd generated_jsonplaceholder
export API_BASE_URL=https://jsonplaceholder.typicode.com
uvicorn server:app --reload --port 8001

PowerShell:

mcpgen generate --from examples/jsonplaceholder.openapi.yaml --mode fastapi --output generated_jsonplaceholder
cd generated_jsonplaceholder
$env:API_BASE_URL = "https://jsonplaceholder.typicode.com"
uvicorn server:app --reload --port 8001

Список доступных безопасных инструментов:

curl http://127.0.0.1:8001/tools

Маршрутизация инструментов по запросу:

curl -X POST http://127.0.0.1:8001/tools \
  -H "Content-Type: application/json" \
  -d "{\"query\":\"get user by id\"}"

Эквивалент PowerShell:

Invoke-RestMethod -Method Post http://127.0.0.1:8001/tools `
  -ContentType "application/json" `
  -Body '{"query":"get user by id"}'

Предварительный просмотр безопасного инструмента:

curl -X POST http://127.0.0.1:8001/tools/get_user_by_id/dry-run \
  -H "Content-Type: application/json" \
  -d "{\"inputs\":{\"id\":1}}"

Выполнение безопасного инструмента GET:

curl -X POST http://127.0.0.1:8001/execute \
  -H "Content-Type: application/json" \
  -d "{\"tool_name\":\"get_user_by_id\",\"params\":{\"id\":1}}"

Эквивалент PowerShell:

Invoke-RestMethod -Method Post http://127.0.0.1:8001/execute `
  -ContentType "application/json" `
  -Body '{"tool_name":"get_user_by_id","params":{"id":1}}'

Показать заблокированное поведение POST:

curl -X POST http://127.0.0.1:8001/tools/create_post/dry-run \
  -H "Content-Type: application/json" \
  -d "{\"inputs\":{\"title\":\"Hello\",\"body\":\"Demo\",\"userId\":1}}"

Показать заблокированное поведение DELETE:

curl -X POST http://127.0.0.1:8001/tools/delete_post/dry-run \
  -H "Content-Type: application/json" \
  -d "{\"inputs\":{\"id\":1}}"

Показать журнал аудита:

cat logs/audit.log

Эквивалент PowerShell:

Get-Content logs\audit.log

Режим MCP

Сгенерируйте сервер MCP в стиле stdio:

mcpgen generate --from examples/jsonplaceholder.openapi.yaml --mode mcp --output generated_jsonplaceholder_mcp

Запуск:

cd generated_jsonplaceholder_mcp
export API_BASE_URL=https://jsonplaceholder.typicode.com
python server.py

PowerShell:

cd generated_jsonplaceholder_mcp
$env:API_BASE_URL = "https://jsonplaceholder.typicode.com"
python server.py

Пример входных данных JSON-RPC tools/list:

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Пример входных данных для предварительного просмотра tools/call:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_user_by_id","arguments":{"id":1}}}

Режим MCP использует те же tools.json, механизм политик и журнал аудита, что и режим FastAPI. В текущей версии MVP tools/call по умолчанию работает в режиме предварительного просмотра. С параметром execution_mode: safe-execute он может выполнять только низкорисковые инструменты GET.

Семантическая маршрутизация инструментов

MCPGen записывает tools.embeddings.json во время генерации и использует его, когда:

routing_mode: semantic

Если эмбеддинги недоступны или семантическое ранжирование не удается, MCPGen автоматически переключается на маршрутизацию по ключевым словам. Вы можете принудительно включить маршрутизацию по ключевым словам с помощью:

routing_mode: keyword

Текст инструмента объединяет имя инструмента, описание и необязательные теги. Пример:

create_invoice create invoice for customer billing payments

По умолчанию MCPGen использует детерминированный локальный механизм эмбеддингов, чтобы демо и тесты работали без загрузки моделей. Чтобы использовать sentence-transformers, установите:

export MCPGEN_EMBEDDING_BACKEND=sentence-transformers

PowerShell:

$env:MCPGEN_EMBEDDING_BACKEND = "sentence-transformers"

Сравните режимы маршрутизации, изменив routing_mode в mcpgen.yaml и перегенерировав сервер. Семантический режим ранжирует по векторному сходству; режим ключевых слов ранжирует по нормализованному пересечению токенов и включает совпавшие термины.

Модель безопасности

MCPGen безопасен по умолчанию:

• В tools.json доступны только низкорисковые инструменты GET.

• Инструменты записи со средним уровнем риска исключены, если будущая конфигурация явно не разрешит их.

• Высокорисковые инструменты DELETE всегда заблокированы.

• Реальное выполнение ограничено только низкорисковыми инструментами GET.

• Выполнение операций записи не реализовано.

• Аутентификация не реализована.

Решения политики возвращают:

{
  "allowed": false,
  "status": "blocked",
  "reason": "Medium-risk tool is not listed in enabled_tools.",
  "risk_level": "medium",
  "tool_name": "create_post"
}

Журналирование аудита

Журналы аудита — это записи JSONL, записываемые в:

logs/audit.log

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

audit_enabled: true
audit_log_path: logs/audit.log
routing_mode: semantic

Каждое событие включает:

• временную метку

• имя инструмента

• метод

• путь

• уровень риска

• режим

• статус

• разрешение

• причину

• источник

• действие

Действия включают:

• policy_evaluation

• dry_run

• execution_started

• execution_success

• execution_error

• execution_blocked

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

Конфигурация по умолчанию:

max_tools: 5
allowed_methods:
  - GET
output_dir: generated_mcp_server
api_base_url: https://api.example.com
enabled_tools: []
execution_mode: dry-run
audit_enabled: true
audit_log_path: logs/audit.log

Для демо JSONPlaceholder установите:

api_base_url: https://jsonplaceholder.typicode.com

Текущие ограничения

• Это MVP, ориентированный на промышленное использование, а не готовый к эксплуатации фреймворк.

• Нет аутентификации или управления секретами, кроме подготовки переменных окружения.

• Нет выполнения операций записи.

• Нет пользовательского интерфейса для подтверждения действий.

• Нет оптимизации векторной базы данных или кэша эмбеддингов.

• Нет ограничения частоты запросов (rate limiting).

• Нет хранилища аудита на базе базы данных.

• Режим MCP использует минимальный каркас stdio, если официальный Python MCP SDK недоступен.

Дорожная карта

• Интеграция с официальным MCP SDK

• Управление аутентификацией и секретами

• Рабочий процесс подтверждения для включенных инструментов среднего риска

• Ограничение частоты запросов

• Валидация запросов/ответов

• Улучшенная поддержка схем OpenAPI

• Подключаемые хранилища аудита

• Более качественные модели семантической маршрутизации и оптимизация кэша эмбеддингов

• Шаблоны развертывания