youtube-knowledge-mcp 2.0.2 → 2.1.0

package/README.md

@@ -39,6 +39,17 @@ 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**
 
+**Build a brain for a channel** (local mode)
+
+- **Read a whole channel** into a searchable corpus of timestamped passages, in
+  any caption language, resumable and safe to interrupt — a second run continues
+  where it stopped and picks up new uploads
+- **Ask what a creator has said** about anything, across every video, and get
+  back the moments themselves with links that open the video there
+- **Measure the channel**: how much was readable, its upload rhythm, its
+  speaking rate, and the phrases it repeats across videos
+- **Keep a written profile** beside the corpus, grounded in passages you can cite
+
 **Built to stay working**
 
 - WebVTT parsed by the W3C reference implementation, not a hand-written matcher
@@ -199,7 +210,7 @@ a cold start. Any paid plan removes that.
 
 ## MCP Tools
 
-27 tools. The 14 read-only ones work over both transports; the 13 that touch
+33 tools. The 14 read-only ones work over both transports; the 19 that touch
 your filesystem are registered only in local (stdio) mode, so a remote
 deployment cannot reach the host's disk.
 
@@ -258,22 +269,56 @@ keyframe-aligned cut. All of these require ffmpeg.
 | `save_to_library`       | `videoId`, `title`, `content`, `contentType`, `channel`, `tags` | Path to the saved note              |
 | `list_library`          | `tag`                                                           | Saved items, newest first           |
 | `get_library_item`      | `videoId`, `contentType`                                        | The saved markdown and its metadata |
-| `search_library`        | `query`, `limit`                                                | Ranked matches with excerpts        |
+| `search_library`        | `query`, `limit`, `offset`                                      | Ranked matches with excerpts        |
 | `update_library_tags`   | `videoId`, `add`, `remove`, `replace`                           | The updated tags                    |
 | `delete_library_item`   | `videoId`, `contentType`                                        | What was deleted                    |
 | `rebuild_library_index` | —                                                               | Number of notes reindexed           |
 
+### Channel brains — local only
+
+| Tool                 | Key parameters                                                    | Returns                                          |
+| -------------------- | ----------------------------------------------------------------- | ------------------------------------------------ |
+| `build_brain`        | `channel`, `maxVideos`, `language`, `since`, `minDurationSeconds` | What was read, what was ruled out, and the stats |
+| `ask_brain`          | `channel`, `query`, `limit`, `offset`                             | Passages with timestamps and `?t=` links         |
+| `list_brains`        | —                                                                 | Every brain built locally                        |
+| `get_brain_info`     | `channel`, `includeVideos`                                        | Coverage, statistics and repeated phrases        |
+| `save_brain_profile` | `channel`, `content`                                              | Path to the saved profile                        |
+| `delete_brain`       | `channel`                                                         | What was removed                                 |
+
+`build_brain` is the only one that touches the network. The rest resolve a
+channel from what is already on disk, so they work offline and cost nothing to
+call.
+
+A brain holds one caption language; pass `language` to read another, and build a
+separate brain per language.
+
+`since` and `minDurationSeconds` describe the brain, not just the call that
+passed them. They are re-applied every time, so narrowing one drops the passages
+of the videos it excludes and widening it reads them back — which is why
+`build_brain` is annotated as destructive. Whether a video qualifies is decided
+from the date and length already recorded, so changing your mind costs no
+requests until there is something new to fetch. Those values come from each
+video's own metadata, never from a guess: a flat channel listing does not carry
+a publication date at all.
+
+`build_brain` also repairs. If the passage file is lost or truncated, the videos
+it can no longer account for are read again on the next call rather than being
+skipped forever as already done.
+
 ## Prompts
 
 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
-`review_library` (local only).
+`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).
 
 ## 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)
 
 ## Error codes
 
@@ -322,6 +367,11 @@ Content is stored in `~/.youtube-knowledge/`:
 │       ├── metadata.json
 │       ├── summary.md
 │       └── skill.md
+├── brains/               # Channel brains
+│   └── {channel_id}/
+│       ├── 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
 ├── downloads/            # Full downloads
 ├── clips/                # Extracted clips
 ├── frames/               # Captured stills
@@ -394,6 +444,18 @@ editor can import.
 `save_to_library` stores it; `search_library` searches across everything saved
 with full-text ranking.
 
+### Build a brain for a creator
+
+```
+"Build a brain for @Fireship, then tell me everything they've said about Rust"
+```
+
+`build_brain` reads the channel into timestamped passages — interrupt it and
+call it again to continue. `ask_brain` then answers from what was actually
+said, returning the moments themselves so every claim can be checked against
+the video. Run `build_brain` again a month later and it reads only the new
+uploads.
+
 ## Testing
 
 ```bash

package/dist/brain-schemas.d.ts

@@ -0,0 +1,502 @@
+import { z } from 'zod';
+/**
+ * The shapes a channel brain is made of.
+ *
+ * Split from `schemas.ts` only for size; the rule there applies here too — a
+ * shape is declared once and used by both the persistence layer and the tools
+ * that report it, so the file on disk and the tool result cannot drift apart.
+ */
+/** Why a video is, or is not, part of the corpus. */
+export declare const brainVideoStateSchema: z.ZodObject<{
+    videoId: z.ZodString;
+    title: z.ZodString;
+    url: z.ZodString;
+    uploadDate: z.ZodString;
+    durationSeconds: z.ZodNumber;
+    state: z.ZodEnum<["pending", "indexed", "no-captions", "failed", "excluded"]>;
+    chunkCount: z.ZodNumber;
+    wordCount: z.ZodNumber;
+    error: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    durationSeconds: number;
+    url: string;
+    uploadDate: string;
+    videoId: string;
+    state: "pending" | "indexed" | "no-captions" | "failed" | "excluded";
+    chunkCount: number;
+    wordCount: number;
+    error?: string | undefined;
+}, {
+    title: string;
+    durationSeconds: number;
+    url: string;
+    uploadDate: string;
+    videoId: string;
+    state: "pending" | "indexed" | "no-captions" | "failed" | "excluded";
+    chunkCount: number;
+    wordCount: number;
+    error?: string | undefined;
+}>;
+export type BrainVideoState = z.infer<typeof brainVideoStateSchema>;
+/** One passage of speech, addressable by timestamp. */
+export declare const brainChunkSchema: z.ZodObject<{
+    id: z.ZodString;
+    videoId: z.ZodString;
+    title: z.ZodString;
+    startSeconds: z.ZodNumber;
+    endSeconds: z.ZodNumber;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    startSeconds: number;
+    endSeconds: number;
+    text: string;
+    videoId: string;
+}, {
+    id: string;
+    title: string;
+    startSeconds: number;
+    endSeconds: number;
+    text: string;
+    videoId: string;
+}>;
+export type BrainChunk = z.infer<typeof brainChunkSchema>;
+export declare const brainChunkFileSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    chunks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        videoId: z.ZodString;
+        title: z.ZodString;
+        startSeconds: z.ZodNumber;
+        endSeconds: z.ZodNumber;
+        text: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        title: string;
+        startSeconds: number;
+        endSeconds: number;
+        text: string;
+        videoId: string;
+    }, {
+        id: string;
+        title: string;
+        startSeconds: number;
+        endSeconds: number;
+        text: string;
+        videoId: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    version: number;
+    chunks: {
+        id: string;
+        title: string;
+        startSeconds: number;
+        endSeconds: number;
+        text: string;
+        videoId: string;
+    }[];
+}, {
+    version: number;
+    chunks: {
+        id: string;
+        title: string;
+        startSeconds: number;
+        endSeconds: number;
+        text: string;
+        videoId: string;
+    }[];
+}>;
+export declare const brainPhraseSchema: z.ZodObject<{
+    phrase: z.ZodString;
+    videoCount: z.ZodNumber;
+    occurrences: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    videoCount: number;
+    phrase: string;
+    occurrences: number;
+}, {
+    videoCount: number;
+    phrase: string;
+    occurrences: number;
+}>;
+export declare const brainMonthlyUploadsSchema: z.ZodObject<{
+    month: z.ZodString;
+    videos: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    month: string;
+    videos: number;
+}, {
+    month: string;
+    videos: number;
+}>;
+/**
+ * What the server can state about a channel without inferring anything.
+ *
+ * Everything here is counted or measured. Claims about what a creator thinks
+ * belong in the profile, which a model writes from quotes it can cite.
+ */
+export declare const brainStatsSchema: z.ZodObject<{
+    videoCount: z.ZodNumber;
+    excludedCount: z.ZodNumber;
+    indexedCount: z.ZodNumber;
+    noCaptionsCount: z.ZodNumber;
+    failedCount: z.ZodNumber;
+    pendingCount: z.ZodNumber;
+    chunkCount: z.ZodNumber;
+    totalWords: z.ZodNumber;
+    medianWordsPerMinute: z.ZodNumber;
+    firstUpload: z.ZodOptional<z.ZodString>;
+    lastUpload: z.ZodOptional<z.ZodString>;
+    uploadsPerMonth: z.ZodArray<z.ZodObject<{
+        month: z.ZodString;
+        videos: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        month: string;
+        videos: number;
+    }, {
+        month: string;
+        videos: number;
+    }>, "many">;
+    recurringPhrases: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        phrase: z.ZodString;
+        videoCount: z.ZodNumber;
+        occurrences: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        videoCount: number;
+        phrase: string;
+        occurrences: number;
+    }, {
+        videoCount: number;
+        phrase: string;
+        occurrences: number;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    videoCount: number;
+    chunkCount: number;
+    excludedCount: number;
+    indexedCount: number;
+    noCaptionsCount: number;
+    failedCount: number;
+    pendingCount: number;
+    totalWords: number;
+    medianWordsPerMinute: number;
+    uploadsPerMonth: {
+        month: string;
+        videos: number;
+    }[];
+    firstUpload?: string | undefined;
+    lastUpload?: string | undefined;
+    recurringPhrases?: {
+        videoCount: number;
+        phrase: string;
+        occurrences: number;
+    }[] | undefined;
+}, {
+    videoCount: number;
+    chunkCount: number;
+    excludedCount: number;
+    indexedCount: number;
+    noCaptionsCount: number;
+    failedCount: number;
+    pendingCount: number;
+    totalWords: number;
+    medianWordsPerMinute: number;
+    uploadsPerMonth: {
+        month: string;
+        videos: number;
+    }[];
+    firstUpload?: string | undefined;
+    lastUpload?: string | undefined;
+    recurringPhrases?: {
+        videoCount: number;
+        phrase: string;
+        occurrences: number;
+    }[] | undefined;
+}>;
+export type BrainStats = z.infer<typeof brainStatsSchema>;
+/** The on-disk document. */
+export declare const brainManifestSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    channel: z.ZodObject<{
+        name: z.ZodString;
+        channelId: z.ZodString;
+        handle: z.ZodString;
+        subscriberCount: z.ZodNumber;
+        channelUrl: z.ZodString;
+        description: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        name: string;
+        channelId: string;
+        handle: string;
+        subscriberCount: number;
+        channelUrl: string;
+    }, {
+        description: string;
+        name: string;
+        channelId: string;
+        handle: string;
+        subscriberCount: number;
+        channelUrl: string;
+    }>;
+    /**
+     * A brain is built from one caption language. Defaulted rather than required
+     * so a manifest written before this existed still reads back.
+     */
+    language: z.ZodDefault<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    videos: z.ZodType<Record<string, {
+        title: string;
+        durationSeconds: number;
+        url: string;
+        uploadDate: string;
+        videoId: string;
+        state: "pending" | "indexed" | "no-captions" | "failed" | "excluded";
+        chunkCount: number;
+        wordCount: number;
+        error?: string | undefined;
+    }>, z.ZodTypeDef, Record<string, unknown>>;
+    stats: z.ZodObject<{
+        videoCount: z.ZodNumber;
+        excludedCount: z.ZodNumber;
+        indexedCount: z.ZodNumber;
+        noCaptionsCount: z.ZodNumber;
+        failedCount: z.ZodNumber;
+        pendingCount: z.ZodNumber;
+        chunkCount: z.ZodNumber;
+        totalWords: z.ZodNumber;
+        medianWordsPerMinute: z.ZodNumber;
+        firstUpload: z.ZodOptional<z.ZodString>;
+        lastUpload: z.ZodOptional<z.ZodString>;
+        uploadsPerMonth: z.ZodArray<z.ZodObject<{
+            month: z.ZodString;
+            videos: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            month: string;
+            videos: number;
+        }, {
+            month: string;
+            videos: number;
+        }>, "many">;
+        recurringPhrases: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            phrase: z.ZodString;
+            videoCount: z.ZodNumber;
+            occurrences: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }, {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        videoCount: number;
+        chunkCount: number;
+        excludedCount: number;
+        indexedCount: number;
+        noCaptionsCount: number;
+        failedCount: number;
+        pendingCount: number;
+        totalWords: number;
+        medianWordsPerMinute: number;
+        uploadsPerMonth: {
+            month: string;
+            videos: number;
+        }[];
+        firstUpload?: string | undefined;
+        lastUpload?: string | undefined;
+        recurringPhrases?: {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }[] | undefined;
+    }, {
+        videoCount: number;
+        chunkCount: number;
+        excludedCount: number;
+        indexedCount: number;
+        noCaptionsCount: number;
+        failedCount: number;
+        pendingCount: number;
+        totalWords: number;
+        medianWordsPerMinute: number;
+        uploadsPerMonth: {
+            month: string;
+            videos: number;
+        }[];
+        firstUpload?: string | undefined;
+        lastUpload?: string | undefined;
+        recurringPhrases?: {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }[] | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    channel: {
+        description: string;
+        name: string;
+        channelId: string;
+        handle: string;
+        subscriberCount: number;
+        channelUrl: string;
+    };
+    version: number;
+    videos: Record<string, {
+        title: string;
+        durationSeconds: number;
+        url: string;
+        uploadDate: string;
+        videoId: string;
+        state: "pending" | "indexed" | "no-captions" | "failed" | "excluded";
+        chunkCount: number;
+        wordCount: number;
+        error?: string | undefined;
+    }>;
+    language: string;
+    createdAt: string;
+    updatedAt: string;
+    stats: {
+        videoCount: number;
+        chunkCount: number;
+        excludedCount: number;
+        indexedCount: number;
+        noCaptionsCount: number;
+        failedCount: number;
+        pendingCount: number;
+        totalWords: number;
+        medianWordsPerMinute: number;
+        uploadsPerMonth: {
+            month: string;
+            videos: number;
+        }[];
+        firstUpload?: string | undefined;
+        lastUpload?: string | undefined;
+        recurringPhrases?: {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }[] | undefined;
+    };
+}, {
+    channel: {
+        description: string;
+        name: string;
+        channelId: string;
+        handle: string;
+        subscriberCount: number;
+        channelUrl: string;
+    };
+    version: number;
+    videos: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    stats: {
+        videoCount: number;
+        chunkCount: number;
+        excludedCount: number;
+        indexedCount: number;
+        noCaptionsCount: number;
+        failedCount: number;
+        pendingCount: number;
+        totalWords: number;
+        medianWordsPerMinute: number;
+        uploadsPerMonth: {
+            month: string;
+            videos: number;
+        }[];
+        firstUpload?: string | undefined;
+        lastUpload?: string | undefined;
+        recurringPhrases?: {
+            videoCount: number;
+            phrase: string;
+            occurrences: number;
+        }[] | undefined;
+    };
+    language?: string | undefined;
+}>;
+export type BrainManifest = z.infer<typeof brainManifestSchema>;
+/** A retrieval result: a moment in a video, with the link that opens it. */
+export declare const brainPassageSchema: z.ZodObject<{
+    videoId: z.ZodString;
+    title: z.ZodString;
+    startSeconds: z.ZodNumber;
+    startFormatted: z.ZodString;
+    endSeconds: z.ZodNumber;
+    score: z.ZodNumber;
+    text: z.ZodString;
+    url: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    url: string;
+    startSeconds: number;
+    startFormatted: string;
+    endSeconds: number;
+    text: string;
+    videoId: string;
+    score: number;
+}, {
+    title: string;
+    url: string;
+    startSeconds: number;
+    startFormatted: string;
+    endSeconds: number;
+    text: string;
+    videoId: string;
+    score: number;
+}>;
+export type BrainPassage = z.infer<typeof brainPassageSchema>;
+/** One row of list_brains. */
+export declare const brainSummarySchema: z.ZodObject<{
+    channelId: z.ZodString;
+    name: z.ZodString;
+    handle: z.ZodString;
+    channelUrl: z.ZodString;
+    language: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    hasProfile: z.ZodBoolean;
+    videoCount: z.ZodNumber;
+    indexedCount: z.ZodNumber;
+    chunkCount: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    channelId: string;
+    handle: string;
+    channelUrl: string;
+    videoCount: number;
+    chunkCount: number;
+    indexedCount: number;
+    language: string;
+    createdAt: string;
+    updatedAt: string;
+    hasProfile: boolean;
+}, {
+    name: string;
+    channelId: string;
+    handle: string;
+    channelUrl: string;
+    videoCount: number;
+    chunkCount: number;
+    indexedCount: number;
+    language: string;
+    createdAt: string;
+    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

@@ -0,0 +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"}