ggRMCP: gRPC 서비스를 MCP 호환 도구로 변환하는 고성능 Go 기반 게이트웨이

ggRMCP는 gRPC 서비스를 MCP (Model Context Protocol) 호환 도구로 변환하는 고성능 Go 기반 게이트웨이로, Claude와 같은 AI 모델이 귀하의 gRPC 서비스를 직접 호출할 수 있도록 합니다. 이는 gRPC 세계와 MCP 생태계 사이의 번역기 역할을 하며, 기존 gRPC 서비스를 수정할 필요 없이 원활한 통합을 제공합니다.

ggRMCP는 gRPC 리플렉션 (gRPC reflection)을 사용하여 사용 가능한 서비스와 메서드를 탐색하고, MCP 도구를 동적으로 생성합니다. 이를 통해 AI 애플리케이션은 gRPC 서비스를 마치 네이티브 도구인 것처럼 상호작용할 수 있으며, 실시간 데이터 액세스 및 처리를 통해 AI 모델의 역량을 강화합니다.

ggRMCP는 FileDescriptorSet 파일을 읽도록 구성할 수도 있어, protobuf 정의에서 주석과 문서를 추출함으로써 더욱 풍부한 AI 애플리케이션 경험을 제공할 수 있습니다.

이를 통해 기존 gRPC 서비스를 AI 사용 사례에 맞춰 다시 작성하거나 조정할 필요 없이 그대로 활용할 수 있어, 애플리케이션에 AI 기능을 통합하는 것이 더욱 쉬워집니다.

ggRMCP는 실험적인 프로젝트이며 아직 프로덕션 환경에 적용할 준비가 되지 않았습니다.

배포 패턴 (Deployment Patterns):

🐳 사이드카 프록시 (Sidecar Proxy): 어떤 언어(Java, Python, C++, Go 등)로 작성된 gRPC 서비스와 함께 배포
🌐 중앙 집중형 게이트웨이 (Centralized Gateway): 여러 gRPC 백엔드를 서비스하는 단일 인스턴스

트랜스코딩 (Transcoding)은 기존 gRPC 서비스에 대한 수정 없이 실시간으로 수행됩니다. 언어에 구애받지 않는 사이드카로서, ggRMCP는 gRPC 리플렉션을 지원하는 모든 언어로 작성된 gRPC 서비스와 함께 작동합니다.

MCP는 애플리케이션이 LLM (Large Language Models)에 컨텍스트를 제공하는 방식을 표준화하는 개방형 프로토콜입니다. MCP를 AI 애플리케이션을 위한 USB-C 포트라고 생각하면 됩니다. 즉, AI 모델을 다양한 데이터 소스 및 도구에 연결하는 표준화된 방법을 제공합니다.

도구 등록 (Tool Registration): 각 gRPC 메서드가 MCP 도구 (tool)가 됩니다
스키마 정의 (Schema Definition): Protobuf 스키마가 JSON 스키마로 변환됩니다
요청/응답 처리 (Request/Response Handling): JSON과 Protobuf 간의 자동 번역을 지원합니다
오류 처리 (Error Handling): MCP 사양을 따르는 표준화된 오류 응답을 제공합니다
헤더 전달 (Header Forwarding): HTTP 헤더가 gRPC 서비스로 안전하게 전달됩니다

🌍 언어 중립성 (Language Agnostic): 어떤 언어로 작성된 gRPC 서비스와도 사이드카 (sidecar) 형태로 작동합니다
🔌 원활한 통합 (Seamless Integration): 기존 gRPC 서비스를 수정 없이 AI 애플리케이션에 연결할 수 있습니다
🚀 사이드카 준비 완료 (Sidecar Ready): 코드 변경 없이 서비스 컨테이너와 함께 배포할 수 있습니다
📡 동적 서비스 발견 (Dynamic Service Discovery): gRPC 서버 리플렉션 (reflection) 또는 FileDescriptorSet을 사용하여 gRPC 서비스를 자동으로 발견합니다
🔄 실시간 도구 생성 (Real-time Tool Generation): 주석 추출을 통해 gRPC 서비스 정의로부터 MCP 도구를 동적으로 생성합니다
📝 스키마 검증 (Schema Validation): Protobuf 스키마를 사용하여 요청/응답을 자동으로 검증합니다
🧠 세션 관리 (Session Management): 복잡한 AI 상호작용을 위한 상태 유지 (stateful) 세션 처리를 지원합니다
📨 헤더 전달 (Header Forwarding): 보안 필터링을 포함하여 gRPC 서비스로의 HTTP 헤더 전달을 구성할 수 있습니다
📋 FileDescriptorSet 지원 (FileDescriptorSet Support): .binpb 디스크립터 파일을 통해 주석과 문서가 포함된 풍부한 도구 스키마를 제공합니다

graph TB
subgraph "Client Layer"
A[MCP Client<br/>Claude AI]
...

구성 요소	위치	목적
Connection Manager	`pkg/grpc/connection.go`	상태 확인 (Health checking) 및 재연결을 통한 gRPC 연결 관리
Service Discoverer	`pkg/grpc/discovery.go`	gRPC 서비스 검색 및 관리
Reflection Client	`pkg/grpc/reflection.go`	서비스 검색을 위한 gRPC Reflection API 처리
MCP Handler	`pkg/server/handler.go`	HTTP 상에서 MCP 프로토콜 구현
Session Manager	`pkg/session/manager.go`	속도 제한 (Rate limiting)을 포함한 사용자 세션 관리
Tool Builder	`pkg/tools/builder.go`	Protobuf 정의로부터 JSON 스키마 생성
Header Filter	`pkg/headers/filter.go`	HTTP 헤더를 필터링하여 gRPC 서비스로 전달
Configuration	`pkg/config/config.go`	중앙 집중식 설정 관리

ggRMCP를 기존 gRPC 서비스와 함께 사이드카 (Sidecar) 컨테이너로 배포하세요:

graph LR
subgraph "Pod/Container Group"
subgraph "Your Service"
...

장점:

✅ 기존 서비스에 코드 변경 불필요
✅ 모든 언어 지원 (Java, Python, C++, Go 등)
✅ 서비스 장애로부터 격리
✅ 독립적인 스케일링 (Scaling) 및 업데이트

단일 ggRMCP 인스턴스가 여러 gRPC 백엔드를 서비스하는 구조:

graph TB
A[AI Client] -->|HTTP/JSON-RPC| B[ggRMCP Gateway]
B -->|gRPC| C[User Service<br/>Java]
...

Go 1.23 이상
Reflection이 활성화된 실행 중인 gRPC 서버 (예시 서비스 제공됨)
make

빌드용 (선택 사항) protoc

FileDescriptorSet 파일 생성용 (선택 사항)

ggRMCP를 테스트하는 가장 빠른 방법은 포함된 hello-service 예제를 사용하는 것입니다:

git clone https://github.com/aalobaidi/ggRMCP
cd ggRMCP
go mod download
...

cd examples/hello-service
# hello 서비스 빌드 및 실행 (기본 포트 50051)
make run
...

이 명령은 localhost:50051 (또는 사용자 정의 포트)에서 Reflection이 활성화되고 SayHello 메서드가 포함된 gRPC 서비스를 시작합니다.

다음 옵션 중 하나를 선택하세요:

옵션 a: gRPC Reflection 사용

# 프로젝트 루트에서 실행
./build/grmcp --grpc-host=localhost --grpc-port=50051 --http-port=50053 --log-level=debug

옵션 b: FileDescriptorSet 사용 (주석이 포함된 강화된 스키마)

# 주석이 포함된 FileDescriptorSet 생성
cd examples/hello-service
make descriptor
...

# 상태(health) 확인
curl http://localhost:50053/health
# 사용 가능한 도구 목록 확인 (hello_helloservice_sayhello가 표시되어야 함)
...

cd examples/hello-service
make install-tools # protobuf 도구 설치 (protoc-gen-go, protoc-gen-go-grpc)
make setup # 도구 설치 및 protobuf 파일 생성
...

MCP 원격 클라이언트 설치:

npm install -g mcp-remote

Claude Desktop 설정

MCP 설정 파일에 추가하세요:
macOS:~/Library/Application Support/Claude/cla_desktop_config.json

Windows:%APPDATA%/Claude/claude_desktop_config.json

{
"mcpServers": {
"grpc-gateway": {
...

Claude Desktop을 재시작하여 설정을 적용하세요.

연결 테스트

이제 Claude가 귀하의 gRPC 서비스 메서드에 도구 (tools)로서 접근할 수 있습니다. 다음을 수행할 수 있습니다:
Claude에게 사용 가능한 도구 목록 요청
특정 gRPC 메서드 호출
복잡한 요청/응답 데이터 처리

# 게이트웨이 상태 확인
curl http://localhost:50053/health
# MCP를 통해 사용 가능한 도구 목록 확인
...

./build/grmcp --help

플래그 (Flag)	기본값 (Default)	설명 (Description)
`--grpc-host`	`localhost`	gRPC 서버 호스트 이름
`--grpc-port`	`50051`	gRPC 서버 포트
`--http-port`	`50053`	MCP 게이트웨이를 위한 HTTP 서버 포트
`--log-level`	`info`	로깅 레벨 (debug, info, warn, error)
`--dev`	`false`	상세 로깅을 포함한 개발 모드 활성화
`--descriptor`	`""`	강화된 스키마를 위한 protobuf FileDescriptorSet 파일 (.binpb) 경로

# 기본 사용법
./build/grmcp --grpc-host=localhost --grpc-port=50051
# 사용자 정의 포트 및 디버그 로깅 사용
...

ggRMCP는 gRPC 서비스를 검색하기 위해 두 가지 방법을 지원합니다:

gRPC Reflection: 실행 중인 gRPC 서버로부터의 동적 서비스 검색 (Dynamic service discovery)
FileDescriptorSet: 풍부한 주석 추출 기능이 포함된 사전 컴파일된 .binpb 파일
Schema Generation: Protobuf 메시지 정의를 문서화된 JSON 스키마 (JSON schemas)로 변환
Tool Registration: 각 gRPC 메서드가 사용 가능한 MCP 도구 (Tool)로 등록됨

검색된 각 gRPC 메서드는 다음과 같은 기능을 갖춘 MCP 도구가 됩니다:

Input Schema: Protobuf 메시지 정의로부터 생성됨
Output Schema: 자동 응답 타입 매핑
Validation: 내장된 요청/응답 검증 (Validation)
Documentation: 메서드 및 파라미터 설명

JSON to Protobuf: 들어오는 JSON 요청은 검증을 거쳐 Protobuf로 변환됨
Header Filtering: HTTP 헤더는 보안을 위해 필터링된 후 gRPC 메타데이터 (Metadata)로 전달됨
gRPC Invocation: 백엔드 서비스에 대한 네이티브 gRPC 호출
Response Conversion: Protobuf 응답이 다시 JSON으로 변환됨
Error Handling: gRPC 에러가 MCP 에러 형식으로 매핑됨

ggRMCP는 Protobuf 정의에서 풍부한 문서와 주석을 추출하기 위해 Protobuf FileDescriptorSet 파일 (.binpb) 로드를 지원합니다. 이 기능은 서비스, 메서드 및 필드에 대한 의미 있는 설명을 포함하여 강화된 도구 스키마를 제공합니다.

# .proto 파일로부터 FileDescriptorSet 생성
protoc --descriptor_set_out=service.binpb \
--include_source_info \
...

Reflection만 사용 시:

{
"name": "user_service_get_user",
"description": "Calls the GetUser method of the user.UserService service",
...

FileDescriptorSet 사용 시:

{
"name": "user_service_get_user",
"description": "Retrieves user information by ID with full profile data",
...

ggRMCP는 보안 중심의 필터링을 갖춘 고급 헤더 전달 (Header forwarding) 기능을 포함합니다:

graph TD
A[HTTP Request Headers] --> B[Header Filter]
B --> C{Enabled?}
...

기본 보안 설정:

차단된 헤더 (Blocked Headers): cookie, set-cookie, host, content-length, mcp-session-id

허용된 헤더 (Allowed Headers): authorization, x-trace-id, user-agent

, x-request-id`

대소문자 구분 없음 (Case Insensitive): 헤더는 기본적으로 대소문자를 구분하지 않고 매칭됩니다. 모두 전달 비활성화 (ForwardAll Disabled): 명시적으로 허용된 헤더만 전달됩니다.

graph TD
A[Incoming Request] --> B{Session Valid?}
B -->|No| C[Create Session]
...

세션 관리 (Session Management): 만료 시간이 포함된 UUID 기반 세션 추적
속도 제한 (Rate Limiting): 세션별 및 전역 속도 제한
입력 검증 (Input Validation): JSON-RPC 및 파라미터 검증
오류 정화 (Error Sanitization): 정보 노출 방지
보안 헤더 (Security Headers): CORS, CSP 및 기타 보호 헤더

엔드포인트 (Endpoint)	메서드 (Method)	목적 (Purpose)
`/`	`GET`	MCP 기능 검색 (capability discovery)
`/`	`POST`	JSON-RPC 메서드 호출
`/health`	`GET`	상태 확인 (Health check) 및 서비스 상태
`/metrics`	`GET`	서비스 통계 및 메트릭 (metrics)

{
"status": "healthy",
"timestamp": "2024-01-01T12:00:00Z",
...
}

# 모든 테스트 실행
make test
# 커버리지(coverage)와 함께 테스트 실행
...

# 통합 테스트 실행 (gRPC 서비스 실행 필요)
go test -tags=integration ./tests/...

# 사용 가능한 도구 목록 조회
curl -X POST http://localhost:50053/ \
-H "Content-Type: application/json" \
...

# 개발 도구 설치
make install-tools
# 린팅 (linting) 실행
...

1. 포트가 이미 사용 중임 (Port already in use)

# 포트를 사용 중인 프로세스 확인
lsof -ti:50051
# 프로세스 종료
...

2. Protobuf 생성 실패 (Protobuf generation fails)

# Protobuf 도구 수동 설치
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
...

3. gRPC 서비스를 찾을 수 없음 (gRPC service not discovered)

gRPC 서비스에 리플렉션 (reflection)이 활성화되어 있는지 확인하세요.
서비스가 지정된 host:port에서 리스닝(listening) 중인지 확인하세요.
방화벽 설정이 연결을 허용하는지 확인하세요.

4. MCP 연결 문제 (MCP connection issues)

설정 변경 후 Claude Desktop을 재시작하세요.
MCP 설정 파일 경로가 올바른지 확인하세요.
ggRMCP 게이트웨이가 실행 중이며 접근 가능한지 확인하세요.

이 프로젝트는 활발히 개발 중입니다. 기여(Contributions)를 환영합니다!

저장소(Repository)를 Fork 하세요
기능 브랜치(Feature branch)를 생성하세요 (git checkout -b feature/amazing-feature)
변경 사항을 적용하세요
새로운 기능에 대한 테스트를 추가하세요
테스트 스위트(Test suite)를 실행하세요 (make test)
변경 사항을 커밋(Commit)하세요 (git commit -m 'Add amazing feature')
브랜치로 푸시(Push)하세요 (git push origin feature/amazing-feature)
풀 리퀘스트(Pull Request)를 생성하세요
Go의 베스트 프랙티스(Best practices)와 관용구(Idioms)를 따르세요
새로운 기능에 대해 포괄적인 테스트를 추가하세요
API 변경 사항에 대한 문서를 업데이트하세요
관습적인 커밋 메시지(Conventional commit messages)를 사용하세요
모든 CI 체크가 통과하는지 확인하세요

이 프로젝트는 MIT 라이선스(MIT License) 하에 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

이 프로젝트를 가능하게 해준 Model Context Protocol (MCP) ;-)
견고한 RPC 프레임워크를 제공한 gRPC 커뮤니티
탁월한 프로그래밍 언어를 제공한 Go 팀

이 Go 구현체는 gRPC-to-MCP 게이트웨이 제품군의 일부입니다:

GrMCP (Java): 오리지널 Java 구현체

Issues: 버그 보고 및 기능 요청은 GitHub Issues를 사용해 주세요
Discussions: 질문 및 커뮤니티 채팅은 GitHub Discussions를 사용해 주세요
Security: 보안 관련 이슈는 ahmad.alobaidy@gmail.com으로 이메일을 보내주세요

ggRMCP: gRPC 서비스를 MCP 호환 도구로 변환하는 고성능 Go 기반 게이트웨이

요약

핵심 포인트

Claude Desktop을 재시작하여 설정을 적용하세요.

댓글