GraphQL 스키마 임베더 MCP 서버

GraphQL 스키마를 인덱싱하고, 임베딩 엔드포인트를 통해 type->field별 임베딩을 저장하며, 관련 타입이 식별되면 run_query 실행을 통해 GraphQL 엔드포인트에서 데이터를 가져올 수 있도록 하는 LLM용 Python MCP 서버입니다.

아키텍처

• GraphQL 스키마: 파싱 및 인덱싱을 수행할 스키마 파일(SDL)을 제공합니다.

• 인덱서: schema_indexer.py는 필드 메타데이터, 퍼지 검색 별칭, Query-root 좌표를 포함하는 GraphQL 필드 노드의 탐색 인덱스를 구축한 다음, 생성된 검색 텍스트를 임베딩하여 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 전송을 사용합니다. HTTP를 원하면 --transport streamable-http를 전달하세요.

• FASTMCP_ 접두사가 붙은 환경 변수(예: FASTMCP_HOST, FASTMCP_PORT, FASTMCP_LOG_LEVEL)를 설정하여 기본값을 재정의할 수도 있습니다.

• 서버는 시작 시 스키마 인덱스가 구축되었는지 확인하며, 임베딩이 계산되면 간단한 진행률 표시줄이 출력됩니다. 배치 크기를 조정하려면 GRAPHQL_EMBED_BATCH_SIZE를 설정하세요.

• 서버는 서버를 추상화 계층으로 설명하고 LLM에게 최소한의 도구 호출로 list_types를 사용한 다음 run_query를 사용하도록 지시하는 MCP instructions(MCP_INSTRUCTIONS로 재정의 가능)를 노출합니다.

MCP Inspector를 사용한 빠른 테스트

PATH에 npm/npx가 필요합니다.

이미 실행 중인 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가 /sse URL을 가리키도록 설정하세요.

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"