# Astro Flow MCP

Astro Flow 的 stdio MCP 桥接服务。它只通过 HTTP 调用 Astro Flow 扩展，不加载节点适配器，也不在 MCP 进程中运行 Siril。扩展负责工作流校验、幂等请求和执行。

**状态：** 独立源码仓库，版本 `0.1.0`；已实现 7 个 MCP 工具及 HTTP 客户端。源码位于 [GitHub](https://github.com/MaojieXu/astro-flow-mcp)，可在本地构建分发包；尚未发布到包索引，也没有自动发布流程。实际运行需另行启动 [ComfyUI Astro Flow 扩展](https://github.com/MaojieXu/comfyui-astro-flow) 提供的 `/astro-flow/v1` 接口。

## 安装与启动

需要 Python 3.10 或更新版本。开发安装示例：

```bash
uv venv --python python3.10 .venv
uv pip install --python .venv/bin/python -e '.[dev]'
ASTRO_FLOW_URL=http://127.0.0.1:8188 .venv/bin/astro-flow-mcp
```

命令使用 stdio 传输；stdout 专供 MCP 协议。MCP 客户端配置示例（将路径替换为本机绝对路径）：

```json
{
  "mcpServers": {
    "astro-flow": {
      "command": "/absolute/path/to/astro-flow-mcp/.venv/bin/astro-flow-mcp",
      "env": {
        "ASTRO_FLOW_URL": "http://127.0.0.1:8188"
      }
    }
  }
}
```

`ASTRO_FLOW_URL` 默认是 `http://127.0.0.1:8188`。设置 `ASTRO_FLOW_TOKEN` 后，所有 HTTP 请求会带上 `Authorization: Bearer <token>`；是否允许无 token 的本机请求由扩展决定。请求超时为 30 秒，客户端不会自动重试编辑或提交。编辑或提交发生传输超时时，请先读取画布或运行状态；若要重试同一次请求，必须保留相同的 `request_id` 和请求体。扩展不可达时，工具返回明确错误。

## 工具

| MCP 工具 | HTTP 请求 | 用途 |
| --- | --- | --- |
| `search_capabilities(query="")` | `GET /astro-flow/v1/capabilities?query=...` | 搜索可用节点能力 |
| `describe_capability(capability_id)` | `GET /astro-flow/v1/capabilities/{capability_id}` | 查看参数与连接说明 |
| `list_canvases()` | `GET /astro-flow/v1/canvases` | 列出打开的画布 |
| `get_workflow(canvas_id)` | `GET /astro-flow/v1/canvases/{canvas_id}` | 读取节点、连线和修订号 |
| `edit_workflow(canvas_id, request_id, expected_revision, operations)` | `POST /astro-flow/v1/canvases/{canvas_id}/edit` | 按修订号编辑 |
| `submit_workflow(canvas_id, request_id, expected_revision)` | `POST /astro-flow/v1/canvases/{canvas_id}/run` | 提交执行 |
| `get_run(run_id)` | `GET /astro-flow/v1/runs/{run_id}` | 读取状态、产物和错误 |

当前扩展每次编辑只接受**一个**操作。操作类型限于 `add_node`、`remove_node`、`set_parameter`、`connect`、`disconnect`，目前只支持 `AstroSirilMetadata` 节点。`add_node` 要求 `node_type="AstroSirilMetadata"` 和 `parameters`（含 `input_path` 字符串及 `timeout` 数字），可选 `position: [x,y]`。`set_parameter` 使用 `node_id`、`name`、`value`；`remove_node` 使用 `node_id`；`connect` 使用 `source_node`、`source_slot`、`target_node`、`target_slot`；`disconnect` 使用 `target_node`、`target_slot`。扩展负责校验这些字段。运行时当前只支持含一个 metadata 输出节点的工作流。

调用前先通过能力工具了解可用节点，再读取画布以取得当前 `revision`。每个预期变更使用新的 `request_id`；重送同一次变更时保留原 ID 和相同请求体。遇到修订冲突，重新读取画布再决定后续编辑。

例如，读取 `c1` 得到 `revision="r1"` 后，可向 `edit_workflow` 传入：

```json
{
  "canvas_id": "c1",
  "request_id": "9c82dcf9-2e5f-43a6-aa7a-e44e748851b5",
  "expected_revision": "r1",
  "operations": [
    {"type": "set_parameter", "node_id": "node-1", "name": "input_path", "value": "/data/light.fit"}
  ]
}
```

上例节点 ID 仅供展示；请以 `get_workflow` 的实际节点为准。成功时工具直接返回扩展的 JSON 对象。`get_run` 当前返回产物文件路径，不返回输出 JSON 文件正文；需要内容时由调用方另行读取该文件。扩展错误 `{ "error": { "code": "...", "message": "..." } }` 会成为 MCP 工具错误，并带 HTTP 状态码。若浏览器端超时返回 `canvas_timeout`，编辑可能已应用；先重新读取画布，再决定是否继续。

## 验证与构建

```bash
.venv/bin/python -m pytest -q
.venv/bin/python -m build --no-isolation
```

测试覆盖 HTTP 路径、请求体、Bearer token、错误、无自动重试，以及真实 stdio MCP 握手/工具发现/调用。上面的本地构建命令使用已安装构建依赖的虚拟环境并加 `--no-isolation`。CI 在 push 和 pull request 时测试、构建；手动触发 `workflow_dispatch` 时保存构建产物。发布到包索引需要人工决定与执行，CI 不会自动上传。

更多实现状态见 [docs/STATUS.md](docs/STATUS.md)。