Metadata-Version: 2.4
Name: clipzing-mcp
Version: 0.2.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
```

## Configure your client

There is no key to copy. On first run the server prints a short code, opens your
browser, and you approve the connection while already signed in — so no secret is
ever displayed, pasted, or written into your config file.

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

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

**Claude Code:**

```bash
claude mcp add clipzing -- uvx clipzing-mcp
```

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

## Approve the connection

The first request triggers pairing:

```
  ┌─────────────────────────────────────────────┐
  │  Connect Clipzing — code  BCDF-2345       │
  └─────────────────────────────────────────────┘
  Opening https://clipzing.com/link?code=BCDF-2345
  Approve there, and this will continue automatically.
```

(This goes to stderr, not stdout — stdout carries the MCP protocol.)

Sign in if you are not already, check that the client name and code match what
your terminal shows, and choose what the agent may do. **Read** is granted by
default; **edit**, **render** and **publish** are opt-in, and your plan caps what
can be offered. Approving stores the credential in your OS keychain (macOS
Keychain, or a `0600` file elsewhere) — never in your project.

The credential expires after 90 days and can be revoked at any time from
**Settings → API keys**. Revoking takes effect immediately.

### If you would rather manage a key yourself

Setting `CLIPZING_API_KEY` skips pairing entirely. This suits CI and servers,
where no browser exists. It is not the recommended path for a workstation: it
puts a long-lived secret in an environment file that is easy to commit.

---

## 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

**Pairing never completes** — the code lives for 10 minutes. If it expired,
restart the client for a fresh one. Approval requires a signed-in browser
session; a code alone grants nothing.

**"Agent access is not included on your current plan"** — MCP is a paid feature.
Starter allows read and edit; Pro adds render and publish.

**"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.
