Skip to main content
Glama
README.md
# Jaz Cloud

> **Status: personal self-hosting.** Right now this runs on my own always-on Mac so I can use
> Jaz from my phone ([SELF-HOST.md](SELF-HOST.md)). It's also the template for a possible paid,
> hosted version later: the server, API keys, daily limits and plugin work today; billing and
> cloud deployment aren't built. For the free version that runs on your own computer, use
> [Jaz](https://github.com/lnc2131/jaz).

A hosted MCP server that lets AI agents "watch" video links. Send it an Instagram,
TikTok, YouTube, Pinterest, X or Facebook link (or any web page) and it returns the
caption, the voiceover transcript with timestamps, and the text shown on screen.

## Repo layout

| Path | What it is |
|---|---|
| `src/jaz_cloud/` | The server: pipeline, API keys, jobs, signed download links |
| `plugins/jaz-cloud/` | Claude Code plugin customers install: skill + `.mcp.json` pointing at your server |
| `skills/jaz/` | The same skill on its own, for skills directories |
| `.claude-plugin/marketplace.json` | Lets customers run `claude plugin marketplace add lnc2131/jaz-cloud` |
| `Dockerfile` | Draft container for deployment (untested) |

## Customer install (once deployed)

```bash
claude plugin marketplace add lnc2131/jaz-cloud
claude plugin install jaz-cloud@jaz-cloud
```

Claude Code asks for the API key (`jaz_...`) during install. Before publishing, replace
`https://YOUR-DOMAIN/mcp` in `plugins/jaz-cloud/.mcp.json` with your server's address.

```
link ─► yt-dlp download ─► ffmpeg ─┬─► faster-whisper ─► transcript
                                   └─► frames every 1.5s ─► RapidOCR ─► on-screen text (deduped)
```

Agents call two MCP tools:

| Tool | What it does |
|---|---|
| `parse_video(url)` | Starts (or reuses) a job and waits up to 25s. Returns the extract, or a `job_id` if it's still processing. |
| `get_result(job_id)` | Waits up to 25s more for a job and returns the extract. |

The agent builds recipes, place lists and so on from the extract (see
`plugins/jaz-cloud/skills/jaz/SKILL.md`), so the server needs no LLM API key.

## Run it locally

```bash
uv sync
uv run jaz-cloud keys create --label me --plan video   # prints the key once
uv run jaz-cloud serve                                   # http://127.0.0.1:8765/mcp
```

Try it without a client:

```bash
uv run jaz-cloud extract "https://youtu.be/jNQXAC9IVRw"
uv run python tests/smoke.py <api-key> "https://youtu.be/jNQXAC9IVRw"
uv run pytest -q
```

Connect Claude Code to the local server:

```bash
claude mcp add --transport http jaz-cloud http://127.0.0.1:8765/mcp --header "Authorization: Bearer <api-key>"
```

## Accounts and limits

- API keys are stored as SHA-256 hashes. `keys create | list | revoke <prefix>`.
- Plans: `extract` (30 new links/day) and `video` (60/day, plus signed download links
  for the original files that last 21 days).
- The same link (any share-link variant for YouTube) on the same UTC day is free for
  a key that already asked for it, and reuses the finished job across keys.
- Failed jobs don't count toward the limit.

## Settings (environment variables)

| Variable | Default | Notes |
|---|---|---|
| `JAZ_DATA_DIR` | `./data` | SQLite DB, media, secret key |
| `JAZ_HOST` / `JAZ_PORT` | `127.0.0.1` / `8765` | |
| `JAZ_PUBLIC_BASE_URL` | `http://127.0.0.1:<port>` | Used in download links and allowed Host headers |
| `JAZ_WHISPER_MODEL` | `large-v3-turbo` | Any faster-whisper model name |
| `JAZ_WHISPER_DEVICE` | `mps` on Apple Silicon, else `auto` | `cuda` on a GPU server |
| `JAZ_WORKERS` | `2` | Parallel jobs |
| `JAZ_MAX_DURATION_S` | `3600` | Longer videos are refused |
| `JAZ_DAILY_LIMIT_EXTRACT` / `_VIDEO` | `30` / `60` | |
| `JAZ_COOKIES_FILE` | none | Netscape cookies file for platforms that demand a login |
| `JAZ_SECRET` | generated | Signs download links |

## Security

- `/mcp` needs `Authorization: Bearer <key>`; everything else is public (`/healthz`,
  signed `/files/...` links).
- Links that resolve to private, loopback or cloud-metadata addresses are refused
  (SSRF). Known gap: DNS rebinding between the check and the fetch.

## Known limits

- **Platform blocking is the main risk of hosting.** Instagram, TikTok and YouTube
  often block or demand logins from datacenter IPs. Works from a home connection;
  on a server you'll likely need `JAZ_COOKIES_FILE` and/or residential proxies.
  Check each platform's terms before offering this commercially.
- Instagram/TikTok photo-only posts depend on yt-dlp support and may fail.
- Transcripts and OCR are machine output and can contain mistakes.
- No billing yet: keys are created by hand.

## Roadmap

1. Billing: Stripe Checkout + webhook that creates/revokes keys per subscription.
2. Deploy: Dockerfile is a draft; host on a GPU box (or CPU with `JAZ_WHISPER_MODEL=small`).
3. Optional server-side structured extract (recipes, places) with an LLM.