Skip to main content
Glama
JeonJunYeong

sample-mcp

by JeonJunYeong
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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

Related MCP server: NestJS MCP Server

🚀 시작하기

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

This server cannot be installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/JeonJunYeong/sample-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server