# RunningHub MCP

Локальный MCP-сервер со способом подключения STDIO для использования workflow RunningHub из Codex. Сервер предоставляет поиск моделей и цен, локальное создание и редактирование workflow, управление проектами и ассетами, выполнение задач, загрузку результатов и создание превью изображений и видео.

Сервер не содержит и не запускает модели генерации локально. Фактическая генерация изображений и видео выполняется через Workflow API RunningHub. Поэтому понадобятся аккаунт RunningHub, ключ Workflow API и совместимый workflow. Стоимость, доступность моделей, лимиты очереди и совместимость workflow определяются RunningHub.

## Возможности

- Поиск публичных моделей RunningHub, схем, цен и интеграционной документации.
- Локальное создание, импорт, редактирование, проверка и экспорт workflow в API-формате.
- Хранение локальных проектов, сцен, ассетов, рабочих элементов, ревизий workflow и планов выполнения в SQLite.
- Загрузка поддерживаемых медиафайлов и LoRA-ассетов, если это поддерживается настроенным API RunningHub.
- Однократная отправка подготовленного workflow, опрос статуса, отмена и восстановление неопределённой отправки без скрытого повторного платного запуска.
- Скачивание подтверждённых результатов изображений и видео в проект, автоматический inline-вывод изображений в текущий чат Codex и публикация результатов как MCP-ресурсов.
- Создание локальных PNG-превью изображений и постеров видео через FFmpeg.
- Фиксация явного решения пользователя перед продолжением или созданием ревизии.

Публичный каталог внутри проекта — это зафиксированный локальный snapshot. Он предназначен для поиска и валидации, но не подтверждает доступность конкретной модели или workflow в вашем аккаунте RunningHub.

## Требования

- Node.js `22.5.0` или новее. Сервер использует встроенный API Node.js `node:sqlite`.
- Аккаунт RunningHub и ключ Workflow API для облачной генерации.
- Codex Desktop, Codex CLI или расширение Codex для IDE.
- FFmpeg в `PATH` для локальных превью изображений и постеров видео. Для поиска и локальной работы с workflow FFmpeg не обязателен; если он не находится в `PATH`, укажите `RUNNINGHUB_FFMPEG_PATH`.

## Установка из GitHub

Этот вариант устанавливает исходный репозиторий. Он удобен, если вы хотите получать обновления и пересобирать сервер после изменений.

### Windows PowerShell

```powershell
git clone <YOUR-REPOSITORY-URL> runninghub-mcp
Set-Location .\runninghub-mcp
npm ci
npm run build
```

### macOS или Linux

```bash
git clone <YOUR-REPOSITORY-URL> runninghub-mcp
cd runninghub-mcp
npm ci
npm run build
```

`npm ci` устанавливает инструменты разработки, необходимые для компиляции TypeScript. Команда `npm run build` создаёт папку `dist/` — именно собранный JavaScript используется Codex.

## Установка готового пакета

В репозитории может находиться папка `rhcomfy-mcp/`. Она содержит только уже собранный сервер, необходимые файлы каталога и документацию по установке. На другом компьютере выполните:

```powershell
Set-Location C:\Path\To\rhcomfy-mcp
npm ci --omit=dev
```

Готовому пакету не нужны `npm run build`, TypeScript, тесты или исходный код. Запуск:

```powershell
npm start
```

В macOS и Linux используются те же команды с соответствующим путём. Не копируйте `node_modules` с компьютера разработки: установите зависимости на целевом компьютере командой `npm ci --omit=dev`.

На Windows установку зависимостей и проверку можно выполнить готовым скриптом из пакета:

```powershell
Set-Location C:\Path\To\rhcomfy-mcp
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
```

Скрипт проверяет Node.js, выполняет `npm ci --omit=dev` и запускает локальную проверку каталога и MCP-handshake. `-SkipDependencies` и `-SkipVerify` предназначены только для диагностики.

## Подключение к Codex

Codex подключается к этому серверу как к локальному MCP-серверу STDIO. Формат `config.toml`, параметры `command`, `args`, `cwd`, `env` и настройка через desktop app описаны в [официальной документации Codex MCP](https://developers.openai.com/codex/mcp).

В готовом пакете есть шаблон `codex-mcp.example.toml`: замените в нём путь к папке пакета и placeholder API-ключа, затем перенесите блок в `%USERPROFILE%\.codex\config.toml` или добавьте сервер через настройки Codex Desktop.

### Вариант A: Codex Desktop

1. Откройте **Settings → MCP servers**.
2. Нажмите **Add server**.
3. Выберите **STDIO**.
4. В поле команды укажите `node`.
5. В аргументы добавьте абсолютный путь к `dist/index.js`.
6. В качестве рабочей директории (`cwd`) укажите корень пакета; это позволяет серверу найти встроенный каталог по умолчанию.
7. Добавьте `RUNNINGHUB_WORKFLOW_API_KEY` как переменную окружения.
8. Сохраните сервер и перезапустите Codex.

### Вариант B: `config.toml`

Обычно Codex читает этот файл из `~/.codex/config.toml`. Используйте абсолютные пути. В примере для Windows применяются строковые литералы TOML, поэтому обратные слеши не нужно экранировать:

```toml
[mcp_servers.runninghub]
command = "node"
args = ['C:\Users\YOUR_NAME\Apps\runninghub-mcp\dist\index.js']
cwd = 'C:\Users\YOUR_NAME\Apps\runninghub-mcp'
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.runninghub.env]
RUNNINGHUB_WORKFLOW_API_KEY = "PASTE_YOUR_KEY_HERE"
RUNNINGHUB_CATALOG_DIR = 'C:\Users\YOUR_NAME\Apps\runninghub-mcp\data\upstream'
```

Для macOS или Linux:

```toml
[mcp_servers.runninghub]
command = "node"
args = ["/Users/your-name/Apps/runninghub-mcp/dist/index.js"]
cwd = "/Users/your-name/Apps/runninghub-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.runninghub.env]
RUNNINGHUB_WORKFLOW_API_KEY = "PASTE_YOUR_KEY_HERE"
RUNNINGHUB_CATALOG_DIR = "/Users/your-name/Apps/runninghub-mcp/data/upstream"
```

Храните API-ключ в секции переменных окружения или в защищённом хранилище операционной системы. Не вставляйте его в prompt, аргументы MCP-инструментов, JSON workflow, файлы проекта или команды shell, которые сохраняются в истории.

### Вариант C: Codex CLI

Официальная команда для добавления STDIO-сервера:

```bash
codex mcp add runninghub -- node /absolute/path/to/runninghub-mcp/dist/index.js
```

После добавления отредактируйте `~/.codex/config.toml` и добавьте `cwd` и секцию `[mcp_servers.runninghub.env]` из примера выше. Проверить список серверов можно командой:

```bash
codex mcp list
```

В Codex TUI команда `/mcp` показывает активные MCP-серверы. В desktop app после изменения конфигурации выполните перезапуск.

## Триггер `rh`

Сервер использует слово `rh` как понятный текстовый триггер для RunningHub-запросов. Например:

```text
rh найди подходящий workflow для генерации изображения кота в космосе. Ничего не запускай.
```

```text
rh подготовь workflow для короткого видео из этого изображения и остановись перед платной отправкой.
```

При таком запросе Codex должен выбрать инструменты RunningHub MCP, выполнить описанный в инструкции порядок и остановиться перед платной операцией, если пользователь явно не подтвердил запуск.

Важно: `rh` — это semantic trigger, а не команда операционной системы. Он не устанавливает и не запускает отключённый MCP-сервер сам по себе. MCP должен быть заранее добавлен в `config.toml` или через настройки Codex и оставаться включённым. Если сервер не подключён, Codex должен сообщить об этом, а не делать вид, что генерация доступна.

Само слово `rh` не является разрешением на генерацию и не подтверждает стоимость. Используйте его как префикс запроса, например `rh найди`, `rh проверь`, `rh подготовь` или `rh запусти после моего подтверждения`.

## Первая проверка после установки

Попросите Codex:

> Используй RunningHub MCP: вызови `rh_get_capabilities`, затем вызови `rh_search_models` с простым запросом для генерации изображения. Не запускай платную задачу.

При корректной установке Codex увидит инструменты RunningHub и получит данные каталога. `rh_get_capabilities` может показать статус облачного выполнения `configured_not_verified` или `unknown` — это нормально, пока конкретный аккаунт и workflow не были проверены.

## Генерация изображений и видео

Рекомендуемый порядок работы:

1. Зарегистрируйте локальную папку проекта или выберите уже созданный проект.
2. Импортируйте API-format workflow JSON либо создайте/отредактируйте workflow локально.
3. Создайте рабочий элемент с описанием нужного изображения или видео.
4. Проверьте workflow и подготовьте неизменяемый план генерации через `rh_prepare_generation`.
5. После проверки workflow и ожидаемой стоимости отправьте план через `rh_run_workflow`.
6. Отслеживайте задачу через `rh_job`.
7. Скачайте результаты через `rh_get_results`.
8. Зафиксируйте решение по результату через `rh_review_result`, прежде чем запрашивать продолжение или ревизию.

Примеры запросов к Codex:

```text
Используй RunningHub MCP, изучи доступные workflow для генерации изображений и скажи, какой из них подходит для этой задачи. Ничего не запускай.
```

```text
Импортируй API-format workflow JSON из <project-relative-path>, проверь его и подготовь план генерации изображения для этого проекта. Остановись перед отправкой и покажи выбранный workflow и ожидаемую стоимость.
```

```text
Используя уже проверенный план, отправь одну задачу RunningHub, дождись завершения, скачай подтверждённый результат и покажи локальные ресурсы результата. Если отправка станет неопределённой, не повторяй её автоматически.
```

Для видео укажите длительность, размеры и все входные медиафайлы, которые требуются выбранному workflow. Для изображения зарегистрируйте исходные изображения или маски внутри проекта, если workflow их использует. Перед загрузкой и отправкой сервер проверяет локальные роли медиафайлов и ограничения профиля.

## Конфигурация

| Переменная | Значение по умолчанию | Назначение |
| --- | --- | --- |
| `RUNNINGHUB_WORKFLOW_API_KEY` | не задана | Включает адаптер официального RunningHub Workflow API. Храните ключ в секрете. |
| `RUNNINGHUB_LIVE_CASES` | `full` | Профиль live harness; `full` используется по умолчанию и требуется для явных платных live-проверок. |
| `RUNNINGHUB_DATA_DIR` | `~/.runninghub` | Локальная SQLite-база и рабочее состояние. |
| `RUNNINGHUB_DB_PATH` | `<data dir>/runninghub.sqlite` | Явный путь к SQLite-базе. |
| `RUNNINGHUB_CATALOG_DIR` | `<cwd>/data/upstream` | Файлы зафиксированного каталога, входящие в пакет. |
| `RUNNINGHUB_PROJECT_ROOT` | не задана | Зарезервированная настройка корня проектов. |
| `RUNNINGHUB_FFMPEG_PATH` | `ffmpeg` | Исполняемый файл FFmpeg для превью и постеров видео. |

Сервер не содержит встроенных учётных данных. MCP-сообщения записываются только в stdout, диагностические сообщения — в stderr.

По умолчанию локальное состояние хранится вне установочной папки:

- Windows: `%USERPROFILE%\.runninghub`
- macOS/Linux: `~/.runninghub`

Сделайте резервную копию этой папки, если хотите сохранить локальные проекты, ревизии, задачи и историю review. Сгенерированные медиафайлы сохраняются в папке output зарегистрированного проекта.

## Что входит в установочный пакет

Минимальный готовый пакет содержит:

| Файл | Назначение |
| --- | --- |
| `dist/**/*.js` | Собранный runtime-код. |
| `data/upstream/model-registry.public.json` | Публичный каталог моделей. |
| `data/upstream/pricing.public.json` | Snapshot публичных цен. |
| `data/upstream/rh-api-contract.md` | Локальный API-контракт для каталоговых и интеграционных инструментов. |
| `data/upstream/llms.txt` | Публичные интеграционные инструкции. |
| `data/upstream/manifest.json` | Метаданные происхождения и ревизии каталога. |
| `package.json` | Runtime-зависимости, версия Node.js и команда запуска. |
| `package-lock.json` | Воспроизводимая установка runtime-зависимостей. |
| `README.md` | Инструкции по установке и подключению к Codex. |
| `install.ps1` | Windows-установка зависимостей и проверка пакета. |
| `verify-install.mjs` | Проверка файлов, каталога и STDIO MCP-handshake без обращения к RunningHub. |
| `codex-mcp.example.toml` | Безопасный шаблон блока `config.toml` с placeholder вместо ключа. |
| `package.ps1` | Создание переносимого ZIP без `node_modules`, секретов и локального состояния. |

Файлы `third_party/upstream/LICENSE` и `UPSTREAM.md` не читаются сервером при запуске, но их следует включать при распространении каталога, чтобы сохранить уведомление и информацию о происхождении данных.

В готовый runtime-пакет не нужно включать:

- `src/` и `tsconfig.json` — исходники TypeScript и конфигурация компилятора.
- `tests/`, `fixtures/` и `scripts/test-live.mjs` — тесты и интерактивные live-проверки для разработки.
- `docs/`, `PROGRESS.md`, `DECISIONS.md`, `ACCEPTANCE.md` и `RUNNINGHUB_MCP_IMPLEMENTATION_PLAN.md` — документацию процесса разработки.
- `node_modules/` — зависимости нужно устанавливать на целевом компьютере.
- `dist/**/*.d.ts` и `dist/**/*.js.map` — декларации типов и source maps, не требующиеся для запуска.
- Временное состояние: `.tmp/`, SQLite-файлы, сгенерированные медиафайлы, API-ключи и приватные данные проектов.

Отдельная папка `rhcomfy-mcp/` в этом репозитории предназначена именно для такого runtime-пакета, а не для второй копии исходного проекта. Файл `rhcomfy-mcp-runtime.zip`, создаваемый `package.ps1`, можно передать на другой компьютер.

## Обновление и сборка runtime-пакета

После изменений в `src/` выполните из корня репозитория:

```powershell
npm run package:runtime
powershell -NoProfile -ExecutionPolicy Bypass -File .\rhcomfy-mcp\package.ps1
```

Первая команда пересобирает проект и синхронизирует в `rhcomfy-mcp/` только актуальные `.js` и публичный каталог. Вторая создаёт `rhcomfy-mcp/rhcomfy-mcp-runtime.zip`; содержимое архива перечислено в таблице выше.

## Команды разработки

Эти команды нужны только при работе с исходным репозиторием:

```bash
npm ci
npm run typecheck
npm run build
npm run test:acceptance:offline
```

Live-harness намеренно не входит в обычную установку. Профиль `RUNNINGHUB_LIVE_CASES` по умолчанию — `full`, но проверки всё равно требуют API-ключ, явные аргументы и могут отправлять платные задачи. Запускайте их только после проверки workflow и понимания возможных расходов.

## Решение проблем

### Codex запускает сервер, но каталог не читается

Скорее всего, сервер запускается с неправильной рабочей директорией. Укажите `cwd` корня пакета и/или задайте `RUNNINGHUB_CATALOG_DIR` абсолютным путём к `data/upstream`.

Если сервер не запускается сразу после распаковки, из папки пакета выполните `npm ci --omit=dev`, затем `npm run verify`. На Windows при заблокированном PowerShell используйте `powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1`; политика меняется только для этого запуска.

### Облачные инструменты возвращают `CAPABILITY_UNKNOWN`

`RUNNINGHUB_WORKFLOW_API_KEY` отсутствует, пуст или недоступен процессу Codex. После изменения окружения перезапустите Codex. Ключ не принимается в качестве аргумента MCP-инструмента.

### Для результата не создаётся превью или постер

Установите FFmpeg и добавьте его в `PATH` либо задайте `RUNNINGHUB_FFMPEG_PATH` абсолютным путём к исполняемому файлу. Исходные результаты провайдера отделены от локальных производных файлов и могут обрабатываться независимо.

### Задача находится в состоянии `SUBMIT_UNKNOWN`

Не вызывайте `rh_run_workflow` повторно. Если RunningHub показывает исходный provider task ID за пределами MCP, выполните reconciliation через `rh_job` с действием `resume`, а затем дождитесь результата. Это предотвращает случайную повторную платную отправку.

### Workflow недоступен

Публичный каталог не является списком разрешений аккаунта. Проверьте workflow ID, модель, схему входных данных, роли медиафайлов и доступ аккаунта RunningHub.

## Безопасность и стоимость

- Считайте `RUNNINGHUB_WORKFLOW_API_KEY` паролем.
- Перед отправкой проверяйте JSON workflow, входные файлы, provider workflow ID и ожидаемую стоимость.
- Не вставляйте подписанные upload URL и приватные payload в prompt или систему контроля версий.
- Генерация, загрузка файлов и polling RunningHub — внешние операции. Локальная проверка и подготовка плана сами по себе не отправляют задачу провайдеру.
- Сервер не выполняет скрытый повтор неопределённой платной отправки.

## Лицензия и происхождение данных

Файлы публичного каталога сохраняют исходное происхождение и уведомление в `UPSTREAM.md` и `third_party/upstream/LICENSE`. Перед публикацией проекта добавьте отдельную лицензию, если хотите определить условия распространения исходного кода сервера.