# Data Collector MCP

基于 FastMCP 的采集器 MCP 服务。

首期提供：

- `project.list`
- `modbus.point_collect_test`
- `collector.modbus_device_create`
- `collector.modbus_point_create`
- `collector.device_list`

默认 MCP 地址：`http://127.0.0.1:8501/mcp`

## 配置

服务使用 PostgreSQL，通过 `DATABASE_URL` 连接数据库。

项目配置存放在 `sys_config` 表中，key 为 `mcp_data_collector_projects`。

如果需要手动建表，推荐使用 PostgreSQL `IDENTITY`，不要直接引用未创建的 `sys_config_id_seq`：

```sql
CREATE TABLE IF NOT EXISTS public.sys_config (
    id integer GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    key character varying(128) NOT NULL UNIQUE,
    value json NOT NULL
);
```

也可以不手动建表，服务启动并访问配置时会通过 SQLAlchemy 自动创建表，但数据库用户需要有建表权限。

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

`data_collector_base_url` 缺失时会直接报错，不回退到 `base_url`。

## 启动

```powershell
python -m data_collector_mcp
```

可选环境变量：

- `DATABASE_URL`，必填
- `MCP_HOST`，默认 `0.0.0.0`
- `MCP_PORT`，默认 `8501`
- `MCP_PATH`，默认 `/mcp`
- `UPSTREAM_REQUEST_TIMEOUT`，默认 `60`

## 测试

```powershell
python -m unittest discover -s tests
```

## MCP 连通性测试

先启动 MCP 服务：

```powershell
$env:DATABASE_URL = "postgresql+psycopg2://postgres:password@127.0.0.1:5432/data_collector_mcp"
& ".venv\Scripts\python.exe" -m data_collector_mcp
```

另开一个 PowerShell 窗口，列出 tools：

```powershell
& ".venv\Scripts\python.exe" tools\test_mcp_call.py --list-tools
```

调用 `project.list`：

```powershell
& ".venv\Scripts\python.exe" tools\test_mcp_call.py --tool project.list
```

调用 `collector.device_list`：

```powershell
& ".venv\Scripts\python.exe" tools\test_mcp_call.py --tool collector.device_list --args '{"project_key":"dev-01","num_points":false}'
```

测试脚本会先打印本次 MCP tool 请求 payload，例如：

```json
{
  "request": {
    "url": "http://127.0.0.1:8501/mcp",
    "tool": "collector.device_list",
    "arguments": {
      "project_key": "dev-01",
      "num_points": false
    }
  }
}
```

创建 Modbus 设备时必须传：

- `payload.device_type`：协议类型，`1=TCP`、`2=RTU`、`3=UDP`、`4=RTU OVER TCP`、`5=RTU OVER UDP`
- `payload.ip`：IP 地址
- `payload.port`：端口号
- `payload.name`：设备名称
- `payload.slave_id`：Modbus 从站 ID
- `payload.word_order`：字顺序，`1=Big Endian`、`2=Small Endian`
- `payload.byte_order`：字节顺序，`1=Big Endian`、`2=Small Endian`
- `payload.address_base`：地址基准，会转换为汇采接口的 `address_offset`

创建 Modbus 点位时必须传：

- `payload.name`：点位名称
- `payload.address`：寄存器地址
- `payload.type`：数据类型
- `payload.func_code` 或 `payload.register_type`：寄存器类型

常见点表数据类型映射：

| 点表类型 | 汇采 `type` |
|---|---|
| `BOOL` / `BOOLEAN` | `bool` |
| `SHORT` | `int16` |
| `WORD` | `uint16` |
| `LONG` | `int32` |
| `DWORD` | `uint32` |
| `FLOAT` / `REAL` | `float32` |
| `DOUBLE` | `float64` |
| `LONGLONG` | `int64` |
| `QWORD` | `uint64` |

`register_type` 可用：

| `register_type` | 转换为 `func_code` |
|---|---:|
| `coil` | `1` |
| `discrete_input` | `2` |
| `holding_register` | `3` |
| `input_register` | `4` |

调用其他 MCP URL：

```powershell
& ".venv\Scripts\python.exe" tools\test_mcp_call.py --url "http://127.0.0.1:8501/mcp" --tool project.list
```