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