duddn2012/go-mcp-server-gateway

Go MCP Server

MCP(Model Context Protocol) 서버 구현을 위한 Go 기반 프로젝트입니다.

아키텍처

Layered Architecture

Router → Controller → Handler → Service → Repository → Model
                                    ↓
                            MCP SDK Integration

계층별 역할:

• Router: HTTP 라우팅 및 미들웨어 적용
• Controller: 요청 라우팅 및 MCP Server 조회
• Handler: MCP 프로토콜 요청 처리
• Service: MCP Server 인스턴스 관리 및 Tool 동기화
• Repository: 데이터베이스 접근
• Model: 도메인 엔티티 정의

Multi-Tenant Architecture

• Base Database: tenants 테이블 관리 (테넌트 메타데이터)
• Tenant Database: 각 테넌트별 독립 데이터베이스
  • 각 테넌트 DB에는 tools, tool_versions 테이블 존재
  • tools: MCP Server 메타정보 관리
  • tool_versions: 각 MCP Server의 버전별 Tool 설정 (JSON)
  • 각 Tool Version의 object 컬럼에 실제 도구들 정의

디렉토리 구조

go_mcp_server/
├── cmd/server/                      # 애플리케이션 진입점
├── internal/                        # 비공개 애플리케이션 코드
│   ├── app.go                       # 애플리케이션 부트스트랩
│   ├── tenant/                      # 테넌트 도메인
│   │   ├── model/                   # 테넌트 엔티티
│   │   ├── repository/              # 테넌트 데이터 접근
│   │   └── service/                 # 테넌트 비즈니스 로직
│   ├── tool/                        # Tool 도메인
│   │   ├── model/                   # Tool, ToolVersion 엔티티
│   │   ├── repository/              # Tool 데이터 접근
│   │   ├── service/                 # Tool 비즈니스 로직
│   │   └── factory/                 # Service 팩토리
│   ├── mcp/                         # MCP 프로토콜 처리
│   │   ├── controller/              # MCP HTTP 컨트롤러
│   │   ├── dto/                     # MCP Data Transfer Objects
│   │   ├── server/                  # MCP Server 생명주기 관리
│   │   ├── service/                 # MCP Server Service
│   │   └── tool/                    # MCP Tool 실행 및 관리
│   ├── job/                         # 백그라운드 Job
│   └── infrastructure/              # 인프라 계층
│       ├── config/                  # 설정 관리
│       ├── database/                # DB 연결 관리
│       ├── middleware/              # HTTP 미들웨어
│       ├── registry/                # MCP Server 레지스트리
│       └── router/                  # 라우팅 설정
└── test/                            # 테스트 유틸리티

빌드 및 실행

# 빌드
go build -o mcp-server ./cmd/server

# 실행
./mcp-server

API 엔드포인트

동적 라우팅 패턴: /{tenant_code}/{mcp_server_name}/{version}

예시:

• POST /OMS_TEST9999/rails-server/1/tools/sync - DB에서 Tool 버전 재로드 및 동기화
• GET /OMS_TEST9999/rails-server/1 - MCP SSE 연결 (Server-Sent Events)
• POST /OMS_TEST9999/rails-server/1 - MCP 요청 처리 (tools/call, tools/list 등)

도구 등록

MCP 서버의 도구는 tool_versions 테이블의 object 컬럼에 JSON 스키마로 정의됩니다. 각 MCP Server는 여러 버전을 가질 수 있으며, 버전별로 다른 Tool 설정을 사용할 수 있습니다.

JSON 스키마 구조

{
  "env": {},
  "tools": [
    {
      "name": "send_faq_url",
      "title": "send_faq_url",
      "run_type": "api_call",
      "connection": {
        "url": "http://localhost:17654/sessions",
        "method": "POST",
        "timeout": 5,
        "authType": "none",
        "credentials": [],
        "max_retries": 3,
        "retry_delay": 1000,
        "connection_type": "remote"
      },
      "description": "고객 전화번호로 FAQ URL 메시지 전송",
      "request_defaults": {
        "body": {
          "password": "rap911$"
        }
      },
      "tool_declaration": {
        "type": "object",
        "required": [
          "body"
        ],
        "properties": {
          "body": {
            "type": "object",
            "required": [
              "login"
            ],
            "properties": {
              "login": {
                "type": "string",
                "description": "Username for authentication"
              }
            },
            "description": "Authentication headers"
          }
        }
      }
    }
  ]
}

스키마 필드 설명

최상위 구조

• env: 환경 변수 (선택)
• tools: 도구 배열 (필수)

도구 필드

• name: 도구 이름 (필수)
• title: 도구 제목 (선택)
• description: 도구 설명 (필수)
• run_type: 실행 타입 ("api_call" 또는 "echo")

Connection 설정

• url: API 엔드포인트 URL
• method: HTTP 메서드 (GET, POST 등)
• timeout: 타임아웃 (초)
• authType: 인증 타입 ("none", "bearer" 등)
• credentials: 인증 정보 배열
• max_retries: 최대 재시도 횟수
• retry_delay: 재시도 지연 시간 (ms)
• connection_type: 연결 타입 ("remote", "local" 등)

Request Defaults

• body: 기본 요청 바디
• headers: 기본 헤더
• query: 기본 쿼리 파라미터

Tool Declaration

• MCP 도구 선언 스키마 (JSON Schema 형식)
• type, required, properties 등 표준 JSON Schema 필드 사용

개발

테스트

go test ./...