TestMcpServer

TestMcpServer

简介

此示例 MCP 服务实现使用了 Anthropic 的开源 Model Context Protocol。 我觉得现有示例实在难以阅读，大多是非常冗长的单文件示例，而且很难看懂。 通过这种更易于管理的方式，我希望用户能找到比目前已有示例更容易理解和上手的内容。 以此作为你下一个 MCP 服务项目的基础。

需要 Node、npm、typescript

功能

MCP 服务目前提供以下工具：

数学工具

• 加法：将两个数字相加
• 减法：用一个数字减去另一个数字
• 乘法：将两个数字相乘
• 除法：用一个数字除以另一个数字（具备除数为零保护）
• 平方根：计算一个数字的平方根
• 幂运算：计算一个数字的另一个数字次幂
• 取模：计算一个数字除以另一个数字的余数
• 对数：计算指定底数下一个数字的对数
• 平均值：计算两个数字的算术平均值

图像处理工具

• 图像转换：在不同格式之间转换图像（PNG/JPG 转 WebP/AVIF），并进行压缩
• 图像缩放：调整图像大小，同时可选择转换格式

文件系统工具

• 目录树：获取指定路径的目录树结构

Git 工具

• 提交历史：显示最近的 git 提交
• 差异：显示不同版本之间的差异

文本实用工具

• 字数统计：统计行数、单词数和字符数
• 搜索替换：在文件中执行搜索和替换

网络工具

• HTTP 请求：执行简单的 HTTP 请求
• Ping：检查与主机的连接

日期/时间实用工具

• 时间戳转换：在时间戳与日期之间转换
• 计划任务：短暂延迟后运行命令

安全工具

• 哈希：为文本或文件生成哈希值
• 校验和：验证文件校验和

浏览器工具

• 控制台捕获：捕获指定 URL 的浏览器控制台日志（错误、警告、信息、日志）

所有工具都包含全面的错误处理和输入验证，以确保稳健运行。

安装

克隆仓库后运行 npm install。 查看 package.json 了解可用脚本。

运行 npm run build 构建服务。 运行 node build/index.js 启动服务。 不过，我建议： 运行 npm run dev，这样保存更改后会自动监视、重新构建并重新运行 inspector，便于你在 localhost:5173 中进行测试

要在 Cursor 中运行 MCP 服务，必须先完成构建。

测试 MCP 工具

此项目使用 Jest 为 MCP 工具提供全面的测试框架。测试可确保所有工具正常工作，并妥善处理边缘情况。

运行测试

运行所有测试：

npm test

运行测试并生成覆盖率报告：

npm run test:coverage

运行指定测试：

npm test -- --testPathPattern=tests/maths/

测试结构

• 控制器测试：直接测试控制器处理方法（tests/maths/、tests/browser/ 等）
• 文件系统测试：使用固定目录进行一致的测试
• 浏览器测试：使用测试 HTML 页面测试浏览器交互
• MCP 模拟测试：通过 MCP 请求/响应流程测试工具
• 边缘情况测试：针对验证和错误处理的专门测试（tests/maths/validation-edge-cases.test.ts）

测试方法

测试套件采用全面的测试方法：

1. 基本功能测试 - 验证工具是否能使用有效输入正常工作
2. 边缘情况测试 - 测试边界条件，例如零值、负数等
3. 错误处理测试 - 验证对无效输入的错误响应是否正确
4. 验证测试 - 使用 null/undefined 值、非数字输入等测试输入验证
5. 溢出测试 - 测试极大数值下的行为

添加新测试

1. 在 tests/ 下相应的类别文件夹中创建测试文件
2. 使用 tests/utils/mcpTestHelper.ts 中的实用工具模拟 MCP 工具调用
3. 对于文件系统测试，请使用 tests/fixtures/ 中的测试夹具
4. 对于浏览器测试，请使用或创建测试 HTML 文件
5. 对于验证边缘情况，请在专门的验证测试文件中添加测试

MCP 服务 - 添加新工具

本指南介绍如何向 MCP 服务添加新工具。此过程包含四个主要部分：

1. 工具定义（/src/definitions/）

首先，在相应的类别文件夹（例如 maths/）中创建工具定义：

// Example: src/definitions/maths/addition.ts
import { Tool } from "@modelcontextprotocol/sdk/types.js";

export const ADDITION: Tool = {
  name: "addition",
  description: "Add two numbers together",
  inputSchema: {
    type: "object",
    properties: {
      a: {
        type: "number",
        description: "First number to add",
      },
      b: {
        type: "number",
        description: "Second number to add",
      },
    },
    required: ["a", "b"],
  },
};

然后将其添加到该类别的主文件中：

// src/definitions/maths/main.ts
import { ADDITION } from "./addition.js";
import { MULTIPLICATION } from "./multiplication.js";

const MATHS_TOOLS = [ADDITION, MULTIPLICATION] as const;

export default MATHS_TOOLS;

2. 控制器实现（/src/controllers/）

将处理方法添加到相应的控制器中：

// src/controllers/MathsController.ts
class MathsController {
  async handleAddition(a: number, b: number) {
    try {
      const result = a + b;
      return {
        content: [
          {
            type: "text",
            text: `Sum: ${result}`,
          },
        ],
        isError: false,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error calculating sum: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
        isError: true,
      };
    }
  }
}

3. 工具注册表（/src/utils/toolRegistry.ts）

在 controllerMap 中注册工具：

const controllerMap: ControllerMap = {
  // Math tools
  addition: {
    controller: MathsController,
    handlerMethod: "handleAddition",
  },
  multiplication: {
    controller: MathsController,
    handlerMethod: "handleMultiplication",
  },
};

注册表导出两个主要函数：

// Get tool definitions for server registration
export function getToolDefinitions() {
  return {
    MATHS_TOOLS,
  };
}

// Get handler for tool execution
export function getToolHandler(toolName: string) {
  const mapping = controllerMap[toolName];
  if (!mapping) {
    return null;
  }

  const controllerInstance = new mapping.controller();
  return async (args: any) => {
    return await controllerInstance[mapping.handlerMethod](
      ...Object.values(args)
    );
  };
}

4. 服务配置（/src/index.ts）

服务已配置为使用工具注册表：

const tools = getToolDefinitions();

const server = new Server(
  {
    name: "mcp-server",
    version: "0.1.0",
  },
  {
    capabilities: {
      tools: getToolDefinitions(), // Register tools array
    },
  }
);

// List available tools
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: tools,
}));

// Handle tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  try {
    const handler = getToolHandler(request.params.name);
    if (!handler) {
      return toolController.getUnknownToolResponse(request.params.name);
    }
    return await handler(request.params.arguments);
  } catch (error) {
    return toolController.getErrorResponse(error);
  }
});

约定

1. 工具名称：使用小写形式（例如 addition、multiplication）
2. 处理方法：命名为 handle + 工具名称的 PascalCase 形式（例如 handleAddition、handleMultiplication）
3. 工具类别：在 definitions/ 下为相关工具建立单独的目录
4. 控制器：在以类别命名的控制器类中组织相关处理程序（例如 MathsController）

示例流程

1. 在 src/definitions/category/toolname.ts 中创建工具定义
2. 将工具添加到该类别的 main.ts
3. 将处理方法添加到相应的控制器
4. 在 toolRegistry.ts 的 controllerMap 中注册工具
5. 测试新工具

将 MCP 服务添加到 Cursor

1. 打开设置
2. 前往 Features
3. 滚动到 MCP Servers
4. 点击 Add new MCP server
5. 为 MCP 服务设置一个你喜欢的 name
6. 将 type 设为 command
7. 本地使用时，服务 URL 应为 node <absolute path to project>\build\index.js>

服务指示灯应变为绿色，并列出已注册的工具。