m2-mcp

Instrument Config MCP

基于 FastMCP 的 AI 查询与点位下发 MCP 服务，用于访问以下接口：

• AI 系统搜索
• AI 策略查询
• AI 在线状态查询
• 点位批量下发

服务特点：

• 通过 project_key 选择项目环境
• 自动处理项目登录和 token 缓存
• 分页保持后端原样，不自动翻页
• 返回结果尽量保持后端原始结构
• 支持按项目对点位执行批量写入

详细设计见 mcp-design.md。

环境要求

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

建议优先使用当前默认 Python 环境运行；如果本机还没有可用环境，再用 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：

uv python install 3.13
uv sync --python 3.13

启动

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

方式一：使用模块启动

uv run python -m m2_mcp

方式二：使用 console script 启动

uv run m2-mcp

可选环境变量：

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

如果需要指定数据库：

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

如果需要指定 HTTP 地址：

set MCP_HOST=0.0.0.0
set MCP_PORT=8500
set MCP_PATH=/mcp
uv run python -m m2_mcp

如果需要指定上游超时：

set UPSTREAM_REQUEST_TIMEOUT=60
uv run python -m m2_mcp

MCP 工具

当前提供以下工具：

• project.list
• search_ai_systems
• search_ai_rcmd_operations
• get_ai_online_v2
• set_multi_values

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

分页规则

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

示例说明：

{
  "state": 0,
  "state_info": "OK",
  "data": {
    "page_size": 20,
    "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：搜索 AI 系统 code

uv run python scripts/smoke_test.py search-ai-systems --project-key dev-01 --keyword TEST --page-num 1

示例 2：按 AI 系统 code 查询策略记录

uv run python scripts/smoke_test.py search-ai-rcmd-operations --project-key dev-01 --codes S1_opt_1 S1_opt_2 --end "2026-04-14 11:28:53"

示例 3：查询 AI 系统控制模式和状态

uv run python scripts/smoke_test.py get-ai-online-v2 --project-key dev-01 --codes S1_opt_1 S1_opt_2 S1_opt_3

示例 4：批量下发点位值

uv run python scripts/smoke_test.py set-multi-values --project-key dev-01 --points-json "[{\"point_id\":\"YKX_1\",\"value\":\"22\"}]"

其中 points 的每一项结构为：

[
  {
    "point_id": "YKX_1",
    "value": "22"
  }
]

联调建议顺序

1. 先运行 search-ai-systems，确认认证链路和 AI 查询接口正常
2. 再运行 search-ai-rcmd-operations 或 get-ai-online-v2 验证 AI 明细接口
3. 最后按需运行 set-multi-values

常见问题

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，通常需要检查：

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

开发说明

核心文件：

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

语法校验：

uv run python -m compileall .