从零到一：用TypeScript打造你的第一个MCP工具服务器

1. 为什么选择TypeScript开发MCP服务器

TypeScript作为JavaScript的超集，在开发MCP服务器时有着天然的优势。我刚开始接触MCP开发时也纠结过语言选择问题，但实际使用下来发现TypeScript的类型系统简直就是为MCP这类协议开发量身定制的。想象一下，当你在定义工具接口时，能够清晰地看到每个参数的类型和返回值结构，这种开发体验比纯JavaScript要舒服太多。

MCP（Model Context Protocol）的核心在于规范化的通信接口，而TypeScript的interface正好可以完美描述这些协议结构。比如定义一个加法工具的输入参数，你可以直接用interface声明：

interface AddParams { a: number; b: number; }

这样不仅代码更易读，还能在编码阶段就捕获类型错误。我遇到过最典型的场景是处理数字输入时，JavaScript需要手动做类型检查，而TypeScript在编译阶段就会提醒你参数类型不匹配的问题。

另一个重要优势是开发工具链的支持。VS Code对TypeScript的智能提示简直不要太友好，当你输入server.tool(时，IDE会自动提示需要填写的参数类型和返回值结构。这对于MCP开发这种需要严格遵循协议规范的场景特别有用，大大降低了出错概率。

2. 从零搭建开发环境

2.1 初始化项目结构

先创建一个干净的项目目录，这是我推荐的标准结构：

mkdir mcp-calculator && cd mcp-calculator npm init -y

接下来安装核心依赖时有个小技巧：把开发依赖和生产依赖分开安装会更清晰。我通常会这样操作：

# 生产依赖 npm install @modelcontextprotocol/sdk zod # 开发依赖 npm install -D typescript @types/node ts-node nodemon

初始化TypeScript配置时，建议使用更严格的编译选项。这是我常用的tsconfig.json配置：

{ "compilerOptions": { "target": "ES2020", "module": "commonjs", "outDir": "./dist", "rootDir": "./src", "strict": true, "esModuleInterop": true, "skipLibCheck": true }, "include": ["src/**/*"] }

2.2 配置开发工作流

在package.json中添加这些脚本会让开发更高效：

{ "scripts": { "build": "tsc", "start": "node dist/server.js", "dev": "nodemon --watch 'src/**/*.ts' --exec 'ts-node' src/server.ts" } }

使用nodemon+ts-node的组合可以实现保存自动重启，实测开发效率提升至少50%。第一次配置时我踩过的坑是忘记安装ts-node，导致nodemon无法正确解析TypeScript文件，所以务必确保这两个开发依赖都已安装。

3. 核心代码实现详解

3.1 构建服务器骨架

先创建一个最基本的服务器实例。这里有个细节需要注意：MCP服务器的name和version字段会暴露给客户端，所以命名要有意义：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio'; const server = new McpServer({ name: 'calculator-server', version: '1.0.0', description: '提供四则运算服务的MCP服务器', capabilities: { tools: {} } });

3.2 实现工具方法

以加法工具为例，完整的实现应该包含三部分：工具定义、参数验证和业务逻辑。我习惯用Zod先定义严格的输入模式：

import { z } from 'zod'; const NumberSchema = z.number({ required_error: "参数必须为数字", invalid_type_error: "参数必须为数字" }).describe("用于计算的数字参数");

然后实现工具逻辑时，建议把核心计算部分提取成纯函数，这样更易于测试：

function addNumbers(a: number, b: number): number { return a + b; } server.tool('add', '执行两个数字的加法运算', { a: NumberSchema, b: NumberSchema }, async ({a, b}) => { const result = addNumbers(a, b); return { content: [{ type: 'text', text: `${a} + ${b} = ${result}` }] }; });

3.3 增强错误处理

对于除法这种可能出错的操作，建议实现两重保护：Zod验证和运行时检查。这是我总结的最佳实践：

server.tool('divide', '执行除法运算', { dividend: NumberSchema, divisor: NumberSchema.min(0.0001, "除数不能为零") }, async ({dividend, divisor}) => { // 双重检查更保险 if (Math.abs(divisor) < Number.EPSILON) { throw new Error("Division by zero"); } const result = dividend / divisor; return { content: [{ type: 'text', text: `${dividend} ÷ ${divisor} = ${result.toFixed(4)}` }] }; });

4. 调试与集成技巧

4.1 VS Code调试配置

在.vscode/launch.json中添加这个配置可以方便调试：

{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Debug MCP Server", "skipFiles": ["<node_internals>/**"], "program": "${workspaceFolder}/src/server.ts", "outFiles": ["${workspaceFolder}/dist/**/*.js"] } ] }

4.2 性能优化建议

当工具调用频繁时，可以考虑添加简单的缓存机制。比如对计算器来说，可以缓存最近的计算结果：

const calculationCache = new Map<string, number>(); function getCacheKey(operation: string, a: number, b: number): string { return `${operation}_${a}_${b}`; } server.tool('add', '加法运算', { a: NumberSchema, b: NumberSchema }, async ({a, b}) => { const cacheKey = getCacheKey('add', a, b); if (calculationCache.has(cacheKey)) { return calculationCache.get(cacheKey); } const result = a + b; calculationCache.set(cacheKey, result); return { content: [{ type: 'text', text: `${a} + ${b} = ${result}` }] }; });

5. 进阶开发思路

5.1 支持批量操作

MCP协议支持批量调用工具，我们可以扩展计算器支持批量计算：

server.batchTool('batch-calculate', '批量执行计算', { operations: z.array(z.object({ type: z.enum(['add', 'subtract', 'multiply', 'divide']), a: NumberSchema, b: NumberSchema })) }, async ({operations}) => { const results = []; for (const op of operations) { let result: number; switch (op.type) { case 'add': result = op.a + op.b; break; case 'subtract': result = op.a - op.b; break; case 'multiply': result = op.a * op.b; break; case 'divide': result = op.a / op.b; break; } results.push({ type: op.type, a: op.a, b: op.b, result }); } return { content: results.map(r => ({ type: 'text', text: `${r.a} ${r.type} ${r.b} = ${r.result}` })) }; });

5.2 添加日志监控

生产环境建议添加详细的运行日志，可以使用winston这样的日志库：

import winston from 'winston'; const logger = winston.createLogger({ level: 'info', format: winston.format.json(), transports: [ new winston.transports.File({ filename: 'error.log', level: 'error' }), new winston.transports.File({ filename: 'combined.log' }) ] }); // 在工具调用中添加日志 server.tool('add', '加法运算', { a: NumberSchema, b: NumberSchema }, async ({a, b}) => { logger.info(`Adding numbers: ${a} + ${b}`); const result = a + b; logger.info(`Result: ${result}`); return { content: [{ type: 'text', text: `${a} + ${b} = ${result}` }] }; });