Skip to main content
Glama
RunningHub MCP Server

RunningHub MCP Server

by tolatolatop
README.md
# 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
```

TDQS

A3.7/5.0

Scored across 8 tools

Disambiguation3/5

There is overlap between submit_task and run_task_and_wait (both submit tasks), and between query_task_outputs and run_task_and_wait (both check status/output). However, descriptions clarify the combination pattern in run_task_and_wait, so ambiguity is limited but still present.

Naming Consistency4/5

Most tools follow a consistent snake_case verb_noun pattern (e.g., get_node_info, submit_task). The exception is run_task_and_wait, which deviates with 'and_wait', and 'list_tasks' vs 'query_task_outputs' use different verbs for similar operations.

Tool Count5/5

8 tools is well-scoped for an AI task runner, covering submission, synchronization, file upload, and status queries without being excessive or minimal.

Completeness4/5

Core workflow (submit/run, query output, sync status, upload files) is covered. Missing tools for listing available applications or canceling tasks, but these are not critical for the primary use case.