MCP服务器模块说明文档
项目概述
MCP服务器模块是一个基于Odoo 17和Python 3.10开发的模块，用于管理和提供MCP（模型上下文协议）服务。该模块集成了FastMCP框架，可以方便地创建、管理和与大型语言模型(LLM) 交互的MCP服务器。
主要功能
-
多服务器架构
- 独立服务器实例：每个mcp.server记录都是独立的MCP服务器
- 自动端口分配：从10888开始自动分配可用端口
- 端口唯一性：确保每个服务器使用唯一端口，防止冲突
- 并发运行：支持多个MCP服务器同时运行
- 独立线程管理：每个服务器运行在独立线程中
- 安全验证机制：API密钥验证和IP白名单控制
-
MCP服务器管理
- 创建和配置MCP服务器
- 界面控制：通过按钮启动/停止/重启服务器
- 批量操作：同时管理多个服务器
- 状态监控：实时查看服务器运行状态
- 控制面板：卡片式的直观管理界面
- 测试服务器连接
- 自动启动功能：模块启动时自动启动活动状态的服务器
-
资源管理
- 创建和管理MCP资源
- 支持多种资源类型（文件、服务、API等）
- 资源内容检索和更新
- 每个服务器可配置独立的资源
-
FastMCP集成
- 基于FastMCP框架提供标准MCP协议实现
- 提供工具和资源注册机制
- 支持异步操作和事件处理
- 每个服务器实例独立的工具和资源
-
API接口
- RESTful API接口，支持外部系统集成
- JSON格式数据交换
- 支持服务器和资源管理
- 多端口API访问
-
自动化功能
- 模块安装时自动创建默认MCP服务器
- Odoo重启后自动恢复活动服务器
- 智能的延迟启动机制确保系统稳定性
- 自动端口冲突检测和解决
-
安全功能
- API密钥验证：所有请求必须包含有效的API密钥
- IP白名单：限制允许访问的IP地址
- 请求日志：记录所有请求以便审计
- 速率限制：防止服务器资源被滥用
- 安全管理界面：方便的安全设置管理
技术架构
mcp_server/
├── __init__.py
├── __manifest__.py
├── controllers/
│ ├── __init__.py
│ └── main.py
├── models/
│ ├── __init__.py
│ └── mcp_server.py
├── services/
│ ├── __init__.py
│ └── fast_mcp_service.py
├── views/
│ └── mcp_server_views.xml
├── security/
│ └── ir.model.access.csv
├── data/
│ └── mcp_server_data.xml
└── static/
└── description/
├── icon.png
└── index.html
核心组件
-
MCP服务器模型 (
models/mcp_server.py)mcp.server: 管理MCP服务器配置和状态mcp.resource: 管理MCP资源
-
FastMCP服务 (
services/fast_mcp_service.py)FastMCPService: 实现FastMCP框架集成- 管理FastMCP服务器实例
- 注册工具和资源
-
控制器 (
controllers/main.py)- 提供RESTful API接口
- 处理外部请求
- 代理FastMCP服务
-
视图 (
views/mcp_server_views.xml)- 定义用户界面
- 提供服务器和资源管理界面
安装要求
- Odoo 17
- Python 3.10+
- FastMCP 2.0+
安装步骤
- 确保满足安装要求
- 安装必要的Python依赖:
pip install -r requirements.txt - 将
mcp_server目录复制到Odoo的addons路径 - 更新Odoo模块列表并安装MCP服务器模块
使用指南
多服务器架构
每个mcp.server记录都是一个独立的MCP服务器实例！
- 独立端口：每个服务器自动分配独立端口（从10888开始）
- 并发运行：可同时运行多个MCP服务器
- 独立配置：每个服务器有独立的资源和工具配置
自动启动功能
模块安装后会自动创建并启动默认MCP服务器，无需手动配置！
- 自动创建：安装模块时自动创建"默认MCP服务器"（端口10888）
- 自动启动：每次Odoo重启后，活动状态的服务器会自动启动
- 即开即用：默认服务器提供完整的Odoo数据访问功能
- 多服务器支持：可创建多个服务器，每个运行在不同端口
基本使用
-
使用控制面板
- 导航到 MCP服务器 > 控制面板
- 查看所有服务器的卡片式界面
- 使用卡片上的按钮直接启动/停止服务器
- 查看服务器状态和基本信息
-
单个服务器管理
- 在服务器表单页面使用头部按钮：
- 启动服务器：启动MCP服务器实例
- 停止服务器：停止运行中的服务器
- 重启服务器：重启服务器实例
- 检查状态：查看详细的服务器状态
- 测试连接：测试服务器连接
- 在服务器表单页面使用头部按钮：
-
批量服务器管理
- 导航到 MCP服务器 > 服务器管理
- 选择多个服务器（勾选复选框）
- 使用操作菜单进行批量启动或停止
- 查看批量操作结果统计
-
创建新服务器
- 点击"创建"按钮
- 填写服务器名称（端口会自动分配）
- 保存后使用"启动服务器"按钮激活
- 每个服务器运行在独立端口上
-
资源管理
- 导航到 MCP服务器 > 资源管理
- 为不同服务器创建不同的资源
- 配置资源类型和内容
-
状态监控
- 使用"检查状态"按钮查看详细信息
- 监控端口占用和线程状态
- 查看最后连接时间和资源数量
FastMCP使用
FastMCP框架允许您注册工具和资源，以供大型语言模型(LLM)使用。
工具示例:
要创建工具，请在 services/fast_mcp_service.py 中使用 @mcp_server.tool() 装饰器定义一个异步函数。
注意: FastMCP不支持使用
*args参数的函数作为工具。请确保所有工具函数使用显式命名的参数。详见 FASTMCP_ARGS_FIX.md。
资源示例:
要创建资源，请在 services/fast_mcp_service.py 中使用 @mcp_server.resource() 装饰器定义一个函数。
高级配置
自定义工具
您可以在fast_mcp_service.py中的_register_default_tools方法中添加自定义工具:
自定义资源
您可以在fast_mcp_service.py中的_register_default_resources方法中添加自定义资源:
故障排除
常见问题
- 无法启动FastMCP服务器
- 确认FastMCP库已正确安装
- 检查服务器URL格式是否正确
- 确保使用正确的传输模式（transport="http"）
- 查看Odoo日志获取详细错误信息
已知问题修复
-
FastMCP服务器启动失败: Unknown transport: http 应该是streamable-http
- 问题: FastMCP不支持"http"传输模式，需要使用"streamable-http"
- 解决方案: 已将传输模式从"http"更改为"streamable-http"
- 修复日期: 2025-07-22
- 详情: FASTMCP_TRANSPORT_FIX.md
-
视图警告: Using active_id in expressions is deprecated
- 问题: 在视图XML中使用active_id被标记为已弃用
- 解决方案: 将context中的active_id替换为id
- 修复日期: 2025-07-22
-
数据库游标错误: Cursor already closed
- 问题: 在异步函数中直接使用server_record导致数据库游标已关闭错误
- 解决方案: 使用安全数据库管理器进行数据库操作
- 修复日期: 2025-07-22
-
自动启动失效: 系统启动时MCP服务器未自动启动
- 问题: 只有点击测试连接才启动服务器，违背自动启动设计
- 解决方案: 使用_register_hook在每次系统启动时自动启动活动服务器
- 修复日期: 2025-07-22
-
导入错误: NameError: name 'threading' is not defined
- 问题: threading模块导入顺序错误，在使用前未定义
- 解决方案: 将import threading移动到文件开头的导入部分
- 修复日期: 2025-07-22
-
端口冲突: 服务器端口不能相同
- 问题: 多个MCP服务器可能使用相同端口导致启动失败
- 解决方案: 添加端口唯一性约束和验证，实现智能端口分配
- 修复日期: 2025-07-22
-
安全漏洞: MCP服务器直接可连接没有校验授权
- 问题: 任何人都可以访问服务器并执行操作，存在严重安全风险
- 解决方案: 添加API密钥验证、IP白名单、请求日志和速率限制等安全机制
- 修复日期: 2025-07-22
-
*FastMCP工具注册失败: Functions with args are not supported as tools
- 问题: FastMCP不支持使用*args参数的函数作为工具
- 解决方案: 修改认证装饰器，在每个工具函数内部直接进行认证检查
- 修复日期: 2025-07-22
- 详情: FASTMCP_ARGS_FIX.md
新增功能
-
自动启动功能 (2025-07-22)
- 模块启动时自动启动活动状态的MCP服务器
- 默认创建并启动"默认MCP服务器"
- 智能延迟启动机制确保系统稳定性
- 详细的启动日志和错误处理
-
API调用失败
- 确认API密钥正确
- 确认服务器处于活动状态
- 检查请求格式和参数
-
资源获取失败
- 确认资源存在且激活
- 确认资源URI格式正确
- 检查资源类型是否支持
开发指南
扩展模型
- 在
models目录下创建新的模型文件 - 在
__init__.py中导入新模型 - 添加必要的字段和方法
- 更新安全访问规则
添加API接口
- 在
controllers/main.py中添加新的路由方法 - 实现请求处理逻辑
- 返回适当的JSON响应
集成新功能
- 根据需求修改现有模型或添加新模型
- 更新视图以支持新功能
- 添加必要的业务逻辑
- 更新文档和测试
版本历史
- 1.0.0 (2025-05-23): 初始版本
- 基本MCP服务器管理功能
- FastMCP集成
- API接口
联系与支持
如有问题或需要支持，请联系:
- 技术支持: support@example.com
- 项目维护: dev@example.com
许可证
本模块基于LGPL-3许可证发布。详见LICENSE文件。