MaxKB集成指南.md•5.11 kB
# MaxKB集成指南
## 概述
本指南将帮助你在MaxKB中集成员工管理MCP服务器，实现通过自然语言与员工管理系统交互。
## 前置条件
1. MaxKB已安装并运行
2. 员工管理MCP服务器已启动
3. 网络连接正常
## 步骤1：启动MCP服务器
### 启动HTTP版本的MCP服务器
```bash
cd /Users/ywt/PycharmProjects/mcp/src
python http_server.py
```
服务器将在 `http://localhost:8000` 启动。
### 验证服务器运行
```bash
# 健康检查
curl http://localhost:8000/health
# 查看可用工具
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{"method": "tools/list", "params": {}}'
```
## 步骤2：配置MaxKB
### 方法1：通过MaxKB管理界面配置
1. 登录MaxKB管理界面
2. 进入 **系统设置** > **MCP配置**
3. 添加新的MCP服务器配置：
```json
{
"employee_management": {
"url": "http://172.20.10.2:8000/mcp",
"transport": "streamable_http"
}
}
```
### 方法2：通过配置文件配置
如果MaxKB支持配置文件，将以下内容添加到配置文件中：
```json
{
"mcp_servers": {
"employee_management": {
"url": "http://localhost:8000/mcp",
"transport": "streamable_http"
}
}
}
```
## 步骤3：测试集成
### 基本测试
在MaxKB中尝试以下自然语言请求：
1. **查看所有员工**
- "帮我查看所有员工信息"
- "显示员工列表"
2. **查询特定员工**
- "查询ID为1的员工信息"
- "获取张三的详细信息"
3. **添加新员工**
- "添加一个新员工，名字叫李四，姓氏叫王五，工资8000，级别是高级"
- "创建员工记录：姓名张三，工资5000，级别中级"
4. **搜索员工**
- "搜索姓氏为'李'的所有员工"
- "查找所有在职员工"
- "显示所有高级员工"
5. **更新员工信息**
- "更新ID为1的员工工资为10000"
- "修改张三的级别为高级"
6. **删除员工**
- "删除ID为1的员工"
- "移除张三的员工记录"
## 可用功能
MCP服务器提供以下9个工具：
| 工具名称 | 功能描述 | 示例用法 |
|---------|---------|---------|
| `get_employee_by_id` | 根据ID查询员工 | "查询ID为1的员工" |
| `get_all_employees` | 查询所有员工 | "显示所有员工" |
| `add_employee` | 新增员工 | "添加新员工张三" |
| `update_employee` | 更新员工信息 | "更新员工信息" |
| `delete_employee` | 删除员工 | "删除员工" |
| `search_employees` | 条件搜索员工 | "搜索李姓员工" |
| `get_employees_by_level` | 根据级别查询员工 | "显示高级员工" |
| `get_active_employees` | 查询在职员工 | "查看在职员工" |
| `sync_employees` | 同步员工数据 | "同步员工数据" |
## 网络配置
### 本地部署
如果MaxKB和MCP服务器在同一台机器上：
```json
{
"employee_management": {
"url": "http://localhost:8000/mcp",
"transport": "streamable_http"
}
}
```
### 远程部署
如果MaxKB和MCP服务器在不同机器上，需要修改URL：
```json
{
"employee_management": {
"url": "http://192.168.1.100:8000/mcp",
"transport": "streamable_http"
}
}
```
### 生产环境
生产环境建议使用HTTPS：
```json
{
"employee_management": {
"url": "https://your-domain.com/mcp",
"transport": "streamable_http"
}
}
```
## 故障排除
### 常见问题
1. **连接失败**
- 检查MCP服务器是否正在运行
- 验证URL是否正确
- 检查网络连接
2. **工具调用失败**
- 查看MCP服务器日志
- 检查API服务是否可用
- 验证参数格式
3. **权限问题**
- 确保MaxKB有权限访问MCP服务器
- 检查防火墙设置
### 日志查看
查看MCP服务器日志：
```bash
# 查看服务器日志
tail -f /path/to/mcp/server.log
# 或者直接运行查看输出
python http_server.py
```
### 测试连接
```bash
# 测试MCP端点
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{"method": "tools/list", "params": {}}'
# 测试工具调用
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{
"method": "tools/call",
"params": {
"name": "get_all_employees",
"arguments": {}
}
}'
```
## 高级配置
### 自定义端口
修改 `src/config/settings.py` 中的端口配置：
```python
http_port: int = Field(default=8000, description="HTTP服务器端口")
```
### 环境变量配置
创建 `.env` 文件：
```env
MCP_HTTP_HOST=0.0.0.0
MCP_HTTP_PORT=8000
MCP_API_BASE_URL=http://your-api-server:10086
```
### 安全配置
生产环境建议添加认证：
```python
# 在http_server.py中添加认证中间件
@app.middleware("http")
async def add_auth_header(request: Request, call_next):
# 添加认证逻辑
pass
```
## 支持
如有问题，请查看：
1. MCP服务器日志
2. MaxKB日志
3. 网络连接状态
4. 配置文件格式
## 更新日志
- v1.0.0: 初始版本，支持基本的员工管理功能
- 支持MaxKB集成
- 提供HTTP API接口