unwatched-mcp

Video URL in → validated runbook out. MCP server + CLI for UNWATCHED. Any AI agent (Claude Code, Cursor, any MCP client) can decode a video into a validated, structured runbook by calling the UNWATCHED API.

Requires Node.js ≥ 18 and an API key from https://unwatched.cloud/app/settings → API Keys.

60-second quickstart

# 1. Install
npm i -g unwatched-mcp        # or use npx below without installing

# 2. Set your key
export UNWATCHED_API_KEY=uk_live_...     # or: ~/.config/unwatched/config

# 3. Decode a video (starts the job, waits, writes the runbook)
unwatched decode "https://www.youtube.com/watch?v=VIDEO_ID" --format yaml -o runbook.yaml

That's it: runbook.yaml now holds the validated runbook.

CLI

unwatched decode <url> [--profile agent] [--format md|yaml|json] [-o file] [--timeout 600]
unwatched library [query] [--json]
unwatched status <job_id> [--wait] [--timeout 600]

• decode starts a job, polls until it completes, fetches the runbook and writes it to -o <file> (or stdout).
• library lists your tenant's previous decodes; query filters client-side.
• status shows job status + artifact list.

API key resolution

1. UNWATCHED_API_KEY environment variable
2. ~/.config/unwatched/config — a file containing either UNWATCHED_API_KEY=uk_live_... or the bare key on one line

UNWATCHED_BASE_URL overrides the API base URL (default https://unwatched.cloud/api/v1).

MCP server

The package ships an MCP server (stdio transport) with these tools:

| Tool | What it does | |---|---| | decode_video(url, profiles?) | start a decode job → returns job_id | | get_job(job_id) | status + artifact list | | get_runbook(job_id, video_id, format: md\|yaml\|json) | runbook content | | list_library(query?) | previous decodes of your tenant | | wait_for_job(job_id, timeout_s=600) | poll until completed/partial/failed |

Typical agent flow: decode_video → wait_for_job → get_job (find the video_id) → get_runbook.

Errors are mapped to actionable messages: 401 → check your API key, 402 → quota exhausted, upgrade at https://unwatched.cloud/app/settings, 429 → rate limited (respects Retry-After).

Claude Code

claude mcp add unwatched --env UNWATCHED_API_KEY=uk_live_... -- npx -y unwatched-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "unwatched": {
      "command": "npx",
      "args": ["-y", "unwatched-mcp"],
      "env": { "UNWATCHED_API_KEY": "uk_live_..." }
    }
  }
}

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "unwatched": {
      "command": "npx",
      "args": ["-y", "unwatched-mcp"],
      "env": { "UNWATCHED_API_KEY": "uk_live_..." }
    }
  }
}

Any other MCP client

Run the server directly over stdio:

UNWATCHED_API_KEY=uk_live_... npx -y unwatched-mcp
# or, when installed globally:
unwatched-mcp

Development

npm install
npm run build
npm test          # smoke tests of the API client with mocked HTTP

Layout: src/api-client.ts (REST wrapper + error mapping), src/cli.ts (commander CLI), src/mcp-server.ts (stdio MCP server), src/config.ts (key/base-URL resolution).

License

MIT