# RunningHub MCP Server

基于 [FastMCP](https://gofastmcp.com/) 框架的 MCP 服务，为 [RunningHub](https://www.runninghub.cn/) AI 应用平台提供完整的工具集。

## 功能概览

- **节点查询** - 获取 AI 应用的可配置节点列表
- **文件上传** - 上传图片/音频/视频到 RunningHub 平台
- **任务提交** - 提交 AI 应用任务并获取 taskId
- **结果查询** - 查询任务执行状态和输出结果
- **一键执行** - 提交任务并自动轮询等待完成
- **任务管理** - 基于本地 JSON 文件的任务持久化管理

## 安装

```bash
# 使用 uv（推荐）
cd runninghub-mcp
uv sync

# 或使用 pip
pip install -e .
```

## 配置

通过环境变量配置服务：

| 环境变量 | 必需 | 默认值 | 说明 |
|---------|------|--------|------|
| `RUNNINGHUB_API_KEY` | 是 | - | RunningHub API 密钥 |
| `RUNNINGHUB_API_HOST` | 否 | `www.runninghub.cn` | API 主机地址 |
| `RUNNINGHUB_TASK_STORE_PATH` | 否 | `~/.runninghub/tasks.json` | 任务持久化文件路径 |

### MCP 客户端配置示例

**Cursor / Claude Desktop (`mcp.json`)**

```json
{
  "mcpServers": {
    "runninghub": {
      "command": "uv",
      "args": ["--directory", "/path/to/runninghub-mcp", "run", "runninghub-mcp"],
      "env": {
        "RUNNINGHUB_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Tool 列表

### 原子工具（API 端点）

| Tool | 说明 | 关键参数 |
|------|------|---------|
| `get_node_info` | 获取 AI 应用的可配置节点列表 | `webapp_id` |
| `upload_file` | 上传文件到 RunningHub | `file_path` |
| `submit_task` | 提交 AI 应用任务 | `webapp_id`, `node_info_list` |
| `query_task_outputs` | 查询任务状态和输出结果 | `task_id` |

### 完整流程工具

| Tool | 说明 |
|------|------|
| `run_task_and_wait` | 提交任务并轮询等待完成，支持自定义超时和轮询间隔 |

### 持久化管理工具

| Tool | 说明 | 关键参数 |
|------|------|---------|
| `list_tasks` | 查询本地存储的任务列表 | `status`(可选), `limit` |
| `get_task_detail` | 获取指定任务的详细信息 | `task_id` |
| `sync_task_status` | 从 API 同步任务最新状态到本地 | `task_id` |

## 使用流程

典型的使用流程如下：

1. 调用 `get_node_info` 获取 AI 应用的节点列表
2. 根据需要修改节点参数（如需上传文件，先调用 `upload_file`）
3. 调用 `run_task_and_wait` 提交任务并等待结果（或分步使用 `submit_task` + `query_task_outputs`）
4. 使用 `list_tasks` / `get_task_detail` 查看历史任务

## 项目结构

```
src/runninghub_mcp/
  __init__.py     # 包入口
  server.py       # FastMCP 服务实例 + Tool 定义 + 入口
  api.py          # RunningHub HTTP API 封装
  storage.py      # 任务持久化管理（JSON 文件）
  models.py       # 数据模型定义
```

## 开发

```bash
# 安装开发依赖
uv sync

# 直接运行服务（STDIO 模式）
RUNNINGHUB_API_KEY=your-key uv run runninghub-mcp

# 使用 fastmcp dev 调试
RUNNINGHUB_API_KEY=your-key uv run fastmcp dev src/runninghub_mcp/server.py
```