feat: add Runware MCP CLI tool and comprehensive example scripts for multi-modal generation

Author: GeekLord

.kiro/steering/openclaw_runware.md

@@ -2,38 +2,38 @@
 inclusion: always
 ---
 
-# OpenClaw Runware Skill
+# OpenClaw Runware skill
 
-Multi-modal Runware.ai skill for OpenClaw: image, video, audio, text, and 3D generation through the official `runware-sdk`, plus MCP-style tooling. Python 3.11+.
+Multi-modal Runware.ai skill for OpenClaw: image, video, audio, text, and 3D generation through the official `runware-sdk` library and MCP tooling. Requires Python 3.11+.
 
 ## Architecture
 
-- `scripts/generate.py` — main CLI generator. Builds a task payload from `--mode` (`image`/`video`/`audio`/`text`/`3d`), sends it via the async `Runware` client, saves each result to disk.
-- `scripts/runware_mcp.py` — MCP-style CLI exposing discrete tools (`run`, `list-models`, `model-pricing`, `model-details`, `account`) mirroring the hosted Runware MCP server's tool set.
-- `skill-config.json` — non-secret defaults (`default_size`, `default_format`, `default_output_dir`); `last_output_dir` is auto-updated by `generate.py` after a save.
-- `RUNWARE_API_KEY` comes from `.env` (see `.env_sample`) or the environment — never from `skill-config.json`.
-- Both scripts open the SDK client per call as an async context manager: `async with Runware(api_key=..., transport="rest") as client:`. Don't hold a client open across multiple requests.
-- This is v2: generation always goes through `runware-sdk`'s `Runware` client. Don't reintroduce raw `requests.post` calls to the old REST API or resurrect `generate_image.py`.
+- `scripts/generate.py`: Main CLI generator. Builds task payloads from `--mode` (`image`, `video`, `audio`, `text`, `3d`), submits requests via an asynchronous `Runware` client session, and saves outputs to disk.
+- `scripts/runware_mcp.py`: MCP CLI exposing discrete tools (`run`, `list-models`, `model-pricing`, `model-details`, `account`) matching the hosted Runware MCP server tool catalog.
+- `skill-config.json`: Non-sensitive configuration defaults (`default_size`, `default_format`, `default_output_dir`). The `last_output_dir` property is updated automatically by `generate.py` after writing an output file.
+- `RUNWARE_API_KEY`: Sourced from `.env` (see `.env_sample`) or system environment variables. Never stored in `skill-config.json`.
+- SDK sessions: Both scripts initialize `Runware` as an asynchronous context manager (`async with Runware(api_key=..., transport="rest") as client:`). Do not share or persist client connections across separate runs.
+- Generation engine: Generation routes through `runware-sdk`. Avoid raw REST requests or legacy standalone image scripts.
 
 ## Conventions
 
-- Target Python 3.11+; use PEP 604 unions (`str | None`), not `Optional[str]`.
-- Import the SDK lazily/defensively (`_import_runware()`), printing a `pip install runware-sdk` hint and `sys.exit(1)` on `ImportError` instead of letting it raise.
-- Module-private helpers are prefixed with `_` (`_parse_size`, `_slugify`, `_resolve_outpath`, etc.) and are the pytest-covered unit surface — keep new helpers named and tested the same way.
-- CLI parsing uses `argparse`. When a change applies to both entry points, update `generate.py` and `runware_mcp.py` together.
-- Modes are driven by lookup tables (`SUPPORTED_MODES`, `MODES_TO_TASKTYPE`, `MODES_TO_EXT`, `_default_model()`). Adding a modality means extending all of them, per `CONTRIBUTING.md`.
-- Catch `RunwareError` (has `.code`) before a generic `Exception` fallback; report failures to `stderr` and exit non-zero rather than letting a traceback surface to the CLI user.
-- Settings precedence is CLI flag > `skill-config.json` value > hardcoded default — preserve this order when adding new configurable options.
+- Python runtime: Python 3.11+. Use PEP 604 union syntax (`str | None`) rather than `Optional[str]`.
+- Dependency checks: Import the SDK with `_import_runware()`, logging a `pip install runware-sdk` hint and exiting with code 1 when the package is missing.
+- Private helpers: Prefix internal utilities with `_` (`_parse_size`, `_slugify`, `_resolve_outpath`, etc.) and maintain unit test coverage in `tests/`.
+- CLI arguments: Use `argparse`. Keep flags and options consistent across `generate.py` and `runware_mcp.py`.
+- Modality mapping: Modalities are defined in `SUPPORTED_MODES`, `MODES_TO_TASKTYPE`, `MODES_TO_EXT`, and `_default_model()`. Adding a modality requires updating all mappings and test cases.
+- Error handling: Catch `RunwareError` before general `Exception` handlers. Write error details to `sys.stderr` and exit with a non-zero code.
+- Configuration precedence: Command-line arguments override `skill-config.json` values, which override module defaults.
 
-## Safety & secrets
+## Safety and secrets
 
-- Never log, print, or persist `RUNWARE_API_KEY` or any credential.
-- `skill-config.json` is committed — keep it secret-free.
-- Keep `_validate_prompt()`'s minor-safety check intact when touching prompt handling; it must hard-block (exit non-zero), not just warn, despite the "WARNING" text in its message.
-- Don't remove `.env` from `.gitignore`; use placeholders (e.g. `your_key_here`) in examples and docs, never real keys.
+- Do not log, print, or persist API credentials.
+- Keep `skill-config.json` free of credentials.
+- Retain prompt validation in `_validate_prompt()` to block requests referencing minors.
+- Ensure `.env` is ignored by git. Use placeholder strings in example commands.
 
-## Testing & docs
+## Testing and documentation
 
-- Unit tests live in `tests/test_generate.py`, one `Test*` class per function under test. Run with `pytest -q`.
-- The integration test skips automatically without `RUNWARE_API_KEY` (`skipif`); CI (`.github/workflows/ci.yml`) runs Python 3.11–3.13 with `pytest -q -m "not integration"`.
-- `README.md` and `SKILL.md` both carry CLI flag tables and quick-start snippets — update both when CLI behavior changes, and add matching usage examples to `examples/README.md`.
+- Unit tests reside in `tests/test_generate.py` and `tests/test_runware_mcp.py`. Run tests using `pytest -q -m "not integration"`.
+- Live integration tests require `RUNWARE_API_KEY` and are marked with `integration`.
+- Maintain CLI reference tables and quick start examples in both `README.md` and `SKILL.md` when command options change.

CONTRIBUTING.md

@@ -1,31 +1,31 @@
 # Contributing to runware-mcp
 
-Thank you for your interest in improving this skill!
+Thank you for helping improve this project.
 
-## Getting Started
+## Getting started
 
-1. Fork the repository and submit a pull request against `main`.
-2. Install development dependencies: `pip install -r requirements.txt`
-3. Run tests: `pytest -q`
-4. For integration tests, set `RUNWARE_API_KEY` in your environment.
+1. Fork the repository and open a pull request against `main`.
+2. Install development packages: `pip install -r requirements.txt`
+3. Run the test suite: `pytest -q -m "not integration"`
+4. To run live integration tests, set `RUNWARE_API_KEY` in your environment.
 
 ## Guidelines
 
-- **Keep changes focused** — open separate PRs for separate features
-- **Include tests** — add unit tests for new behaviors, update existing tests when behavior changes
-- **Update docs** — if you add a feature, update `SKILL.md`, `README.md`, and examples as appropriate
-- **Use clear commit messages** — reference issue numbers where applicable
-- **Minimal dependencies** — avoid adding new packages unless necessary
+- Keep pull requests focused on a single change or feature.
+- Include unit tests for bug fixes or new functionality.
+- Update `SKILL.md`, `README.md`, and `examples/README.md` when changing CLI arguments or default settings.
+- Write clear commit messages.
+- Keep external dependencies minimal.
 
-## Adding a New Mode
+## Adding a new mode
 
-To add a new generation mode (e.g., a new modality):
+When adding a new generation modality:
 
-1. Add the mode to `SUPPORTED_MODES`, `MODES_TO_TASKTYPE`, `MODES_TO_EXT`, and `_default_model()` in `scripts/generate.py`
-2. Add the corresponding `--mode` choice in `scripts/runware_mcp.py`
-3. Update tests accordingly
-4. Add example commands to `examples/README.md`
+1. Update `SUPPORTED_MODES`, `MODES_TO_TASKTYPE`, `MODES_TO_EXT`, and `_default_model()` in `scripts/generate.py`.
+2. Update the `--mode` choices in `scripts/runware_mcp.py`.
+3. Add corresponding tests in `tests/test_generate.py` and `tests/test_runware_mcp.py`.
+4. Add example commands in `examples/README.md`.
 
-## Reporting Issues
+## Reporting issues
 
-Open issues for bugs, feature requests, or documentation corrections. Include steps to reproduce and minimal examples when possible.
+Open an issue for bugs, documentation errors, or feature suggestions. Please include steps to reproduce unexpected behavior and sample inputs when possible.

README.md

@@ -4,22 +4,22 @@
 [![Repository](https://img.shields.io/badge/Repository-OpenClaw__Runware__API-blue?style=flat&logo=github)](https://github.com/GeekLord/OpenClaw_Runware_API)
 [![Python](https://img.shields.io/badge/Python-3.11%2B-blue?style=flat&logo=python)](https://www.python.org/)
 
-**Multi-modal Runware.ai skill** — image, video, audio, text, and 3D generation via the official `runware-sdk` Python library, plus MCP-style tooling.
+OpenClaw skill for media generation with the official Runware Python SDK (`runware-sdk`) and Model Context Protocol (MCP) tooling. Supports image, video, audio, text, and 3D generation.
 
-This repository contains an OpenClaw-compatible skill that connects to [Runware.ai's MCP server](https://runware.ai/mcp) and exposes a clean Python CLI for generating media, browsing models, checking pricing, and managing your account.
+This repository connects to the [Runware MCP server](https://runware.ai/mcp) and provides a Python CLI to generate media, browse models, check pricing, and check account balances.
 
-## Features
+## Capabilities
 
-- **Multi-modal** — Generate images, videos, audio, text, and 3D models
-- **Official SDK** — Uses `runware-sdk` (async, typed, JSON-Schema validated)
-- **MCP integration** — MCP-style tools (`run`, `list-models`, `model-pricing`, `model-details`, `account`)
-- **Hosted MCP server** — Can connect directly to `https://mcp.runware.ai` (OAuth 2.1, no local install needed)
-- **Sync + async** — Sync delivery for fast tasks, async polling for long-running ones
-- **Safe-by-default** — Lightweight prompt filtering
-- **Configurable** — Default model, size, format via `skill-config.json`
-- **Tested** — Pytest unit tests + optional integration tests
+- Image, video, audio, text, and 3D generation
+- Direct integration with `runware-sdk` (async and schema validated)
+- MCP tool wrappers for `run`, `list-models`, `model-pricing`, `model-details`, and `account`
+- Connection options for hosted MCP (`https://mcp.runware.ai`), local npm package (`@runware/mcp`), or local Python scripts
+- Synchronous delivery for fast requests and asynchronous polling for long tasks
+- Prompt guard for minor safety
+- Configurable defaults in `skill-config.json`
+- Unit test suite with pytest
 
-## Quick Start
+## Quick start
 
 ```bash
 # Install dependencies
@@ -34,18 +34,18 @@ python scripts/generate.py --prompt "A serene mountain landscape" --mode image -
 # Generate a video
 python scripts/generate.py --prompt "Waves crashing on a beach" --mode video --duration 8 --outfile waves.mp4
 
-# Browse models via MCP-style CLI
+# Browse models via MCP CLI
 python scripts/runware_mcp.py list-models --category image --search "flux"
 
 # Check account balance
 python scripts/runware_mcp.py account
 ```
 
-## MCP Server Connection
+## MCP server connection
 
-### 1. Hosted (easiest — no install)
+### 1. Hosted server
 
-Any MCP-compatible client can connect to Runware's hosted server:
+Any MCP-compatible client can connect directly to Runware's hosted endpoint:
 
 ```json
 {
@@ -55,9 +55,9 @@ Any MCP-compatible client can connect to Runware's hosted server:
 }
 ```
 
-Authentication is handled via OAuth 2.1 — your API key stays server-side, encrypted in the OAuth session.
+Authentication uses OAuth 2.1, keeping the API key inside the session.
 
-### 2. Local (self-hosted)
+### 2. Local Node package
 
 ```json
 {
@@ -71,7 +71,7 @@ Authentication is handled via OAuth 2.1 — your API key stays server-side, encr
 }
 ```
 
-### 3. Python (this skill)
+### 3. Local Python script
 
 ```json
 {
@@ -88,61 +88,68 @@ Authentication is handled via OAuth 2.1 — your API key stays server-side, encr
 
 | File | Purpose |
 |------|---------|
-| `scripts/generate.py` | Main multi-modal generator |
-| `scripts/runware_mcp.py` | MCP-style CLI tool interface |
-| `skill-config.json` | Default settings (no secrets) |
-| `SKILL.md` | OpenClaw skill metadata & usage |
-| `tests/test_generate.py` | Pytest tests |
-| `examples/` | Example commands |
+| `scripts/generate.py` | CLI generator for all supported modalities |
+| `scripts/runware_mcp.py` | MCP CLI tool interface |
+| `skill-config.json` | Default settings (non-sensitive) |
+| `SKILL.md` | Skill definition and integration docs |
+| `tests/test_generate.py` | Unit and integration tests for generation |
+| `tests/test_runware_mcp.py` | Unit tests for MCP CLI interface |
+| `examples/` | Sample commands for each modality |
 
 ## Configuration
 
-`skill-config.json` fields:
+Default settings live in `skill-config.json`:
 
-- `default_size` — default image size (e.g. `"1024x1024"`)
-- `default_format` — output format (`png`/`jpg`/`webp`/`mp4`/`wav`/`glb`)
-- `default_output_dir` — default output directory
-- `last_output_dir` — auto-updated by the script
+- `default_size`: default image dimensions (e.g. `"1024x1024"`)
+- `default_format`: default output format (`png`, `jpg`, `mp4`, `wav`, `glb`)
+- `default_output_dir`: default save location
+- `last_output_dir`: automatically updated by the script after each save
 
-## CLI Reference
+## CLI reference
 
 ### `scripts/generate.py`
 
 | Flag | Description |
 |------|-------------|
-| `--prompt` | Text prompt |
-| `--mode` | `image`, `video`, `audio`, `text`, or `3d` |
-| `--model` | Runware model ID (e.g. `runware:400@1`) |
+| `--prompt` | Text prompt for generation |
+| `--mode` | Generation mode: `image`, `video`, `audio`, `text`, or `3d` |
+| `--model` | Model ID (e.g. `runware:400@1`) |
 | `--size` | Dimensions (e.g. `1024x1024`) |
-| `--sync` / `--no-sync` | Sync vs async delivery |
-| `--duration` | Video duration (seconds) |
-| `--num-results` | Number of outputs |
-| `--extra KEY VALUE` | Extra payload parameters |
-| `--outfile` | Output filename |
+| `--sync` / `--no-sync` | Synchronous delivery vs asynchronous polling |
+| `--duration` | Video duration in seconds |
+| `--num-results` | Number of outputs to create |
+| `--extra KEY VALUE` | Extra payload parameters (repeatable) |
+| `--outfile` | Output file path |
 
 ### `scripts/runware_mcp.py`
 
 | Command | Description |
 |---------|-------------|
-| `run --prompt "..."` | Run inference task |
-| `list-models` | Browse model catalog |
-| `model-pricing --model X` | Get model pricing |
+| `run --prompt "..."` | Run an inference task |
+| `list-models` | Browse the model catalog |
+| `model-pricing --model X` | Check pricing for a model |
 | `model-details --model X` | Get model metadata |
-| `account` | Show account info & balance |
+| `account` | View account details and balance |
 
 ## Testing
 
+Run unit tests:
+
 ```bash
-pytest -q
+pytest -q -m "not integration"
 ```
 
-Integration tests require `RUNWARE_API_KEY` set in the environment.
+To run the live integration test, set `RUNWARE_API_KEY` in your environment:
+
+```bash
+pytest -q
+```
 
 ## Safety
 
-- Prompt filter blocks requests referencing minors
-- Users must follow [Runware's terms of service](https://runware.ai/terms)
-- API key stays client-side or in OAuth session — never committed
+- Prompts referencing minors are blocked locally before sending requests.
+- Requests must follow [Runware terms of service](https://runware.ai/terms).
+- API keys stay in local `.env` files or OAuth sessions and are never committed to version control.
 
 ## Architecture
 
@@ -152,39 +159,39 @@ graph TD
     User -->|Tool call| MCP[scripts/runware_mcp.py]
     Gen -->|async with Runware| SDK[runware-sdk]
     MCP -->|async with Runware| SDK
-    SDK -->|"run()"| API[Runware.ai API]
+    SDK -->|run| API[Runware.ai API]
     API -->|Results| SDK
     SDK -->|Decoded output| Gen
     SDK -->|Decoded output| MCP
     Gen -->|Save| Output[Local file]
     MCP -->|Print| Output2[JSON stdout]
 
     MCP_Client[MCP Client e.g. Claude Desktop]
-    MCP_Client -->|stdio / HTTP| MCP_Server["npx @runware/mcp"]
+    MCP_Client -->|stdio / HTTP| MCP_Server[npx @runware/mcp]
     MCP_Server --> API
 ```
 
 ## Migration from v1.x
 
-| Old | New |
-|-----|-----|
+| Version 1.x | Version 2.0 |
+|-------------|-------------|
 | `scripts/generate_image.py` | `scripts/generate.py` |
-| `requests.post` to `/v1/tasks` | `runware-sdk` `client.run()` |
-| Manual UUIDs & response parsing | SDK handles schema, validation, delivery |
-| Image-only | Image + video + audio + text + 3D |
+| Direct HTTP calls to `/v1/tasks` | `runware-sdk` via `client.run()` |
+| Manual request IDs and payload formatting | SDK schema validation and delivery handling |
+| Image only | Image, video, audio, text, and 3D |
 | Python 3.8+ | Python 3.11+ |
 
 ## Author
 
-**Shobhit Kumar Prabhakar** — [@GeekLord](https://github.com/GeekLord/)
+**Shobhit Kumar Prabhakar** ([@GeekLord](https://github.com/GeekLord/))
 
 ## License
 
-MIT — see LICENSE.
+MIT (see LICENSE)
 
 ## Links
 
 - [Runware MCP Server](https://runware.ai/mcp)
-- [Runware MCP Docs](https://runware.ai/docs/platform/mcp)
+- [Runware MCP Documentation](https://runware.ai/docs/platform/mcp)
 - [Runware Python SDK](https://runware.ai/docs/platform/python)
-- [Official @runware/mcp GitHub](https://github.com/runware/mcp)
+- [Official @runware/mcp GitHub repository](https://github.com/runware/mcp)