MCP GraphQL 통합

MCP GraphQL 통합에 대해 설명합니다.

이 설계는 GitLab GraphQL API를 활용하는 Model Context Protocol(MCP) 도구를 만들기 위한 재사용 가능한 패턴을 소개합니다. 이 솔루션은 두 계층 아키텍처를 제공합니다: GraphQL 실행 및 오류 처리를 담당하는 재사용 가능한 GraphqlTool 클래스와 유효성 검사 및 응답 포맷팅을 처리하는 GraphqlService 를 확장하는 서비스 래퍼입니다. 이 패턴을 통해 개발자는 일관된 보안 및 오류 처리 방식을 유지하면서 최소한의 보일러플레이트로 새로운 GraphQL 기반 MCP 도구를 만들 수 있습니다. 이 구현을 통해 AI 클라이언트(Duo 에이전트 플랫폼, Claude, Cursor 등)는 GraphQL 뮤테이션과 쿼리를 통해 GitLab 리소스에 대한 복잡한 작업을 수행할 수 있으며, 기존 GraphQL 스키마 정의와 인가 로직을 재사용합니다. 동기 # 현재 상태 # GitLab MCP 구현은 REST API 엔드포인트를 MCP 도구로 노출하는 route_setting :mcp 를 사용하는 경로 기반 아키텍처를 사용합니다. REST 작업에 효과적이지만 이 접근법은 GraphQL 통합에 한계가 있습니다: GraphQL 기반 MCP 도구를 위한 내장 패턴 없음 개발자가 GraphQL 실행을 수동으로 연결해야 함 REST와 GraphQL 도구 간의 일관성 없는 오류 처리 일반적인 GraphQL 작업을 위한 재사용 가능한 추상화 없음 원자적 다중 작업 요청 지원 없음 목표 # 재사용성 : GraphQL 기반 MCP 도구의 보일러플레이트를 제거하는 기본 클래스 생성 일관성 : 모든 GraphQL 도구에 걸쳐 균일한 오류 처리 및 응답 포맷팅 유지 개발자 경험 : 50줄 미만의 코드로 새 GraphQL MCP 도구 생성 가능 보안 : 기존 GraphQL 인가 활용 타입 안전성 : 런타임 오류 방지를 위해 정적 GraphQL 스키마 정의 사용 유지보수성 : 더 쉬운 테스트를 위해 비즈니스 로직과 GraphQL 작업을 분리 원자성 : 단일 요청에서 여러 뮤테이션 지원 비목표 # 기존 경로 기반 MCP 아키텍처 대체 GraphQL 프록시 또는 쿼리 빌더 생성 도구 생성을 위한 자동 스키마 내성 구현 GraphQL 구독 지원(실시간 업데이트) 범용 GraphQL 클라이언트 라이브러리 생성 병렬 뮤테이션 실행(GraphQL은 순차적으로 뮤테이션을 실행함) 솔루션 # GraphQL 기반 MCP 도구를 위한 두 계층 아키텍처 도입: 계층 1: GraphQL 도구 클래스 ( Mcp::Tools::GraphqlTool ) GraphQL 작업(쿼리/뮤테이션)을 정적 상수로 정의 단일 뮤테이션 또는 하나의 요청에 여러 뮤테이션 지원 입력 파라미터를 GraphQL 입력 형식으로 변환 GitlabSchema 에 대해 작업 실행 결과 처리 및 오류 처리 표준화 계층 2: 서비스 래퍼 ( Mcp::Tools::*Service < GraphqlService ) 사용자 유효성 검사와 GraphQL 도구 실행을 제공하는 Grap