MCP node-ts-boilerplate

MCP服务器TypeScript模板

一个全面的TypeScript模板，用于使用Node.js创建模型上下文协议（MCP）服务器。

特性

• 🚀 TypeScript -完全类型安全和现代JavaScript功能
• 🛠️ 示例工具 -用于演示MCP功能的预构建工具
• 🔧 错误处理 -使用适当的MCP错误代码进行稳健的错误处理
• 📝 可扩展 -易于添加新工具和功能
• 🏗️ 生产就绪 -包括正确的构建管道和配置

快速开始

先决条件

• Node.js 16或更高版本
• npm或纱线

安装

1. 克隆或创建项目目录：

   mkdir my-mcp-server
   cd my-mcp-server

1. 复制模板文件 （package.json、tsconfig.json、src/index.ts）

1. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

1. 测试服务器：

   npm start

项目结构

mcp_node-ts-boilderplate/
├── src/
│   └── index.ts              ← Main server code
├── build/                    ← Generated (after npm run build)
├── .env                      ← secrets
├── .gitignore                ← Git ignore rules
├── LICENSE                   ← MIT license
├── package.json              ← Dependencies and scripts
├── README.md                 ← Documentation
├── setup.sh                  ← Setup script
├── tsconfig.json             ← TypeScript config
└── claude_desktop_config.example.json ← Config example

可用脚本

• npm run build -将TypeScript编译为JavaScript
• npm start -运行已编译的服务器
• npm run dev -在一个命令中构建和运行
• npm run watch -注意更改并重新编译
• npm run clean -删除构建目录

示例工具包括

该模板包括以下示例工具：

1. get_current时间 -以ISO格式返回当前日期/时间
2. calculate_sum -将两个数字相加
3. echo消息 -回显带有前缀的消息
4. fetch_data -向URL发出HTTP GET请求

添加您自己的工具

要添加新工具，请执行以下操作：

1. 添加工具定义 在 ListToolsRequestSchema 处理器
2. 执行工具逻辑 在 CallToolRequestSchema 处理器
3. 创建辅助函数 根据需要

例子：

// In ListToolsRequestSchema handler
{
  name: "my_custom_tool",
  description: "Description of what this tool does",
  inputSchema: {
    type: "object",
    properties: {
      param1: {
        type: "string",
        description: "Description of param1",
      },
    },
    required: ["param1"],
  },
}

// In CallToolRequestSchema handler
case "my_custom_tool":
  this.validateArgs(args, ["param1"]);
  const result = await myCustomFunction(args.param1 as string);
  return {
    content: [
      {
        type: "text",
        text: result,
      },
    ],
  };

连接到克劳德桌面

1. 构建您的服务器：

   npm run build

1. 查找您的项目路径：

   pwd  # Copy this path

1. 配置Claude桌面 通过编辑 claude_desktop_config.json:

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%/Claude/claude_desktop_config.json

1. 添加您的服务器配置：

   {
     "mcpServers": {
       "my-mcp-server": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO/YOUR/PROJECT/build/index.js"]
       }
     }
   }

1. 重新启动克劳德桌面

开发技巧

调试

• 使用 console.error() 用于调试消息（它们不会干扰MCP通信）
• 如果您的服务器未连接，请检查Claude Desktop日志
• 在测试之前，确保您的服务器成功构建

错误处理

该模板包括全面的错误处理：

• 工具参数的输入验证
• 正确的MCP错误代码
• 优雅的错误恢复

TypeScript的好处

• 类型安全 -在编译时捕获错误
• 智能感知 -更好的开发体验
• 重构 -安全代码更改

常见问题

1. 服务器未连接：确保您已经构建了项目(npm run build)
2. 工具未出现：检查Claude Desktop配置文件路径
3. 权限错误：确保build/index.js文件可访问

资源

• MCP官方文件
• MCP SDK TypeScript
• 克劳德桌面

许可证

麻省理工学院许可证-欢迎将此模板用于您自己的项目！