Metadata-Version: 2.4
Name: zyng-mcp
Version: 0.15.1
Summary: Zyng MCP client — record your running app with an agent, publish a managed narrated pitch.
Author-email: Rahul Gaur <rahul.nbg@gmail.com>
License: Proprietary
Project-URL: Homepage, https://zyng.work
Project-URL: Studio, https://app.zyng.work
Keywords: mcp,zyng,playwright,video,walkthrough,agent,loom
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0
Requires-Dist: playwright>=1.40
Requires-Dist: requests>=2.31
Requires-Dist: pydantic>=2.5
Requires-Dist: pillow>=10
Provides-Extra: keychain
Requires-Dist: keyring>=24; extra == "keychain"
Dynamic: license-file

# zyng-mcp

Record a running app with your coding agent, get back a **managed, directed launch film** — without
ever recording it yourself.

Point your agent (Claude Desktop, Claude Code, or any MCP client) at your localhost app. This server
captures real product proof **keyless and free**, then uses hosted Zyng Director to assemble the first
cut, review it, and publish it on your credits. No TTS key ever leaves your machine, the video engine
stays managed.

## Tools

| tool | what it does | needs |
|------|--------------|-------|
| `account` | your Zyng credit balance (the "do I have credits?" check) | API token |
| `direct` | read a local app's brand + route map so your agent can understand the product before capture | Chromium, no key |
| `capture_clips` | drive a running app headless, screen-record a feature into a raw clip + timeline | Chromium, no key |
| `trailer` | send the URL, brief, and captured proof into hosted Director, get back the exact reviewable spec, review token, and hosted Studio project URL, free | API token |
| `review` | local review page and markdown for the exact spec and clips, free | nothing |
| `estimate` | approximate the credit cost before spending | API token |
| `voices` | voice catalog, and whether premium voices are unlocked for this account | API token |
| `publish` | upload clips + a composition spec → a managed narrated stitch, downloaded as MP4 | API token, spends credits |

## Install

```bash
pipx install zyng-mcp            # or: pip install ./zyng_mcp-0.1.0-py3-none-any.whl
python -m playwright install chromium   # one-time browser download (~150MB)
```

`capture_clips` needs Chromium; `publish` does not (the render happens on Zyng). No ffmpeg required.

## Get an API token

1. Sign in at **https://app.zyng.work** (Google).
2. Avatar menu → **API tokens** → **Mint**, and copy the `zyk_…` token (shown once).

A fresh account includes free credits; 1 credit = 1 second of finished video.

## Recording apps that need a login

Never put a password in a capture spec — it would land in the agent's context, the tool-call logs,
and (if typed on screen) the uploaded video. Three on-machine options instead, all resolved locally
so the credential never reaches the agent or Zyng:

**HTTP Basic Auth (the browser's `WWW-Authenticate` dialog — e.g. a staging site):**
```bash
zyng-mcp secret set staging_basic_auth   # hidden prompt; enter:  username:password
```
Then pass the secret's **name** to capture (the agent never sees the value):
```json
{ "do": "capture_clips", "http_auth": "staging_basic_auth" }
```
Playwright answers the challenge at the network layer — no dialog, nothing on screen, `authenticated:true`.


**Preferred — a saved session (nothing is typed or recorded):**
```bash
zyng-mcp login http://localhost:3000   # opens a browser; log in by hand, press Enter to save
```
This writes the authenticated session to `~/.zyng/state/<host>.json` (chmod 600). `capture_clips`
auto-detects it for that host, so recordings start already signed in — the result shows
`"authenticated": true`. No login step, no password on screen.

**If you must demonstrate the login itself — a named secret (the agent only sees the name):**
```bash
zyng-mcp secret set acme_password      # hidden prompt; stored in the OS keychain or a chmod-600 file
```
Then a step references it by name (never the value):
```json
{ "do": "fill", "selector": "#password", "secret": "acme_password" }
```
The value is resolved at capture time and never enters the spec, the tool call, a log, or the result.
Keychain storage needs `pipx install "zyng-mcp[keychain]"`; otherwise it falls back to
`~/.zyng/secrets.json` (chmod 600). You can also pass a secret as an env var, e.g.
`ZYNG_SECRET_ACME_PASSWORD`.

> Anything visible on screen during capture ends up in the uploaded MP4 — prefer the saved session
> for anything sensitive, and use a throwaway/test account where you can.

## Register with your agent

Add to `claude_desktop_config.json` (Claude Desktop) or `.mcp.json` (Claude Code):

```json
{
  "mcpServers": {
    "zyng": {
      "command": "zyng-mcp",
      "env": {
        "ZYNG_API_KEY": "zyk_your_token_here",
        "ZYNG_BASE_URL": "https://app.zyng.work"
      }
    }
  }
}
```

(If you installed with `pipx`, `zyng-mcp` is on your PATH. With a venv, use the absolute path to the
`zyng-mcp` script, or `command: "python", args: ["-m", "zyng_mcp.server"]`.)

## Use it

Tell your agent something like:

> My app is running at http://localhost:3000. Record the sign-in and the dashboard, then publish a
> 30-second pitch. Say "this is the fastest way to onboard" over the dashboard.

The preferred flow is: ask whether this should be a desktop cut or a mobile-first cut, capture one proof
clip per payoff with `capture_clips`, call `trailer` to let hosted Director assemble the first cut, show
the review, then `publish` once you approve it.

Director's story grounding now defaults to Zyng's approved launch-video corpus. In practice, that means
the first cut is influenced by the vetted internal benchmark set only. Public review candidates and
source-queue references do not affect live retrieval until they are promoted into the approved corpus.

The brief should sound like Director, not a form fill. Ask in plain language:

- what should this cut make unmistakable?
- who is this for?
- what product proof should it show?

If the product needs a little understanding first, use `direct` before capture. It reads the local brand
and route map so the agent can form a stronger brief before it calls `trailer`.

### Spec shapes

`trailer` input:
```json
{
  "url": "http://localhost:3000",
  "nudge": "Focus on onboarding speed for founders.",
  "clips": ["/abs/path/dashboard.webm", "/abs/path/report.webm"],
  "register": "cinematic",
  "audio_mode": "music_captions",
  "aspect": "16:9"
}
```

`trailer` returns the exact publish `spec`, an `estimate`, a local `review_url`, a `review_token`, and a
hosted `project_url` that opens the same cut in Zyng Studio. Show that to the user first. Then call
`publish` with the same `spec`, same clips, and the token.

`capture_clips` spec:
```json
{ "url": "http://localhost:3000", "title": "Dashboard", "aspect": "16:9",
  "steps": [
    { "do": "wait",  "ms": 1000, "say": "Here's the dashboard." },
    { "do": "click", "selector": "text=New report", "say": "One click to a new report." }
  ] }
```

`publish` spec, usually returned by `trailer` (clip files matched by basename to the captured clips you pass in `clips`):
```json
{ "title": "My app", "theme": "dawn", "voice": "narrator", "aspect": "16:9",
  "segments": [
    { "card": { "layout": "title", "heading": "My app", "narration": "A quick tour." } },
    { "clip": { "file": "dashboard.webm", "audio": "narrate", "say": "This is the dashboard." } }
  ] }
```

## Notes

- **Credits + voice are managed.** You never ship an ElevenLabs/OpenAI key; Zyng renders with its own
  voice and charges your balance (gate-at-zero with a clear error).
- **Selectors come from your source**, not pixel-guessing — Zyng executes the steps your agent authors,
  so a recording is deterministic and re-runnable. A bad selector returns a clean error naming the step.
- Set `ZYNG_BASE_URL` to a different host to target a self-hosted or staging studio.
