mcp-graphql-enhanced

LLM과 GraphQL API 간의 실제 상호 운용성 문제를 해결하는 향상된 GraphQL용 MCP(Model Context Protocol) 서버입니다.

mcp-graphql을 완벽하게 대체하며, 동적 헤더, 강력한 변수 파싱 기능을 제공하고 기존 기능과의 호환성을 유지합니다.

💬 커뮤니티 및 지원

대화에 참여하세요! 이 브리지를 Neo4j, Discord 데이터 그래프 또는 일반적인 GraphQL과 함께 사용하는 것에 대해 궁금한 점이 있다면 저희와 함께 이야기해 보세요:

• Discord 채널: #mcp-graphql-enhanced

• 서버: 공식 GraphQL Discord

이곳은 피드백을 공유하거나, 문제를 보고하거나, 브리지를 위한 새로운 "향상된" 기능을 제안하기에 가장 좋은 장소입니다.

Related MCP server: mcp-graphql-schema

✨ 주요 향상 기능

• ✅ 내장 GraphiQL IDE — 사전 구성된 헤더와 함께 http://localhost:MCP_PORT/ (또는 /graphiql)에서 시각적 플레이그라운드 제공.

• ✅ 듀얼 전송 — STDIO(로컬 CLI/클라이언트 도구용) 및 HTTP/JSON-RPC(외부/브라우저 클라이언트용) 모두 지원.

• ✅ 동적 헤더 — 도구 인수를 통해 Authorization, X-API-Key 등을 전달 (구성 재시작 불필요)

• ✅ 강력한 변수 파싱 — “Query variables must be a null or an object” 오류 수정

• ✅ 필터링된 인트로스펙션 — LLM 컨텍스트 노이즈를 줄이기 위해 특정 타입만 요청 (예: typeNames: ["Query", "User"])

• ✅ 전체 MCP 호환성 — Claude Desktop, Cursor, Glama와 호환

• ✅ 기본 보안 설정 — 명시적으로 활성화하지 않는 한 뮤테이션(Mutation) 비활성화

• ✅ 동적 스키마 진화 — Neo4j와 같이 GraphQL 타입을 즉석에서 재생성하는 서버를 위한 스마트 진단 및 간극 분석.

• ✅ 심층 관찰 가능성 — GraphQL 확장 기능에서 Cypher 자동 추출 및 정리.

🚀 다중 엔드포인트 브로드캐스트 (v3.9.0+에서 실험적 기능)

v3.9.0부터 서버는 여러 GraphQL 엔드포인트를 동시에 쿼리하는 기능을 지원합니다. 이는 원래 서로 다른 환경(예: Node.js 및 Python 백엔드) 간에 뮤테이션을 동기화하기 위해 설계되었지만, 데이터 집계에 강력한 가능성을 열어줍니다.

• 호환성 유지: ENDPOINT에 단일 URL을 제공하면 서버는 이전과 동일하게 작동합니다.

• 스마트 집계: 쉼표로 구분된 여러 URL이 제공되면 서버는 모든 URL에 쿼리를 브로드캐스트하고 결과 배열을 병합합니다.

• 무료 티어 제한 우회: Neo4j Aura와 같은 "무료 티어" 클라우드 데이터베이스 사용자에게 적합합니다. 데이터를 여러 무료 인스턴스에 분할하고 이 브리지를 사용하여 단일 통합 그래프로 쿼리함으로써 엔티티 개수 제한을 효과적으로 우회할 수 있습니다.

• 중복 제거: 브리지는 AI의 컨텍스트 창을 깨끗하게 유지하기 위해 고유 필드를 기반으로 중복 객체를 자동으로 제거합니다.

⚠️ 주의: 이 기능은 모든 엔드포인트가 동일하거나 매우 유사한 GraphQL 스키마를 공유한다고 가정합니다. 인트로스펙션은 목록의 첫 번째 엔드포인트를 대상으로 수행됩니다.

💡 사용 사례: WSL과 Windows(PowerShell) 연결

Windows 개발자에게 흔한 과제는 Windows Subsystem for Linux(WSL)와 호스트 OS 간의 네트워크 격리입니다. 이 기능을 사용하면 이 두 세계를 "통합 신경계"로 연결할 수 있습니다.

Claude Desktop을 위한 구성 예시:

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

• 하이브리드 생태계: Windows 네이티브 프로세스(PowerShell)와 Linux 기반 환경(WSL) 전반에서 원활하게 데이터를 쿼리하고 집계합니다.

• mDNS 지원: .local 주소를 사용하면 브리지가 WSL 환경 내에서 호스트 머신의 IP를 자동으로 확인합니다.

• 투명한 집계: AI 어시스턴트는 데이터가 서로 다른 운영 체제에서 동시에 가져오고 있다는 사실을 모른 채 단일 통합 스키마와 상호 작용합니다.

🔍 고급 관찰 가능성 및 Cypher

이 브리지는 LLM이 그래프 데이터베이스와 상호 작용하는 방식에 대한 심층적인 통찰력을 제공합니다.

🕸️ 자동 Cypher 추출

@neo4j/graphql과 같이 쿼리 실행 계획을 반환하는 GraphQL 서버 구현의 경우, 브리지는 자동으로 다음을 수행합니다:

1. 응답에서 extensions.cypher를 감지합니다.

2. 내부 헤더(예: CYPHER 5 또는 빈 PARAMS)를 제거하여 출력을 정리합니다.

3. AI가 분석할 수 있도록 정리된 Cypher 블록을 도구 출력에 직접 삽입합니다.

참고: 이 기능을 사용하려면 GraphQL 서버가 응답 확장 기능에 디버그 정보를 포함하도록 구성되어 있어야 합니다.

🎨 비주얼 커맨드 센터 (GraphiQL)

표준 MCP 서버와 달리, 이 서버는 인간을 위한 시각적 인터페이스를 제공합니다. ENABLE_HTTP=true로 실행하면 브라우저에서 모든 기능을 갖춘 GraphiQL IDE를 열 수 있습니다.

• 엔드포인트: http://localhost:6274/ (또는 /graphiql)

• 헤더 동기화: 환경에 설정된 모든 헤더(예: GitHub 토큰)는 즉각적인 테스트를 위해 GraphiQL "Headers" 탭에 자동으로 삽입됩니다.

💻 HTTP / 듀얼 전송

이 서버는 이제 듀얼 전송 모드로 실행되며, 표준 STDIO 통신(대부분의 MCP 클라이언트에서 사용)과 포트 6274의 새로운 HTTP JSON-RPC 엔드포인트를 모두 지원합니다.

이를 통해 외부 시스템, 웹 애플리케이션 및 직접적인 curl 명령이 터미널의 실시간 요청 로깅([HTTP-RPC] 로그)과 함께 서버 도구에 액세스할 수 있습니다.

자동 포트 선택

서버는 기본적으로 포트 6274를 사용합니다. EADDRINUSE 오류가 발생하면 서버는 자동으로 다음 사용 가능한 포트를 찾습니다. 최종 바인딩된 포트는 서버 로그를 확인하세요 (예: [HTTP] Started server on http://localhost:6275).

포트 충돌(EADDRINUSE) 해결 및 자동 포트 선택

서버는 기본적으로 포트 6274를 사용합니다. EADDRINUSE: address already in use :::6274 오류(오래된 프로세스로 인해 로컬 개발 시 흔히 발생)가 발생하면 서버는 자동으로 다음 사용 가능한 포트를 찾습니다(최대 10회 시도, 여러 서버를 생성하지 않음).

이렇게 하면 기본 포트가 차단된 경우에도 서버가 성공적으로 시작됩니다. curl 또는 클라이언트 도구가 기본 6274에서 실패하는 경우 항상 서버 로그에서 최종 바인딩된 포트를 확인하세요 (예: [HTTP] Started server on http://localhost:6275).

특정 포트를 강제하려면(예: 외부 방화벽 설정을 보장하기 위해), 여전히 MCP_PORT 환경 변수를 명시적으로 설정할 수 있습니다:

HTTP 엔드포인트 테스트

서버가 실행 중인 경우(예: npm run dev를 통해) curl을 사용하여 엔드포인트를 테스트할 수 있습니다:

# 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(기본값): MCP Inspector에서 실행될 때만 자동으로 HTTP를 활성화합니다...

• 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 구성 예시

npx 패키지(간편함 권장) 또는 Docker 이미지(재현성 및 격리에 이상적)를 사용하여 Claude Desktop을 GraphQL API에 연결할 수 있습니다.

✅ 옵션 1: npx 사용

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

🐳 옵션 2: Docker 사용 (자동 풀 지원)

{
  "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를 만들고 클라이언트가 특정 쿼리 필드 및/또는 변수만 입력하도록 도구 호출을 제한하는 것을 권장합니다. 이를 참조로 사용할 수 있습니다.