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脚本(带安全检查)
### 🧪 测试系统
- **全面的测试覆盖**: 包括单元测试、集成测试和协议测试
- **测试运行器**: 支持运行单个测试或所有测试
- **模块化测试**: 每个功能都有独立的测试文件
## 快速开始
### 安装依赖```bash
npm install
启动服务器```bash
npm start
或者
node src/index.js
### 运行测试```bash
# 运行所有测试
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
开发指南
添加新工具
- 创建工具类
在src/tools/目录下创建新的工具文件,继承BaseTool类:```javascript
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: '执行结果'
}
]
};
}
}
2. **注册工具**
在 `src/tools/tool-manager.js` 的 `initializeTools` 方法中添加新工具:```javascript
import { MyTool } from './my-tool.js';
initializeTools() {
const tools = [
new EchoTool(),
new CalculateTool(),
new PythonTool(),
new MyTool(), // 添加新工具
];
// ...
}
- 编写测试
在test/目录下创建对应的测试文件。
工具接口说明
所有工具都必须实现以下接口:
getInputSchema(): 返回工具的输入参数JSON Schemaexecute(args): 执行工具逻辑,返回MCP标准格式的结果validateArgs(args, required): 验证输入参数(继承自BaseTool)
错误处理
工具执行过程中的错误会被自动转换为MCP标准错误格式:
- 未知工具 → MethodNotFound
- 执行错误 → InternalError
技术栈
- Node.js: 运行时环境
- ES Modules: 模块系统
- MCP SDK: Model Context Protocol SDK
- Child Process: 用于执行Python脚本
- JSDoc: 类型提示和文档
安全特性
- 输入验证: 所有工具都进行严格的输入验证
- 代码沙箱: Python工具包含基本的代码安全检查
- 超时控制: 防止长时间运行的脚本
- 资源限制: 限制内存和输出缓冲区大小
贡献指南
- Fork 项目
- 创建功能分支
- 编写测试
- 提交代码
- 创建 Pull Request
许可证
MIT License
支持
如果遇到问题,请查看:
- Python工具说明
- 测试说明
- 架构设计说明
- 项目的测试文件作为使用示例
