ts-mcp-server-template

快速创建 MCP (Model Context Protocol) 服务器项目的脚手架工具。

特性

• 🚀 一键创建 MCP 服务器项目
• 📦 开箱即用的 TypeScript 配置
• 🛠️ 简单的工具注册机制
• 🔒 类型安全，使用 Zod 进行参数验证
• 📝 包含完整的示例代码

快速开始

使用 npm create（推荐）

npm create ts-mcp-server-template my-project

使用 npx

npx create-ts-mcp-server-template my-project

使用 npm init

npm init ts-mcp-server-template my-project

使用步骤

1. 创建项目

   npm create ts-mcp-server-template my-mcp-server

2. 进入项目目录

   cd my-mcp-server

3. 安装依赖

   npm install

4. 开发模式运行

   npm run dev

5. 构建项目

   npm run build

6. 生产模式运行

   npm start

项目结构

创建的项目包含以下结构：

my-mcp-server/
├── src/
│   ├── index.ts          # 服务器入口
│   ├── server.ts         # MCP 服务器封装
│   ├── types.ts          # 类型定义
│   └── tools/
│       ├── index.ts      # 工具注册中心
│       ├── example.ts    # 示例工具
│       └── README.md     # 工具开发指南
├── package.json
├── tsconfig.json
└── README.md

添加新工具

步骤 1: 创建工具文件

在 src/tools/ 目录下创建新的工具文件，例如 src/tools/my-tool.ts：

import { z } from 'zod';
import type { ToolDefinition } from '../types.js';

export const myTool: ToolDefinition = {
  name: 'my-tool',
  description: '工具描述',
  inputSchema: z.object({
    param1: z.string().describe('参数1描述'),
    param2: z.number().describe('参数2描述'),
  }),
  execute: async ({ param1, param2 }) => {
    // 实现工具逻辑
    return `处理结果: ${param1} - ${param2}`;
  },
};

步骤 2: 注册工具

在 src/tools/index.ts 中导入并注册你的工具：

import { myTool } from './my-tool.js';

const tools: ToolDefinition[] = [
  calculatorTool,
  greetingTool,
  myTool, // 添加你的工具
];

步骤 3: 重启服务器

重启服务器后，新工具即可使用。

示例工具

创建的项目包含两个示例工具：

1. calculator - 执行数学计算

   • 支持加法、减法、乘法、除法
   • 输入：{ operation: 'add', a: 1, b: 2 }

2. greeting - 生成问候语

   • 支持多语言（中文、英文、西班牙文、法文）
   • 输入：{ name: 'Alice', language: 'en' }

配置 MCP 客户端

在 Cursor 或其他 MCP 客户端中配置服务器：

Cursor 配置 (~/.cursor/mcp.json)

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "sh",
      "args": [
        "-c",
        "cd /path/to/my-mcp-server && npx -y tsx src/index.ts"
      ]
    }
  }
}

调试

MCP 服务器通过标准输入输出（stdio）进行通信。你可以使用 MCP Inspector 进行调试：

npm install -g @modelcontextprotocol/inspector
mcp-inspector

注意事项

• 所有工具名称必须唯一
• 使用 Zod Schema 确保类型安全
• 执行函数中的错误会被自动捕获并返回
• 服务器通过 stdio 通信，不要使用 console.log，使用 console.error 输出日志

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！