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 install2.设置服务器名称
src/index.ts 在文件中修改服务器名称：
const server = new McpServer({
name: 'typescript-mcp-server', // 여기를 원하는 서버 이름으로 변경
version: '1.0.0',
// 활성화 하고자 하는 기능 설정
capabilities: {
tools: {},
resources: {}
}
})💡 提示：目前锅炉板上已经实现了计算器、人事工具和服务器信息资源的示例。
3.构建
npm run build4.运行
node build/index.js构建成功后 build/ 在目录中创建编译的JavaScript文件，服务器等待MCP客户端的连接。
🛠️ 开发指南
添加MCP工具
向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）必须设置为环境变量。📦 主要依赖性
- @模型上下文协议/sdk：实现MCP协议的官方SDK
- 黄道带：TypeScript优先模式验证库
- 打字稿：TypeScript编译器
- @拥抱脸/推理：使用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连接
可以在Cursor上测试开发的MCP服务器：
修改配置文件
./.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是多少？”（测试计算器工具）
- “打个招呼说你好”（人事工具测试）
- “告诉我现在的时间”（测试时间工具）
- “请生成骑马的宇航员的图像”（图像生成工具测试）
- 查询服务器信息资源
🔗 参考资料
📄 许可证
麻省理工学院