gorela-developer-mcp-server

고릴라(Gorela) 개발자 사이트 MCP 서버

이 프로젝트는 Model Context Protocol을 사용하여 구현된 MCP 서버(MCP Server)로, 고릴라(Gorela) API 문서를 AI 모델에 컨텍스트로 제공합니다.

고릴라(Gorela)는 바로고(BAROGO)에서 제공하는 배달 중계 플랫폼으로, 주문 제휴사와 배달대행사를 연결하는 API를 제공합니다.

Cursor AI IDE와 같은 MCP 호스트 환경에서 AI가 고릴라 API에 대해 이해하고 응답할 수 있도록 지원합니다.

목차

• 기능
• 요구사항
• 설치
• 빌드
• 실행
• Cursor AI IDE와 연동하기
• 문제 해결

기능

이 MCP 서버는 다음 기능을 제공합니다:

• 요청된 경로의 고릴라 API 문서를 안전하게 가져와 AI 모델에 컨텍스트로 제공

요구사항

• Node.js 18.0.0 이상

설치

의존성 패키지 설치:

npm install

빌드

npm run build

실행

npm 저장소 배포 버전 실행 (권장)

npm 저장소에 배포된 버전은 설치 없이 바로 실행할 수 있습니다:

npx gorela-developer-mcp-server

로컬 빌드 버전 실행

로컬에서 빌드한 버전 실행:

npm start

실행 후 로그는 프로젝트 루트 디렉토리의 logs/mcp-server.log 파일에서 확인할 수 있습니다. 로그 경로는 실행 환경에 상관없이 항상 프로젝트 루트를 기준으로 저장됩니다.

개발 모드로 실행:

npm run dev

Cursor AI IDE와 연동하기

이 MCP 서버는 Cursor AI IDE(MCP Host)에 연결되어 AI 모델이 고릴라 API 문서를 컨텍스트로 활용할 수 있게 합니다.

1. Cursor AI 설정

Cursor AI IDE의 Settings 메뉴를 통해 MCP 서버를 등록할 수 있습니다.

중요: 설정만 하면 됩니다. 사용자가 별도로 서버를 실행할 필요가 없습니다. Cursor IDE가 필요할 때 자동으로 서버를 실행합니다.

설정 단계:

1. Cursor AI IDE에서 Settings 메뉴로 이동합니다.
2. "MCP" 섹션을 찾습니다.
3. "Add new global MCP server" 버튼을 클릭합니다.
4. 그러면 ~/.cursor/mcp.json 파일이 열립니다.

이 파일에 다음과 같이 고릴라 MCP 서버 정보를 추가합니다:

방법 1: npx 사용 (권장)

{
  "mcpServers": {
    "gorela-api-docs": {
      "name": "Gorela Developer Site MCP",
      "type": "stdio",
      "command": "npx",
      "args": ["gorela-developer-mcp-server"]
    }
  }
}

방법 2: 직접 경로 지정

이 방법을 사용하려면 먼저 프로젝트를 설치하고 빌드해야 합니다:

# 프로젝트 디렉토리로 이동
cd /실제경로/gorela-developer-mcp-server

# 필요한 패키지 설치
npm install

# 프로젝트 빌드
npm run build

그런 다음 Cursor의 MCP 설정에 다음과 같이 추가합니다:

{
  "mcpServers": {
    "gorela-api-docs": {
      "name": "Gorela Developer Site MCP",
      "type": "stdio",
      "command": "node",
      "args": ["/실제경로/gorela-developer-mcp-server/dist/index.js"]
    }
  }
}

중요: 방법 2 사용 시 /실제경로 부분을 여러분의 실제 프로젝트 경로로 변경해야 합니다. 예를 들어 macOS에서는 /Users/사용자명/Projects/gorela-developer-mcp-server/dist/index.js 같은 형태가 될 수 있습니다.

Windows에서는 경로가 다를 수 있으며, 백슬래시(\) 대신 슬래시(/)를 사용해야 합니다. 예: C:/Users/사용자명/Projects/gorela-developer-mcp-server/dist/index.js

파일을 저장한 후 Cursor IDE를 다시 시작하면 MCP 서버가 등록됩니다.

참고: 설정 파일이 비어있는 경우 위 형식에 맞춰 전체 내용을 작성하고, 이미 다른 MCP 서버가 등록되어 있는 경우에는 mcpServers 객체 내에 추가해주시면 됩니다.

2. Cursor AI에서 사용하기

MCP 서버가 설정되면, Cursor AI의 채팅 인터페이스에서 다음과 같이 사용할 수 있습니다:

/mcp 고릴라 연동에 필요한 api를 간단히 숙지해주세요.

고릴라 api 호출 헤더를 어떻게 설정해야 하나요?

주문 접수 api 유형에 대해 알려주세요.

주문 접수시 고정 요금, 유연 요금, 의무 수행, 자율 수행, 주소 기반, 상점 기반에 대한 차이점을 알려주세요.

예약 주문 접수시 유의사항에 대해 알려주세요.

주문 조회 api 테스트 코드를 작성해주세요.

3. 연동 장점

Cursor AI와 MCP 서버를 연동하면 다음과 같은 장점이 있습니다:

• 개발자는 IDE를 떠나지 않고도 고릴라 API 문서에 접근할 수 있습니다.
• AI의 도움을 받아 API 문서 내용을 더 쉽게 이해하고 활용할 수 있습니다.
• 고릴라 API에 대한 자연어 질문을 통해 신속한 답변과 코드 예시를 얻을 수 있습니다.
• 개발 생산성이 향상되고 고릴라 연동에 필요한 시간이 단축됩니다.

4. 로그 확인

MCP 서버는 모든 작업을 프로젝트 루트 디렉토리의 logs/mcp-server.log 파일에 로깅합니다. 서버 실행 시 로그 파일의 정확한 경로가 시작 로그에 기록됩니다. 서버 동작이나 문제 해결이 필요할 때 이 로그 파일을 확인하세요. 로그 파일에는 다음과 같은 정보가 포함됩니다:

• 서버 시작 및 연결 정보
• API 문서 요청 및 응답
• 오류 상황 및 경고 메시지
• 보안 관련 이벤트 (예: 상위 디렉토리 접근 시도)

문제 해결

MCP 서버가 로드되지 않는 경우

1. Cursor IDE를 재시작했는지 확인합니다.
2. ~/.cursor/mcp.json 파일의 경로 및 명령어가 올바른지 확인합니다.
3. 로그 파일을 확인하여 오류 메시지를 파악합니다.
4. npx 명령어 사용 시 인터넷 연결이 정상적인지 확인합니다.

Node.js 환경 관련 문제

다음과 같은 환경 설정 문제가 발생할 수 있습니다:

# Node.js 버전 확인
node --version

# TypeScript 관련 패키지가 설치되어 있는지 확인
npm list typescript ts-node

• Node.js 버전은 18 이상을 권장합니다.
• 필요한 패키지가 누락된 경우 npm install을 실행하세요.
• TypeScript 컴파일 오류가 발생하면 로그를 확인하고 해당 파일을 수정하세요.

문서를 찾을 수 없는 경우

API 문서 URL 경로가 변경되었거나 네트워크 연결 문제일 수 있습니다:

1. 인터넷 연결이 정상적인지 확인합니다.
2. 로그 파일에서 관련 오류 메시지를 확인합니다.
3. 개발자 사이트에 접속하여 문서가 존재하는지 확인합니다.

MCP 서버가 응답하지 않는 경우

1. 실행 중인 MCP 서버 프로세스가 있는지 확인합니다.
2. 로그 파일에서 오류나 타임아웃 메시지를 확인합니다.
3. 시스템 리소스(메모리, CPU) 사용량이 정상적인지 확인합니다.