Multi-Purpose MCP Server

# 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