# 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 下的兼容问题。

默认数据库地址：

```text
sqlite:///llm_proxy.db
```

默认上游超时：

```text
UPSTREAM_REQUEST_TIMEOUT=60
```

## 项目配置

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

示例：

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

## 安装

在项目根目录执行：

```bash
uv sync
```

如果本机还没有可用的 Python 环境，可先安装 3.13：

```bash
uv python install 3.13
uv sync --python 3.13
```

## 启动

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

方式一：使用模块启动

```bash
uv run python -m m2_mcp
```

方式二：使用 console script 启动

```bash
uv run m2-mcp
```

可选环境变量：

- `MCP_HOST`，默认 `127.0.0.1`
- `MCP_PORT`，默认 `8500`
- `MCP_PATH`，默认 `/mcp`

如果需要指定数据库：

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

如果需要指定 HTTP 地址：

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

如果需要指定上游超时：

```bash
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`
- `get_command_log`

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

## 分页规则

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

示例说明：

```json
{
  "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

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

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

```bash
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 系统控制模式和状态

```bash
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：批量下发点位值

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

其中 `points` 的每一项结构为：

```json
[
  {
    "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`

语法校验：

```bash
uv run python -m compileall .
```