# Using ClipCabinet clips

ClipCabinet turns screen recordings and screenshots into AI-readable "clips".
Each clip carries a transcript, captioned frames, a summary, and extracted
artifacts (links, errors, code, file paths, tickets). Use this skill to find,
read, and cite clips as context.

## How to reach clips

Primary path: the ClipCabinet MCP server (seven tools). If no MCP connection is
available, use the fallback: append `.md` to any clip or share URL to read its
transcript, summary, and artifacts as Markdown (for example `/s/<token>.md`).

## Tools, and when to use each

| Tool | Use it to |
| --- | --- |
| `search_recordings` | Find a clip by meaning. Start here for "find the clip about X". |
| `get_recording` | Ingest one clip fully: transcript, frames, artifacts, signed URLs. |
| `search_within_recording` | Find the moment inside one clip; returns a `{recordingId}@{timestampMs}` cite. |
| `get_frame` | Get a frame PNG (signed URL) + caption to run vision on. |
| `get_audio_clip` | Get a signed URL for an audio segment `[startMs, endMs]`. |
| `list_recordings` | Browse or filter the library by `kind` (`video` or `screenshot`). |
| `list_artifacts` | Cross-clip search of every URL, error, code snippet, file path, or ticket id. |

See `references/mcp-tools.md` for arguments and output shapes.

## Core workflows

- "Use this clip" / a clip link or id is given: call `get_recording`, then read
  the summary, transcript, and artifacts.
- "Find a clip about X": `search_recordings`, then `get_recording` on the best
  hit.
- "Where did they say or show X": `search_within_recording`, cite the moment as
  `{recordingId}@{timestampMs}`, and `get_frame` for the visual.
- "What links / errors / code did they show": `list_artifacts`.

See `references/consuming-clips.md` for video-vs-screenshot handling and citing.

## Connecting

If the MCP tools are not available, the user must connect first: mint an API
token in ClipCabinet Settings then API tokens, and add the ClipCabinet MCP
server to this client. See `references/connecting.md`, or the user can open
`/docs/mcp` on clipcabinet.com.


---

# ClipCabinet MCP tools

Auth: a Bearer API token, minted by the user in Settings then API tokens.

- `list_recordings(kind?)` — the user's clips. Returns id, title, summary,
  durationSec, status, createdAt, and `kind` ("video" | "screenshot").
  durationSec is 0 for screenshots. Pass `kind` to filter.
- `search_recordings(query, kind?)` — semantic search over the title+summary
  embedding. Returns ranked clips with `kind`.
- `get_recording(id)` — full details. For `kind="video"`: metadata, transcript
  turns, sampled frames with captions, artifacts, and 1-hour signed URLs
  (videoUrl, audioUrl, frame PNGs). For `kind="screenshot"`: transcript is
  empty, frames has exactly one entry (the screenshot + a vision caption), and
  imageUrl plus optional contextImageUrl are populated. Capture context
  (viewport, screen, devicePixelRatio, userAgent, pageTitle, sourceUrl) is
  returned for both when set.
- `search_within_recording(id, query)` — semantic search across one clip's
  transcript turns and frame captions; returns top hits with timestamps and a
  `{recordingId}@{timestampMs}` cite.
- `get_frame(id, timestampMs)` — the frame PNG nearest the timestamp as a 1-hour
  signed URL plus its caption.
- `get_audio_clip(id, startMs, endMs)` — a 1-hour signed URL for the extracted
  audio segment. Screenshot clips have no audio; this returns
  `{ error: "audio_unavailable" }` instead of throwing.
- `list_artifacts(query?)` — cross-clip artifact search: every URL, error, code
  snippet, file path, or ticket id, each with surrounding context and a cite.

Signed URLs expire in one hour. Fetch them promptly.

# Consuming clips

## Video vs screenshot

Branch on the `kind` field.

- `video`: has a transcript (turns with timestamps), multiple captioned frames,
  and signed videoUrl/audioUrl. Read the summary first, then the transcript;
  use `get_frame` or `get_audio_clip` for specific moments.
- `screenshot`: no transcript, no audio. `get_recording` returns one captioned
  frame plus `imageUrl` (and `contextImageUrl` if the user captured a wider
  context image). Run vision on `imageUrl`.

## Citing

Cite a specific moment as `{recordingId}@{timestampMs}`. `search_within_recording`
and `list_artifacts` already return this cite; reuse it verbatim so the user can
jump to the spot.

## Ingesting as context

When asked to use a clip, prefer the structured fields over the raw video:
summary for the gist, transcript for what was said, frame captions for what was
shown, artifacts for the concrete links/errors/code. Only fetch frame PNGs or
audio when a specific visual or spoken detail matters.

# Connecting to ClipCabinet

The agent cannot mint tokens; the user does this once.

1. In ClipCabinet, open Settings then API tokens and mint a token (it is a
   Bearer token, prefixed `kg_`), or use a per-client connect card, which mints
   and sends the token for you.
2. Add the ClipCabinet MCP server to this client. It is an HTTP-transport MCP
   server:
   - URL: `https://mcp.clipcabinet.com/mcp`
   - Auth header: `Authorization: Bearer <your token>`

   For exact per-client config (Claude Code, Cursor, VS Code, Codex), see
   clipcabinet.com/docs/mcp.

No MCP connection? Use the Markdown fallback: append `.md` to any clip URL or
share URL (for example `https://clipcabinet.com/s/<token>.md`) to read the
transcript, summary, and artifacts as plain Markdown. No token required for a
public share link.