simple-mcp-server

NeoZhangTCL/simple-mcp-server

3.2

If you are the rightful owner of simple-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This project is a server implementation based on the Model Context Protocol (MCP), offering a modular tool system.

Tools

  1. Echo Tool

    Echoes the input text.

  2. Calculate Tool

    Performs safe mathematical calculations.

  3. Python Tool

    Executes Python scripts with safety checks.

MCP Server 项目

这是一个基于 Model Context Protocol (MCP) 的服务器实现，提供了模块化的工具系统。

项目结构

mcp-server/
├── src/                    # 源代码目录
│   ├── index.js           # 主服务器文件
│   ├── config.js          # 配置文件
│   ├── tools/             # 工具模块目录
│   │   ├── base-tool.js   # 基础工具类
│   │   ├── echo-tool.js   # Echo工具
│   │   ├── calculate-tool.js  # 计算工具
│   │   ├── python-tool.js     # Python脚本工具
│   │   └── tool-manager.js    # 工具管理器
│   └── utils/             # 工具函数目录
│       └── logger.js      # 日志工具
├── test/                  # 测试目录
│   ├── basic-test.js      # 基本功能测试
│   ├── simple-python-test.js  # 简单Python测试
│   ├── mcp-test.js        # MCP协议测试
│   ├── mcp-python-test.js # Python MCP测试
│   └── run-tests.js       # 测试运行器
├── README-PYTHON.md       # Python工具详细说明
├── README-TESTS.md        # 测试说明
├── package.json           # 项目依赖
└── package-lock.json      # 锁定文件

功能特性

🛠️ 工具系统

  • 模块化设计: 每个工具都是独立的模块
  • 基础工具类: 提供统一的工具接口
  • 工具管理器: 统一管理所有工具的注册和执行
  • 类型安全: 使用JSDoc提供类型提示

🔧 内置工具

  1. Echo工具: 回显输入的文本
  2. 计算工具: 执行安全的数学计算
  3. Python工具: 运行Python脚本（带安全检查）

🧪 测试系统

  • 全面的测试覆盖: 包括单元测试、集成测试和协议测试
  • 测试运行器: 支持运行单个测试或所有测试
  • 模块化测试: 每个功能都有独立的测试文件

快速开始

安装依赖

npm install

启动服务器

npm start
# 或者
node src/index.js

运行测试

# 运行所有测试
cd test && node run-tests.js

# 运行特定测试
cd test && node run-tests.js basic      # 基本功能测试
cd test && node run-tests.js python     # Python工具测试
cd test && node run-tests.js mcp        # MCP协议测试
cd test && node run-tests.js mcp-python # Python MCP测试

# 直接运行单个测试文件
cd test && node basic-test.js

开发指南

添加新工具

  1. 创建工具类 在 src/tools/ 目录下创建新的工具文件，继承 BaseTool 类：
import { BaseTool } from './base-tool.js';

export class MyTool extends BaseTool {
  constructor() {
    super('my_tool', '我的工具描述');
  }

  getInputSchema() {
    return {
      type: 'object',
      properties: {
        // 定义输入参数
      },
      required: ['param1']
    };
  }

  async execute(args) {
    this.validateArgs(args, ['param1']);
    // 实现工具逻辑
    return {
      content: [
        {
          type: 'text',
          text: '执行结果'
        }
      ]
    };
  }
}
  1. 注册工具 在 src/tools/tool-manager.js 的 initializeTools 方法中添加新工具：
import { MyTool } from './my-tool.js';

initializeTools() {
  const tools = [
    new EchoTool(),
    new CalculateTool(),
    new PythonTool(),
    new MyTool(),  // 添加新工具
  ];
  // ...
}
  1. 编写测试 在 test/ 目录下创建对应的测试文件。

工具接口说明

所有工具都必须实现以下接口：

  • getInputSchema(): 返回工具的输入参数JSON Schema
  • execute(args): 执行工具逻辑，返回MCP标准格式的结果
  • validateArgs(args, required): 验证输入参数（继承自BaseTool）

错误处理

工具执行过程中的错误会被自动转换为MCP标准错误格式：

  • 未知工具 → MethodNotFound
  • 执行错误 → InternalError

技术栈

  • Node.js: 运行时环境
  • ES Modules: 模块系统
  • MCP SDK: Model Context Protocol SDK
  • Child Process: 用于执行Python脚本
  • JSDoc: 类型提示和文档

安全特性

  • 输入验证: 所有工具都进行严格的输入验证
  • 代码沙箱: Python工具包含基本的代码安全检查
  • 超时控制: 防止长时间运行的脚本
  • 资源限制: 限制内存和输出缓冲区大小

贡献指南

  1. Fork 项目
  2. 创建功能分支
  3. 编写测试
  4. 提交代码
  5. 创建 Pull Request

许可证

MIT License

支持

如果遇到问题，请查看：

  • 项目的测试文件作为使用示例