AI导哈

MCP服务器管理模块

基于Odoo 17和Python 3.10开发的MCP服务器管理模块，提供多服务器架构、资源管理和FastMCP框架集成，适用于大型语言模型交互和自动化服务管理。

  • by kaikongbj
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 kaikongbj/odoo-mcp

使用说明

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。

资源示例:

要创建资源，请在 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

  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

新增功能

  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文件。

相关 MCP