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. 의존성 설치

npm install

2. 환경 변수 설정

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

Hugging Face API 토큰 발급

1. Hugging Face에 계정을 생성합니다
2. Settings > Access Tokens에서 새 토큰을 생성합니다
3. 토큰을 복사합니다

환경 변수 설정

Windows (PowerShell):

$env:HF_TOKEN="your_hugging_face_token_here"

Windows (Command Prompt):

set HF_TOKEN=your_hugging_face_token_here

Linux/macOS:

export HF_TOKEN="your_hugging_face_token_here"

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

HF_TOKEN=your_hugging_face_token_here

3. 빌드

npm run build

4. 실행

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에서 사용 가능한 시간대 목록을 확인할 수 있습니다.

🛠️ 개발 가이드

MCP 도구(Tool) 추가하기

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

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}`
                }
            ]
        }
    }
)

더 복잡한 도구 예시

// 날씨 정보 조회 도구
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 서버에 리소스를 추가하여 외부 데이터나 파일에 대한 접근을 제공할 수 있습니다:

// 리소스 등록
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로 컴파일하고 실행 권한 설정

📋 사용 예시

시간 조회 도구 사용

// 한국 시간 조회 (기본값)
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)"

완전한 서버 예시

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 파일을 편집합니다:

{
    "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 공식 문서
• MCP TypeScript SDK
• Node.js MCP 서버 개발 가이드
• Zod 문서

📄 라이선스

MIT