TypeScript MCP Server 보일러플레이트
TypeScript MCP SDK를 활용하여 Model Context Protocol (MCP) 서버를 빠르게 개발할 수 있는 보일러플레이트 프로젝트입니다.
📁 프로젝트 구조
typescript-mcp-server-boilerplate/
├── src/
│ └── index.ts # MCP 서버 메인 진입점
├── build/ # 컴파일된 JavaScript 파일 (빌드 후 생성)
├── package.json # 프로젝트 의존성 및 스크립트
├── tsconfig.json # TypeScript 설정
└── README.md # 프로젝트 문서
🚀 시작하기
1. 의존성 설치
npm install
2. 서버 이름 설정
src/index.ts 파일에서 서버 이름을 수정하세요:
const server = new McpServer({
name: 'typescript-mcp-server', // 여기를 원하는 서버 이름으로 변경
version: '1.0.0',
// 활성화 하고자 하는 기능 설정
capabilities: {
tools: {},
resources: {}
}
})
💡 팁: 현재 보일러플레이트에는 이미 계산기와 인사 도구, 그리고 서버 정보 리소스가 예시로 구현되어 있습니다.
3. 빌드
npm run build
4. 실행
node build/index.js
빌드가 성공하면 build/ 디렉토리에 컴파일된 JavaScript 파일이 생성되고, 서버가 MCP 클라이언트의 연결을 대기합니다.
🛠️ 개발 가이드
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)
}
]
}
}
)
이미지 생성 도구 예시
// AI 이미지 생성 도구 (Hugging Face FLUX.1 모델 사용)
server.tool(
'generate_image',
'Generates an image from a text prompt using AI image generation (FLUX.1-schnell model)',
{
prompt: z.string().describe('Text description of the image to generate')
},
async ({ prompt }) => {
const client = new InferenceClient(process.env.HF_TOKEN)
// Generate image
const image = await client.textToImage({
provider: 'fal-ai',
model: 'black-forest-labs/FLUX.1-schnell',
inputs: prompt,
parameters: { num_inference_steps: 5 }
})
// Convert Blob to base64
const arrayBuffer = await (image as any).arrayBuffer()
const buffer = Buffer.from(arrayBuffer)
const base64Data = buffer.toString('base64')
return {
content: [
{
type: 'image' as const,
data: base64Data,
mimeType: 'image/png'
}
],
_meta: {
annotations: {
audience: ['user'],
priority: 0.9
}
}
}
}
)
참고: 이미지 생성 도구를 사용하려면 Hugging Face API 토큰(
HF_TOKEN)을 환경 변수로 설정해야 합니다.
📦 주요 의존성
- @modelcontextprotocol/sdk: MCP 프로토콜 구현을 위한 공식 SDK
- zod: TypeScript 우선 스키마 검증 라이브러리
- typescript: TypeScript 컴파일러
- @huggingface/inference: Hugging Face AI 모델 사용을 위한 라이브러리
🔧 스크립트
npm run build: TypeScript를 JavaScript로 컴파일하고 실행 권한 설정
📋 사용 예시
완전한 서버 예시
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { z } from 'zod'
// 서버 생성
const server = new McpServer({
name: 'my-mcp-server',
version: '1.0.0',
capabilities: {
tools: {},
resources: {}
}
})
// 간단한 인사 도구
server.tool(
'greet',
{
name: z.string().describe('인사할 사람의 이름'),
language: z
.enum(['ko', 'en'])
.optional()
.default('ko')
.describe('인사 언어 (기본값: ko)')
},
async ({ name, language }) => {
const greeting =
language === 'ko' ? `안녕하세요, ${name}님!` : `Hello, ${name}!`
return {
content: [
{
type: 'text',
text: greeting
}
]
}
}
)
// 시스템 정보 리소스
server.resource(
'system-info',
'system://info',
{
name: '시스템 정보',
description: '서버의 현재 상태 및 시스템 정보',
mimeType: 'application/json'
},
async () => {
const systemInfo = {
server: 'my-mcp-server',
version: '1.0.0',
timestamp: new Date().toISOString(),
uptime: process.uptime()
}
return {
contents: [
{
uri: 'system://info',
mimeType: 'application/json',
text: JSON.stringify(systemInfo, null, 2)
}
]
}
}
)
// 서버 시작
async function main() {
const transport = new StdioServerTransport()
await server.connect(transport)
console.error('MCP 서버가 시작되었습니다')
}
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"],
"env": {
"HF_TOKEN": "your-huggingface-api-token-here"
}
}
}
}
주의:
- 절대 경로를 사용해야 합니다.
pwd명령어로 현재 경로를 확인하세요.- 이미지 생성 도구를 사용하려면
env섹션에 Hugging Face API 토큰을 설정해야 합니다.- Hugging Face 토큰은 https://huggingface.co/settings/tokens에서 발급받을 수 있습니다.
테스트 명령어
Cursor MCP에서 다음과 같이 테스트해볼 수 있습니다:
- "5 더하기 3은 얼마야?" (계산기 도구 테스트)
- "안녕하세요 라고 인사해줘" (인사 도구 테스트)
- "현재 시간 알려줘" (시간 도구 테스트)
- "말을 타고 있는 우주인 이미지 생성해줘" (이미지 생성 도구 테스트)
- 서버 정보 리소스 조회
🔗 참고 자료
📄 라이선스
MIT