instrument-data-mcp

Instrument Config MCP

基于 FastMCP 的只读配置查询 MCP 服务，用于访问以下接口：

• 位置管理
• 系统管理
• 设备类型
• 仪表类型
• 设备搜索
• 仪表搜索

服务特点：

• 通过 project_key 选择项目环境
• 自动处理项目登录和 token 缓存
• 正式查询参数以 id 为准
• 分页保持后端原样，不自动翻页
• 返回结果尽量保持后端原始结构

详细设计见 mcp-design.md。

环境要求

• Python 3.11 到 3.13
• 一个可访问的 sys_config 表
• DATABASE_URL 指向包含 sys_config 的数据库

Windows 下建议固定使用 uv 的 Python 3.13 环境，避免 pywin32 在 Python 3.14 下的兼容问题。

默认数据库地址：

sqlite:///llm_proxy.db

默认上游超时：

UPSTREAM_REQUEST_TIMEOUT=60

项目配置

服务会从 sys_config 中读取 key 为 mcp_project_data_projects 的 JSON 数组。

示例：

[
  {
    "project_key": "dev-01",
    "project_name": "DEV开发环境",
    "base_url": "http://192.168.1.109:32080",
    "username": "admin",
    "password": "123456",
    "enabled": true
  }
]

安装

在项目根目录执行：

uv sync --python 3.13

启动

默认以 HTTP 模式启动，默认地址：http://127.0.0.1:8500/mcp

方式一：使用模块启动

uv run --python 3.13 python -m instrument_config_mcp

方式二：使用 console script 启动

uv run --python 3.13 instrument-config-mcp

可选环境变量：

• MCP_HOST，默认 127.0.0.1
• MCP_PORT，默认 8500
• MCP_PATH，默认 /mcp

如果需要指定数据库：

set DATABASE_URL=sqlite:///llm_proxy.db
uv run --python 3.13 python -m instrument_config_mcp

如果需要指定 HTTP 地址：

set MCP_HOST=127.0.0.1
set MCP_PORT=8500
set MCP_PATH=/mcp
uv run --python 3.13 python -m instrument_config_mcp

如果需要指定上游超时：

set UPSTREAM_REQUEST_TIMEOUT=60
uv run --python 3.13 python -m instrument_config_mcp

MCP 工具

当前提供以下工具：

• project.list
• list_locations
• list_system_tree
• list_systems
• list_device_types
• list_meter_types
• search_devices
• search_meters

除 project.list 外，其他工具都必须传 project_key。

分页规则

• 默认 page_size=100
• 由调用方显式传 page_num
• 服务不自动翻页
• 如果当前页后面还有数据，返回中会附带 mcp_note

示例说明：

{
  "state": 0,
  "state_info": "OK",
  "data": {
    "page_size": 100,
    "page_num": 1,
    "total_page": 8,
    "total": 115,
    "data": []
  },
  "mcp_note": "Current result is page 1. If the target was not found, continue with page_num=2."
}

本地联调

仓库内提供了一个简单的 smoke test 脚本：scripts/smoke_test.py

示例 1：查询位置第一页

uv run --python 3.13 python scripts/smoke_test.py list-locations --project-key dev-01 --keyword F1

示例 2：查询系统树

uv run --python 3.13 python scripts/smoke_test.py list-system-tree --project-key dev-01

示例 3：查询设备类型

uv run --python 3.13 python scripts/smoke_test.py list-device-types --project-key dev-01

示例 4：按位置搜索仪表

uv run --python 3.13 python scripts/smoke_test.py search-meters --project-key dev-01 --location-id 162 --show-below true --page-num 1

示例 5：按系统和设备类型搜索设备

uv run --python 3.13 python scripts/smoke_test.py search-devices --project-key dev-01 --system-ids 21 --device-type-ids 5

联调建议顺序

1. 先运行 list-device-types 和 list-meter-types，确认认证链路正常
2. 再运行 list-locations 或 list-system-tree，确认配置接口可访问
3. 最后运行 search-devices 或 search-meters 做正式搜索

常见问题

1. project_key not found

说明 sys_config 中没有对应的 project_key。

2. project 'xxx' is disabled

说明项目配置存在，但 enabled=false。

3. login failed

重点检查：

• base_url
• username
• password
• 上游登录接口是否可访问

4. upstream returned non-JSON response

说明上游接口返回的不是 JSON，通常需要检查：

• 域名或路径是否错误
• 网关是否拦截
• 登录态是否失效

开发说明

核心文件：

• instrument_config_mcp/auth.py
• instrument_config_mcp/db.py
• instrument_config_mcp/config_api.py
• instrument_config_mcp/server.py

语法校验：

uv run --python 3.13 python -m compileall .