MCP 服务器模板

一个使用 TypeScript 创建模型上下文协议 (MCP) 服务器的模板。此模板为构建兼容 MCP 的服务器奠定了坚实的基础，并提供了合适的工具、类型安全性和最佳实践。

特征

• 🚀 全面支持 TypeScript

• 🏗️基于容器的依赖注入

• 📦具有 DataProcessor 接口的基于服务的架构

• 🛠️ 带有测试的示例工具实现

• 🧪 Vitest 测试框架

• 📝 类型定义

• 🔌 MCP SDK 集成

Related MCP server: MCP Server Starter

入门

发展

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 检查器

该模板包括用于工具可视化调试的 MCP 检查器：

1. 启动检查器：

   npx @modelcontextprotocol/inspector node dist/index.js

2. 在http://localhost:5173打开检查器 UI

检查员提供：

• 测试工具的可视化界面

• 实时请求/响应监控

• 工具元数据检查

• 交互式测试环境

使用游标进行本地测试

要使用 Cursor 在本地测试您的 MCP 服务器：

1. 构建并链接包：

   npm run build
   npm run link

2. 验证二进制文件是否有效：

   npx example-mcp-tool

3. 将服务器添加到 Cursor：

   • 打开光标设置

   • 导航至“功能”选项卡

   • 向下滚动到 MCP 服务器部分

   • 点击“添加服务器”

   • 选择“命令”类型

   • 给它起一个名字（例如，“本地示例工具”）

   • 输入命令： npx example-mcp-tool

   • 点击确认

4. 通过检查 MCP 服务器部分是否显示您的服务器正在运行，验证服务器是否在 Cursor 中正确启动。

注意：如果您更改了代码，请记住重建并重新链接：

npm run build
npm run link

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

npm run unlink

这将删除在开发期间创建的全局符号链接。