Stevennevins MCP Server Template

🚀 MCP 服务器模板

本项目是一个用于创建 Model Context Protocol (MCP) 服务器的 TypeScript 模板。它为构建兼容 MCP 的服务器提供了坚实基础，具备完整的工具支持、类型安全和最佳实践，能帮助开发者更高效地搭建服务器。

✨ 主要特性

• 🚀 完全支持 TypeScript，保障代码类型安全。
• 🏗️ 基于容器的依赖注入，提升代码可维护性。
• 📦 采用服务导向架构，带有 DataProcessor 接口，便于功能扩展。
• 🛠️ 提供工具实现示例及测试，方便开发者参考。
• 🧪 集成 Vitest 测试框架，可对代码进行全面测试。
• 📝 包含类型定义文件，增强代码可读性。
• 🔌 整合 MCP SDK，与 MCP 协议无缝对接。

🚀 快速开始

开发步骤

1. 安装依赖：

npm install

2. 启动开发服务器（带热重载）：

npm run dev

3. 构建项目：

npm run build

4. 运行测试：

npm test

5. 启动生产服务器：

npm start

📦 安装指南

按照上述快速开始中的开发步骤，依次执行命令即可完成项目的安装与启动。

💻 使用示例

基础用法

项目结构

src/
├── index.ts          # 入口文件
├── interfaces/       # 接口定义
│   └── tool.ts      # DataProcessor 接口
└── tools/           # 工具实现
    └── example.ts   # 示例工具

创建工具

1. 按照 src/tools/example.ts 中的示例导出您的工具和处理器：

// 在 your-tool.ts 文件中
export const YOUR_TOOLS = [
  {
    name: "your-tool-name",
    description: "Your tool description",
    parameters: {
      // 您的工具参数模式
    },
  },
];

export const YOUR_HANDLERS = {
  "your-tool-name": async (request) => {
    // 您的工具处理器实现
    return {
      toolResult: {
        content: [{ type: "text", text: "Result" }],
      },
    };
  },
};

2. 在 src/index.ts 中注册您的工具：

// 在 src/index.ts 文件中
import { YOUR_TOOLS, YOUR_HANDLERS } from "./tools/your-tool.js";

// 合并所有工具
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. 打开 inspector UI 界面：http://localhost:5173 Inspector 提供了：

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

使用 Cursor 进行本地测试

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

1. 构建并链接包：

npm run build
npm run link

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

npx example-mcp-tool

3. 在 Cursor 中添加服务器：
   • 打开 Cursor 设置
   • 导航到特性选项卡
   • 滚动到底部 MCP 服务器部分
   • 点击“添加服务器”
   • 选择“命令”类型
   • 输入名称（例如：“本地示例工具”）
   • 输入命令：npx example-mcp-tool
   • 点击确认
4. 在 Cursor 中检查 MCP 服务器部分，确保服务器显示为运行状态。

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

npm run build
npm run link

📚 详细文档

注意事项

⚠️ 重要提示

• 确保所有依赖项已正确安装。
• 在生产环境中使用前，请进行充分的测试。
• 查看 MCP 文档以获取更多信息。