内容
<!-- mcp-name: io.github.jsgorana/ignition-mcp -->
# ignition-mcp
MCP（模型上下文协议）服务器，适用于 Inductive Automation Ignition。它为 AI 助手（如 Claude Desktop、Claude Code）或任何 [MCP 客户端](https://modelcontextprotocol.io) 提供结构化访问 Ignition 网关的能力：浏览和写入标签，查询历史和报警，管理项目，部署完整的 Perspective 视图。
已在 Ignition 8.3 版本下测试通过。包含 43 种工具，涵盖标签、历史、报警、项目、网关管理和 Perspective。服务器默认只读；所有写入操作都需要明确授权。
```
你： "将一个 Perspective 仪表盘部署到名为 LineOverview 的新项目中，并绑定一个连接到 [default]Line1/Speed 的仪表。"
克劳德： （启动项目，写入视图，连接标签绑定，触发扫描）
-> https://gateway:8088/data/perspective/client/LineOverview
```
## 为什么有两个层面
Ignition 8.3 自带原生 REST API，但它不提供实时的标签值、标签历史、报警查询或 Perspective 视图资源。`ignition-mcp` 通过两个传输层面弥补了这一不足：
- **REST层面。** 网关的原生 `/data/api/v1` API，使用 API 密钥认证，用于项目、网关配置、模块、日志、备份和 Perspective 会话诊断。
- **桥接层面。** 一个小型 WebDev 项目（`mcp-bridge`），您只需在网关上安装一次。它通过 HMAC 签名的 HTTP 请求，暴露网关的脚本接口（`system.tag.*`、`system.alarm.*`、`system.db.*` 和项目文件 I/O）。
需要桥接的工具如果未安装，会显示明确的错误消息。您可以随时运行 `ignition_diagnose` 以查看已配置的内容和缺失的内容。
## 快速入门
### 1. 在网关上创建 API 密钥
网关 Web UI -> 配置 -> 安全 -> API 密钥 -> 创建。命名，例如 `claude`。复制完整的令牌；它类似于 `claude:AbCd...`。
密钥的自动创建的安全级别（`Authenticated/<key-name>`）需要在配置 -> 安全 -> 常规 -> 网关读/写权限下授予网关读/写访问权限。跳过此步骤，调用将返回 HTTP 403；`ignition_diagnose` 将告知您并提供确切的修复方法。
### 2. 安装 ignition-mcp
```bash
pipx install ignition-mcp
# 或：uvx ignition-mcp
# 或：pip install ignition-mcp
```
### 3. 配置您的 MCP 客户端
克劳德桌面版（`claude_desktop_config.json`）或克劳德代码版（`.mcp.json`）：
```json
{
"mcpServers": {
"ignition": {
"command": "ignition-mcp",
"env": {
"IGNITION_URL": "http://localhost:8088",
"IGNITION_API_TOKEN": "claude:YOUR_SECRET_HERE"
}
}
}
}
```
重启客户端，并要求它运行 `ignition_diagnose`。您应该获得一个全绿色的检查清单，除了关于桥接的警告，这是下一步。
### 4. 安装桥接（推荐，需要实时数据和 Perspective 部署）
生成一个随机密钥，启用写入，并让服务器为您安装桥接：
```json
"env": {
"IGNITION_URL": "http://localhost:8088",
"IGNITION_API_TOKEN": "claude:YOUR_SECRET_HERE",
"IGNITION_BRIDGE_SECRET": "a-long-random-string",
"IGNITION_ALLOW_WRITES": "true"
}
```
要求您的助手安装桥接（这会运行 `bridge_install` 工具），然后再次运行 `ignition_diagnose` 以确认桥接检查为绿色。参见 [docs/bridge.md](docs/bridge.md) 以获取手动安装路径和故障排除信息。
## 配置
| 变量 | 必需 | 默认值 | 含义 |
|---|---|---|---|
| `IGNITION_URL` | 是 | 无 | 网关基本 URL，例如 `http://localhost:8088` |
| `IGNITION_API_TOKEN` | 是 | 无 | API 密钥，`name:secret` |
| `IGNITION_BRIDGE_SECRET` | 否 | 未设置 | 桥接的 HMAC 密钥；无密钥时桥接工具被禁用 |
| `IGNITION_ALLOW_WRITES` | 否 | `false` | 所有变更工具的主开关 |
| `IGNITION_TLS_VERIFY` | 否 | `true` | 设置为 `false` 以适用于自签名开发网关 |
| `IGNITION_TIMEOUT_S` | 否 | `30` | 每请求超时，单位：秒 |
| `IGNITION_TAG_WRITE_ALLOWLIST` | 否 | 未设置 | 以逗号分隔的 glob 模式；标签写入仅限于这些模式 |
## 安全模型
- 默认只读。变更工具除非 `IGNITION_ALLOW_WRITES=true` 且调用传递 `confirm=true`，否则拒绝运行。您的助手在您批准操作后设置 `confirm`。
- 破坏性操作会回显名称。删除项目或视图需要重新发送其确切名称。
- 标签写入允许列表可限制可写入的标签到特定的路径 glob。
- REST 变更将 API 密钥的身份带入 Ignition 的审计日志；桥接变更记录到 `mcp-bridge` 日志。密钥从不被记录或回显。
- 桥接的文件端点仅限于 `data/projects/`；该树之外的任何内容都不可达。
## 工具目录
| 领域 | 工具 |
|---|---|
| 诊断 | `ignition_diagnose`、`gateway_info`、`gateway_trial_status`、`gateway_trial_reset` |
| 标签 | `tag_browse`、`tag_read`、`tag_write`、`tag_create`、`tag_config_export`、`tag_config_import` |
| 历史 | `history_query`、`history_providers` |
| 报警 | `alarm_status`、`alarm_journal`、`alarm_acknowledge` |
| 项目 | `project_list`、`project_get`、`project_create`、`project_delete`、`project_export`、`project_import`、`project_scan` |
| Perspective | `perspective_bootstrap_project`、`perspective_list_views`、`perspective_get_view`、`perspective_upsert_view`、`perspective_delete_view`、`perspective_validate_view`、`perspective_page_config_get/set`、`perspective_session_props_get`、`perspective_style_upsert`、`perspective_list_sessions` |
| 网关管理 | `gateway_modules`、`gateway_logs_query`、`gateway_logger_set_level`、`gateway_backup`、`gateway_performance`、`config_resource_list` |
| 数据库 | `db_run_named_query`、`db_query` |
| 桥接 | `bridge_install`、`bridge_status` |
服务器还暴露 MCP 资源，供助手读取以创建有效的 Perspective 视图：
`ignition://docs/view-schema` 和 `ignition://templates/view/{flex-basic,coordinate-basic,tag-bound-dashboard}`。
## 构建 Perspective 视图
参见 [docs/perspective-authoring.md](docs/perspective-authoring.md) 以获取完整文档。简而言之：助手读取视图模式资源，从模板开始，在本地使用 `perspective_validate_view` 验证，然后使用 `perspective_upsert_view` 部署，后者再次验证，写入视图，并触发项目扫描。一个完整的往返示例在 [examples/deploy-dashboard.md](examples/deploy-dashboard.md) 中。
## 开发
```bash
git clone https://github.com/jsgorana/ignition-mcp
cd ignition-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ruff check src tests # 静态检查
ruff format --check src tests # 格式检查
mypy src # 类型检查
pytest tests/unit # 单元测试，无需网关
python bridge/build_zip.py # 重建桥接项目存档
# 实时集成套件（需要安装桥接的真实 8.3 网关）：
IGNITION_URL=... IGNITION_API_TOKEN=... IGNITION_BRIDGE_SECRET=... \
IGNITION_ALLOW_WRITES=true python tests/live/live_check.py
```
## 致谢
基于 [模型上下文协议](https://modelcontextprotocol.io) 及其 [Python SDK](https://github.com/modelcontextprotocol/python-sdk)，使用 [httpx](https://www.python-httpx.org/) 进行 HTTP 请求。[ignition-sdk-examples](https://github.com/inductiveautomation/ignition-sdk-examples) 仓库在理解 Ignition 的模块和脚本 API 如何协同工作方面非常有用。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
## 免责声明
本项目独立且由社区构建。它与 Inductive Automation 无关，也未获得 Inductive Automation 的认可或赞助。"Ignition" 和 "Perspective" 是 Inductive Automation, LLC 的商标，仅在此用于描述兼容性。在将任何启用写入的工具指向重要的内容之前，请先在非生产网关上进行测试。
