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

默认数据库地址：

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

## 启动

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

方式一：使用模块启动

```bash
uv run --python 3.13 python -m instrument_config_mcp
```

方式二：使用 console script 启动

```bash
uv run --python 3.13 instrument-config-mcp
```

可选环境变量：

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

如果需要指定数据库：

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

如果需要指定 HTTP 地址：

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

如果需要指定上游超时：

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

示例说明：

```json
{
  "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：查询位置第一页

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

示例 2：查询系统树

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

示例 3：查询设备类型

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

示例 4：按位置搜索仪表

```bash
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：按系统和设备类型搜索设备

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

语法校验：

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