simple-mcp-server

NeoZhangTCL/simple-mcp-server

3.1

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
3
Resources
0
Prompts
0

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

支持

如果遇到问题，请查看：

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