Odoo MCP Server

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