MaxKB配置指南.md•3.41 kB
# MaxKB MCP配置完整指南
## 问题分析
MaxKB报错 `[ErrorDetail(string='MCP configuration is invalid', code='invalid')]` 通常是因为：
1. **配置格式不正确** - MaxKB对MCP配置有严格的验证规则
2. **传输协议不匹配** - MaxKB可能只支持特定的传输协议
3. **URL格式问题** - 端点路径可能不正确
4. **JSON结构问题** - 配置的JSON结构可能不符合MaxKB期望
## 解决方案
### 方案1：使用SSE传输协议（推荐）
MaxKB可能只支持SSE传输协议，请使用以下配置：
```json
{
"employee_management": {
"url": "http://localhost:8000/events",
"transport": "sse"
}
}
```
**启动SSE服务器：**
```bash
cd /Users/ywt/PycharmProjects/mcp/src
python sse_server.py
```
### 方案2：使用标准MCP服务器配置
```json
{
"mcpServers": {
"employee_management": {
"command": "python",
"args": ["/Users/ywt/PycharmProjects/mcp/src/sse_server.py"],
"env": {
"PYTHONPATH": "/Users/ywt/PycharmProjects/mcp/src"
}
}
}
}
```
### 方案3：简化配置格式
```json
{
"employee_management": {
"url": "http://localhost:8000/events"
}
}
```
## 测试步骤
### 1. 启动服务器
```bash
cd /Users/ywt/PycharmProjects/mcp/src
python sse_server.py
```
### 2. 验证服务器
```bash
# 健康检查
curl http://localhost:8000/health
# 测试SSE端点
curl -N http://localhost:8000/events
# 测试MCP端点
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 1}'
```
### 3. 在MaxKB中配置
1. 登录MaxKB管理界面
2. 进入 **系统设置** > **MCP配置**
3. 尝试上述配置格式之一
4. 点击保存
## 常见问题排查
### 问题1：端口被占用
```bash
# 查找占用端口的进程
lsof -ti:8000
# 杀死进程
lsof -ti:8000 | xargs kill -9
```
### 问题2：网络连接问题
- 确保MaxKB能访问MCP服务器
- 检查防火墙设置
- 如果是Docker环境，确保网络配置正确
### 问题3：配置格式问题
- 确保JSON格式正确
- 检查字段名称和值
- 尝试不同的配置结构
## 调试方法
### 1. 查看MaxKB日志
```bash
# 查看MaxKB容器日志
docker logs maxkb-container
# 或查看日志文件
tail -f /opt/maxkb/logs/maxkb.log
```
### 2. 查看MCP服务器日志
```bash
# 直接运行查看输出
python sse_server.py
# 或查看日志文件
tail -f /path/to/mcp/server.log
```
### 3. 网络测试
```bash
# 从MaxKB容器内测试连接
docker exec -it maxkb-container curl http://host.docker.internal:8000/health
```
## 配置格式对比
| 格式 | 传输协议 | 端点 | 适用场景 |
|------|----------|------|----------|
| HTTP | streamable_http | /mcp | 标准HTTP |
| SSE | sse | /events | 实时推送 |
| 标准MCP | stdio | - | 进程通信 |
## 推荐配置
基于MaxKB的特性，推荐使用：
```json
{
"employee_management": {
"url": "http://localhost:8000/events",
"transport": "sse"
}
}
```
这个配置：
- ✅ 使用SSE传输协议
- ✅ 端点路径正确
- ✅ 格式简洁
- ✅ 符合MaxKB要求
## 下一步
如果仍然有问题，请：
1. 提供MaxKB的详细错误日志
2. 确认MaxKB版本
3. 检查网络连接
4. 尝试不同的配置格式
记住：MaxKB对MCP配置的验证可能很严格，需要完全符合其期望的格式。