MCP Server Template

MCP 服务模板

用于使用 TypeScript 创建 Model Context Protocol（MCP）服务的模板。此模板为构建兼容 MCP 的服务提供了坚实基础，包含完善的工具、类型安全性和最佳实践。

功能

• 🚀 完整的 TypeScript 支持
• 🏗️ 基于容器的依赖注入
• 📦 基于服务的架构，包含 DataProcessor 接口
• 🛠️ 示例工具实现及测试
• 🧪 Vitest 测试框架
• 📝 类型定义
• 🔌 MCP SDK 集成

开始使用

开发

1. 安装依赖：

   npm install
   

2. 启动支持热重载的开发服务：

   npm run dev
   

3. 构建项目：

   npm run build
   

4. 运行测试：

   npm test
   

5. 启动生产服务：

   npm start
   

项目结构

src/
├── index.ts          # Entry point
├── interfaces/       # Interface definitions
│   └── tool.ts      # DataProcessor interface
└── tools/           # Tool implementations
    └── example.ts   # Example tool

创建工具

1. 参照 src/tools/example.ts 中的示例导出工具及其处理程序：

   // In your-tool.ts
   export const YOUR_TOOLS = [
     {
       name: "your-tool-name",
       description: "Your tool description",
       parameters: {
         // Your tool parameters schema
       },
     },
   ];
   
   export const YOUR_HANDLERS = {
     "your-tool-name": async (request) => {
       // Your tool handler implementation
       return {
         toolResult: {
           content: [{ type: "text", text: "Result" }],
         },
       };
     },
   };
   

2. 在 src/index.ts 的 ALL_TOOLS 和 ALL_HANDLERS 常量中注册工具：

   // In src/index.ts
   import { YOUR_TOOLS, YOUR_HANDLERS } from "./tools/your-tool.js";
   
   // Combine all tools
   const ALL_TOOLS = [...EXAMPLE_TOOLS, ...YOUR_TOOLS];
   const ALL_HANDLERS = { ...EXAMPLE_HANDLERS, ...YOUR_HANDLERS };
   

服务会自动：

• 在可用工具列表中列出你的工具
• 处理输入验证
• 处理发往你工具的请求
• 按照 MCP 协议格式化响应

测试

此模板内置了用于本地测试的 TestClient 和用于可视化调试的 MCP Inspector。

使用 TestClient

TestClient 提供了一种简单的工具测试方式：

import { TestClient } from "./utils/TestClient";

describe("YourTool", () => {
  const client = new TestClient();

  it("should process data correctly", async () => {
    await client.assertToolCall(
      "your-tool-name",
      { input: "test" },
      (result) => {
        expect(result.toolResult.content).toBeDefined();
      }
    );
  });
});

使用 MCP Inspector

此模板内置 MCP Inspector，可用于可视化调试工具：

1. 启动 Inspector：

   npx @modelcontextprotocol/inspector node dist/index.js
   

2. 在 http://localhost:5173 打开 Inspector 界面

Inspector 提供：

• 用于测试工具的可视化界面
• 实时请求／响应监控
• 工具元数据检查
• 交互式测试环境

使用 Cursor 进行本地测试

使用 Cursor 在本地测试 MCP 服务：

1. 构建并链接程序包：

   npm run build
   npm run link
   

2. 验证二进制文件是否正常工作：

   npx example-mcp-tool
   

3. 将服务添加到 Cursor：

   • 打开 Cursor 设置
   • 前往 Features 选项卡
   • 向下滚动到 MCP Servers 部分
   • 点击 "Add Server"
   • 选择 "Command" 类型
   • 为其命名（例如 "Local Example Tool"）
   • 输入命令：npx example-mcp-tool
   • 点击 Confirm

4. 检查 MCP Servers 部分，确认你的服务显示为正在运行，以验证服务是否在 Cursor 中正常启动。

注意：如果修改了代码，请记得重新构建并链接：

npm run build
npm run link

测试完成后，可以取消链接程序包：

npm run unlink

这将移除开发过程中创建的全局符号链接。