# AI Control MCP Design

## 1. 目标

基于现有 AI 接口和点位写入接口，使用 `FastMCP` 构建一个面向大模型的 MCP 服务。

当前版本目标：

- 提供 AI 系统搜索能力
- 提供 AI 策略记录查询能力
- 提供 AI 在线状态与控制模式查询能力
- 提供点位批量下发能力
- 支持通过 `project_key` 选择项目环境
- 保持上游接口原有分页和返回结构

当前版本不做的事情：

- 不做 AI 系统 code 的自动猜测或纠错
- 不做复杂缓存失效策略
- 不对策略结果做额外业务推断
- 不对写入点位做复杂审批流封装

## 2. 设计原则

### 2.1 查询参数以 AI 系统 code 为准

AI 相关正式查询工具统一使用 `code`，而不是名称参数。

所有业务工具都必须显式传入 `project_key`，用于定位项目配置和认证信息。

原因：

- 名称可能重名
- AI 系统名称可能被修改，但 `code` 更稳定
- 大模型基于名称自动猜测容易产生静默误查
- 上游 AI 明细接口本身就是按 `codes` 查询

因此当前版本采用两层结构：

- 搜索工具：返回候选项和 `code`
- 明细工具：使用 `code` 发起正式查询

### 2.2 搜索工具负责“给 code”

当前版本不单独提供 `find_ai_system` 这类解析工具。

原因：

- `search_ai_systems` 已足够支撑“先查候选，再拿 code”流程
- 减少工具数量，避免能力重复
- 保持 MCP 工具边界清晰

### 2.3 分页保持上游原样

所有分页接口都保留上游原有分页行为：

- AI 搜索接口默认请求各自的默认 `page_size`
- 由调用方显式传入 `page_num`
- MCP 不自动翻页

这样可以避免一次调用返回过大数据，也更符合上游原始接口行为。

当某一页没有找到目标结果时，MCP 应明确提示：

- 当前只查询了指定页
- 如需继续查找，可以继续传更大的 `page_num`

### 2.4 返回结构尽量保持上游原样

当前版本不对接口返回结果做额外整理：

- 不做字段重命名
- 不做结构扁平化
- 不做业务字段推断
- 不做统一 `items` 包装

MCP 以“尽量接近上游返回”的方式对外暴露结果，只补充必要的工具层说明。

### 2.5 写接口保持最小封装

`set_multi_values` 直接透传点位和值，只补充项目鉴权和错误处理。

原因：

- 点位写入本身是高风险操作
- 工具层不应替用户推断写入值
- 保持请求体和上游接口文档一致，便于排查问题

## 3. 接口分析

## 3.1 项目配置与认证

项目配置来自 `sys_config` 中的 `mcp_project_data_projects`。

单个项目配置至少包含：

- `project_key`
- `project_name`
- `base_url`
- `username`
- `password`
- `enabled`

业务请求流程：

1. 通过 `project_key` 找到项目配置
2. 从项目配置读取 `base_url`、`username`、`password`
3. 先读取当前项目的 token 缓存
4. 如缓存不存在或已过期，则调用登录接口重新获取 token
5. 使用获取到的 token 访问 AI 查询接口或点位写入接口

登录接口：

- `POST {base_url}/api/ai/auth/password_login`

登录成功条件：

- 返回 JSON
- `errcode` 为 `0` 或 `0.0`
- 响应中包含 `token`

业务请求认证方式：

- 请求头使用 `Authorization`
- header 的值直接使用 token 原文
- 不额外拼接 `Bearer ` 前缀

token 缓存策略：

- 按 `project_key` 单独缓存
- 缓存内容存储在 `sys_config`
- 当 `expire_at` 仍未过期时直接复用
- 当缓存失效时重新登录并回写缓存

## 3.2 AI 系统搜索

接口：`POST /api/ai/system/search`

用途：

- 按关键字搜索 AI 系统
- 获取后续接口需要的 AI 系统 `code`

输入特点：

- 支持分页
- 支持 `order_by`
- 关键字为空时可按默认排序返回结果

输出特点：

- 返回 `results` 数组
- 每条结果包含 `id`、`name`、`code`、`ctrl_mode_point_id`、`status_formula`
- 返回 `page`、`page_size`、`total_pages`、`total`

MCP 处理建议：

- 默认请求 `page_size=20`
- 保持结果结构原样返回
- 若存在下一页则追加 `mcp_note`

## 3.3 AI 策略记录查询

接口：`POST /api/ai/ai_rcmd_operation/search_ai_rcmd_operation`

用途：

- 按 AI 系统 `code` 查询策略记录
- 判断策略属于自动控制还是推荐参考

主要过滤字段：

- `codes`
- `end`
- `order`
- `page_size`
- `page_num`

输出特点：

- 返回 `results` 数组
- 每条结果包含 `id`、`code`、`status`、`auto_exec`、`data`、`create_time`
- `data.rcmd` 中包含策略建议明细

MCP 处理建议：

- 默认请求 `page_size=20`
- 保持结果结构原样返回
- `auto_exec=true` 表示自动控制，否则为推荐参考
- 若存在下一页则追加 `mcp_note`

## 3.4 AI 在线状态查询

接口：`POST /api/ai/ai_rcmd_operation/ai_online_v2`

用途：

- 查询 AI 系统当前控制模式和运行状态

输入特点：

- 按 `codes` 批量查询
- 非分页接口

输出特点：

- 返回 `details` 对象
- `details.<code>` 包含 `status`、`control_mode`、`ctrl_mode_point_id`、`status_formula`

MCP 处理建议：

- 保持结果结构原样返回
- `control_mode=1` 表示自动控制，否则为推荐参考
- `status=0` 表示正常，`status=1` 表示异常

## 3.5 点位批量下发

接口：`POST /basedataportal/value/set_multi_values`

用途：

- 批量下发点位值

输入特点：

- 请求体包含 `points`
- 每项至少包含 `point_id` 和 `value`
- 支持 `from` 标记来源

输出特点：

- 返回 `state`、`state_info`、`data`

MCP 处理建议：

- 不改写请求体字段语义
- 成功条件沿用 `state == 0`
- 错误时直接暴露上游错误信息

## 4. 业务关系梳理

## 4.1 AI 系统

- AI 系统有 `name` 和稳定的 `code`
- AI 系统可能带有控制模式点位 `ctrl_mode_point_id`
- AI 系统可能配置状态公式 `status_formula`

## 4.2 AI 策略记录

- 策略记录按 AI 系统 `code` 归属
- 一条策略记录可能包含多个推荐分组和多个点位建议
- `auto_exec` 可区分自动控制和推荐参考

## 4.3 AI 在线状态

- AI 在线状态按 AI 系统 `code` 返回
- `control_mode` 表示控制模式
- `status` 表示运行状态

## 4.4 点位下发

- 点位下发与 AI 查询能力解耦
- 点位写入通过 `point_id` 和 `value` 执行
- 写入接口适合在确认 AI 状态或策略后按需调用

## 5. 当前 MCP 工具清单

当前版本聚焦 AI 系统查询、策略查询、在线状态查询和点位批量下发。

## 5.1 `search_ai_systems`

用途：

- 查询 AI 系统候选项
- 获取后续接口需要的 `code`

建议入参：

- `project_key: str`
- `keyword: str = ""`
- `page_size: int = 20`
- `page_num: int = 1`
- `order_by: list[str] | None = None`

内部调用：

- `/api/ai/system/search`

返回字段：

- `results[].id`
- `results[].name`
- `results[].code`
- `results[].remark`
- `results[].ctrl_mode_point_id`
- `results[].status_formula`

备注：

- 主要目标是从搜索结果中拿到 AI 系统 `code`
- 接口返回 `page`、`page_size`、`total_pages`、`total`

## 5.2 `search_ai_rcmd_operations`

用途：

- 按 AI 系统 `code` 查询策略记录
- 判断某条策略属于自动控制还是推荐参考

建议入参：

- `project_key: str`
- `codes: list[str]`
- `end: str`
- `page_size: int = 20`
- `page_num: int = 1`
- `order: str = "-create_time"`

内部调用：

- `/api/ai/ai_rcmd_operation/search_ai_rcmd_operation`

返回字段：

- `results[].id`
- `results[].workflow_id`
- `results[].code`
- `results[].status`
- `results[].auto_exec`
- `results[].data`
- `results[].create_time`
- `results[].operation_name`

备注：

- `auto_exec=true` 表示自动控制，否则为推荐参考
- 该接口支持分页

## 5.3 `get_ai_online_v2`

用途：

- 查询 AI 系统当前控制模式和状态

建议入参：

- `project_key: str`
- `codes: list[str]`

内部调用：

- `/api/ai/ai_rcmd_operation/ai_online_v2`

返回字段：

- `details.<code>.id`
- `details.<code>.name`
- `details.<code>.code`
- `details.<code>.status`
- `details.<code>.control_mode`
- `details.<code>.ctrl_mode_point_id`
- `details.<code>.status_formula`

备注：

- `control_mode=1` 表示自动控制，否则为推荐参考
- `status=0` 表示正常，`status=1` 表示异常

## 5.4 `set_multi_values`

用途：

- 批量下发点位值

建议入参：

- `project_key: str`
- `points: list[{"point_id": str, "value": str}]`
- `from_: str = "M2_BACKEND"`

内部调用：

- `/basedataportal/value/set_multi_values`

返回字段：

- `state`
- `state_info`
- `data`

备注：

- `points` 中每项固定包含 `point_id` 和 `value`

## 6. MCP 调用流程建议

## 6.1 搜索 AI 系统并拿到 code

步骤：

1. 调用 `search_ai_systems(project_key=..., keyword=...)`
2. 从 `results` 中选择目标 AI 系统 `code`
3. 将 `code` 用于后续策略查询或状态查询

## 6.2 按 AI 系统 code 查询策略记录

步骤：

1. 调用 `search_ai_systems(project_key=..., keyword=...)`
2. 从结果中提取一个或多个 `code`
3. 调用 `search_ai_rcmd_operations(project_key=..., codes=[...], end=...)`

## 6.3 查询 AI 在线状态后执行点位下发

步骤：

1. 调用 `get_ai_online_v2(project_key=..., codes=[...])`
2. 确认目标 AI 系统状态和控制模式
3. 按需调用 `set_multi_values(project_key=..., points=[...])`

## 7. 分页设计

当前仅对支持分页的 AI 查询接口透传分页参数，不做自动翻页。

约定：

- `search_ai_systems` 默认使用 `page_size=20`
- `search_ai_rcmd_operations` 默认使用 `page_size=20`
- 由调用方显式指定 `page_num`
- MCP 返回当前页原始结果
- 若存在下一页，则追加 `mcp_note`

适用接口：

- `/api/ai/system/search`
- `/api/ai/ai_rcmd_operation/search_ai_rcmd_operation`

不涉及分页控制的接口：

- `/api/ai/ai_rcmd_operation/ai_online_v2`
- `/basedataportal/value/set_multi_values`

## 8. 返回结果规范

当前版本继续尽量保持上游接口的返回结构：

- AI 查询接口保留 `errcode`、`msg`、`results`、`details`、`page`、`total_pages` 等字段
- 点位下发接口保留 `state`、`state_info`、`data`
- 不重组为统一的 `items` 结构

这样可以降低实现复杂度，也便于和上游接口文档直接对照。

## 9. 错误处理策略

当前版本采用简单直接的错误策略。

### 9.1 HTTP 错误

- 请求失败时直接抛出错误
- 错误信息包含接口路径、状态码、响应体摘要

### 9.2 业务错误

- 当 AI 接口返回 `errcode != 0` 时视为业务失败
- 当点位下发接口返回 `state != 0` 时视为业务失败
- 错误中优先包含 `msg` 或 `state_info`

### 9.3 空结果

- 空结果不视为错误
- 保持上游原始返回结构，只是结果列表为空

## 10. FastMCP 实现建议

建议继续采用现有轻量三层结构。

## 10.1 HTTP Client 层

职责：

- 发送 HTTP 请求
- 根据 `project_key` 定位项目配置
- 处理登录和 token 获取
- 处理响应状态和业务状态
- 透传分页参数和原始 JSON 结构

当前模块：

- `auth.py`

## 10.2 API 封装层

职责：

- 封装 AI 查询和点位下发接口
- 保持上游返回结构
- 只做必要的参数组织

当前模块：

- `config_api.py`

## 10.3 MCP Tool 层

职责：

- 暴露 `FastMCP` 工具
- 定义工具参数和返回结果
- 对分页结果补充 `mcp_note`

当前模块：

- `server.py`

## 11. 当前暂不处理的问题

以下能力可在后续版本再补：

- AI 系统 code 的别名或模糊纠错
- 对策略结果做更细粒度的语义整理
- 点位下发前的额外安全校验
- 本地缓存和缓存刷新机制
- 返回结果裁剪和排序策略

## 12. 建议的下一步

实现顺序建议如下：

1. 保持 `project.list` 和登录链路稳定
2. 完善 AI 查询工具的联调样例
3. 补充 `set_multi_values` 的安全使用说明
4. 增加少量联调脚本或示例调用