# Multi-Purpose MCP Server

다양한 기능을 제공하는 Model Context Protocol (MCP) 서버입니다. 시간 조회, 계산기, 인사말, 코드 리뷰, 이미지 생성 등의 기능을 포함하고 있습니다.

## 🚀 주요 기능

- **현재 시간 조회**: 지정된 시간대의 현재 시간을 조회합니다
- **다양한 시간대 지원**: Asia/Seoul, America/New_York, Europe/London 등 모든 IANA 시간대 지원
- **계산기**: 두 숫자에 대한 사칙연산을 수행합니다
- **다국어 인사말**: 다양한 언어로 인사말을 제공합니다
- **코드 리뷰**: 코드에 대한 상세한 리뷰 프롬프트를 생성합니다
- **이미지 생성**: 텍스트 프롬프트를 사용하여 AI 이미지를 생성합니다

## 📁 프로젝트 구조

```
time-mcp-server/
├── src/
│   └── index.ts          # MCP 서버 메인 진입점
├── build/                # 컴파일된 JavaScript 파일 (빌드 후 생성)
├── package.json          # 프로젝트 의존성 및 스크립트
├── tsconfig.json         # TypeScript 설정
└── README.md            # 프로젝트 문서
```

## 🚀 시작하기

### 1. 의존성 설치

```bash
npm install
```

### 2. 환경 변수 설정

이미지 생성 기능을 사용하려면 Hugging Face API 토큰이 필요합니다.

#### Hugging Face API 토큰 발급
1. [Hugging Face](https://huggingface.co/)에 계정을 생성합니다
2. [Settings > Access Tokens](https://huggingface.co/settings/tokens)에서 새 토큰을 생성합니다
3. 토큰을 복사합니다

#### 환경 변수 설정
Windows (PowerShell):
```powershell
$env:HF_TOKEN="your_hugging_face_token_here"
```

Windows (Command Prompt):
```cmd
set HF_TOKEN=your_hugging_face_token_here
```

Linux/macOS:
```bash
export HF_TOKEN="your_hugging_face_token_here"
```

또는 `.env` 파일을 생성하여 설정할 수 있습니다:
```
HF_TOKEN=your_hugging_face_token_here
```

### 3. 빌드

```bash
npm run build
```

### 4. 실행

```bash
node build/index.js
```

빌드가 성공하면 `build/` 디렉토리에 컴파일된 JavaScript 파일이 생성되고, 서버가 MCP 클라이언트의 연결을 대기합니다.

## 🛠️ 사용 방법

### 1. 시간 조회 도구

현재 시간을 조회하는 도구입니다:

- **도구 이름**: `current_time`
- **매개변수**: 
  - `timezone` (선택사항): 시간대 (예: Asia/Seoul, America/New_York, Europe/London)
  - 시간대를 지정하지 않으면 한국 시간대(Asia/Seoul)를 사용합니다

### 2. 계산기 도구

두 숫자에 대한 사칙연산을 수행하는 도구입니다:

- **도구 이름**: `calculator`
- **매개변수**:
  - `num1`: 첫 번째 숫자
  - `num2`: 두 번째 숫자
  - `operation`: 연산자 (add, subtract, multiply, divide)

### 3. 인사말 도구

다양한 언어로 인사말을 제공하는 도구입니다:

- **도구 이름**: `greeting`
- **매개변수**:
  - `name`: 사용자의 이름
  - `language`: 인사말을 할 언어 (korean, english, japanese, chinese, spanish, french, german, italian, portuguese, russian)

### 4. 코드 리뷰 도구

코드에 대한 상세한 리뷰 프롬프트를 생성하는 도구입니다:

- **도구 이름**: `code_review`
- **매개변수**:
  - `code`: 리뷰할 코드
  - `language` (선택사항): 코드 언어 (javascript, typescript, python, java, cpp, go, rust)
  - `reviewType` (선택사항): 리뷰 유형 (comprehensive, security, performance, readability, best_practices)

### 5. 이미지 생성 도구

텍스트 프롬프트를 사용하여 AI 이미지를 생성하는 도구입니다:

- **도구 이름**: `generate_image`
- **매개변수**:
  - `prompt`: 이미지 생성을 위한 프롬프트
- **반환 형식**: base64-encoded PNG 이미지

### 사용 예시

1. **한국 시간 조회** (기본값):
   ```
   현재 시간을 알려줘
   ```

2. **특정 시간대 시간 조회**:
   ```
   뉴욕 시간을 알려줘
   ```
   또는
   ```
   Europe/London 시간대의 현재 시간을 알려줘
   ```

3. **계산기 사용**:
   ```
   5 더하기 3은 얼마야?
   10 나누기 2는?
   ```

4. **다국어 인사말**:
   ```
   안녕하세요 라고 인사해줘
   Hello라고 영어로 인사해줘
   ```

5. **코드 리뷰**:
   ```
   다음 코드를 리뷰해줘: function add(a, b) { return a + b; }
   ```

6. **이미지 생성**:
   ```
   고양이가 우주를 여행하는 이미지를 생성해줘
   ```

### 지원하는 시간대 예시

- `Asia/Seoul` - 한국 시간대 (기본값)
- `America/New_York` - 뉴욕 시간대
- `America/Los_Angeles` - 로스앤젤레스 시간대
- `Europe/London` - 런던 시간대
- `Europe/Paris` - 파리 시간대
- `Asia/Tokyo` - 도쿄 시간대
- `Asia/Shanghai` - 상하이 시간대
- `Australia/Sydney` - 시드니 시간대

> 💡 **팁**: 모든 IANA 시간대를 지원합니다. [IANA Time Zone Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)에서 사용 가능한 시간대 목록을 확인할 수 있습니다.

## 🛠️ 개발 가이드

### MCP 도구(Tool) 추가하기

MCP 서버에 새로운 도구를 추가하려면 `server.tool()` 메서드에 **Zod 스키마를 직접** 정의하여 등록합니다:

```typescript
import { z } from 'zod'

// 계산기 도구 추가
server.tool(
    'calculator',
    {
        operation: z
            .enum(['add', 'subtract', 'multiply', 'divide'])
            .describe('수행할 연산 (add, subtract, multiply, divide)'),
        a: z.number().describe('첫 번째 숫자'),
        b: z.number().describe('두 번째 숫자')
    },
    async ({ operation, a, b }) => {
        // 연산 수행
        let result: number
        switch (operation) {
            case 'add':
                result = a + b
                break
            case 'subtract':
                result = a - b
                break
            case 'multiply':
                result = a * b
                break
            case 'divide':
                if (b === 0) throw new Error('0으로 나눌 수 없습니다')
                result = a / b
                break
            default:
                throw new Error('지원하지 않는 연산입니다')
        }

        const operationSymbols = {
            add: '+',
            subtract: '-',
            multiply: '×',
            divide: '÷'
        } as const

        const operationSymbol =
            operationSymbols[operation as keyof typeof operationSymbols]

        return {
            content: [
                {
                    type: 'text',
                    text: `${a} ${operationSymbol} ${b} = ${result}`
                }
            ]
        }
    }
)
```

#### 더 복잡한 도구 예시

```typescript
// 날씨 정보 조회 도구
server.tool(
    'get_weather',
    {
        city: z.string().describe('날씨를 조회할 도시명'),
        unit: z
            .enum(['celsius', 'fahrenheit'])
            .optional()
            .default('celsius')
            .describe('온도 단위 (기본값: celsius)')
    },
    async ({ city, unit }) => {
        try {
            // 실제 날씨 API 호출 로직 (예시)
            const weatherData = await fetchWeatherData(city, unit)

            return {
                content: [
                    {
                        type: 'text',
                        text: `${city}의 현재 날씨:
온도: ${weatherData.temperature}°${unit === 'celsius' ? 'C' : 'F'}
날씨: ${weatherData.condition}
습도: ${weatherData.humidity}%
풍속: ${weatherData.windSpeed}km/h`
                    }
                ]
            }
        } catch (error) {
            throw new Error(
                `날씨 정보를 가져올 수 없습니다: ${(error as Error).message}`
            )
        }
    }
)

// 도우미 함수
async function fetchWeatherData(city: string, unit: string) {
    // 실제 날씨 API 호출 구현
    // 여기서는 예시 데이터 반환
    return {
        temperature: unit === 'celsius' ? 22 : 72,
        condition: '맑음',
        humidity: 65,
        windSpeed: 12
    }
}
```

### 리소스 추가하기

MCP 서버에 리소스를 추가하여 외부 데이터나 파일에 대한 접근을 제공할 수 있습니다:

```typescript
// 리소스 등록
server.resource(
    'example-file',
    'file://example.txt',
    {
        name: '예시 텍스트 파일',
        description: '예시 텍스트 파일 설명',
        mimeType: 'text/plain'
    },
    async () => {
        return {
            contents: [
                {
                    uri: 'file://example.txt',
                    mimeType: 'text/plain',
                    text: '예시 파일 내용입니다.'
                }
            ]
        }
    }
)

// 동적 리소스 예시
server.resource(
    'app-settings',
    'config://settings',
    {
        name: '애플리케이션 설정',
        description: '애플리케이션의 현재 설정 정보',
        mimeType: 'application/json'
    },
    async () => {
        const settings = {
            theme: 'dark',
            language: 'ko-KR',
            notifications: true,
            lastUpdated: new Date().toISOString()
        }

        return {
            contents: [
                {
                    uri: 'config://settings',
                    mimeType: 'application/json',
                    text: JSON.stringify(settings, null, 2)
                }
            ]
        }
    }
)
```

## 📦 주요 의존성

-   **@modelcontextprotocol/sdk**: MCP 프로토콜 구현을 위한 공식 SDK
-   **@huggingface/inference**: Hugging Face Inference API 클라이언트 (이미지 생성용)
-   **zod**: TypeScript 우선 스키마 검증 라이브러리
-   **typescript**: TypeScript 컴파일러

## 🔧 스크립트

-   `npm run build`: TypeScript를 JavaScript로 컴파일하고 실행 권한 설정

## 📋 사용 예시

### 시간 조회 도구 사용

```typescript
// 한국 시간 조회 (기본값)
const koreanTime = await getCurrentTime() // "2024-01-15 14:30:25 (Asia/Seoul)"

// 뉴욕 시간 조회
const newYorkTime = await getCurrentTime('America/New_York') // "2024-01-15 00:30:25 (America/New_York)"

// 런던 시간 조회
const londonTime = await getCurrentTime('Europe/London') // "2024-01-15 05:30:25 (Europe/London)"
```

### 완전한 서버 예시

```typescript
import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
import { z } from 'zod'

// 시간 도구 스키마
const TimeToolSchema = z.object({
    timezone: z.string().optional().describe('시간대 (예: Asia/Seoul, America/New_York)')
})

// 현재 시간 조회 함수
const getCurrentTime = (timezone: string = 'Asia/Seoul'): string => {
    const now = new Date()
    const options: Intl.DateTimeFormatOptions = {
        timeZone: timezone,
        year: 'numeric',
        month: '2-digit',
        day: '2-digit',
        hour: '2-digit',
        minute: '2-digit',
        second: '2-digit',
        hour12: false
    }
    
    const formatter = new Intl.DateTimeFormat('ko-KR', options)
    const timeString = formatter.format(now)
    
    return `${timeString} (${timezone})`
}

// 서버 생성
const server = new Server(
    {
        name: 'time-mcp-server',
        version: '1.0.0',
    },
    {
        capabilities: {
            tools: {},
        },
    }
)

// 도구 등록
server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
        tools: [
            {
                name: 'current_time',
                description: '현재 시간을 지정된 시간대에서 조회하는 도구',
                inputSchema: {
                    type: 'object',
                    properties: {
                        timezone: {
                            type: 'string',
                            description: '시간대 (예: Asia/Seoul, America/New_York)'
                        }
                    },
                    required: []
                }
            }
        ]
    }
})

// 도구 호출 처리
server.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (request.params.name === 'current_time') {
        const { timezone } = TimeToolSchema.parse(request.params.arguments)
        const currentTime = getCurrentTime(timezone)
        
        return {
            content: [
                {
                    type: 'text',
                    text: `현재 시간: ${currentTime}`
                }
            ]
        }
    }
    
    throw new Error(`알 수 없는 도구: ${request.params.name}`)
})

// 서버 시작
async function main() {
    const transport = new StdioServerTransport()
    await server.connect(transport)
    console.error('Time MCP Server started')
}

main().catch(console.error)
```

## 🔧 Cursor MCP 연결

개발한 MCP 서버를 Cursor에서 테스트할 수 있습니다:

### 설정 파일 수정

`./.cursor/mcp.json` 파일을 편집합니다:

```json
{
    "mcpServers": {
        "typescript-mcp-server": {
            "command": "node",
            "args": ["/ABSOLUTE/PATH/TO/YOUR/PROJECT/build/index.js"]
        }
    }
}
```

> **주의**: 절대 경로를 사용해야 합니다. `pwd` 명령어로 현재 경로를 확인하세요.

### 테스트 명령어

Cursor MCP에서 다음과 같이 테스트해볼 수 있습니다:

-   "현재 시간을 알려줘" (한국 시간 조회)
-   "뉴욕 시간을 알려줘" (뉴욕 시간 조회)
-   "Europe/London 시간대의 현재 시간을 알려줘" (런던 시간 조회)
-   "5 더하기 3은 얼마야?" (계산기 도구 테스트)
-   "안녕하세요 라고 인사해줘" (인사 도구 테스트)
-   "다음 코드를 리뷰해줘: function add(a, b) { return a + b; }" (코드 리뷰 테스트)
-   "고양이가 우주를 여행하는 이미지를 생성해줘" (이미지 생성 테스트)

## 🔗 참고 자료

-   [Model Context Protocol 공식 문서](https://modelcontextprotocol.io/)
-   [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
-   [Node.js MCP 서버 개발 가이드](https://modelcontextprotocol.io/docs/develop/build-server#node)
-   [Zod 문서](https://zod.dev/)

## 📄 라이선스

MIT