Advanced Hasura GraphQL MCP Server

고급 Hasura GraphQL MCP 서버

버전: 1.1.0

이 모델 컨텍스트 프로토콜(MCP) 서버는 AI 에이전트(Cursor 또는 Claude Desktop 등)가 Hasura GraphQL 엔드포인트와 상호 작용할 수 있도록 고급 인터페이스를 제공합니다. 이를 통해 에이전트는 API 구조를 파악하고, 읽기 전용 쿼리와 뮤테이션(주의 필요)을 모두 실행하고, 데이터를 미리 보고, 집계를 수행하고, 서비스 상태를 확인할 수 있습니다.

이 서버는 자연어 요청에 따라 Hasura API를 동적으로 활용할 수 있도록 하여 LLM 기능을 향상시킵니다.

특징

이 서버는 다음과 같은 MCP 기능을 제공합니다.

자원:

• Hasura GraphQL 스키마( hasura:/schema )
  • 표준 인트로스펙션을 통해 얻은 전체 GraphQL 스키마 정의를 제공합니다.
  • MIME 유형: application/json
  • 에이전트는 이 리소스를 읽고 유형, 필드, 인수, 지침 등을 포함한 API의 전체 구조를 이해할 수 있습니다.

도구:

• run_graphql_query
  • 설명: Hasura 엔드포인트에 대해 읽기 전용 GraphQL 쿼리를 실행합니다. 특정 도구를 사용할 수 없을 때 데이터를 가져오는 데 사용합니다. 쿼리가 데이터를 수정하지 않도록 합니다. 예: query { users { id name } }
  • 입력: { query: string, variables?: object }
  • 참고: mutation 으로 시작하는 문자열의 실행을 방지하기 위한 기본 검사를 수행합니다. 주로 쿼리 자체가 읽기 전용인지 확인합니다.
• run_graphql_mutation
  • 설명: GraphQL 뮤테이션을 실행하여 데이터를 삽입, 업데이트 또는 삭제합니다. 주의해서 사용하고 , 작업이 의도된 대로 안전하게 수행되는지 확인하십시오. 제공된 관리자 비밀번호 또는 기본 역할에 대해 구성된 Hasura 권한을 사용합니다. 예: mutation { insert_users_one(object: {name: "Test"}) { id } }
  • 입력: { mutation: string, variables?: object }
  • 보안: Hasura 역할에 따라 허용되는 모든 변형을 허용합니다. 적절한 Hasura 권한이 구성되어 있는지 확인하세요.
• list_tables
  • 설명: Hasura에서 관리하는 사용 가능한 데이터 테이블(또는 컬렉션)을 스키마별로 설명과 함께 정리하여 나열합니다. 이는 내부/집계 유형을 제외하고 'id' 필드가 있는 객체 유형을 찾습니다. 사용 가능한 데이터 소스를 찾는 데 유용합니다.
  • 입력: { schemaName?: string } (선택적 스키마 이름, 가능한 경우 필드 설명에서 추론을 시도하며, 개념적으로는 'public'으로 기본 설정됨)
• describe_table
  • 설명: GraphQL 유형과 설명과 함께 모든 열(필드)을 포함한 특정 테이블의 구조를 보여줍니다.
  • 입력: { tableName: string, schemaName?: string }
• list_root_fields
  • 설명: GraphQL 스키마에서 사용 가능한 최상위 쿼리, 뮤테이션 또는 구독 필드를 나열합니다. 작업의 주요 진입점을 이해하는 데 유용합니다.
  • 입력: { fieldType?: 'QUERY' | 'MUTATION' | 'SUBSCRIPTION' } (선택적 필터)
• describe_graphql_type
  • 설명: 스키마 인트로스펙션을 사용하여 특정 GraphQL 유형(객체, 입력, 스칼라, 열거형, 인터페이스, 공용체)에 대한 세부 정보를 제공합니다. 특정 유형과 관련된 쿼리 또는 뮤테이션을 구성하는 방법을 이해하는 데 필수적입니다.
  • 입력: { typeName: string } (대소문자 구분 유형 이름)
• preview_table_data
  • 설명: 지정된 테이블에서 제한된 행 샘플(기본값 5개)을 가져와 데이터 구조와 내용을 미리 봅니다. 공통 스칼라 및 열거형 필드를 자동으로 선택합니다.
  • 입력: { tableName: string, limit?: number }
• aggregate_data
  • 설명: 지정된 테이블에 대해 간단한 집계(개수, 합계, 평균, 최소값, 최대값)를 수행합니다. 선택적으로 Hasura 'where' 필터를 적용할 수 있습니다. 테이블 이름을 찾으려면 'list_tables'를 사용하세요. 개수 집계가 아닌 집계에는 'field'가 필요합니다.
  • 입력: { tableName: string, aggregateFunction: 'count'|'sum'|'avg'|'min'|'max', field?: string, filter?: object }
• health_check
  • 설명: 구성된 Hasura GraphQL 엔드포인트에 접근 가능하고 기본 GraphQL 쿼리( { __typename } )에 응답하는지 확인합니다. 특정 HTTP 상태 엔드포인트 URL이 알려진 경우 선택적으로 해당 URL을 확인할 수 있습니다.
  • 입력: { healthEndpointUrl?: string } (선택적 특정 건강 URL)

요구 사항

• Node.js(v18 이상 권장, 지정된 경우 .nvmrc 또는 package.json engines 확인)
• pnpm (또는 npm / yarn , 명령을 적절히 조정하세요)
• 실행 중인 Hasura GraphQL 엔드포인트에 액세스합니다.
• (선택 사항이지만 권장) 특권 액세스를 위한 Hasura 관리자 비밀번호 또는 올바르게 구성된 기본 역할 권한.

설정 및 설치

1. 저장소를 복제합니다(해당되는 경우):지엑스피1
2. 종속성 설치:
   pnpm install
3. 서버 구축:
   pnpm run build
   이렇게 하면 TypeScript 코드가 dist 디렉토리로 컴파일됩니다.

서버 실행

터미널에서 컴파일된 스크립트를 실행하고 Hasura 엔드포인트 URL과 선택적으로 관리자 비밀번호를 제공합니다.

예:

또는

관리자 비밀번호가 필요하지 않은 경우(기본 역할 권한 사용):

서버가 시작되고, 초기 스키마 검사를 시도하고, STDIO 전송에 연결하고, stderr 에 상태 메시지를 로깅합니다. stdin 에서 MCP JSON-RPC 요청을 수신하고 stdout 으로 응답을 전송합니다.

MCP 클라이언트(예: Cursor, Claude Desktop)와 함께 사용

이 서버를 Cursor와 같은 MCP 클라이언트에 연결하려면:

1. 절대 경로 찾기:
   • 노드 실행 파일: 터미널에서 which node 실행하나요?
   • 서버 스크립트: mcp-hasura-advanced 디렉터리로 이동하여 pwd 실행합니다. 결과에 /dist/index.js 추가합니다.
   • 프로젝트 디렉토리: pwd 의 출력.
2. 클라이언트 구성: 클라이언트의 구성 파일을 엽니다(예: Cursor의 경우 settings.json , Claude Desktop의 경우 claude_desktop_config.json ).
3. 서버 항목 추가: 적절한 키 아래에 항목을 추가합니다(예: Cursor의 경우 cursor.customMcpServers 배열, Claude Desktop의 경우 mcpServers 개체).

예제 커서 settings.json :

예시 Claude Desktop claude_desktop_config.json :

4. 플레이스홀더 바꾸기: 모든 플레이스홀더( /path/to/... , https://YOUR... , YOUR_ADMIN_SECRET )를 실제 값으로 업데이트합니다.
5. 클라이언트 재시작/다시 로드: 구성을 저장하고 MCP 클라이언트 애플리케이션을 재시작하거나 다시 로드합니다.
6. 서버 선택: 클라이언트 UI에서 "내 고급 하수라 서버"(또는 지정한 이름)를 선택합니다.
7. 상호작용: 클라이언트의 채팅에서 자연어 프롬프트를 사용하여 서버 도구를 활용합니다(예: "Hasura 서버를 사용하여 테이블 나열", "'users' 테이블 설명", "'orders' 테이블에서 데이터 미리 보기", "Hasura 서버를 사용하여 { products { name price } } 쿼리 실행").

개발

• 개발 모드에서 실행: pnpm run dev <ENDPOINT> [SECRET] 사용하여 ts-node 로 직접 서버를 실행하면 더 빠른 반복이 가능합니다(빌드 단계가 필요하지 않음).
• 테스트: 서버를 수동으로 실행( pnpm start ... )하고 JSON-RPC 요청을 stdin 으로 파이프하여 개별 도구를 테스트합니다.