instrument-data-mcp/mcp-design.md

Instrument Config MCP Design

1. 目标

基于现有配置接口，使用 FastMCP 构建一个面向大模型的查询型 MCP 服务。

第一版目标：

• 提供位置、系统、设备类型、仪表类型的查询能力
• 提供设备、仪表的正式搜索能力
• 支持通过 project_key 选择项目环境
• 保持接口原有分页行为，默认请求 page_size=100
• 以 id 作为正式查询参数，避免名称重名带来的歧义

第一版不做的事情：

• 不做名称到 id 的自动猜测
• 不做复杂缓存失效策略
• 不做写接口
• 不做额外的业务推断型工具

2. 设计原则

2.1 查询参数以 ID 为准

正式搜索工具统一使用 id 参数，而不是名称参数。

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

原因：

• 名称可能重名
• 树结构下可能出现同名节点
• 大模型如果基于名称做自动选择，容易产生静默误查
• 接口本身的正式过滤条件也是以 id 为主

因此第一版采用两层结构：

• 列表工具：返回候选项和 id
• 搜索工具：使用 id 发起正式查询

2.2 列表工具负责“给 ID”

第一版不单独提供 find_locations、find_systems 这类解析工具。

原因：

• 已有列表接口足够支撑“先查候选，再拿 id”流程
• 减少工具数量，避免能力重复
• 保持 MCP 工具边界清晰

2.3 分页保持后端原样

所有分页接口都保留后端原有分页行为：

• 默认请求 page_size=100
• 由调用方显式传入 page_num
• MCP 不自动翻页

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

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

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

2.4 返回结构尽量保持后端原样

第一版不对树结构或接口返回结果做额外整理：

• 不做扁平化
• 不做去重
• 不做额外路径拼接
• 不做字段重命名

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

3. 接口分析

3.0 项目配置与认证

项目配置来自 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 访问配置接口

登录接口：

• 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.1 位置搜索

接口：POST /api/configapi/location/list

用途：

• 按关键字搜索位置
• keyword 为空时可全量拉取

输入特点：

• 支持分页
• 返回树结构

输出特点：

• 节点包含 children
• 节点包含 id、code、full_code、name、parent_id、level

MCP 处理建议：

• 默认请求 page_size=100
• 保持树结构原样返回
• 以 id 作为后续设备/仪表查询参数

3.2 仪表搜索

接口：POST /api/configapi/meter/list

用途：

• 按安装位置、仪表类型、状态、测量对象关联维度搜索仪表
• keyword 为空时可全量拉取

主要过滤字段：

• location_id
• show_below
• keyword
• meter_type_id
• measurement_location_ids
• measurement_system_ids
• measurement_device_type_ids
• status

字段语义：

• location_id：仪表安装位置
• measurement_location_ids：仪表关联的测量位置
• measurement_system_ids：仪表关联的测量系统
• measurement_device_type_ids：仪表关联的测量设备类型

注意：

• 安装位置和测量位置不是一个概念
• 返回中存在父子仪表关系：parent_id、parent_name
• keyword 更适合定义为“模糊匹配名称、编号等文本字段”

关于 measurement_flag 的当前工作假设：

• 0：无
• 1：设备
• 2：其他非设备对象

该语义来自现有页面文案和样例数据，但后续若后端给出正式定义，应以正式定义为准。

3.3 系统树

接口：POST /api/configapi/system/tree

用途：

• 获取系统类型树和系统节点

结构特点：

• type=1：系统类型
• type=2：系统

MCP 处理建议：

• 保持树结构原样返回
• 不额外补充扁平节点列表

3.4 系统列表

接口：POST /api/configapi/system/list

用途：

• 按系统类型查询系统列表
• 可作为系统全量列表接口使用

主要过滤字段：

• system_type_id
• show_below

MCP 处理建议：

• 默认请求 page_size=100
• 用于给设备搜索或其他工具提供系统 id

3.5 设备类型列表

接口：POST /api/configapi/devicetype/list

用途：

• 返回设备类型字典

特点：

• 当前支持 page_size=-1 全量返回
• 非分页核心接口

3.6 设备搜索

接口：POST /api/configapi/device/list

用途：

• 按位置、系统、设备类型、关键字查询设备
• keyword 为空时可全量拉取

主要过滤字段：

• location_id
• show_below
• keyword
• system_ids
• device_type_ids

MCP 处理建议：

• 默认请求 page_size=100
• 使用 id 过滤
• 返回结构尽量保持后端原样

3.7 仪表类型列表

接口：POST /api/configapi/metertype/list

用途：

• 返回仪表类型字典

特点：

• 当前支持 page_size=-1 全量返回
• 供仪表搜索使用

3.8 拓扑详情与节点数据

接口：

• POST /api/configapi/topo/get
• POST /api/configapi/topo/get_data

用途：

• topo/get：读取单张拓扑结构、data_options、dimension_config
• topo/get_data：读取单张拓扑在某个展示维度和单个时间点下的节点数据

关键约束：

• topo/get_data 一次只支持一个拓扑、一个 display、一个时间点
• display=instant 不带时间参数
• display=accu 需要显式传 accu_step 和 ts
• 不能直接返回时间范围数据，需要由 MCP 层做多次调用聚合

当前 MCP 处理：

• topology.get_node 查询时实时调用 1 次 instant
• 再调用 12 次小时累计和 7 次日累计
• 节点值按 node_id 直接匹配

3.9 拓扑分组配置

来源字段：

• topo/get 返回中的 dimension_config

适用范围：

• 仅 topology_type=2 的拓扑图

结构特点：

• dimension_config.dimensions 表示分组配置
• dimension_config.filter 表示筛选配置
• filter.conditions[].fields 存储业务对象 ID 列表，需要额外解析名称

枚举语义：

• order: 1=顺序，2=逆序
• filter_type: 1=所有，2=任一
• match_type: 1=等于，2=不等于，3=包含，4=不包含

对象类型语义：

• 11=位置
• 12=系统类型
• 13=系统
• 14=设备类型
• 15=设备
• 16=仪表类型
• 17=仪表型号
• 18=仪表
• 19=拓扑图分组
• 20=拓扑图

名称解析来源：

• 11 -> list_locations
• 12 -> list_system_tree
• 13 -> list_systems
• 14 -> list_device_types
• 15 -> search_devices
• 16 -> list_meter_types
• 18 -> search_meters
• 19 -> 本地拓扑分组缓存
• 20 -> 本地拓扑注册缓存

当前限制：

• 17（仪表型号）暂未实现名称解析，需要后续补接口或规则

4. 业务关系梳理

4.1 位置

• 位置是树结构
• 设备安装在位置上
• 仪表也安装在位置上

4.2 系统

• 系统存在系统类型和具体系统两层
• 设备可归属某系统
• 仪表可关联某系统作为测量对象

4.3 设备

• 设备有设备类型
• 设备属于位置和系统

4.4 仪表

• 仪表有仪表类型
• 仪表存在父子层级
• 仪表安装在某位置
• 仪表可以关联位置、系统、设备类型等测量对象维度

5. 第一版 MCP 工具清单

第一版只保留必要工具，不做额外封装工具。

5.1 list_locations

用途：

• 查询位置候选项
• 为后续正式搜索提供 location_id

建议入参：

• project_key: str
• keyword: str | None = None

内部调用：

• /api/configapi/location/list

返回字段：

• id
• name
• code
• full_code
• parent_id
• level

备注：

• keyword 为空时全量拉取
• 返回后端原始树结构

5.2 list_system_tree

用途：

• 获取系统类型和系统的树结构信息

建议入参：

• project_key: str
• 无

内部调用：

• /api/configapi/system/tree

返回字段：

• 保持后端原始字段结构

5.3 list_systems

用途：

• 获取系统列表
• 为设备或其他查询提供 system_id

建议入参：

• project_key: str
• page_size: int = 100
• page_num: int = 1
• system_type_id: int = 0
• show_below: bool = True

内部调用：

• /api/configapi/system/list

返回字段：

• id
• name
• code
• system_type_id
• system_type_name

5.4 list_device_types

用途：

• 获取设备类型列表

建议入参：

• project_key: str
• 无

内部调用：

• /api/configapi/devicetype/list

返回字段：

• id
• name
• code

5.5 list_meter_types

用途：

• 获取仪表类型列表

建议入参：

• project_key: str
• 无

内部调用：

• /api/configapi/metertype/list

返回字段：

• id
• name
• code

5.6 search_devices

用途：

• 按正式过滤条件查询设备

建议入参：

• project_key: str
• page_size: int = 100
• page_num: int = 1
• keyword: str | None = None
• location_id: int = 0
• show_below: bool = True
• system_ids: list[int] | None = None
• device_type_ids: list[int] | None = None

内部调用：

• /api/configapi/device/list

返回字段：

• id
• name
• code
• device_type_id
• device_type_name
• location_id
• location_name
• system_id
• system_name
• parent_id
• is_group
• location_full_code

备注：

• keyword 为空时表示不按关键字过滤
• 若当前页未找到目标结果，可继续传更大的 page_num

5.7 search_meters

用途：

• 按正式过滤条件查询仪表

建议入参：

• project_key: str
• page_size: int = 100
• page_num: int = 1
• keyword: str | None = None
• location_id: int = 0
• show_below: bool = True
• meter_type_id: int = 0
• measurement_location_ids: list[int] | None = None
• measurement_system_ids: list[int] | None = None
• measurement_device_type_ids: list[int] | None = None
• status: int | None = None

内部调用：

• /api/configapi/meter/list

返回字段：

• id
• name
• code
• meter_type_id
• meter_type_name
• location_id
• location_name
• parent_id
• parent_name
• measurement_flag
• measurement_device_id
• measurement_device_name
• measurement_location_id
• measurement_location_name
• measurement_system_id
• measurement_system_name
• measurement_device_type_id
• measurement_device_type_name
• status
• meter_model_id
• meter_model_name
• meter_model_brand
• code_prefix

备注：

• keyword 为空时表示不按关键字过滤
• 若当前页未找到目标结果，可继续传更大的 page_num
• 第一版不对 measurement_flag 做强校验，只透传查询条件

5.8 topology.group_list

用途：

• 返回缓存中的拓扑分组树

建议入参：

• project_key: str

5.9 topology.list

用途：

• 返回缓存中的拓扑列表
• 可按分组或对象类型过滤

建议入参：

• project_key: str
• group_id: int | None = None
• object_type_code: int | None = None

5.10 topology.get_node

用途：

• 获取一个节点及其直接邻域
• 同时返回当前拓扑的节点实时值和累计值窗口

建议入参：

• project_key: str
• topology_id: int
• node_id: str = 'root'
• include_siblings: bool = True
• include_children: bool = True

返回结构：

• data_window
• topology
• node
• parents
• children
• siblings

说明：

• topology 中包含 data_options、metric_definitions、dimension_config
• node.data.instant 为实时值
• node.data.accu.hourly 为最近 12 个整点小时累计值
• node.data.accu.daily 为最近 7 个日零点累计值

5.11 topology.get_group_config

用途：

• 返回 type=2 拓扑图的分组配置和筛选配置

建议入参：

• project_key: str
• topology_id: int

返回结构：

• supported
• raw_dimension_config
• groupings
• filter

说明：

• groupings 由 dimension_config.dimensions 派生
• filter 由 dimension_config.filter 派生
• filter.conditions[].field_items 为解析后的 id + name

5.12 topology.find_context

用途：

• 按实体快速反查命中的拓扑节点上下文

建议入参：

• project_key: str
• entity_type: str
• entity_id: int
• topology_id: int | None = None
• include_siblings: bool = True
• ancestor_depth: int = 5
• descendant_depth: int = 2

6. MCP 调用流程建议

6.1 按位置查仪表

步骤：

1. 调用 list_locations(keyword=...) 需要传入 project_key
2. 从返回结果中选择目标 location_id
3. 调用 search_meters(project_key=..., location_id=..., show_below=...)

6.2 按系统查设备

步骤：

1. 调用 list_systems(project_key=..., ...) 或 list_system_tree(project_key=...)
2. 从返回结果中选择目标 system_id
3. 调用 search_devices(project_key=..., system_ids=[...])

6.3 按设备类型和系统查仪表

步骤：

1. 调用 list_device_types(project_key=...) 获取 device_type_id
2. 调用 list_systems(project_key=..., ...) 获取 system_id
3. 调用 search_meters(project_key=..., measurement_device_type_ids=[...], measurement_system_ids=[...])

7. 分页设计

第一版不做自动翻页。

约定：

• 如果接口支持分页，则默认使用 page_size=100
• 由调用方显式指定 page_num
• MCP 返回当前页原始结果

适用接口：

• location/list
• system/list
• device/list
• meter/list

不涉及分页控制的接口：

• system/tree
• devicetype/list
• metertype/list

8. 返回结果规范

第一版建议尽量保持后端接口的返回结构：

• 保留 state
• 保留 state_info
• 保留 data
• 不重组为统一的 items 结构

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

9. 错误处理策略

第一版建议采用简单直接的错误策略。

9.1 HTTP 错误

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

9.2 业务错误

• 当返回 state != 0 时视为业务失败
• 错误中包含 state 和 state_info

9.3 空结果

• 空结果不视为错误
• 保持后端原始返回结构，只是结果列表为空

10. FastMCP 实现建议

建议采用三层结构。

10.1 HTTP Client 层

职责：

• 发送 HTTP 请求
• 注入公共参数，如 operator
• 根据 project_key 定位项目配置
• 处理登录和 token 获取
• 处理响应状态和业务状态
• 透传分页参数

建议模块：

• client.py

10.2 Service 层

职责：

• 封装接口调用
• 保持后端返回结构
• 只做必要的参数组织

建议模块：

• services/location.py
• services/system.py
• services/device.py
• services/meter.py

10.3 MCP Tool 层

职责：

• 暴露 FastMCP 工具
• 定义工具参数和返回结果

建议模块：

• server.py

11. 第一版暂不处理的问题

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

• 按名称自动解析 id
• 仪表型号列表及按型号查询
• 本地缓存和缓存刷新机制
• 更细的参数校验
• 返回结果裁剪和排序策略

12. 建议的下一步

实现顺序建议如下：

1. 搭建 FastMCP 基础服务
2. 实现通用 HTTP Client 和分页参数透传
3. 实现 list_locations、list_systems、list_device_types、list_meter_types
4. 实现 search_devices 和 search_meters
5. 增加少量联调脚本或示例调用