mcp-graphql-enhanced

Улучшенный MCP-сервер (Model Context Protocol) для GraphQL, который решает реальные проблемы взаимодействия между LLM и GraphQL API.

Прямая замена для mcp-graphql — с динамическими заголовками, надежным парсингом переменных и без критических изменений.

💬 Сообщество и поддержка

Присоединяйтесь к обсуждению! Если у вас есть вопросы об использовании этого моста с Neo4j, графами данных Discord или GraphQL в целом, заходите к нам:

• Канал в Discord: #mcp-graphql-enhanced

• Сервер: Официальный GraphQL Discord

Это лучшее место, чтобы поделиться своим мнением, сообщить о проблемах или предложить новые «улучшенные» функции для моста.

Related MCP server: mcp-graphql-schema

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

• ✅ Встроенная IDE GraphiQL — Визуальная песочница по адресу http://localhost:MCP_PORT/ (или /graphiql) с предварительно настроенными заголовками.

• ✅ Двойной транспорт — Поддерживает как STDIO (для локальных CLI/клиентских инструментов), так и HTTP/JSON-RPC (для внешних/браузерных клиентов).

• ✅ Динамические заголовки — передавайте Authorization, X-API-Key и т.д. через аргументы инструментов (без перезагрузки конфигурации).

• ✅ Надежный парсинг переменных — исправляет ошибку “Query variables must be a null or an object”.

• ✅ Фильтруемая интроспекция — запрашивайте только определенные типы (например, typeNames: ["Query", "User"]) для уменьшения шума в контексте LLM.

• ✅ Полная совместимость с MCP — работает с Claude Desktop, Cursor, Glama.

• ✅ Безопасность по умолчанию — мутации отключены, если не включены явно.

• ✅ Динамическая эволюция схемы — Умная диагностика и анализ пробелов для серверов, которые перегенерируют типы GraphQL «на лету» (например, Neo4j).

• ✅ Глубокая наблюдаемость — Автоматическое извлечение и очистка Cypher из расширений GraphQL.

🚀 Широковещательная рассылка на несколько эндпоинтов (Экспериментально в v3.9.0+)

Начиная с v3.9.0, сервер поддерживает одновременный запрос к нескольким GraphQL-эндпоинтам. Изначально это было разработано для синхронизации мутаций между различными средами (например, бэкендами на Node.js и Python), но это открывает мощные возможности для агрегации данных.

• Никаких критических изменений: Если вы указываете один URL в ENDPOINT, сервер ведет себя так же, как и раньше.

• Умная агрегация: Когда указано несколько URL через запятую, сервер транслирует запрос на все из них и объединяет полученные массивы.

• Обход ограничений бесплатного тарифа: Идеально подходит для пользователей облачных баз данных с «бесплатным тарифом» (например, Neo4j Aura). Вы можете распределить свои данные по нескольким бесплатным экземплярам и использовать этот мост для запроса к ним как к единому унифицированному графу, эффективно обходя ограничения на количество сущностей.

• Дедупликация: Мост автоматически удаляет дублирующиеся объекты на основе их уникальных полей, чтобы поддерживать чистоту контекстного окна ИИ.

⚠️ Используйте на свой страх и риск: Эта функция предполагает, что все эндпоинты используют одну и ту же (или очень похожую) схему GraphQL. Интроспекция выполняется по первому эндпоинту в списке.

💡 Вариант использования: Соединение WSL и Windows (PowerShell)

Распространенная проблема для разработчиков на Windows — сетевая изоляция между подсистемой Windows для Linux (WSL) и хостовой ОС. Эта функция позволяет объединить эти два мира в «Единую нервную систему».

Пример конфигурации для Claude Desktop:

{
  "ENDPOINT": "http://DESKTOP-NAME.local:2311/graphql,http://127.0.0.1:4000/graphql"
}

• Гибридная экосистема: Беспрепятственно запрашивайте и агрегируйте данные между процессами Windows (PowerShell) и средами на базе Linux (WSL).

• Поддержка mDNS: Используя адреса .local, мост автоматически разрешает IP хост-машины из среды WSL.

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

🔍 Продвинутая наблюдаемость и Cypher

Мост предоставляет глубокое понимание того, как LLM взаимодействует с вашей графовой базой данных.

🕸️ Автоматическое извлечение Cypher

Для реализаций GraphQL-серверов, которые возвращают планы выполнения запросов (например, @neo4j/graphql), мост автоматически:

1. Обнаруживает extensions.cypher в ответе.

2. Очищает вывод, удаляя внутренние заголовки (например, CYPHER 5 или пустые PARAMS).

3. Внедряет чистый блок Cypher непосредственно в вывод инструмента для анализа ИИ.

Примечание: Эта функция требует, чтобы ваш GraphQL-сервер был настроен на включение отладочной информации в расширениях ответа.

🎨 Визуальный командный центр (GraphiQL)

В отличие от стандартных MCP-серверов, этот предоставляет визуальный интерфейс для людей. При запуске с ENABLE_HTTP=true вы можете открыть полнофункциональную IDE GraphiQL в своем браузере.

• Эндпоинт: http://localhost:6274/ (или /graphiql)

• Синхронизация заголовков: Любые заголовки, установленные в вашей среде (например, токены GitHub), автоматически внедряются во вкладку «Headers» GraphiQL для немедленного тестирования.

💻 HTTP / Двойной транспорт

Теперь этот сервер работает в режиме двойного транспорта, поддерживая как стандартную связь STDIO (используемую большинством MCP-клиентов), так и новый эндпоинт HTTP JSON-RPC на порту 6274.

Это позволяет внешним системам, веб-приложениям и прямым командам curl получать доступ к инструментам сервера с логированием запросов в реальном времени в вашем терминале (логи [HTTP-RPC]).

Автоматический выбор порта

Сервер по умолчанию использует порт 6274. Если вы столкнетесь с ошибкой EADDRINUSE, сервер автоматически найдет следующий доступный порт. Проверяйте логи сервера для определения конечного порта (например, [HTTP] Started server on http://localhost:6275).

Разрешение конфликтов портов (EADDRINUSE) и автоматический выбор порта

Сервер по умолчанию использует порт 6274. Если вы столкнетесь с ошибкой EADDRINUSE: address already in use :::6274 (часто встречается при локальной разработке из-за зависших процессов), сервер автоматически найдет следующий доступный порт (до 10 попыток, без запуска нескольких серверов).

Это гарантирует успешный запуск сервера, даже если порт по умолчанию занят. Всегда проверяйте логи сервера для определения конечного порта (например, [HTTP] Started server on http://localhost:6275), если ваш curl или клиентский инструмент выдает ошибку на порту 6274 по умолчанию.

Чтобы принудительно задать конкретный порт (например, для гарантированных настроек внешнего брандмауэра), вы все еще можете явно установить переменную окружения MCP_PORT:

Тестирование HTTP-эндпоинта

Вы можете протестировать эндпоинт с помощью curl, пока сервер запущен (например, через npm run dev):

# Test the health check (assuming the server bound to the default or found the next available port)
curl http://localhost:6274/health

# Example: Test the query tool via JSON-RPC (using port 6275 if 6274 was busy)
curl -X POST http://localhost:6275/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"query-graphql","params":{"query":"query { __typename }"},"id":1}'

## 🔍 Filtered Introspection
Avoid 50k-line schema dumps. Ask for only what you need:
`@introspect-schema typeNames ["Query", "User"]`
## 🔍 Debug & Inspect
Use the official MCP Inspector to test your server live:
```bash
npx @modelcontextprotocol/inspector \
  -e ENDPOINT=https://api.example.com/graphql \
  npx @letoribo/mcp-graphql-enhanced

Переменные окружения (Критическое изменение в 1.0.0)

Примечание: Начиная с версии 1.0.0, аргументы командной строки были заменены переменными окружения.

• auto (по умолчанию): Автоматически включает HTTP только при запуске в MCP Inspector...

• true: Всегда включать HTTP-сервер

• false: Полностью отключить HTTP-сервер

Примеры

# Basic usage
ENDPOINT=http://localhost:3000/graphql npx @letoribo/mcp-graphql-enhanced
# With auth header
ENDPOINT=https://api.example.com/graphql \
HEADERS='{"Authorization":"Bearer xyz"}' \
npx @letoribo/mcp-graphql-enhanced
# Enable mutations
ENDPOINT=http://localhost:3000/graphql \
ALLOW_MUTATIONS=true \
npx @letoribo/mcp-graphql-enhanced
# Use local schema file
ENDPOINT=http://localhost:3000/graphql \
SCHEMA=./schema.graphql \
npx @letoribo/mcp-graphql-enhanced
# Change the HTTP port
MCP_PORT=8080 npx @letoribo/mcp-graphql-enhanced
# Disable HTTP transport (fastest, recommended for Claude Desktop)
ENABLE_HTTP=false npx @letoribo/mcp-graphql-enhanced
# Test the surgical precision and the IDE immediately:
ENDPOINT=https://api.github.com/graphql \
HEADERS='{"Authorization":"Bearer YOUR_GITHUB_TOKEN"}' \
ENABLE_HTTP=true \
npx @letoribo/mcp-graphql-enhanced

# Then visit http://localhost:6274/graphiql

🖥️ Примеры конфигурации Claude Desktop

Вы можете подключить Claude Desktop к своему GraphQL API, используя либо пакет npx (рекомендуется для простоты), либо Docker-образ (идеально для воспроизводимости и изоляции).

✅ Вариант 1: Использование npx

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "npx",
      "args": ["@letoribo/mcp-graphql-enhanced"],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql"
      }
    }
  }
}

🐳 Вариант 2: Использование Docker (поддерживается авто-pull)

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "sh",
      "args": [
        "-c",
        "docker run --rm -i -e ENDPOINT=$ENDPOINT -e HEADERS=$HEADERS -e ALLOW_MUTATIONS=$ALLOW_MUTATIONS ghcr.io/letoribo/mcp-graphql-enhanced:main"
      ],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql",
        "HEADERS": "{\"Authorization\": \"Bearer YOUR_TOKEN\"}",
        "ALLOW_MUTATIONS": "false"
      }
    }
  }
}

🧪 Вариант 3: Использование node с локальной сборкой (для разработки)

Если вы клонировали репозиторий и собрали проект (npm run build → вывод в dist/):

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql",
        "ALLOW_MUTATIONS": "true"
      }
    }
  }
}

Ресурсы

• graphql-schema: Сервер предоставляет схему GraphQL как ресурс, к которому могут обращаться клиенты. Это либо локальный файл схемы, файл схемы, размещенный по URL, либо результат запроса интроспекции.

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

Сервер предоставляет два основных инструмента:

1. introspect-schema: Этот инструмент извлекает схему GraphQL или отфильтрованное подмножество (через typeNames). Используйте его в первую очередь, если у вас нет доступа к схеме как к ресурсу. Он использует либо локальный файл схемы, файл схемы, размещенный по URL, либо запрос интроспекции. Фильтруемая интроспекция (typeNames) доступна только при использовании активного GraphQL-эндпоинта (не с файлом SCHEMA или URL).

2. query-graphql: Выполнение запросов GraphQL к эндпоинту. По умолчанию мутации отключены, если ALLOW_MUTATIONS не установлено в true.

Вопросы безопасности

Мутации по умолчанию отключены для предотвращения непреднамеренных изменений данных. Всегда проверяйте входные данные HEADERS и SCHEMA в рабочей среде. По возможности используйте HTTPS-эндпоинты и краткосрочные токены.

Настройка для вашего собственного сервера

Это очень общая реализация, которая позволяет выполнять полную интроспекцию и дает пользователям возможность делать что угодно (включая мутации). Если вам нужна более специфическая реализация, я бы предложил создать свой собственный MCP и ограничить вызов инструментов для клиентов, чтобы они могли вводить только определенные поля запроса и/или переменные. Вы можете использовать это в качестве справочного материала.