README.md•3.98 kB
# 员工管理系统 MCP Server
基于Model Context Protocol (MCP)的员工管理系统API代理服务器，为前端提供统一的MCP协议接口来调用后端员工管理API。
## 功能特性
- 🚀 完整的员工管理功能支持
- 🔧 基于MCP协议的标准化接口
- 🛡️ 完善的错误处理和重试机制
- 📝 详细的日志记录
- ⚙️ 灵活的配置管理
- 🔐 支持API认证
## 支持的API功能
### 员工管理
- ✅ 根据ID查询员工 (`get_employee_by_id`)
- ✅ 查询所有员工 (`get_all_employees`)
- ✅ 新增员工 (`add_employee`)
- ✅ 更新员工信息 (`update_employee`)
- ✅ 删除员工 (`delete_employee`)
- ✅ 条件搜索员工 (`search_employees`)
- ✅ 根据级别查询员工 (`get_employees_by_level`)
- ✅ 查询在职员工 (`get_active_employees`)
- ✅ 同步员工数据 (`sync_employees`)
## 快速开始
### 1. 安装依赖
```bash
pip install -r requirements.txt
```
### 2. 配置环境变量
复制环境变量示例文件并修改配置：
```bash
cp env.example .env
```
编辑 `.env` 文件，配置后端API地址：
```env
# 后端API配置
MCP_API_BASE_URL=http://localhost:10086
```
### 3. 启动服务器
```bash
python main.py
```
服务器将在 `localhost:8000` 启动。
## 配置说明
### 环境变量
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `MCP_HOST` | localhost | MCP服务器主机 |
| `MCP_PORT` | 8000 | MCP服务器端口 |
| `MCP_API_BASE_URL` | http://localhost:10086 | 后端API基础URL |
| `MCP_API_TIMEOUT` | 30 | API请求超时时间(秒) |
| `MCP_API_KEY` | - | API密钥（可选） |
| `MCP_LOG_LEVEL` | INFO | 日志级别 |
## 项目结构
```
mcp-server/
├── src/
│ ├── __init__.py
│ ├── server.py # MCP服务器主入口
│ ├── tools/ # MCP工具定义
│ │ ├── __init__.py
│ │ ├── api_proxy.py # API代理工具
│ │ └── base.py # 基础工具类
│ ├── models/ # 数据模型
│ │ ├── __init__.py
│ │ └── schemas.py # 请求响应模型
│ ├── config/ # 配置管理
│ │ ├── __init__.py
│ │ └── settings.py # 服务器配置
│ └── utils/ # 工具函数
│ ├── __init__.py
│ └── helpers.py # 辅助函数
├── main.py # 项目主入口
├── requirements.txt # 依赖管理
├── env.example # 环境变量示例
└── README.md # 项目文档
```
## 使用示例
### 前端调用示例
```javascript
// 查询所有员工
const result = await mcpClient.callTool("get_all_employees", {});
// 根据ID查询员工
const employee = await mcpClient.callTool("get_employee_by_id", {
userId: 1001
});
// 新增员工
const newEmployee = await mcpClient.callTool("add_employee", {
firstName: "三",
lastName: "张",
salary: 8000.0,
currency: "CNY",
birthdate: "1990-01-01",
isActive: true,
level: "3"
});
```
## 开发指南
### 添加新的API工具
1. 在 `src/tools/api_proxy.py` 中添加新的工具方法
2. 在 `get_all_tools()` 方法中注册新工具
3. 在 `execute()` 方法中添加工具调用逻辑
### 自定义配置
可以通过环境变量或修改 `src/config/settings.py` 来自定义配置。
## 故障排除
### 常见问题
1. **连接后端API失败**
- 检查后端服务是否启动
- 确认API地址配置是否正确
- 检查网络连接
2. **工具调用失败**
- 查看服务器日志获取详细错误信息
- 检查请求参数格式是否正确
- 确认后端API返回格式
### 日志查看
服务器运行时会输出详细的日志信息，包括：
- 工具注册信息
- API调用详情
- 错误和异常信息
## 许可证
MIT License
## 贡献
欢迎提交Issue和Pull Request来改进这个项目。 # mcp-server