Metadata-Version: 2.4
Name: clipzing-mcp
Version: 0.1.0
Summary: MCP server for Clipzing — talk to your clip library from Claude.
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Clipzing MCP server

Connect Claude (or any MCP client) to your Clipzing account, so you can ask
about your clips in plain language instead of clicking through the dashboard.

```
You: Which of my clips scored highest, and what's actually said in it?
You: Show me frames from that clip at 0:05, 0:20 and 0:40 — do the captions
     cover his face?
You: Using the transcript, draft a LinkedIn post in my voice.
```

**This release is read-only.** It can look at your library; it cannot edit,
delete, publish or spend credits. That is deliberate — see [Safety](#safety).

---

## Install

Requires Python 3.10+. No dependencies.

```bash
uvx clipzing-mcp          # run without installing
# or
pipx install clipzing-mcp
```

## Get an API key

1. Sign in to <https://clipzing.com>
2. Settings → **API keys** → *Create key*
3. Copy it immediately — **it is shown once and cannot be recovered.**

Keys expire after 90 days by default and can be revoked at any time.

## Configure your client

**Claude Desktop** — `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "clipzing": {
      "command": "uvx",
      "args": ["clipzing-mcp"],
      "env": { "CLIPZING_API_KEY": "czk_live_..." }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add clipzing --env CLIPZING_API_KEY=czk_live_... -- uvx clipzing-mcp
```

Restart the client, then ask it to list your clips.

---

## Tools

| Tool | What it does |
|---|---|
| `list_clips` | Your clips, newest first, with optional search |
| `get_clip` | Full detail for one clip — captions, virality score, edit state |
| `get_clip_frames` | **Actual frames as images**, at timestamps you choose |
| `get_transcript` | What is said, as prose or with timings |
| `get_usage` | Plan, remaining credits, render-queue state |
| `list_jobs` | Recent uploads and their processing status |

`get_clip_frames` is the interesting one: it lets the model *see* your video, so
it can answer things like "are the captions covering his face at 0:38?" rather
than guessing from metadata.

---

## Safety

**Read-only.** No tool in this release writes anything. Even if the model is
told to — for example by text embedded in one of your own transcripts — there is
no delete, publish or render tool for it to reach.

**Scoped keys.** A key carries explicit scopes and the server enforces them.
Keys default to `read` only; `edit`, `render` and `publish` must be granted
deliberately. Enforcement is server-side, so nothing running on your machine can
exceed what the key allows.

**Your key stays local.** It is read from the environment, sent only to
clipzing.com over HTTPS, and never written to disk or logs by this process.

**No dependencies.** This package installs nothing beyond the Python standard
library, so there is no third-party code in the process that holds your key.

**Revocable.** Delete a key in Settings and it stops working immediately.

### Bounds

Frames are capped at 8 per call and 720px wide. Larger images cost you model
context without helping the model see better.

---

## Troubleshooting

**"CLIPZING_API_KEY is not set"** — the client did not pass the env var. Check
the `env` block in your config, then fully restart the client.

**"Authentication failed"** — the key is wrong, revoked, or expired. Create a
new one; do not retry the old one.

**"This API key is missing the 'x' scope"** — the key was created without that
permission. Create a new key with the scope you need.

**"Clipzing is at capacity"** — the render queue is saturated. Nothing was
charged. Try again shortly.

Diagnostics go to stderr and appear in your client's MCP logs. Set
`CLIPZING_BASE_URL` to point at a different environment.

---

## Development

```bash
python -m pytest tests/ -q

# Drive the protocol by hand:
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | CLIPZING_API_KEY=czk_live_x python -m clipzing_mcp.server
```

Architecture note: this is a **client**, not a service. It runs on the user's
machine and calls the Clipzing HTTP API — it never touches the database, so no
credentials beyond the API key are ever distributed.
