使用TypeScript构建一个最简单的MCP服务器

什么是MCP？

Model Context Protocol（模型上下文协议）是一个开放标准，它允许AI助手与外部工具和数据源进行标准化通信。简单来说，MCP就像是AI和各种工具之间的"翻译官"，让AI能够调用你编写的自定义功能。

项目准备

1. 初始化项目

首先，让我们创建一个新的TypeScript项目：

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

2. 安装核心依赖

# 核心MCP SDK
npm install @modelcontextprotocol/sdk

# 输入验证库
npm install zod

# TypeScript相关依赖
npm install -D typescript @types/node

# 创建TypeScript配置
npx tsc --init

3. 项目结构设计

mcp-calculator-server/
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript配置
├── src/
│   └── server/
│       └── index.ts      # 主服务器文件
├── build/                # 编译输出
└── .vscode/
    └── mcp.json          # VS Code MCP配置

核心代码实现

1. 服务器基础框架

让我们从最基本的服务器结构开始：

#!/usr/bin/env node

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

/**
 * MCP Calculator Server
 * 一个功能完整的计算器MCP服务器
 */

// 创建服务器实例
const server = new McpServer({
  name: "mcp-calculator-server",
  version: "1.0.0",
  description: "提供基本四则运算功能的MCP计算器服务器",
  capabilities: {
    resources: {},  // 资源能力
    tools: {},      // 工具能力
  },
});

2. 输入验证Schema定义

使用Zod进行严格的输入验证：

// 数字参数验证
const NumberSchema = z.number().describe("数值参数，支持整数和浮点数");

// 可以扩展更复杂的验证规则
const PositiveNumberSchema = z.number().positive().describe("正数");
const IntegerSchema = z.number().int().describe("整数");

3. 工具实现：加法运算

server.tool(
  "add",
  "执行两个数字的加法运算，返回它们的和。支持整数和浮点数。",
  {
    a: NumberSchema,
    b: NumberSchema,
  },
  async ({ a, b }) => {
    const result = a + b;
    
    // 记录操作日志（用于调试）
    console.error(`计算: ${a} + ${b} = ${result}`);
    
    return {
      content: [
        {
          type: "text",
          text: `${a} + ${b} = ${result}`,
        },
      ],
    };
  }
);

4. 错误处理：除法运算

在实际项目中，错误处理至关重要：

server.tool(
  "divide",
  "执行两个数字的除法运算，包含除零错误检查。",
  {
    dividend: NumberSchema.describe("被除数"),
    divisor: NumberSchema.describe("除数"),
  },
  async ({ dividend, divisor }) => {
    // 除零检查
    if (divisor === 0) {
      console.error(`错误: 除数不能为零`);
      return {
        content: [
          {
            type: "text",
            text: "错误：除数不能为零，请检查输入参数。",
          },
        ],
      };
    }
    
    const result = dividend / divisor;
    console.error(`计算: ${dividend} ÷ ${divisor} = ${result}`);
    
    return {
      content: [
        {
          type: "text",
          text: `${dividend} ÷ ${divisor} = ${result}`,
        },
      ],
    };
  }
);

5. 服务器启动逻辑

async function main() {
  try {
    // 使用标准输入输出传输
    const transport = new StdioServerTransport();
    await server.connect(transport);
    
    console.error("MCP计算器服务器已启动，使用stdio传输");
  } catch (error) {
    console.error("服务器启动失败:", error);
    process.exit(1);
  }
}

// 启动服务器并处理异常
main().catch((error) => {
  console.error("主函数执行失败:", error);
  process.exit(1);
});

完整的服务器代码

将所有部分组合起来，我们得到了一个完整的MCP计算器服务器。这个服务器包含四个基本运算工具：

• add: 加法运算
• subtract: 减法运算
• multiply: 乘法运算
• divide: 除法运算（含错误处理）

每个工具都有详细的描述和严格的输入验证，确保服务器的稳定性和易用性。

#!/usr/bin/env node

/**
 * 新手版 MCP 计算器服务器
 * 
 * 这是一个简化的MCP服务器示例，适合初学者学习
 * 提供基本的加减乘除运算功能
 * 
 * 安装依赖：
 * npm install @modelcontextprotocol/sdk zod
 * 
 * 编译运行：
 * npx tsc
 * node build/server/index.js
 */

// 导入需要的模块
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: "simple-calculator",
  version: "1.0.0",
  capabilities: {
    resources: {},
    tools: {},
  },
});

// 定义数字验证规则
const NumberSchema = z.number().describe("数字");

// 加法工具
server.tool(
  "add",
  "计算两个数字相加",
  {
    a: NumberSchema,
    b: NumberSchema,
  },
  async ({ a, b }) => {
    const result = a + b;
    
    return {
      content: [
        {
          type: "text",
          text: `${a} + ${b} = ${result}`,
        },
      ],
    };
  }
);

// 减法工具
server.tool(
  "subtract",
  "计算两个数字相减",
  {
    a: NumberSchema,
    b: NumberSchema,
  },
  async ({ a, b }) => {
    const result = a - b;
    
    return {
      content: [
        {
          type: "text",
          text: `${a} - ${b} = ${result}`,
        },
      ],
    };
  }
);

// 乘法工具
server.tool(
  "multiply",
  "计算两个数字相乘",
  {
    a: NumberSchema,
    b: NumberSchema,
  },
  async ({ a, b }) => {
    const result = a * b;
    
    return {
      content: [
        {
          type: "text",
          text: `${a} × ${b} = ${result}`,
        },
      ],
    };
  }
);

// 除法工具
server.tool(
  "divide",
  "计算两个数字相除",
  {
    a: NumberSchema,
    b: NumberSchema,
  },
  async ({ a, b }) => {
    // 检查除数是否为零
    if (b === 0) {
      return {
        content: [
          {
            type: "text",
            text: "错误：不能除以零",
          },
        ],
      };
    }
    
    const result = a / b;
    
    return {
      content: [
        {
          type: "text",
          text: `${a} ÷ ${b} = ${result}`,
        },
      ],
    };
  }
);

// 启动服务器
async function main() {
  try {
    const transport = new StdioServerTransport();
    await server.connect(transport);
    console.error("计算器服务器已启动");
  } catch (error) {
    console.error("启动失败:", error);
    process.exit(1);
  }
}

main().catch((error) => {
  console.error("运行出错:", error);
  process.exit(1);
});

/*
使用方法：

1. 安装依赖包
   npm install @modelcontextprotocol/sdk zod

2. 编译 TypeScript
   npx tsc

3. 在 VS Code 中配置 .vscode/mcp.json：
   {
     "servers": {
       "calculator": {
         "type": "stdio",
         "command": "node",
         "args": ["你的绝对路径/server/index.js"]
       }
     }
   }

4. 重启 VS Code，然后就可以使用计算功能了

代码说明：

- McpServer: 创建 MCP 服务器
- server.tool(): 定义可用的工具/功能
- NumberSchema: 验证输入必须是数字
- async/await: 处理异步操作
- StdioServerTransport: 使用标准输入输出通信

每个工具包含：
- 名称 (如 "add")
- 描述 (如 "计算两个数字相加")
- 参数定义 (如 {a: NumberSchema, b: NumberSchema})
- 实现函数 (执行具体的计算逻辑)
*/

VS Code集成配置

1. 创建MCP配置文件

在项目根目录的.vscode/mcp.json中配置：

{
  "servers": {
    "mcp-calculator": {
      "type": "stdio",
      "command": "node",
      "args": ["你的绝对路径/server/index.js"]
    }
  }
}

MCP配置参数详解

配置示例解析

{
  "servers": {
    "calculator": {              // 服务器名称（自定义）
      "type": "stdio",           // 使用标准输入输出通信
      "command": "node",         // 使用Node.js执行
      "args": [                  // 传递给node的参数
        "你的绝对路径/server/index.js" // 编译后的服务器文件路径
      ]
    },
    "file-manager": {            // 可以配置多个服务器
      "type": "stdio",
      "command": "python",
      "args": ["-m", "my_mcp_server"]
    }
  }
}

⚠️ 重要提示：

• 路径必须指向编译后的.js文件，不是.ts源文件
• 确保编译后的文件存在且有执行权限

2. 编译和构建

# 使用tsc编译，在目录下生成js文件
npx tsc

3. 测试服务器

# 1. 首先确保TypeScript已编译
npx tsc

# 2. 直接运行服务器测试
node build/server/index.js

# 3. 如果正常，您应该看到类似输出：
# "计算器服务器已启动"

# 4. 使用 Ctrl+C 停止服务器

参考资源

• MCP官方文档
• Zod验证库