Skip to content

Commit 419742c

Browse files
GeekLordGeekLord
committed
v2.0: multi-modal upgrade with runware-sdk + MCP support
BREAKING: replaces old raw-REST generate_image.py with modern async SDK. - New scripts/generate.py: multi-modal (image, video, audio, text, 3D) - New scripts/runware_mcp.py: MCP-style CLI tools (run, list-models, model-pricing, model-details, account) - Uses official runware-sdk (typed, validated, async) - Updates SKILL.md, README, examples for v2.0 - New CI workflow with Python 3.11-3.13 matrix - Streamlined skill-config.json, .gitignore, requirements.txt
1 parent a82041a commit 419742c

16 files changed

Lines changed: 1105 additions & 458 deletions

‎.env_sample‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
RUNWARE_API_KEY=YOUR_RUNWARE_API_KEY_HERE
1+
RUNWARE_API_KEY=YOUR_RUNWARE_KEY_HERE

‎.github/workflows/ci.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.11", "3.12", "3.13"]
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
- name: Set up Python ${{ matrix.python-version }}
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: ${{ matrix.python-version }}
22+
- name: Install dependencies
23+
run: |
24+
python -m pip install --upgrade pip
25+
pip install -r requirements.txt
26+
- name: Run unit tests
27+
run: pytest -q -m "not integration"

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,10 @@ __pycache__/
88
.venv/
99
env/
1010
venv/
11+
12+
# Output images/media
13+
runware_output/
14+
15+
# OS files
16+
.DS_Store
17+
Thumbs.db

‎CONTRIBUTING.md‎

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,31 @@
1-
Contributing to runware-image
1+
# Contributing to runware-mcp
22

3-
Thank you for your interest in improving this skill. Please follow these guidelines to make contributions easy to review and integrate.
3+
Thank you for your interest in improving this skill!
44

5-
- Fork the repository and submit a pull request against the main branch.
6-
- Run tests locally: python -m pip install -r requirements.txt && pytest
7-
- Keep changes small and focused; open separate PRs for separate features.
8-
- Include unit tests for new behaviors and update existing tests when behavior changes.
9-
- For changes that introduce new dependencies, update requirements.txt and explain why in the PR description.
10-
- Use clear commit messages and reference issue numbers where applicable.
5+
## Getting Started
116

12-
Reporting issues
7+
1. Fork the repository and submit a pull request against `main`.
8+
2. Install development dependencies: `pip install -r requirements.txt`
9+
3. Run tests: `pytest -q`
10+
4. For integration tests, set `RUNWARE_API_KEY` in your environment.
11+
12+
## Guidelines
13+
14+
- **Keep changes focused** — open separate PRs for separate features
15+
- **Include tests** — add unit tests for new behaviors, update existing tests when behavior changes
16+
- **Update docs** — if you add a feature, update `SKILL.md`, `README.md`, and examples as appropriate
17+
- **Use clear commit messages** — reference issue numbers where applicable
18+
- **Minimal dependencies** — avoid adding new packages unless necessary
19+
20+
## Adding a New Mode
21+
22+
To add a new generation mode (e.g., a new modality):
23+
24+
1. Add the mode to `SUPPORTED_MODES`, `MODES_TO_TASKTYPE`, `MODES_TO_EXT`, and `_default_model()` in `scripts/generate.py`
25+
2. Add the corresponding `--mode` choice in `scripts/runware_mcp.py`
26+
3. Update tests accordingly
27+
4. Add example commands to `examples/README.md`
28+
29+
## Reporting Issues
1330

1431
Open issues for bugs, feature requests, or documentation corrections. Include steps to reproduce and minimal examples when possible.

‎README.md‎

Lines changed: 137 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -1,127 +1,190 @@
1-
# runware-image
1+
# runware-mcp
22

33
[![GitHub Author](https://img.shields.io/badge/Author-GeekLord-181717?style=flat&logo=github)](https://github.com/GeekLord/)
44
[![Repository](https://img.shields.io/badge/Repository-OpenClaw__Runware__API-blue?style=flat&logo=github)](https://github.com/GeekLord/OpenClaw_Runware_API)
5-
[![Python](https://img.shields.io/badge/Python-3.8%2B-blue?style=flat&logo=python)](https://www.python.org/)
5+
[![Python](https://img.shields.io/badge/Python-3.11%2B-blue?style=flat&logo=python)](https://www.python.org/)
66

7+
**Multi-modal Runware.ai skill** — image, video, audio, text, and 3D generation via the official `runware-sdk` Python library, plus MCP-style tooling.
78

8-
Runware Image Skill - a small CLI skill to generate images on-demand via the Runware.ai Image Inference API.
9-
10-
This repository contains an OpenClaw-style skill that provides a Python CLI script to submit text-to-image tasks to Runware, save generated images locally, and includes tests, examples, and CI configuration to make the skill production-ready for publishing to ClawHub (or GitHub first).
9+
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.
1110

1211
## Features
1312

14-
- Submit text-to-image tasks to Runware's task API (imageInference).
15-
- Default synchronous generation (returns base64 image data) with support for async/webhook workflows.
16-
- Safe-by-default prompt validation to reduce the risk of generating images of minors.
17-
- Default output directory: `~/runware_images` (created automatically). The script remembers the last used output directory.
18-
- Minimal dependencies. Tests can be configured to run in CI with secrets for integration or skipped when no RUNWARE_API_KEY is present.
13+
- **Multi-modal** — Generate images, videos, audio, text, and 3D models
14+
- **Official SDK** — Uses `runware-sdk` (async, typed, JSON-Schema validated)
15+
- **MCP integration** — MCP-style tools (`run`, `list-models`, `model-pricing`, `model-details`, `account`)
16+
- **Hosted MCP server** — Can connect directly to `https://mcp.runware.ai` (OAuth 2.1, no local install needed)
17+
- **Sync + async** — Sync delivery for fast tasks, async polling for long-running ones
18+
- **Safe-by-default** — Lightweight prompt filtering
19+
- **Configurable** — Default model, size, format via `skill-config.json`
20+
- **Tested** — Pytest unit tests + optional integration tests
1921

20-
## Contents
22+
## Quick Start
2123

22-
- `SKILL.md` - Skill metadata and usage guidance (required by OpenClaw skills).
23-
- `skill-config.json` - Default settings (no secrets). Contains `default_size`, `default_format`, and `default_output_dir`.
24-
- `scripts/generate_image.py` - Primary CLI script (Python 3.8+).
25-
- `requirements.txt` - Minimal dependencies.
26-
- `tests/test_generate_image.py` - Pytest unit test that mocks Runware responses.
27-
- `examples/` - Example CLI commands.
28-
- `.github/workflows/ci.yml` - GitHub Actions CI workflow to run tests.
29-
- `LICENSE`, `CONTRIBUTING.md` - Project metadata.
24+
```bash
25+
# Install dependencies
26+
pip install -r requirements.txt
3027

31-
## System Architecture
28+
# Set your API key
29+
echo "RUNWARE_API_KEY=your_key_here" > .env
3230

33-
```mermaid
34-
graph TD
35-
User[User / Terminal] -->|Run| Script[scripts/generate_image.py]
36-
Script -->|Load| Env[.env]
37-
Script -->|Load| Config[skill-config.json]
38-
Script -->|POST /run| Runware[Runware.ai API]
39-
Runware -->|JSON Response| Script
40-
Script -->|Decode & Save| Image[Output Image]
41-
```
31+
# Generate an image
32+
python scripts/generate.py --prompt "A serene mountain landscape" --mode image --outfile landscape.png
4233

43-
## Quick Start (GitHub)
34+
# Generate a video
35+
python scripts/generate.py --prompt "Waves crashing on a beach" --mode video --duration 8 --outfile waves.mp4
4436

45-
1. Clone the repository:
37+
# Browse models via MCP-style CLI
38+
python scripts/runware_mcp.py list-models --category image --search "flux"
4639

47-
```bash
48-
git clone <repo-url>
49-
cd runware-image
40+
# Check account balance
41+
python scripts/runware_mcp.py account
5042
```
5143

52-
2. Create a Python virtual environment and install deps:
44+
## MCP Server Connection
5345

54-
```bash
55-
python -m venv .venv
56-
source .venv/bin/activate # or .\.venv\Scripts\activate on Windows
57-
pip install -r requirements.txt
46+
### 1. Hosted (easiest — no install)
47+
48+
Any MCP-compatible client can connect to Runware's hosted server:
49+
50+
```json
51+
{
52+
"mcpServers": {
53+
"runware": { "url": "https://mcp.runware.ai" }
54+
}
55+
}
5856
```
5957

60-
3. Set your Runware API key.
61-
- Create a `.env` file in the root of the skill: `RUNWARE_API_KEY=your_key`
62-
- OR set it in the environment: `$env:RUNWARE_API_KEY = "<YOUR_KEY>"`
58+
Authentication is handled via OAuth 2.1 — your API key stays server-side, encrypted in the OAuth session.
6359

64-
4. Generate an image (sync):
60+
### 2. Local (self-hosted)
6561

66-
```bash
67-
python scripts/generate_image.py --prompt "A photorealistic portrait of an adult (age 28)" --sync --outfile "portrait.png"
62+
```json
63+
{
64+
"mcpServers": {
65+
"runware": {
66+
"command": "npx",
67+
"args": ["-y", "@runware/mcp"],
68+
"env": { "RUNWARE_API_KEY": "your-api-key" }
69+
}
70+
}
71+
}
72+
```
73+
74+
### 3. Python (this skill)
75+
76+
```json
77+
{
78+
"mcpServers": {
79+
"runware-python": {
80+
"command": "python",
81+
"args": ["scripts/runware_mcp.py"]
82+
}
83+
}
84+
}
6885
```
6986

70-
By default, images are saved under `~/runware_images/` unless you provide an absolute path or a relative filename. The script also remembers the last directory used.
87+
## Files
88+
89+
| File | Purpose |
90+
|------|---------|
91+
| `scripts/generate.py` | Main multi-modal generator |
92+
| `scripts/runware_mcp.py` | MCP-style CLI tool interface |
93+
| `skill-config.json` | Default settings (no secrets) |
94+
| `SKILL.md` | OpenClaw skill metadata & usage |
95+
| `tests/test_generate.py` | Pytest tests |
96+
| `examples/` | Example commands |
7197

7298
## Configuration
7399

74-
`skill-config.json` contains defaults used by the CLI. Fields:
100+
`skill-config.json` fields:
75101

76-
- `default_size` - default image size (e.g., "1024x1024").
77-
- `default_format` - output format (png/jpg/webp).
78-
- `default_output_dir` - default output directory (for example, `~/runware_images` on Unix-like systems).
79-
- `last_output_dir` - automatically updated by the script to remember the last save location.
102+
- `default_size` — default image size (e.g. `"1024x1024"`)
103+
- `default_format` — output format (`png`/`jpg`/`webp`/`mp4`/`wav`/`glb`)
104+
- `default_output_dir` — default output directory
105+
- `last_output_dir` — auto-updated by the script
80106

81-
Do NOT store API keys in this file. Use the `RUNWARE_API_KEY` environment variable or a secret manager.
107+
## CLI Reference
82108

83-
## Safety
109+
### `scripts/generate.py`
84110

85-
- The script implements a simple prompt filter to block prompts that reference minors (e.g., "teen", ages under 21). This is a lightweight safeguard but does not replace human judgment or platform policies.
86-
- Users are responsible for ensuring they have legal rights to generate and host requested imagery and for following Runware's terms of service.
111+
| Flag | Description |
112+
|------|-------------|
113+
| `--prompt` | Text prompt |
114+
| `--mode` | `image`, `video`, `audio`, `text`, or `3d` |
115+
| `--model` | Runware model ID (e.g. `runware:400@1`) |
116+
| `--size` | Dimensions (e.g. `1024x1024`) |
117+
| `--sync` / `--no-sync` | Sync vs async delivery |
118+
| `--duration` | Video duration (seconds) |
119+
| `--num-results` | Number of outputs |
120+
| `--extra KEY VALUE` | Extra payload parameters |
121+
| `--outfile` | Output filename |
87122

88-
## Testing & CI
123+
### `scripts/runware_mcp.py`
89124

90-
- Tests are in `tests/` and use pytest. The included test stubs/mocks `requests.post` so CI does not require real API keys.
91-
- GitHub Actions workflow `.github/workflows/ci.yml` runs the tests on push and pull requests.
125+
| Command | Description |
126+
|---------|-------------|
127+
| `run --prompt "..."` | Run inference task |
128+
| `list-models` | Browse model catalog |
129+
| `model-pricing --model X` | Get model pricing |
130+
| `model-details --model X` | Get model metadata |
131+
| `account` | Show account info & balance |
92132

93-
Run tests locally:
133+
## Testing
94134

95135
```bash
96136
pytest -q
97137
```
98138

99-
## Examples
139+
Integration tests require `RUNWARE_API_KEY` set in the environment.
100140

101-
See `examples/README.md` for example prompts and usage patterns (sync vs async).
102-
103-
## Packaging & Publishing
141+
## Safety
104142

105-
Before publishing to ClawHub:
143+
- Prompt filter blocks requests referencing minors
144+
- Users must follow [Runware's terms of service](https://runware.ai/terms)
145+
- API key stays client-side or in OAuth session — never committed
106146

107-
1. Ensure `skill-config.json` contains no secrets.
108-
2. Run tests and fix any issues.
109-
3. Optionally package the skill using the project packaging script (if available) or create a .zip that follows the skill layout.
147+
## Architecture
110148

111-
I can assist with creating the .skill package and publishing to ClawHub when you’re ready.
149+
```mermaid
150+
graph TD
151+
User[User / Terminal] -->|Prompt| Gen[scripts/generate.py]
152+
User -->|Tool call| MCP[scripts/runware_mcp.py]
153+
Gen -->|async with Runware| SDK[runware-sdk]
154+
MCP -->|async with Runware| SDK
155+
SDK -->|run()| API[Runware.ai API]
156+
API -->|Results| SDK
157+
SDK -->|Decoded output| Gen
158+
SDK -->|Decoded output| MCP
159+
Gen -->|Save| Output[Local file]
160+
MCP -->|Print| Output2[JSON stdout]
161+
162+
MCP_Client[MCP Client e.g. Claude Desktop]
163+
MCP_Client -->|stdio / HTTP| MCP_Server["npx @runware/mcp"]
164+
MCP_Server --> API
165+
```
112166

113-
## Contributing
167+
## Migration from v1.x
114168

115-
See `CONTRIBUTING.md` for contribution guidelines. Keep changes small, include tests, and run CI locally.
169+
| Old | New |
170+
|-----|-----|
171+
| `scripts/generate_image.py` | `scripts/generate.py` |
172+
| `requests.post` to `/v1/tasks` | `runware-sdk` `client.run()` |
173+
| Manual UUIDs & response parsing | SDK handles schema, validation, delivery |
174+
| Image-only | Image + video + audio + text + 3D |
175+
| Python 3.8+ | Python 3.11+ |
116176

117177
## Author
118178

119-
- **Shobhit Kumar Prabhaar** - [GitHub Profile](https://github.com/GeekLord/)
179+
**Shobhit Kumar Prabhakar** — [@GeekLord](https://github.com/GeekLord/)
120180

121181
## License
122182

123-
This project is licensed under the MIT License - see LICENSE.
183+
MIT — see LICENSE.
124184

125-
## Contact / Support
185+
## Links
126186

127-
Open an issue or a pull request on the repository. For Runware API specifics, consult: https://runware.ai/docs/getting-started/introduction
187+
- [Runware MCP Server](https://runware.ai/mcp)
188+
- [Runware MCP Docs](https://runware.ai/docs/platform/mcp)
189+
- [Runware Python SDK](https://runware.ai/docs/platform/python)
190+
- [Official @runware/mcp GitHub](https://github.com/runware/mcp)

0 commit comments

Comments
 (0)