youtube-knowledge-mcp 2.1.0 → 3.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/youtube-knowledge-mcp.svg)](https://www.npmjs.com/package/youtube-knowledge-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/Node.js-22%2B-green.svg)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-22.13%2B-green.svg)](https://nodejs.org/)
 [![GitHub stars](https://img.shields.io/github/stars/teobouancheau/youtube-knowledge-mcp?style=social)](https://github.com/teobouancheau/youtube-knowledge-mcp)
 
 A Model Context Protocol (MCP) server that gives AI assistants the ability to search, analyze, and extract knowledge from YouTube videos. Works with Claude Desktop, Claude Code, Claude.ai, Cursor and any MCP-compatible client.
@@ -18,6 +18,7 @@ Supports both **local** (stdio) and **remote** (Streamable HTTP) transports.
 - **Search** videos and channels by keyword
 - **Fetch** videos from a playlist or channel
 - **Video, channel and playlist metadata**, chapters, and top comments
+- **Thumbnails**: look at any video's thumbnail or a channel's avatar or banner as an image, or save every thumbnail of a channel to disk
 - **Transcripts with timestamps**, sliced by time range or chapter, and capped so a
   three-hour video cannot flood your context
 - **Search inside a transcript** and get back `?t=` links that open the video at
@@ -39,6 +40,19 @@ Supports both **local** (stdio) and **remote** (Streamable HTTP) transports.
 - **Read them back**, and **search across all of them** with full-text ranking
 - **Tag, retag and delete**
 
+**Extract exhaustively, and prove it** (local mode)
+
+- **Catalogue a whole channel** across every tab — videos, shorts, streams,
+  releases, podcasts — into a local SQLite store, resumably
+- **Harvest comments with their replies**, every field YouTube returns, and
+  search them locally with full-text ranking and real pagination
+- **A completeness receipt on every extraction**: `complete` is true only when
+  the server can _prove_ it holds everything in scope, so a partial harvest can
+  never be mistaken for a full history
+- **Ask what you actually have** with `get_coverage`, which never touches the
+  network — cheap enough to call before every claim
+- **Remove what you hold**, including one author's comments everywhere
+
 **Build a brain for a channel** (local mode)
 
 - **Read a whole channel** into a searchable corpus of timestamped passages, in
@@ -50,18 +64,25 @@ Supports both **local** (stdio) and **remote** (Streamable HTTP) transports.
   speaking rate, and the phrases it repeats across videos
 - **Keep a written profile** beside the corpus, grounded in passages you can cite
 
+**Study a channel's thumbnails** (local mode)
+
+- **Save every thumbnail** of a channel, plus its avatar and banner, resumably, at the largest size YouTube serves, with each image's real pixel size recorded
+
 **Built to stay working**
 
 - WebVTT parsed by the W3C reference implementation, not a hand-written matcher
 - Typed, actionable errors — "no captions in en, try: fr, es, de" rather than a
   wall of yt-dlp stderr
-- Timeouts, retry with backoff, and a concurrency limit on every yt-dlp call
+- Timeouts, adaptive backoff and a concurrency limit on every yt-dlp call, with
+  cooldowns and a circuit breaker so a long harvest survives being throttled
 - `check_health` diagnoses missing or outdated yt-dlp and ffmpeg
+- Bearer auth, a loopback default bind, an allowlist on every URL and image host, and typed error codes on every failure
 - Structured output on every tool, plus MCP resources, prompts and completions
+- An end-to-end suite runs the built server against real yt-dlp over both transports every week
 
 ## Prerequisites
 
-- Node.js 22+
+- Node.js 22.13+ — the version where `node:sqlite`, which the harvest store uses, is available without a flag
 - [yt-dlp](https://github.com/yt-dlp/yt-dlp#installation) — required by every tool.
   `brew install yt-dlp` (macOS) or `pip install -U yt-dlp`
 - [ffmpeg](https://ffmpeg.org/) — required for downloads, clip extraction and frame
@@ -154,7 +175,11 @@ npm run build
 npm run start:http
 ```
 
-The server listens on `PORT` (default 3000). Set `PORT` environment variable to change.
+The server listens on `127.0.0.1:PORT` (default 3000). To reach it from another
+machine set `MCP_BIND_HOST=0.0.0.0` together with `MCP_AUTH_TOKEN`; the server
+refuses to start exposed and unauthenticated unless you also set
+`MCP_ALLOW_UNAUTHENTICATED=true`. Behind a reverse proxy, set `MCP_TRUST_PROXY`
+to the number of hops and `MCP_PUBLIC_URL` to the address clients use.
 
 #### Docker
 
@@ -210,7 +235,7 @@ a cold start. Any paid plan removes that.
 
 ## MCP Tools
 
-33 tools. The 14 read-only ones work over both transports; the 19 that touch
+44 tools. The 15 read-only ones work over both transports; the 29 that touch
 your filesystem are registered only in local (stdio) mode, so a remote
 deployment cannot reach the host's disk.
 
@@ -220,18 +245,19 @@ available for this video. Call get_transcript again with one of: fr, es, de.`
 
 ### Discovery — remote + local
 
-| Tool                | Key parameters   | Returns                                                          |
-| ------------------- | ---------------- | ---------------------------------------------------------------- |
-| `search_videos`     | `query`, `limit` | Matching videos with durations, channels and view counts         |
-| `search_channels`   | `query`, `limit` | Matching channels with subscriber counts                         |
-| `fetch_videos`      | `url`, `limit`   | Videos in a playlist or channel                                  |
-| `get_video_info`    | `video`          | Title, channel, duration, views, likes, description, tags        |
-| `get_channel_info`  | `channel`        | Name, handle, subscriber count, description                      |
-| `get_playlist_info` | `url`            | Title, channel, video count, last updated                        |
-| `get_chapters`      | `video`          | Chapter titles with start/end times and deep links               |
-| `get_comments`      | `video`, `limit` | Top-level comments by popularity                                 |
-| `list_formats`      | `video`          | Available formats grouped by video+audio, video-only, audio-only |
-| `check_health`      | —                | yt-dlp and ffmpeg status, versions, and staleness warnings       |
+| Tool                | Key parameters                             | Returns                                                                                           |
+| ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `search_videos`     | `query`, `limit`                           | Matching videos with durations, channels and view counts                                          |
+| `search_channels`   | `query`, `limit`                           | Matching channels with subscriber counts                                                          |
+| `fetch_videos`      | `url`, `limit`, `cursor`                   | One page of a playlist or channel, with a cursor. `total` is present only when YouTube states one |
+| `get_video_info`    | `video`                                    | Title, channel, duration, views, likes, description, tags                                         |
+| `get_channel_info`  | `channel`                                  | Name, handle, subscriber count, description, avatar and banner                                    |
+| `get_playlist_info` | `url`                                      | Title, channel, video count, last updated                                                         |
+| `get_chapters`      | `video`                                    | Chapter titles with start/end times and deep links                                                |
+| `get_comments`      | `video`, `limit`, `includeReplies`, `sort` | Comments with replies and a completeness receipt saying how many of the video's comments this is  |
+| `list_formats`      | `video`                                    | Available formats grouped by video+audio, video-only, audio-only                                  |
+| `get_thumbnail`     | `video`, `channel`, `image`, `quality`     | A video thumbnail, channel avatar or banner as an image, with its real size                       |
+| `check_health`      | —                                          | yt-dlp and ffmpeg status, versions, staleness warnings, and which session options are set         |
 
 ### Transcripts — remote + local
 
@@ -274,6 +300,35 @@ keyframe-aligned cut. All of these require ffmpeg.
 | `delete_library_item`   | `videoId`, `contentType`                                        | What was deleted                    |
 | `rebuild_library_index` | —                                                               | Number of notes reindexed           |
 
+### Exhaustive harvest — local only
+
+Extraction that stores what it reads, and proves what it holds. Every tool here
+returns a **completeness receipt**: `complete` is true only when the server can
+prove it has everything in scope, and a consumer must not describe the data as a
+full history while it is false.
+
+| Tool               | Key parameters                                                         | Returns                                                     |
+| ------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `harvest_channel`  | `channel`, `maxVideos`                                                 | Every video across all tabs, catalogued, with a receipt     |
+| `harvest_comments` | `video`, `maxComments`, `sort`, `maxRepliesPerThread`                  | Comments and replies stored locally, with a receipt         |
+| `get_coverage`     | `scope`, `incompleteOnly`, `verify`, `limit`, `offset`                 | What the server can prove it holds, and what it cannot      |
+| `query_comments`   | `video`, `channel`, `match`, `author`, `threadOf`, `order`, `limit`    | Full-text search over stored comments, with real pagination |
+| `query_videos`     | `channel`, `match`, `since`, `until`, `withComments`, `order`, `limit` | The catalogued videos, filtered and sorted                  |
+| `prune_harvest`    | `channel`, `video`, `author`, `scope`, `confirm`, `vacuum`             | What was removed from the store                             |
+| `repair_store`     | `confirm`                                                              | Moves a damaged store aside and starts a fresh one          |
+
+`get_coverage` never contacts YouTube, so it is cheap enough to call before
+making any claim about the data. Check `anyIncomplete` first.
+
+There is no cursor for comments: YouTube exposes none for a live read, so
+`harvest_comments` cannot page. To get more, run it again with a larger
+`maxComments` — rows are upserted on the comment id, so a re-run costs requests
+and never data.
+
+`prune_harvest` exists because the store holds personal data at scale: display
+names, channel ids and free-text opinions from people who never used this tool.
+The `author` filter is the per-person erasure path.
+
 ### Channel brains — local only
 
 | Tool                 | Key parameters                                                    | Returns                                          |
@@ -289,6 +344,24 @@ keyframe-aligned cut. All of these require ffmpeg.
 channel from what is already on disk, so they work offline and cost nothing to
 call.
 
+### Channel thumbnails — local only
+
+| Tool                        | Key parameters                               | Returns                                                   |
+| --------------------------- | -------------------------------------------- | --------------------------------------------------------- |
+| `fetch_channel_thumbnails`  | `channel`, `maxVideos`, `tabs`, `quality`    | Every thumbnail saved to disk, plus the avatar and banner |
+| `list_channel_thumbnails`   | `channel`, `tab`, `state`, `limit`, `offset` | Saved entries with paths and decoded sizes                |
+| `delete_channel_thumbnails` | `channel`                                    | What was removed                                          |
+
+One yt-dlp listing per tab, then the images from YouTube's image hosts
+directly, so a five-hundred-video channel costs a handful of listings and not
+five hundred extractions. For each video the fetch tries the largest image
+YouTube serves (`maxresdefault`, 1280 wide where it exists) and keeps it only if
+it decodes wider than the image the listing offered; otherwise it keeps the
+listed image, and failing that the small `hqdefault`. Every width and height in
+the manifest was decoded from the saved bytes, never read off a URL. Shorts are
+listed with portrait thumbnails and saved under `shorts/`. The run is resumable:
+interrupt it and call again, and only what is missing or truncated is fetched.
+
 A brain holds one caption language; pass `language` to read another, and build a
 separate brain per language.
 
@@ -309,16 +382,18 @@ skipped forever as already done.
 
 Reusable workflows your client can invoke directly: `summarize_video`,
 `extract_skill`, `compare_videos`, `research_topic`, `channel_deep_dive`,
-`clip_from_quote` (find a phrase, then cut the clip around it), and — local
-only — `review_library`, `create_brain` (build a channel's corpus, then write
-its profile from it) and `ask_creator` (answer a question strictly from a
-brain, with citations).
+`clip_from_quote` (find a phrase, then cut the clip around it),
+`study_thumbnails` (save a channel's thumbnails, look at a sample, describe
+what recurs), and — local only — `review_library`, `create_brain` (build a
+channel's corpus, then write its profile from it) and `ask_creator` (answer a
+question strictly from a brain, with citations).
 
 ## Resources
 
 - `youtube://transcript/{videoId}` — a timestamped transcript, fetched and cached on first read
 - `youtube://library/{videoId}/{summary|skill}` — a saved note (local only, and enumerable)
 - `youtube://brain/{channelId}/{manifest|profile}` — what a channel brain covers, or the profile written from it (local only, and enumerable)
+- `youtube://thumbnails/{channelId}/manifest` — what `fetch_channel_thumbnails` saved for a channel (local only, and enumerable)
 
 ## Error codes
 
@@ -334,25 +409,51 @@ them, each prefixed with a code and followed by a next step.
 | `RATE_LIMITED`, `TIMEOUT`                                           | Transient; retried automatically with backoff before surfacing               |
 | `YTDLP_MISSING`, `FFMPEG_MISSING`, `YTDLP_FAILED`                   | A tooling problem; the message says how to fix it                            |
 | `INVALID_INPUT`                                                     | A bad argument, caught before any network call                               |
+| `BOT_CHECK`                                                         | YouTube asked this address to sign in; set the cookie settings below         |
+| `FETCH_FAILED`                                                      | An image could not be downloaded from YouTube's image hosts                  |
 | `CANCELLED`                                                         | The client cancelled the request                                             |
 
 ## Environment variables
 
 All optional.
 
-| Variable                        | Default   | Purpose                                                                                                  |
-| ------------------------------- | --------- | -------------------------------------------------------------------------------------------------------- |
-| `MCP_AUTH_TOKEN`                | unset     | Require this bearer token on the HTTP transport. **Set this if you expose the server beyond localhost.** |
-| `MCP_ALLOWED_HOSTS`             | unset     | Comma-separated Host allowlist; enables DNS-rebinding protection                                         |
-| `MCP_ALLOWED_ORIGINS`           | unset     | Comma-separated Origin allowlist                                                                         |
-| `MCP_BIND_HOST`                 | `0.0.0.0` | Interface to bind                                                                                        |
-| `PORT`                          | `3000`    | HTTP port. The Docker image sets `10000`; Render and similar platforms inject their own                  |
-| `MCP_RATE_LIMIT`                | `60`      | Requests per window, per client                                                                          |
-| `MCP_RATE_WINDOW_MS`            | `60000`   | Rate-limit window                                                                                        |
-| `MCP_SESSION_IDLE_MS`           | `1800000` | Close HTTP sessions idle this long                                                                       |
-| `MCP_MAX_SESSIONS`              | `1000`    | Reject new sessions past this many                                                                       |
-| `YOUTUBE_MCP_MAX_CONCURRENCY`   | `3`       | Concurrent yt-dlp processes                                                                              |
-| `YOUTUBE_MCP_TRANSCRIPT_TTL_MS` | 30 days   | Transcript cache lifetime                                                                                |
+| Variable                           | Default     | Purpose                                                                                                                                                      |
+| ---------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `MCP_AUTH_TOKEN`                   | unset       | Require this bearer token on the HTTP transport. **Set this if you expose the server beyond localhost.**                                                     |
+| `MCP_ALLOWED_HOSTS`                | unset       | Comma-separated Host allowlist; enables DNS-rebinding protection                                                                                             |
+| `MCP_ALLOWED_ORIGINS`              | unset       | Comma-separated Origin allowlist                                                                                                                             |
+| `MCP_BIND_HOST`                    | `127.0.0.1` | Interface to bind. The Docker image sets `0.0.0.0`. A non-loopback bind refuses to start without `MCP_AUTH_TOKEN` unless `MCP_ALLOW_UNAUTHENTICATED=true`    |
+| `MCP_ALLOW_UNAUTHENTICATED`        | `false`     | Explicit consent to listen on a network interface with no token                                                                                              |
+| `MCP_TRUST_PROXY`                  | `false`     | `true`, `false`, or the number of reverse-proxy hops whose `X-Forwarded-*` headers to believe. Off, forwarded headers are ignored for rate limiting and URLs |
+| `MCP_PUBLIC_URL`                   | unset       | The URL clients reach the server at; used in the OAuth metadata it publishes instead of the request's Host                                                   |
+| `MCP_MAX_BODY_BYTES`               | `1048576`   | Largest request body accepted                                                                                                                                |
+| `MCP_MODE`                         | unset       | `http` selects the HTTP transport when no `--http` flag is given                                                                                             |
+| `PORT`                             | `3000`      | HTTP port. The Docker image sets `10000`; Render and similar platforms inject their own                                                                      |
+| `MCP_RATE_LIMIT`                   | `60`        | Requests per window, per client                                                                                                                              |
+| `MCP_RATE_WINDOW_MS`               | `60000`     | Rate-limit window                                                                                                                                            |
+| `MCP_SESSION_IDLE_MS`              | `1800000`   | Close HTTP sessions idle this long                                                                                                                           |
+| `MCP_MAX_SESSIONS`                 | `1000`      | Reject new sessions past this many                                                                                                                           |
+| `YOUTUBE_MCP_MAX_CONCURRENCY`      | `3`         | Concurrent yt-dlp processes                                                                                                                                  |
+| `YOUTUBE_MCP_TRANSCRIPT_TTL_MS`    | 30 days     | Transcript cache lifetime                                                                                                                                    |
+| `YOUTUBE_MCP_STATS_TTL_MS`         | 1 day       | Per-video stats cache lifetime                                                                                                                               |
+| `YOUTUBE_MCP_COOKIES_FROM_BROWSER` | unset       | Browser whose cookies yt-dlp should read: `brave`, `chrome`, `chromium`, `edge`, `firefox`, `opera`, `safari`, `vivaldi` or `whale`. See Signed-in content   |
+| `YOUTUBE_MCP_COOKIES_FILE`         | unset       | A Netscape-format cookies file inside your home directory, as an alternative to a browser                                                                    |
+| `YOUTUBE_MCP_PROXY`                | unset       | An `http`, `https`, `socks4` or `socks5` proxy URL for yt-dlp                                                                                                |
+| `YOUTUBE_MCP_SLEEP_REQUESTS_S`     | unset       | Seconds yt-dlp sleeps between its own requests, to stay under YouTube's limits                                                                               |
+
+### Signed-in content
+
+Some videos need a signed-in session — age-restricted, members-only, private
+ones you have access to — and YouTube sometimes asks an address to prove it is
+not a bot before serving any video at all. Those failures arrive as
+`LOGIN_REQUIRED`, `AGE_GATED` or `BOT_CHECK`, and each names the fix: set
+`YOUTUBE_MCP_COOKIES_FROM_BROWSER` to a browser you are signed in with, or
+`YOUTUBE_MCP_COOKIES_FILE` to a cookies file, and restart the server.
+
+Cookies are your account. Use them in local (stdio) mode, keep a cookies file
+readable by you alone, and know that content read this way may be personal.
+The server validates both settings at boot, never logs the file's path or
+contents, and never surfaces yt-dlp's output.
 
 ## Library Storage
 
@@ -372,6 +473,13 @@ Content is stored in `~/.youtube-knowledge/`:
 │       ├── manifest.json # What the brain covers, and where a build stopped
 │       ├── chunks.json   # The timestamped passages
 │       └── profile.md    # The written account, if one was saved
+├── thumbnails/           # Saved channel thumbnails
+│   └── {channel_id}/
+│       ├── manifest.json # Every image, its decoded size, where it is
+│       ├── channel/      # avatar.* and banner.*
+│       ├── videos/       # {video_id}.jpg (or .png / .webp)
+│       ├── shorts/
+│       └── streams/
 ├── downloads/            # Full downloads
 ├── clips/                # Extracted clips
 ├── frames/               # Captured stills
@@ -469,6 +577,11 @@ client over an in-memory transport, exercises the library against a real
 temporary filesystem, and snapshots the tool manifest so any change to the
 public surface shows up as a reviewable diff.
 
+An end-to-end lane (`E2E=1 npm run test:e2e`) drives the built server through
+real MCP clients over both transports against real yt-dlp and the real network,
+in an isolated temporary home. It runs weekly in CI and on every release before
+anything is published; see CONTRIBUTING.md.
+
 ## Development
 
 ```bash
@@ -480,7 +593,7 @@ npm run start:http # Run server (HTTP)
 npm run validate   # Typecheck + lint + format check + test
 ```
 
-CI runs the same gate on Node 22 and 24 for every push and pull request,
+CI runs the same gate on Node 22.22, 22 and 24 for every push and pull request,
 then boots the built server as a real MCP client to verify the manifest.
 
 ## Contributing
@@ -490,9 +603,11 @@ project layout, coding standards, and how to add a tool.
 
 ## Security
 
-The HTTP transport is unauthenticated unless you set `MCP_AUTH_TOKEN`. See
-[SECURITY.md](SECURITY.md) before exposing it beyond localhost, and to report a
-vulnerability.
+The HTTP transport binds loopback and refuses to listen on a network interface
+without `MCP_AUTH_TOKEN`. Caller-supplied URLs must be on a YouTube host before
+anything is handed to yt-dlp, every yt-dlp target follows a `--` terminator, and
+ids are validated before they become paths. See [SECURITY.md](SECURITY.md) for
+the deployment checklist and how to report a vulnerability.
 
 ## License
 

package/dist/brain-schemas.d.ts

@@ -226,6 +226,8 @@ export declare const brainManifestSchema: z.ZodObject<{
         subscriberCount: z.ZodNumber;
         channelUrl: z.ZodString;
         description: z.ZodString;
+        avatarUrl: z.ZodOptional<z.ZodString>;
+        bannerUrl: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         description: string;
         name: string;
@@ -233,6 +235,8 @@ export declare const brainManifestSchema: z.ZodObject<{
         handle: string;
         subscriberCount: number;
         channelUrl: string;
+        avatarUrl?: string | undefined;
+        bannerUrl?: string | undefined;
     }, {
         description: string;
         name: string;
@@ -240,6 +244,8 @@ export declare const brainManifestSchema: z.ZodObject<{
         handle: string;
         subscriberCount: number;
         channelUrl: string;
+        avatarUrl?: string | undefined;
+        bannerUrl?: string | undefined;
     }>;
     /**
      * A brain is built from one caption language. Defaulted rather than required
@@ -345,6 +351,8 @@ export declare const brainManifestSchema: z.ZodObject<{
         handle: string;
         subscriberCount: number;
         channelUrl: string;
+        avatarUrl?: string | undefined;
+        bannerUrl?: string | undefined;
     };
     version: number;
     videos: Record<string, {
@@ -391,6 +399,8 @@ export declare const brainManifestSchema: z.ZodObject<{
         handle: string;
         subscriberCount: number;
         channelUrl: string;
+        avatarUrl?: string | undefined;
+        bannerUrl?: string | undefined;
     };
     version: number;
     videos: Record<string, unknown>;
@@ -489,14 +499,4 @@ export declare const brainSummarySchema: z.ZodObject<{
     updatedAt: string;
     hasProfile: boolean;
 }>;
-export declare const brainLockSchema: z.ZodObject<{
-    pid: z.ZodNumber;
-    startedAt: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    pid: number;
-    startedAt: string;
-}, {
-    pid: number;
-    startedAt: string;
-}>;
 //# sourceMappingURL=brain-schemas.d.ts.map

package/dist/brain-schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brain-schemas.d.ts","sourceRoot":"","sources":["../src/brain-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AAEH,qDAAqD;AACrD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAchC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,uDAAuD;AACvD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;EAO3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG/B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;EAI5B,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;;;;;;EAGpC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmB3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,4BAA4B;AAC5B,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;IAG9B;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMH,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,8BAA8B;AAC9B,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY7B,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;EAG1B,CAAC"}
+{"version":3,"file":"brain-schemas.d.ts","sourceRoot":"","sources":["../src/brain-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AAEH,qDAAqD;AACrD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAchC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,uDAAuD;AACvD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;EAO3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG/B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;EAI5B,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;;;;;;EAGpC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmB3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,4BAA4B;AAC5B,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAG9B;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMH,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,8BAA8B;AAC9B,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY7B,CAAC"}

package/dist/brain-schemas.js

@@ -106,8 +106,4 @@ export const brainSummarySchema = z.object({
     indexedCount: z.number().int(),
     chunkCount: z.number().int(),
 });
-export const brainLockSchema = z.object({
-    pid: z.number().int(),
-    startedAt: z.string(),
-});
 //# sourceMappingURL=brain-schemas.js.map

package/dist/brain-schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"brain-schemas.js","sourceRoot":"","sources":["../src/brain-schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"brain-schemas.js","sourceRoot":"","sources":["../src/brain-schemas.ts"],"names":[],"mappings":"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"}

package/dist/harvest-schemas.d.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+/**
+ * The shapes a completeness receipt is made of.
+ *
+ * This server exists to extract everything YouTube will serve, and the failure
+ * mode that matters is not "we got 3%" — it is "we got 3% and reported 100%".
+ * A receipt travels with every extraction result so a consumer can never
+ * describe a sample as a full history by accident.
+ *
+ * The invariants that make `complete` mean something live in
+ * `utils/coverage.ts`, which is the only place allowed to build one.
+ */
+export declare const harvestScopeSchema: z.ZodEnum<["channel-catalog", "video-details", "video-comments"]>;
+export type HarvestScope = z.infer<typeof harvestScopeSchema>;
+export declare const completenessReasonSchema: z.ZodEnum<["COMPLETE", "CAP_REACHED", "BUDGET_SPENT", "RATE_LIMITED", "CANCELLED", "TIMEOUT", "SOURCE_REFUSED", "COMMENTS_DISABLED", "SOURCE_SILENT", "PARTIAL_ERROR", "NOT_ATTEMPTED"]>;
+export type CompletenessReason = z.infer<typeof completenessReasonSchema>;
+/**
+ * Where a total came from.
+ *
+ * `source-exhausted` is the one value that is not a number YouTube reported:
+ * it means the listing ended on its own, which is its own kind of proof.
+ */
+export declare const expectedSourceSchema: z.ZodEnum<["youtube:comment_count", "youtube:playlist_count", "source-exhausted"]>;
+export type ExpectedSource = z.infer<typeof expectedSourceSchema>;
+export declare const coverageSchema: z.ZodObject<{
+    scope: z.ZodEnum<["channel-catalog", "video-details", "video-comments"]>;
+    targetId: z.ZodString;
+    complete: z.ZodBoolean;
+    reason: z.ZodEnum<["COMPLETE", "CAP_REACHED", "BUDGET_SPENT", "RATE_LIMITED", "CANCELLED", "TIMEOUT", "SOURCE_REFUSED", "COMMENTS_DISABLED", "SOURCE_SILENT", "PARTIAL_ERROR", "NOT_ATTEMPTED"]>;
+    have: z.ZodNumber;
+    expected: z.ZodOptional<z.ZodNumber>;
+    expectedSource: z.ZodOptional<z.ZodEnum<["youtube:comment_count", "youtube:playlist_count", "source-exhausted"]>>;
+    ranToExhaustion: z.ZodOptional<z.ZodBoolean>;
+    source: z.ZodString;
+    harvestedAt: z.ZodString;
+    staleAfter: z.ZodOptional<z.ZodString>;
+    limitApplied: z.ZodOptional<z.ZodNumber>;
+    sortApplied: z.ZodOptional<z.ZodEnum<["top", "new"]>>;
+    resumeToken: z.ZodOptional<z.ZodString>;
+    note: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    have: number;
+    scope: "channel-catalog" | "video-details" | "video-comments";
+    targetId: string;
+    complete: boolean;
+    reason: "RATE_LIMITED" | "TIMEOUT" | "CANCELLED" | "COMPLETE" | "CAP_REACHED" | "BUDGET_SPENT" | "SOURCE_REFUSED" | "COMMENTS_DISABLED" | "SOURCE_SILENT" | "PARTIAL_ERROR" | "NOT_ATTEMPTED";
+    source: string;
+    harvestedAt: string;
+    expected?: number | undefined;
+    note?: string | undefined;
+    ranToExhaustion?: boolean | undefined;
+    expectedSource?: "youtube:playlist_count" | "source-exhausted" | "youtube:comment_count" | undefined;
+    staleAfter?: string | undefined;
+    limitApplied?: number | undefined;
+    sortApplied?: "top" | "new" | undefined;
+    resumeToken?: string | undefined;
+}, {
+    have: number;
+    scope: "channel-catalog" | "video-details" | "video-comments";
+    targetId: string;
+    complete: boolean;
+    reason: "RATE_LIMITED" | "TIMEOUT" | "CANCELLED" | "COMPLETE" | "CAP_REACHED" | "BUDGET_SPENT" | "SOURCE_REFUSED" | "COMMENTS_DISABLED" | "SOURCE_SILENT" | "PARTIAL_ERROR" | "NOT_ATTEMPTED";
+    source: string;
+    harvestedAt: string;
+    expected?: number | undefined;
+    note?: string | undefined;
+    ranToExhaustion?: boolean | undefined;
+    expectedSource?: "youtube:playlist_count" | "source-exhausted" | "youtube:comment_count" | undefined;
+    staleAfter?: string | undefined;
+    limitApplied?: number | undefined;
+    sortApplied?: "top" | "new" | undefined;
+    resumeToken?: string | undefined;
+}>;
+export type Coverage = z.infer<typeof coverageSchema>;
+//# sourceMappingURL=harvest-schemas.d.ts.map

package/dist/harvest-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harvest-schemas.d.ts","sourceRoot":"","sources":["../src/harvest-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,kBAAkB,mEAO7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,wBAAwB,0LAqBnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,oFAI/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4EzB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/harvest-schemas.js

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+/**
+ * The shapes a completeness receipt is made of.
+ *
+ * This server exists to extract everything YouTube will serve, and the failure
+ * mode that matters is not "we got 3%" — it is "we got 3% and reported 100%".
+ * A receipt travels with every extraction result so a consumer can never
+ * describe a sample as a full history by accident.
+ *
+ * The invariants that make `complete` mean something live in
+ * `utils/coverage.ts`, which is the only place allowed to build one.
+ */
+export const harvestScopeSchema = z.enum([
+    /** Which videos a channel has. */
+    'channel-catalog',
+    /** Full per-video metadata snapshots. */
+    'video-details',
+    /** Comments and replies for one video. */
+    'video-comments',
+]);
+export const completenessReasonSchema = z.enum([
+    /** Provably everything: the source stated a total and we hold it, or the source ran out. */
+    'COMPLETE',
+    /** The caller's own limit stopped it. */
+    'CAP_REACHED',
+    /** The wall-clock budget for this call ran out. */
+    'BUDGET_SPENT',
+    /** YouTube throttled this client. */
+    'RATE_LIMITED',
+    /** The MCP client aborted the request. */
+    'CANCELLED',
+    'TIMEOUT',
+    /** BOT_CHECK, LOGIN_REQUIRED, PRIVATE, AGE_GATED or MEMBERS_ONLY. */
+    'SOURCE_REFUSED',
+    /** Comments are turned off for this video, so zero is the true total. */
+    'COMMENTS_DISABLED',
+    /** The source states no total, so exhaustion is unprovable. */
+    'SOURCE_SILENT',
+    /** Some items failed; each cost only itself. */
+    'PARTIAL_ERROR',
+    'NOT_ATTEMPTED',
+]);
+/**
+ * Where a total came from.
+ *
+ * `source-exhausted` is the one value that is not a number YouTube reported:
+ * it means the listing ended on its own, which is its own kind of proof.
+ */
+export const expectedSourceSchema = z.enum([
+    'youtube:comment_count',
+    'youtube:playlist_count',
+    'source-exhausted',
+]);
+export const coverageSchema = z.object({
+    scope: harvestScopeSchema,
+    targetId: z.string().describe('Channel id for a catalog, video id for details or comments'),
+    complete: z
+        .boolean()
+        .describe('True ONLY when this server can prove it holds every item in scope. False means the ' +
+        'data is a SAMPLE. A consumer must not describe it as a full history while this is false.'),
+    reason: completenessReasonSchema.describe('Why complete is what it is. Always present, including when complete is true.'),
+    have: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe('Items this store actually holds for this target, counted from the store.'),
+    expected: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('The total the SOURCE states. Absent when the source states none — never inferred, ' +
+        'never copied from have. Absent with complete:false means "unknown how much is missing".'),
+    expectedSource: expectedSourceSchema
+        .optional()
+        .describe('Where expected came from. Absent if and only if expected is absent.'),
+    ranToExhaustion: z
+        .boolean()
+        .optional()
+        .describe("Whether the source's own iteration finished rather than being cut off. Necessary for " +
+        'completeness but not sufficient: a cap also ends iteration.'),
+    source: z.string().describe('The exact extraction path, including tool version and flags.'),
+    harvestedAt: z.string().describe('ISO-8601 of the last item written for this target'),
+    staleAfter: z
+        .string()
+        .optional()
+        .describe('ISO-8601 after which this should be re-checked. Comments accrue, so a complete ' +
+        'receipt goes stale without becoming wrong.'),
+    limitApplied: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('The cap the caller asked for. Present if and only if one was applied.'),
+    sortApplied: z
+        .enum(['top', 'new'])
+        .optional()
+        .describe('Ordering the source applied. A capped "top" harvest is a BIASED PREFIX of a stream, ' +
+        'not a random sample.'),
+    resumeToken: z
+        .string()
+        .optional()
+        .describe('Opaque. Pass to the same tool to continue. Absent if and only if complete.'),
+    note: z.string().optional(),
+});
+//# sourceMappingURL=harvest-schemas.js.map

package/dist/harvest-schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harvest-schemas.js","sourceRoot":"","sources":["../src/harvest-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,IAAI,CAAC;IACvC,kCAAkC;IAClC,iBAAiB;IACjB,yCAAyC;IACzC,eAAe;IACf,0CAA0C;IAC1C,gBAAgB;CACjB,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC7C,4FAA4F;IAC5F,UAAU;IACV,yCAAyC;IACzC,aAAa;IACb,mDAAmD;IACnD,cAAc;IACd,qCAAqC;IACrC,cAAc;IACd,0CAA0C;IAC1C,WAAW;IACX,SAAS;IACT,qEAAqE;IACrE,gBAAgB;IAChB,yEAAyE;IACzE,mBAAmB;IACnB,+DAA+D;IAC/D,eAAe;IACf,gDAAgD;IAChD,eAAe;IACf,eAAe;CAChB,CAAC,CAAC;AAGH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC;IACzC,uBAAuB;IACvB,wBAAwB;IACxB,kBAAkB;CACnB,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,KAAK,EAAE,kBAAkB;IACzB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4DAA4D,CAAC;IAE3F,QAAQ,EAAE,CAAC;SACR,OAAO,EAAE;SACT,QAAQ,CACP,qFAAqF;QACnF,0FAA0F,CAC7F;IAEH,MAAM,EAAE,wBAAwB,CAAC,QAAQ,CACvC,8EAA8E,CAC/E;IAED,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,EAAE;SACL,WAAW,EAAE;SACb,QAAQ,CAAC,0EAA0E,CAAC;IAEvF,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,EAAE;SACL,WAAW,EAAE;SACb,QAAQ,EAAE;SACV,QAAQ,CACP,oFAAoF;QAClF,yFAAyF,CAC5F;IAEH,cAAc,EAAE,oBAAoB;SACjC,QAAQ,EAAE;SACV,QAAQ,CAAC,qEAAqE,CAAC;IAElF,eAAe,EAAE,CAAC;SACf,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,uFAAuF;QACrF,6DAA6D,CAChE;IAEH,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8DAA8D,CAAC;IAE3F,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;IAErF,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,iFAAiF;QAC/E,4CAA4C,CAC/C;IAEH,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,QAAQ,EAAE;SACV,QAAQ,CAAC,uEAAuE,CAAC;IAEpF,WAAW,EAAE,CAAC;SACX,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;SACpB,QAAQ,EAAE;SACV,QAAQ,CACP,sFAAsF;QACpF,sBAAsB,CACzB;IAEH,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,4EAA4E,CAAC;IAEzF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC"}

package/dist/http/app.d.ts

@@ -0,0 +1,16 @@
+import type { Express } from 'express';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type HttpConfig } from './config.js';
+import type { RateLimiter } from './rate-limiter.js';
+import type { SessionStore } from './sessions.js';
+/** The Express application: routes, authentication and rate limiting. */
+export interface AppDependencies {
+    createServer: (mode: 'http') => McpServer;
+    sessions: SessionStore;
+    limiter: RateLimiter;
+    /** The bound port, known only once listening; read lazily for that reason. */
+    port: () => number;
+    startedAt: number;
+}
+export declare function buildApp(config: HttpConfig, deps: AppDependencies): Express;
+//# sourceMappingURL=app.d.ts.map

package/dist/http/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/http/app.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAmC,MAAM,SAAS,CAAC;AAOxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAYzE,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,yEAAyE;AAEzE,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,CAAC;IAC1C,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,WAAW,CAAC;IACrB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAqK3E"}