MCP-сервер для встраивания GraphQL-схем

Python MCP-сервер для LLM, который индексирует GraphQL-схему, сохраняет эмбеддинги для каждого type->field через эндпоинт эмбеддингов и обеспечивает быстрый поиск, а также выполнение run_query после идентификации соответствующих типов для получения данных из вашего GraphQL-эндпоинта.

Архитектура

• GraphQL-схема: предоставьте файл схемы (SDL) для выполнения парсинга и индексации.

• Индексатор: schema_indexer.py строит индекс навигации по узлам полей GraphQL, включая метаданные полей, псевдонимы для нечеткого поиска и координаты корня запроса (Query-root), затем встраивает сгенерированный поисковый текст и сохраняет его в data/metadata.json + data/vectors.npz.

• Сервер: server.py предоставляет MCP-инструменты list_types и run_query. Сервер гарантирует наличие индекса схемы при запуске; он вызывает эндпоинт эмбеддингов только при переиндексации или встраивании нового запроса.

• Персистентность: data/ добавлена в .gitignore, поэтому вы можете пересоздавать данные локально, не засоряя репозиторий.

Настройка

Установите переменные окружения. Вы можете начать с .env.example.

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

• GRAPHQL_EMBED_API_KEY (или OPENAI_API_KEY)

• GRAPHQL_EMBEDDINGS_URL (полный URL для эмбеддингов)

• GRAPHQL_EMBED_MODEL

• GRAPHQL_EMBED_API_KEY_HEADER / GRAPHQL_EMBED_API_KEY_PREFIX

• GRAPHQL_EMBED_HEADERS (строка JSON-объекта для дополнительных заголовков) Авторизация эндпоинта (при использовании GRAPHQL_ENDPOINT_URL):

• GRAPHQL_ENDPOINT_HEADERS (строка JSON-объекта, объединяется с любыми флагами --header)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 src/server.py

Запуск MCP-сервера

python3 src/server.py                # SSE on 127.0.0.1:8000/sse by default
python3 src/server.py --transport sse     # explicit SSE
python3 src/server.py --transport streamable-http  # Streamable HTTP on 127.0.0.1:8000/mcp
# Or: point at a live GraphQL endpoint (requires introspection enabled)
python3 src/server.py --endpoint https://api.example.com/graphql
# Endpoint auth headers (repeat --header)
python3 src/src/server.py --endpoint https://api.example.com/graphql --header "Authorization: Bearer $TOKEN"
# Options: --host 0.0.0.0 --port 9000 --log-level DEBUG --mount-path /myapp

Тест локального эндпоинта (пример сервера в репозитории):

# Terminal 1
python3 examples/graphql_test_server/server.py

# Terminal 2
python3 src/server.py --transport sse --endpoint http://127.0.0.1:4000/graphql

Инструменты:

• list_types(query, limit=5) — поиск по сходству эмбеддингов среди узлов полей GraphQL. Результаты возвращаются по оценке косинусного сходства и включают coordinates (массив шагов пути от Query), а также query для полей Query и select для вложенных полей объектов.

• run_query(query) — если установлен --endpoint, проксирует запрос к эндпоинту; в противном случае проверяет/выполняет его относительно локальной схемы (без резолверов; в основном для проверки валидации/структуры, данные возвращаются как null). И индексация, и выполнение запросов используют одну и ту же модель эмбеддингов (по умолчанию text-embedding-3-small, можно переопределить через конфиг/окружение или --model).

Ранжирование (list_types):

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

Пример вывода list_types:

[
  {
    "field": "users",
    "summary": "Query.users(limit: Int) -> [User!]!",
    "coordinates": ["Query.users(limit: <Int>)"],
    "query": "query { users(limit: <Int>) { id name orders { id total status } } }"
  },
  {
    "type": "Order",
    "field": "total",
    "summary": "Order.total -> Float!",
    "coordinates": ["Query.user(id: <ID!>)", "User.orders", "Order.total"]
  },
  {
    "type": "User",
    "field": "orders",
    "summary": "User.orders -> [Order!]!",
    "coordinates": ["Query.user(id: <ID!>)", "User.orders"],
    "select": "orders { id total status }"
  }
]

Примечания:

• python3 src/server.py по умолчанию использует транспорт sse; передайте --transport streamable-http, если хотите использовать HTTP.

• Вы также можете установить переменные окружения с префиксом FASTMCP_ (например, FASTMCP_HOST, FASTMCP_PORT, FASTMCP_LOG_LEVEL) для переопределения значений по умолчанию.

• Сервер гарантирует, что индекс схемы построен при запуске; если вычисляются эмбеддинги, выводится простой индикатор выполнения. Установите GRAPHQL_EMBED_BATCH_SIZE для настройки размера пакета.

• Сервер предоставляет MCP-инструкции (переопределяются через MCP_INSTRUCTIONS), которые описывают сервер как уровень абстракции и указывают LLM использовать list_types, а затем run_query с минимальным количеством вызовов инструментов.

Быстрый тест с помощью MCP Inspector

Требуется наличие npm/npx в PATH.

Подключение к уже запущенному SSE-серверу

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

python3 src/server.py --transport sse --port 8000

В другом терминале (запуск Inspector и указание на /sse):

npx @modelcontextprotocol/inspector --transport sse --server-url http://127.0.0.1:8000/sse

Настройка в Claude Desktop / CLI

Если вы запускаете этот сервер локально через SSE (по умолчанию), укажите Claude URL /sse.

claude mcp add --transport sse graphql-mcp http://127.0.0.1:8000/sse

Вы также можете настроить его через JSON (например, файл конфигурации):

{
  "mcpServers": {
    "graphql-mcp": {
      "type": "sse",
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

Если вы выставляете этот сервер за авторизацией, передайте заголовки:

claude mcp add --transport sse private-graphql http://127.0.0.1:8000/sse \
  --header "Authorization: Bearer your-token-here"