sample-mcp

NestJS + TypeScript 기반 MCP (Model Context Protocol) Server 샘플 프로젝트입니다.

Claude Desktop, Cursor, Codex 등 MCP를 지원하는 클라이언트에서 바로 연결하여 사용할 수 있습니다.

---

📁 프로젝트 구조

sample-mcp/
├── src/
│   ├── main.ts                          # 앱 진입점 (stdio transport로 MCP 서버 시작)
│   ├── app.module.ts                    # NestJS 루트 모듈
│   ├── config/
│   │   └── app.config.ts               # 환경변수 설정
│   └── mcp/
│       ├── mcp.module.ts               # MCP 모듈
│       ├── mcp.service.ts              # MCP Server 핵심 서비스
│       └── tools/
│           ├── base.tool.ts            # 모든 Tool의 추상 기반 클래스
│           ├── tool.registry.ts        # Tool 중앙 관리 레지스트리
│           ├── tools.module.ts         # Tools NestJS 모듈
│           └── ping/
│               ├── ping.tool.ts        # ping Tool 구현체
│               └── ping.dto.ts         # ping Tool 입출력 타입 정의
├── .env                                 # 환경변수 (gitignore 대상)
├── .env.example                         # 환경변수 예시
├── .prettierrc                          # Prettier 설정
├── eslint.config.mjs                    # ESLint 설정
├── nest-cli.json                        # NestJS CLI 설정
├── tsconfig.json                        # TypeScript 설정 (strict mode)
└── package.json

---

🚀 시작하기

1. 의존성 설치

pnpm install

2. 환경변수 설정

cp .env.example .env

.env 파일을 필요에 따라 수정합니다:

MCP_SERVER_NAME=sample-mcp
MCP_SERVER_VERSION=1.0.0
LOG_LEVEL=log
NODE_ENV=development

3. 빌드

pnpm build

4. 실행

# 프로덕션 (빌드 후)
pnpm start:prod

# 개발 모드 (watch)
pnpm start:dev

⚠️ 중요: MCP Server는 stdio transport를 사용합니다.
직접 실행하면 터미널에서 JSON-RPC 메시지를 기다리는 상태가 됩니다.
실제 사용 시 MCP Client (Claude Desktop, Cursor 등)에서 이 서버를 실행합니다.

---

🔌 MCP Client 연결 설정

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json 파일을 편집합니다:

{
  "mcpServers": {
    "sample-mcp": {
      "command": "node",
      "args": ["/절대경로/sample-mcp/dist/main.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

또는 pnpm + ts-node로 빌드 없이 실행:

{
  "mcpServers": {
    "sample-mcp": {
      "command": "pnpm",
      "args": ["--dir", "/절대경로/sample-mcp", "start:prod"],
      "env": {}
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "sample-mcp": {
      "command": "node",
      "args": ["/절대경로/sample-mcp/dist/main.js"]
    }
  }
}

---

🛠️ 구현된 Tool

ping

MCP 서버 연결 상태를 확인하는 테스트 Tool입니다.

입력:

{
  "message": "hello"
}

출력:

{
  "success": true,
  "message": "pong",
  "receivedMessage": "hello"
}

---

➕ 새로운 Tool 추가하��

1. Tool 파일 생성

   src/mcp/tools/<tool-name>/
   ├── <tool-name>.tool.ts    # BaseTool 상속
   └── <tool-name>.dto.ts     # Zod 스키마 + 타입 정의
   

2. <tool-name>.tool.ts 구현

   import { Injectable } from '@nestjs/common';
   import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
   import { BaseTool } from '../base.tool';
   
   @Injectable()
   export class MyTool extends BaseTool {
     get definition(): Tool {
       return {
         name: 'my-tool',
         description: 'Tool 설명',
         inputSchema: {
           type: 'object',
           properties: {
             input: { type: 'string', description: '입력값' },
           },
           required: ['input'],
         },
       };
     }
   
     async execute(args: Record<string, unknown>): Promise<CallToolResult> {
       // 로직 구현
       return this.success({ result: 'ok' });
     }
   }
   

3. tools.module.ts에 등록

   @Module({
     providers: [ToolRegistry, PingTool, MyTool], // ✅ 추가
     exports: [ToolRegistry],
   })
   export class ToolsModule {}
   

4. tool.registry.ts에 주입

   constructor(
     private readonly pingTool: PingTool,
     private readonly myTool: MyTool, // ✅ 추가
   ) {
     this.registerTools([this.pingTool, this.myTool]); // ✅ 배열에 추가
   }
   

---

🧹 코드 품질

# 린트 검사 및 자동 수정
pnpm lint

# 코드 포맷팅
pnpm format

# 테스트
pnpm test

---

📦 기술 스택

항목	버전
NestJS	^11.0.0
TypeScript	^5.1.3 (strict mode)
MCP SDK	^1.12.1
Zod	^3.25.0
pnpm	latest
Node.js	≥ 18.0.0