{
  "markdown": "# @clipy/mcp\n\nGive your AI agent access to your [Clipy](https://clipy.online) screen recordings.\n\n> Developed in the Clipy monorepo. A public mirror for browsing the source and filing\n> issues lives at **[github.com/manovagyanik1/clipy-mcp](https://github.com/manovagyanik1/clipy-mcp)**\n> (MIT), kept in sync with each npm release.\n\nThis is a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. It lets\nClaude, Cursor, Windsurf, and other MCP-capable agents **search your recordings and read\ntheir transcripts and AI summaries** — so you can do things like _\"turn this bug-report\nrecording into a Linear ticket\"_ without leaving your agent — and, with the `record`\ntool, **record a web app headlessly** and get it back as a Clipy recording (_\"build the\nfeature, then record the outcome\"_).\n\nThe canonical cross-surface operating contract is\n**[clipy.online/agents.md](https://clipy.online/agents.md)**. For the exact\nconnected MCP version and schemas, use the standard `tools/list` request.\n\nThe read tools need the `recordings:read` scope, which every key gets by default. The\nwrite tools — `record`, the session tools (`start_recording`, `add_marker`, `add_chapter`,\n`stop_recording`, `abort_recording`), and `replace_transcript` — additionally need the\nkey to carry the `ingest` scope (\"Record & upload\"), which the server enforces. A\n`recordings:read`-only key can read your recordings but cannot create, modify, or\ndelete anything.\n\n## Setup\n\nLog in once with the Clipy CLI:\n\n```bash\nnpx @clipy/cli@latest login\n```\n\nIt opens your browser; click **Approve** once. The key is saved to\n`~/.config/clipy/config.json`, **and this server reads that file** — so there is no key to\ncopy anywhere, and no secret ends up in your shell history or your MCP config.\n\nThen add the server to your MCP client.\n\n### Claude Code\n\nThe `--scope user` flag installs Clipy **globally** for every project. Without it,\n`claude mcp add` defaults to `local` scope (the current folder only):\n\n```bash\nclaude mcp add --scope user clipy -- npx -y @clipy/mcp\n```\n\n### Codex\n\nThis writes the server to your global `~/.codex/config.toml`, so it's available in every\nCodex session:\n\n```bash\ncodex mcp add clipy -- npx -y @clipy/mcp\n```\n\nOr add it to `~/.codex/config.toml` by hand:\n\n```toml\n[mcp_servers.clipy]\ncommand = \"npx\"\nargs = [\"-y\", \"@clipy/mcp\"]\n```\n\n### Claude Desktop / Cursor / Windsurf\n\nEdit the matching **user-level** config (`claude_desktop_config.json`, `~/.cursor/mcp.json`,\nor the Windsurf MCP config) directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"clipy\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@clipy/mcp\"]\n    }\n  }\n}\n```\n\nAdd an `\"env\": { \"CLIPY_API_KEY\": \"clipy_sk_live_xxx\" }` block only if you are not using\n`clipy login` on this machine.\n\n### Setting the key explicitly\n\nUse `CLIPY_API_KEY` when there is no `clipy login` to read from — CI, a container — or\nwhen you deliberately want a different key than the logged-in one. An explicit env var\nalways wins over the config file. Mint keys at\n**https://clipy.online/settings/api-keys** (shown only once).\n\n> **Never inline your key into the server's launch command** — e.g.\n> `\"command\": \"sh\", \"args\": [\"-c\", \"CLIPY_API_KEY=… npx -y @clipy/mcp\"]`. Command-line\n> arguments are visible to **every local process** via the process table (`ps`, `/proc`),\n> so a key placed there is effectively world-readable on the machine. Put it in the `env`\n> block instead. (`claude mcp add --env …` / `codex mcp add --env …` write that `env` block\n> for you — they expose the key only in the argv of that single setup command, never in the\n> long-running server's.)\n\n## Tools\n\n| Tool | What it does |\n| --- | --- |\n| `search_memory` | **Search the whole Clipy memory at once** — every screen recording the user made *and* every video they imported — returning the matching moments with timestamps and a URL that opens at that point. Matching is semantic as well as literal, so \"login flow\" finds a moment where someone said \"the authentication screen\". Reach for this first when the user refers to something they showed, recorded, or watched; the per-library tools below each see only half the picture. Each hit carries `kind` (`recording` or `context`) to tell you which tool to read next, a `resolution` saying whether its timestamp is an exact moment or a ~50s span, and a `semantic.status` to check before treating an empty result as \"nothing recorded\". |\n| `search_recordings` | Search your recordings by keyword (title + description). |\n| `list_recordings` | List your most recent recordings. |\n| `get_recording` | Metadata for one recording (status, duration, transcript/summary status). |\n| `get_transcript` | The full timestamped transcript + plaintext. |\n| `get_summary` | The AI summary: TL;DR, key points, action items. |\n| `get_browser_diagnostics` | Privacy-redacted visited routes, console warnings/errors, page exceptions, and failed fetch/XHR metadata. The evidence is explicitly labelled page-reported; headers, bodies, cookies, tokens, typed values, and raw query values are never captured. |\n| `wait_for_artifacts` | Poll until a recording's transcript/summary finish processing. |\n| `download_recording` | Download the MP4 locally so you can clip it or extract frames yourself (e.g. with ffmpeg). |\n| `get_key_moments` | Key moments: timestamps, captions, and click coordinates. |\n| `get_agent_context` | The full agent-context bundle (summary + key moments + transcript + available browser diagnostics) as markdown. |\n| `record` | **Record a web app headlessly** and upload it as a Clipy recording; returns its share + agent-context URLs. Accepts a `type` (recording kind), `viewports` (sweep several screen sizes into one video), `storageState` / `userDataDir`+`profileDirectory` / `initScript` (record behind a login), and timestamped `notes` that become the (silent) recording's transcript. Needs Playwright in this server's environment and an `ingest`-scoped key (see below). |\n| `start_recording` | **Start a recording session** that keeps recording while you work (drive the page with your own browser tools, run commands, …). Accepts `type`, `storageState` / `userDataDir`+`profileDirectory` / `initScript`, and `exposeCdp` (get a CDP endpoint + in-page `window.__clipyMark`/`window.__clipyChapter` bridge to drive the recorded page). Auto-stops + uploads at `maxSeconds` (default 600) so it can never run away. |\n| `add_marker` | Drop a narration marker into the active session (live clock, or backdate with `atSeconds`) — markers become the recording's transcript chapters. Can carry evidence in one of two provenances: **clipy-verified** (`assertSelector` / `assertText` / `assertUrl`) where Clipy checks the page itself, or **driver-attested** (`observed` + `verdict`) where you report what your own tooling saw. Clipy-verified outcomes render with a verdict glyph (✓ pass, ✗ failure that can abort via `failMode`, ⚠ unverified — never a silent pass); driver-attested ones render with a weaker-looking **hedge glyph** (`≈`) so the two are never mistaken at a glance, and they are tallied in separate segments. Navigations + console errors are added automatically as `[auto]` marks. |\n| `add_chapter` | Drop a `=== CHAPTER: <label> ===` boundary into the active session — split a recording into named sections (ideal for before/after demos). |\n| `stop_recording` | Finish the session: close the browser, upload, return the share + agent-context URLs. |\n| `abort_recording` | Discard the active session; nothing is uploaded. |\n| `list_context_documents` | List the user's **context documents** — YouTube videos and local video files they imported with `clipy context import`, so agents can read them. A separate library from their own screen recordings. |\n| `get_context_document` | One context document's metadata: source, duration, tags, the server's classification (video type, whether visual evidence is needed, planned moments), and which transcript/frames exist. Not the transcript itself. |\n| `read_context_document` | Read a context document as compiled markdown — header, metadata, then the timestamped transcript with frame captions interleaved. Takes `startMs`/`endMs` so you can walk a two-hour video section by section instead of flooding your context. |\n| `replace_transcript` | **Replace a recording's transcript** with text you author (needs the `ingest` scope). Call `get_transcript` first and pass its `revision`; stale replacements are rejected instead of overwriting a concurrent edit. The summary regenerates automatically. Marked as agent-edited, never passed off as speech-to-text. |\n\nRead tools accept a recording's **public id** (the slug in its share URL) or the full\n`https://clipy.online/video/<id>` URL.\n\n> **Capturing the real screen is CLI-only.** These tools record a headless Chromium page.\n> To record the actual Mac screen or a window's initial screen area (ScreenCaptureKit — the real\n> logged-in browser), use the Clipy CLI: `clipy record --source mac-screen --window \"<app>\"`.\n\n### Using `record`\n\n`record` opens a URL in a headless Chromium (works in CI / cloud sandboxes, no display),\nrecords for a few seconds, and streams it into Clipy — then returns the id so you can call\n`wait_for_artifacts` and `get_agent_context` to read it back. It needs:\n\n1. **Playwright** in the environment running this MCP server:\n   ```bash\n   npm install -g playwright && npx playwright install chromium\n   ```\n2. An API key with the **\"Record & upload\" (ingest)** permission — choose it when you mint\n   the key at [clipy.online/settings/api-keys](https://clipy.online/settings/api-keys).\n\nParameters: `url` (required, http/https), `durationSeconds` (default 15, max 300, applied\nper viewport pass), `name`, `description`, `type` (recording kind — `bug_report`,\n`feature_request`, `product_demo`, `walkthrough_tutorial`, `feedback_review`,\n`discussion_talk`, `other`, plus aliases), `viewports` (e.g. `mobile,desktop` or\n`390x844,1440x900` — recorded sequentially into one video, frame sized to the largest,\neach pass slow-scrolled and auto-chaptered), `storageState` / `initScript` (paths, never\nlogged), `notes`, and `width`/`height` (default 1280×720, ignored when `viewports` is set).\n\n**Recording behind a login.** `storageState` seeds exactly what its JSON contains (cookies +\nlocalStorage) but can't reproduce a whole browser identity (IndexedDB, service workers, some\ncross-origin auth). For a full identity, pass `userDataDir` — Chrome's **user-data root**\n(macOS: `~/Library/Application Support/Google/Chrome`) — in one of two modes:\n\n- **Copy a named profile (recommended).** Add `profileDirectory` (`\"Profile 1\"`, `\"Default\"`, …\n  — the exact folder from `chrome://version` → *Profile Path*). Clipy **copies** that profile\n  into a temporary root and records the copy, so your real profile is never opened or modified\n  and the copy is deleted after upload. The tool result discloses the copy (profile name, bytes,\n  and a warning if Chrome was running while it was copied).\n\n  > ⚠️ **macOS: cookie logins may not survive the copy.** Chrome encrypts cookies with the\n  > *Chrome Safe Storage* Keychain key; the recorder's bundled Chromium looks for *Chromium Safe\n  > Storage*. So on macOS a copied profile can produce a browser that **looks like your identity\n  > but is silently logged out** wherever the session is cookie-based — `localStorage`/\n  > `Preferences`-based sessions still work. This is a pre-existing Playwright-vs-Chrome\n  > constraint, not something the copy introduces, and the copy disclosure repeats it. **If the\n  > recording lands logged out, that's why.** Record the real browser with the CLI's\n  > `clipy record --source mac-screen`, or drive your own browser and attach evidence via\n  > `add_marker`'s `observed`/`verdict`.\n- **Open the `Default` profile directly.** Omit `profileDirectory`. Clipy opens the root's\n  `Default` profile **and writes to it**, so it's refused while a live Chrome holds it locked —\n  quit Chrome first. When the dir looks like a real Chrome root, the result carries a\n  `userDataDirWarning` saying so and pointing you at `profileDirectory` (ephemeral copy) or the\n  CLI's `--source mac-screen` instead. Prefer those unless you specifically want in-place use.\n\n> Playwright **strips** Chromium's `--profile-directory` (it always loads `Default` from whatever\n> dir it's given), so copying is the only way to record a named profile. Pointing `userDataDir`\n> at a profile subdir (`.../Chrome/Default`) is **refused** — launching from there would silently\n> record a blank, logged-out profile.\n\n`storageState` and `userDataDir` are mutually exclusive; `profileDirectory` requires `userDataDir`.\n\n### Check the camera before you work\n\n`record` and `start_recording` both return a `source` object describing **what is actually\nbeing recorded**, resolved fresh at start time — the post-redirect `url`, the page `title`,\nand the recording `viewport`:\n\n```json\n\"source\": {\n  \"kind\": \"headless_browser\",\n  \"title\": \"Orders — Admin\",\n  \"url\": \"https://app.example.com/orders\",\n  \"viewport\": { \"width\": 1280, \"height\": 720 }\n}\n```\n\nCompare it against the surface your driver is acting on **before** doing minutes of work.\nThis exists because driver-attested evidence proves what the *driver* observed and nothing\nties it to what the *camera* saw — it's entirely possible to produce truthful marks over\nfootage of the wrong thing. **Clipy will never focus or foreground a window or tab for you**;\npointing the driver and the camera at the same surface is the caller's job.\n\n`kind` is always `headless_browser` here: these tools record a headless page Clipy owns.\nCapturing a real application's initial screen area or a display is CLI-only\n(`clipy record --source mac-screen --window \"<app>\"`), so no window id or window title is\nreported — an empty or invented one would be exactly the kind of false confidence this\nfield exists to prevent.\n\n### Evidence on a marker: two provenances\n\n`add_marker` can carry evidence in exactly one of two provenances — they are tallied and rendered\nseparately, never pooled:\n\n| Provenance | How | What it means |\n| --- | --- | --- |\n| **clipy-verified** | `assertSelector` / `assertText` / `assertUrl` | Clipy checked the recorded page itself. Strongest evidence. Renders `[assert ✓ verified-by-clipy; …]`, or `[ASSERT ✗ verified-by-clipy; …]`, or `[ASSERT ⚠ clipy could not evaluate — …]` when it couldn't check. |\n| **driver-attested** | `observed` + `verdict` (both required) | *You* report what your own tooling saw. Clipy vouches only that you **said** it — not that it verified it — which is falsifiable against the recorded frames. Renders with a **hedge glyph** rather than a verdict glyph: `[≈ ASSERT driver-attested; observed=…]`, or `[≈ FAILED driver-attested; observed=…]`. |\n\nUse **driver-attested** when your agent drives its own browser/tooling while Clipy records (e.g.\n`--source mac-screen` on the CLI) or when there's no Clipy-owned page to assert against. It's\nweaker than clipy-verified but far stronger than plain prose. The transcript's leading\n`[verification]` note segments the two, e.g.\n`[verification] 3 clipy-verified: 2 passed, 1 failed · 2 driver-attested: 2 passed, 0 failed`.\n\n### Driving the recorded page over CDP (`start_recording` + `exposeCdp: true`)\n\nPass `exposeCdp: true` to `start_recording` and the recording browser opens a Chrome\nDevTools Protocol endpoint; the result returns `cdpHttpUrl` + `cdpUrl`. Connect your own\nPlaywright and drive the page while Clipy records it:\n\n```js\nconst { chromium } = require(\"playwright\");\nconst browser = await chromium.connectOverCDP(cdpHttpUrl);\nconst page = browser.contexts()[0].pages()[0]; // the page being recorded\nawait page.goto(\"http://localhost:3000/settings\");\nawait browser.close();                          // detaches; the recording keeps going\n```\n\nIt's **off by default** — while it's open, any local process can attach to that browser.\n`CLIPY_DISABLE_CDP=1` is a hard kill switch that forces it off. Gotchas: the recorded page\nis `contexts()[0].pages()[0]` (a new context you open won't be captured); `page.viewportSize()`\nreads `null` over a CDP attach; and to change the viewport use `newCDPSession` +\n`Emulation.setDeviceMetricsOverride`, not `setViewportSize`.\n\n**In-page bridge (zero extra tool calls).** When `exposeCdp` is on, the recorded page also\nexposes `window.__clipyMark(text, opts?)` and `window.__clipyChapter(label)`, so your CDP\ndriver can drop asserted marks/chapters from inside the page:\n\n```js\nawait page.evaluate(() =>\n  window.__clipyMark(\"saved the form\", { assertSelector: \".toast\", assertText: \"Saved\" }),\n);\nawait page.evaluate(() => window.__clipyChapter(\"AFTER — fix applied\"));\n```\n\n`opts` mirrors `add_marker` (`assertSelector` / `assertText` / `assertUrl` / `failMode`);\n`assertText` requires `assertSelector` (the call rejects otherwise), and a failed assert with\n`failMode: \"abort\"` discards the session — same annotations and tally as the tools.\n\n## Config\n\n| Env var | Required | Default | Notes |\n| --- | --- | --- | --- |\n| `CLIPY_API_KEY` | no | `apiKey` from `~/.config/clipy/config.json` | Your personal key from `/settings/api-keys`. Set it only when `clipy login` has not run on this machine; when set it overrides the config file. |\n| `CLIPY_API_URL` | no | `https://clipy.online` | Override for self-hosted/staging. |\n\n## Privacy\n\nYour key only ever reads **your own** recordings. Revoke it any time at\n`/settings/api-keys`. The server runs locally on your machine; your key is never sent\nanywhere except to the Clipy API over HTTPS.\n",
  "bytes": 17578,
  "sha": "96847e3b3001b8b4314e618487b7c2145ad25dd804f17ec8dc75204b8a43a9dc",
  "repo_slug": "manovagyanik1/clipy-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_online_clipy_mcp_ad45aab0/readme"
}