Metadata-Version: 2.4
Name: jxy-rpa-workflow-mcp-server
Version: 0.1.3
Summary: MCP server for JXY RPA workflow actions
Requires-Python: >=3.12
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: python-socks[asyncio]>=2.0.0
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# jxy-rpa-workflow-mcp-server

JXY RPA 工作流 MCP 服务，提供 RPA 指令查询功能。

## 安装

```bash
cd jxy-rpa-workflow-mcp-server
uv sync
```

## 运行

### STDIO 模式（默认）

```bash
uv run jxy-rpa-workflow-mcp-server
```

### SSE 模式

```bash
uv run jxy-rpa-workflow-mcp-server --transport sse --host 0.0.0.0 --port 9123
```

SSE 模式启动后，MCP 端点地址为 `http://0.0.0.0:9123/sse`。

### Streamable HTTP 模式

```bash
uv run jxy-rpa-workflow-mcp-server --transport streamable-http --host 0.0.0.0 --port 9123
```

Streamable HTTP 模式启动后，MCP 端点地址为 `http://0.0.0.0:9123/mcp`。

## 可用工具

### instruction

RPA 指令查询工具。

参数：

- `action`: 操作类型
  - `list`: 获取指令列表（需要 `keyword` 过滤，支持 `limit` 限制），返回标准指令和扩展指令
  - `types`: 查询 RPA 复合类型（可选 `location` 指定类型名，不传返回全量）
- `keyword`: 关键字过滤（匹配 name、desc 或 location），`list` 时必填
- `limit`: 返回数量上限，默认 50，仅 `list` 时有效
- `location`: 仅 `types` 时可选，指定类型名

### project

项目操作工具。

参数：

- `action`: 操作类型
  - `info`: 获取当前打开项目的信息
  - `create`: 创建新项目（需要 `app_name` 和 `app_path`，可选 `description`）
  - `update`: 更新项目信息（需要 `updates`）
- `app_name`: 项目名称（仅 `create` 时使用）
- `app_path`: 项目路径（仅 `create` 时使用）
- `description`: 项目描述（仅 `create` 时可选）
- `updates`: 要更新的字段（仅 `update` 时使用）

### workflow

工作流管理工具。

参数：

- `action`: 操作类型
  - `list`: 获取所有工作流列表
  - `create`: 创建新工作流（可选 `filename`，不传则自动生成）
  - `delete`: 删除工作流（需要 `seq_tag`）
  - `info`: 获取工作流详情（需要 `seq_tag`）
  - `update`: 更新工作流（需要 `flow`，包含 Seq、nodes、edges）
  - `open`: 打开指定流程（需要 `seq_tag`）
- `seq_tag`: 流程的 SeqTag 标识
- `filename`: 工作流文件名（仅 `create` 时使用，仅允许字母和数字）
- `flow`: 流程对象（仅 `update` 时使用），包含 Seq、nodes、edges

### workflow_node

工作流节点操作工具。

参数：

- `action`: 操作类型
  - `add`: 添加节点（需要 `location`）
  - `update`: 更新节点（需要 `node_id` 和 `updates`）
  - `delete`: 删除节点（需要 `node_id`）
  - `info`: 获取节点详情（需要 `node_id`）
  - `enable`: 启用/禁用节点（需要 `node_id` 或 `node_ids`，以及 `enabled`）
  - `available_vars`: 查询节点可访问的变量（需要 `node_id`）
- `seq_tag`: 流程的 SeqTag 标识
- `node_id`: 节点 ID
- `node_ids`: 多个节点 ID（仅 `enable` 时可用，与 `node_id` 二选一）
- `location`: 指令的唯一标识（仅 `add` 时使用），通过 `instruction(action='list')` 获取
- `updates`: 要更新的字段（仅 `update` 时使用），可包含 `data` (dict) 和 `position` (dict {x, y})
- `enabled`: 是否启用（仅 `enable` 时使用）
- `items`: 批量操作数组。每项可包含 `action`, `seq_tag`, `node_id`, `node_ids`, `location`, `updates`, `enabled`；
  未提供的字段会继承外层同名参数。批量执行时每项之间间隔 50ms，返回 `{"results": [...]}`。

批量示例：

```python
workflow_node(
    action="delete",
    seq_tag="flow-1",
    items=[
        {"node_id": "node-1"},
        {"node_id": "node-2"},
    ],
)
```

### workflow_edge

工作流连线操作工具。

参数：

- `action`: 操作类型
  - `add`: 添加连线（需要 `seq_tag`, `source`, `target`, `source_handle`, `target_handle`）
  - `delete`: 删除连线（需要 `seq_tag`, `edge_id`）
  - `info`: 获取连线详情（需要 `seq_tag`, `edge_id`）
- `seq_tag`: 流程的 SeqTag 标识
- `edge_id`: 连线 ID
- `source`: 源节点 ID（仅 `add` 时使用）
- `target`: 目标节点 ID（仅 `add` 时使用）
- `source_handle`: 源节点句柄（仅 `add` 时使用）
- `target_handle`: 目标节点句柄（仅 `add` 时使用）
- `items`: 批量操作数组。每项可包含 `action`, `seq_tag`, `edge_id`, `source`, `target`, `source_handle`,
  `target_handle`；未提供的字段会继承外层同名参数。批量执行时每项之间间隔 50ms，返回 `{"results": [...]}`。

批量示例：

```python
workflow_edge(
    action="add",
    seq_tag="flow-1",
    items=[
        {"source": "node-1", "target": "node-2", "source_handle": "source", "target_handle": "target"},
        {"source": "node-2", "target": "node-3", "source_handle": "source", "target_handle": "target"},
    ],
)
```

### main_process_var

主流程参数操作工具。

参数：

- `action`: 操作类型
  - `list`: 获取所有主流程参数列表
  - `info`: 获取指定参数详情（需要 `vartag`）
  - `add`: 添加参数（可选 `var_direction`, `var_name`, `data_type`, `var_desc`, `input_props`）
  - `update`: 更新参数（需要 `vartag` 和 `updates`）
  - `delete`: 删除参数（需要 `vartag`）
- `vartag`: 参数的唯一标识
- `var_direction`: 参数方向，`input` 或 `output`，默认 `input`（仅 `add` 时使用）
- `var_name`: 参数名称（可选，不提供则自动生成）
- `data_type`: 数据类型（可选），枚举值: `str`, `number`, `bool`, `list`, `date`, `datetime`, `time`, `daterange`, `month`, `monthrange`, `FilePath`, `DirectoryPath`, `account`
- `var_desc`: 参数描述（可选）
- `input_props`: 组件属性（可选），如 `{"placeholder": "请输入", "required": false, "uiComponent": "input"}`
- `updates`: 要更新的字段（仅 `update` 时使用），可包含 `varname`, `dataType`, `vardesc`

### sub_process_var

子流程参数操作工具。

参数：

- `action`: 操作类型
  - `list`: 获取子流程所有参数列表（需要 `seq_tag`）
  - `info`: 获取指定参数详情（需要 `vartag`）
  - `add`: 添加参数（需要 `seq_tag`，可选 `var_direction`, `var_name`, `data_type`, `var_desc`）
  - `update`: 更新参数（需要 `vartag` 和 `updates`）
  - `delete`: 删除参数（需要 `vartag`）。注意：会同步删除所有引用该子流程的 Subflow 节点中的参数配置
- `seq_tag`: 子流程的 SeqTag 标识
- `vartag`: 参数的唯一标识
- `var_direction`: 参数方向，`input` 或 `output`，默认 `input`（仅 `add` 时使用）
- `var_name`: 参数名称（可选，不提供则自动生成）
- `data_type`: 数据类型（可选），枚举值: `str`, `number`, `bool`, `list`, `date`, `datetime`, `time`, `daterange`, `month`, `monthrange`, `FilePath`, `DirectoryPath`, `account`, `any`
- `var_desc`: 参数描述（可选）
- `updates`: 要更新的字段（仅 `update` 时使用），可包含 `varname`, `dataType`, `vardesc`, `vardirection`

### global_var

全局变量操作工具。

参数：

- `action`: 操作类型
  - `list`: 获取所有全局变量列表
  - `info`: 获取指定变量详情（需要 `vartag`）
  - `add`: 添加变量（可选 `var_name`, `data_type`, `var_desc`, `input_props`）
  - `update`: 更新变量（需要 `vartag` 和 `updates`）
  - `delete`: 删除变量（需要 `vartag`）
- `vartag`: 变量的唯一标识
- `var_name`: 变量名称（可选，仅允许字母和数字，不提供则自动生成）
- `data_type`: 数据类型（可选），枚举值: `str`, `number`, `bool`, `list`, `date`, `datetime`, `time`, `daterange`, `month`, `monthrange`, `FilePath`, `DirectoryPath`, `account`, `any`
- `var_desc`: 变量描述（可选）
- `input_props`: 组件属性（可选），如 `{"placeholder": "请输入", "required": false, "uiComponent": "input"}`
- `updates`: 要更新的字段（仅 `update` 时使用），可包含 `varname`, `dataType`, `vardesc`, `inputProps`

### get_parameter_rules

获取工作流参数编辑规则文档。返回主流程参数和子流程参数的详细编辑规则说明（Markdown 格式）。在使用参数相关工具前，建议先调用此工具了解参数规则。

### element

元素操作工具。

参数：

- `action`: 操作类型
  - `list`: 获取元素列表
  - `info`: 获取指定元素详情（需要 `element_id`）
  - `add`: 添加元素（需要 `element_info`）
  - `update`: 更新元素（需要 `element_id` 和 `updates`）
  - `delete`: 删除元素（需要 `element_id`）
- `element_id`: 元素 ID
- `element_info`: 元素信息（仅 `add` 时使用）
- `updates`: 要更新的字段（仅 `update` 时使用）

`add` 返回包含 `elementId` (uuid) 字段的字典。

### run

运行相关操作工具（同步等待模式，运行指令会等待任务完成后返回结果）。

参数：

- `action`: 操作类型
  - `project`: 运行项目（可选 `runtime_args`, `main_flow_seq_tag`）
  - `flow`: 运行指定流程（需要 `seq_tag`，可选 `runtime_args`）
  - `node`: 运行单个节点（需要 `seq_tag` 和 `node_id`）
  - `node_from`: 从指定节点开始运行（需要 `seq_tag` 和 `node_id`）
  - `stop`: 停止当前运行
  - `status`: 查询运行状态
  - `log`: 获取运行日志
  - `compile`: 编译项目（可选 `main_flow_seq_tag`）
  - `checklist`: 获取检查清单（可选 `seq_tag`，不传则检查所有流程）
- `seq_tag`: 流程的 SeqTag 标识
- `node_id`: 节点 ID（仅 `node`/`node_from` 时使用）
- `runtime_args`: 运行时参数（仅 `project`/`flow` 时可选）
- `main_flow_seq_tag`: 指定主流程（仅 `project`/`compile` 时可选）

## MCP 配置示例

### 本地启动模式（由客户端启动进程）

#### STDIO 模式

```json
{
  "mcpServers": {
    "jxy-rpa-workflow": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/jxy-rpa-workflow-mcp-server",
        "jxy-rpa-workflow-mcp-server"
      ]
    }
  }
}
```

#### Streamable HTTP 模式

```json
{
  "mcpServers": {
    "jxy-rpa-workflow": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/jxy-rpa-workflow-mcp-server",
        "jxy-rpa-workflow-mcp-server",
        "--transport",
        "streamable-http",
        "--host",
        "0.0.0.0",
        "--port",
        "9123"
      ]
    }
  }
}
```

#### SSE 模式

```json
{
  "mcpServers": {
    "jxy-rpa-workflow": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/jxy-rpa-workflow-mcp-server",
        "jxy-rpa-workflow-mcp-server",
        "--transport",
        "sse",
        "--host",
        "0.0.0.0",
        "--port",
        "9123"
      ]
    }
  }
}
```

### 远程连接模式（连接已运行的服务）

适用于服务已独立启动的场景，直接通过 URL 连接。

#### Streamable HTTP

```json
{
  "mcpServers": {
    "jxy-rpa-workflow": {
      "url": "http://localhost:9123/mcp"
    }
  }
}
```

#### SSE

```json
{
  "mcpServers": {
    "jxy-rpa-workflow": {
      "url": "http://localhost:9123/sse"
    }
  }
}
```
