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

业务请求流程：

通过 project_key 找到项目配置
从项目配置读取 base_url、username、password
先读取当前项目的 token 缓存
如缓存不存在或已过期，则调用登录接口重新获取 token
使用获取到的 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

步骤：

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

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

步骤：

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

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

步骤：

调用 get_ai_online_v2(project_key=..., codes=[...])
确认目标 AI 系统状态和控制模式
按需调用 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. 建议的下一步

实现顺序建议如下：

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

mcp-design.md 12 KB لینک دائمی تاريخچه خام

AI Control MCP Design

1. 目标

2. 设计原则

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

2.2 搜索工具负责“给 code”

2.3 分页保持上游原样

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

2.5 写接口保持最小封装

3. 接口分析

3.1 项目配置与认证

3.2 AI 系统搜索

3.3 AI 策略记录查询

3.4 AI 在线状态查询

3.5 点位批量下发

4. 业务关系梳理

4.1 AI 系统

4.2 AI 策略记录

4.3 AI 在线状态

4.4 点位下发

5. 当前 MCP 工具清单

5.1 search_ai_systems

5.2 search_ai_rcmd_operations

5.3 get_ai_online_v2

5.4 set_multi_values

6. MCP 调用流程建议

6.1 搜索 AI 系统并拿到 code

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

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

7. 分页设计

8. 返回结果规范

9. 错误处理策略

9.1 HTTP 错误

9.2 业务错误

9.3 空结果

10. FastMCP 实现建议

10.1 HTTP Client 层

10.2 API 封装层

10.3 MCP Tool 层

11. 当前暂不处理的问题

12. 建议的下一步

mcp-design.md 12 KB

لینک دائمی تاريخچه خام

5.1 `search_ai_systems`

5.2 `search_ai_rcmd_operations`

5.3 `get_ai_online_v2`

5.4 `set_multi_values`