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

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

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

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

## 목차

- [기능](#기능)
- [요구사항](#요구사항)
- [설치](#설치)
- [빌드](#빌드)
- [실행](#실행)
- [Cursor AI IDE와 연동하기](#cursor-ai-ide와-연동하기)
- [문제 해결](#문제-해결)

## 기능

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

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

## 요구사항

- Node.js 18.0.0 이상

## 설치

의존성 패키지 설치:

```bash
npm install
```

## 빌드

```bash
npm run build
```

## 실행

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

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

```bash
npx gorela-developer-mcp-server
```

### 로컬 빌드 버전 실행

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

```bash
npm start
```

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

개발 모드로 실행:

```bash
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 사용 (권장)

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

#### 방법 2: 직접 경로 지정

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

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

# 필요한 패키지 설치
npm install

# 프로젝트 빌드
npm run build
```

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

```json
{
  "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 환경 관련 문제

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

```bash
# 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) 사용량이 정상적인지 확인합니다.