youtube-knowledge-mcp 2.1.0 → 2.2.0

package/README.md

@@ -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
@@ -50,6 +51,10 @@ 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
@@ -57,7 +62,9 @@ Supports both **local** (stdio) and **remote** (Streamable HTTP) transports.
   wall of yt-dlp stderr
 - Timeouts, retry with backoff, and a concurrency limit on every yt-dlp call
 - `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
 
@@ -154,7 +161,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 +221,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
+37 tools. The 15 read-only ones work over both transports; the 22 that touch
 your filesystem are registered only in local (stdio) mode, so a remote
 deployment cannot reach the host's disk.
 
@@ -220,18 +231,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`                         | Videos in a playlist or channel, with thumbnail URLs                                      |
+| `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`                       | Top-level comments by popularity                                                          |
+| `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
 
@@ -289,6 +301,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 +339,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 +366,50 @@ 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_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 +429,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 +533,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
@@ -490,9 +559,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":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEhE;;;;;;GAMG;AAEH,qDAAqD;AACrD,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;IACvF,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE;IAC3B,KAAK,EAAE,CAAC;SACL,IAAI,CAAC,CAAC,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;SACjE,QAAQ,CACP,4JAA4J,CAC7J;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC5B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;CAC5E,CAAC,CAAC;AAIH,uDAAuD;AACvD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IAC/C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;CACjB,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACzB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC;CAClC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;IAC9E,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;CAC9B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC;IACrC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;CACzB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC;IAC9F,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IAC3F,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC9B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACjC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC7B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC9B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC5B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC5B,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE;IAChC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,yBAAyB,CAAC;IACnD,gBAAgB,EAAE,CAAC;SAChB,KAAK,CAAC,iBAAiB,CAAC;SACxB,QAAQ,EAAE;SACV,QAAQ,CACP,0QAA0Q,CAC3Q;CACJ,CAAC,CAAC;AAIH,4BAA4B;AAC5B,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACzB,OAAO,EAAE,iBAAiB;IAC1B;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IAClC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,aAAa,CAAC,qBAAqB,CAAC;IAC5C,KAAK,EAAE,gBAAgB;CACxB,CAAC,CAAC;AAIH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;CACrE,CAAC,CAAC;AAIH,8BAA8B;AAC9B,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE;IACvB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC5B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC9B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;CAC7B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC"}
+{"version":3,"file":"brain-schemas.js","sourceRoot":"","sources":["../src/brain-schemas.ts"],"names":[],"mappings":"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"}

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"}

package/dist/http/app.js

@@ -0,0 +1,176 @@
+import { randomUUID } from 'node:crypto';
+import express from 'express';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { hostHeaderValidation, localhostHostValidation, } from '@modelcontextprotocol/sdk/server/middleware/hostHeaderValidation.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { runPreflight } from '../utils/preflight.js';
+import { serverVersion } from '../utils/version.js';
+import { bearerToken, clientKey, jsonRpcError, publicBaseUrl, securityHeaders, sessionIdOf, tokenMatches, } from './auth.js';
+import { isLoopback } from './config.js';
+export function buildApp(config, deps) {
+    const { createServer, sessions, limiter, port, startedAt } = deps;
+    const app = express();
+    // `req.ip` honours forwarded headers only when the operator names the proxies.
+    app.set('trust proxy', config.trustProxy);
+    app.disable('x-powered-by');
+    app.use(securityHeaders());
+    // Every route, before anything else: an unauthenticated flood is still a flood.
+    app.use((req, res, next) => {
+        const { allowed, remaining, retryAfter } = limiter.check(clientKey(req));
+        res.setHeader('RateLimit-Limit', String(config.rateLimit));
+        res.setHeader('RateLimit-Remaining', String(remaining));
+        if (allowed) {
+            next();
+            return;
+        }
+        // Without Retry-After a client has no idea how long to wait.
+        res.setHeader('Retry-After', String(retryAfter));
+        jsonRpcError(res, 429, -32000, `Rate limit exceeded. Retry in ${retryAfter}s.`);
+    });
+    function hasValidToken(req) {
+        return (config.authToken === undefined ||
+            tokenMatches(bearerToken(req.headers.authorization), config.authToken));
+    }
+    /** Returns true when the request may proceed; otherwise it has been answered. */
+    function authorize(req, res) {
+        if (hasValidToken(req))
+            return true;
+        // RFC 9728: point unauthenticated callers at the resource metadata.
+        const metadata = `${publicBaseUrl(config, req, port())}/.well-known/oauth-protected-resource`;
+        res.setHeader('WWW-Authenticate', `Bearer realm="youtube-knowledge-mcp", resource_metadata="${metadata}"`);
+        jsonRpcError(res, 401, -32001, 'Unauthorized');
+        return false;
+    }
+    // Ahead of Host validation on purpose: a container's own HEALTHCHECK and every
+    // platform probe arrive over loopback with a Host the allowlist may not name,
+    // and a service that 403s its probe never goes live. Unauthenticated callers
+    // learn only whether the service is up; versions and counts need the token.
+    app.get('/health', (req, res) => {
+        void runPreflight().then((report) => {
+            const status = report.ok ? 'ok' : 'degraded';
+            const body = hasValidToken(req)
+                ? {
+                    status,
+                    version: serverVersion(),
+                    uptimeSeconds: Math.round((Date.now() - startedAt) / 1000),
+                    ytDlp: report.ytDlp,
+                    ffmpeg: report.ffmpeg,
+                    sessions: sessions.size,
+                }
+                : { status };
+            res.writeHead(report.ok ? 200 : 503, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(body));
+        });
+    });
+    app.use(express.json({ limit: config.maxBodyBytes }));
+    app.use(bodyErrorHandler);
+    // The same decision the SDK's createMcpExpressApp makes, made explicitly so a
+    // body limit could be configured: an allowlist when one is given, loopback
+    // validation when bound to loopback, nothing when bound wide (a token is
+    // then required by assertSafeToStart).
+    if (config.allowedHosts.length > 0)
+        app.use(hostHeaderValidation(config.allowedHosts));
+    else if (isLoopback(config.bindHost))
+        app.use(localhostHostValidation());
+    app.post('/mcp', async (req, res) => {
+        if (!authorize(req, res))
+            return;
+        const sessionId = sessionIdOf(req);
+        try {
+            const existing = sessionId === undefined ? undefined : sessions.get(sessionId);
+            if (existing !== undefined && sessionId !== undefined) {
+                sessions.touch(sessionId);
+                await existing.transport.handleRequest(req, res, req.body);
+                return;
+            }
+            if (!sessionId && isInitializeRequest(req.body)) {
+                await openSession(req, res);
+                return;
+            }
+            jsonRpcError(res, 400, -32000, 'Bad Request: No valid session ID provided');
+        }
+        catch (error) {
+            console.error('Error handling MCP request:', error);
+            jsonRpcError(res, 500, -32603, 'Internal server error');
+        }
+    });
+    async function openSession(req, res) {
+        // Reserved before the first await, so concurrent initializes cannot all
+        // pass a size check and overshoot the cap together.
+        if (!sessions.reserve()) {
+            jsonRpcError(res, 503, -32000, 'Server is at capacity. Try again shortly.');
+            return;
+        }
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            // Hosts are checked by the port-agnostic middleware above on every
+            // route; the transport's own check would compare the whole Host header,
+            // port included, and reject every deployment on a non-default port.
+            ...(config.allowedOrigins.length > 0
+                ? { enableDnsRebindingProtection: true, allowedOrigins: config.allowedOrigins }
+                : {}),
+            onsessioninitialized: (id) => {
+                sessions.commit(id, transport);
+            },
+        });
+        transport.onclose = () => {
+            if (transport.sessionId)
+                sessions.delete(transport.sessionId);
+        };
+        try {
+            await createServer('http').connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        finally {
+            // The transport carries an id only once the session was initialised, so
+            // its absence means the reservation was never turned into a session.
+            if (transport.sessionId === undefined)
+                sessions.release();
+        }
+    }
+    const bySession = async (req, res) => {
+        if (!authorize(req, res))
+            return;
+        const sessionId = sessionIdOf(req);
+        const session = sessionId === undefined ? undefined : sessions.get(sessionId);
+        if (sessionId === undefined || session === undefined) {
+            jsonRpcError(res, 404, -32001, 'Invalid or missing session ID');
+            return;
+        }
+        sessions.touch(sessionId);
+        await session.transport.handleRequest(req, res);
+    };
+    app.get('/mcp', bySession);
+    app.delete('/mcp', bySession);
+    // RFC 9728 protected-resource metadata, so OAuth-capable clients can discover
+    // how to authenticate instead of guessing.
+    app.get('/.well-known/oauth-protected-resource', (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            resource: `${publicBaseUrl(config, req, port())}/mcp`,
+            bearer_methods_supported: ['header'],
+            resource_documentation: 'https://github.com/teobouancheau/youtube-knowledge-mcp#readme',
+        }));
+    });
+    return app;
+}
+/**
+ * Body-parser failures arrive as errors with an HTTP status; Express 5 routes
+ * them to the first four-argument middleware. Answered in the JSON-RPC shape
+ * every other refusal uses, and never with the parser's own message.
+ */
+function bodyErrorHandler(error, _req, res, next) {
+    const status = typeof error === 'object' && error !== null && 'status' in error
+        ? Number(error.status)
+        : Number.NaN;
+    if (status === 413) {
+        jsonRpcError(res, 413, -32600, 'Request body too large.');
+        return;
+    }
+    if (status >= 400 && status < 500) {
+        jsonRpcError(res, status, -32700, 'Request body could not be parsed.');
+        return;
+    }
+    next(error);
+}
+//# sourceMappingURL=app.js.map

package/dist/http/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/http/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACnG,OAAO,EACL,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,qEAAqE,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,WAAW,EACX,SAAS,EACT,YAAY,EACZ,aAAa,EACb,eAAe,EACf,WAAW,EACX,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,UAAU,EAAmB,MAAM,aAAa,CAAC;AAe1D,MAAM,UAAU,QAAQ,CAAC,MAAkB,EAAE,IAAqB;IAChE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAClE,MAAM,GAAG,GAAY,OAAO,EAAE,CAAC;IAE/B,+EAA+E;IAC/E,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC1C,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5B,GAAG,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC,CAAC;IAE3B,gFAAgF;IAChF,GAAG,CAAC,GAAG,CAAC,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QAC1D,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QACzE,GAAG,CAAC,SAAS,CAAC,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;QAC3D,GAAG,CAAC,SAAS,CAAC,qBAAqB,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;QACxD,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QACD,6DAA6D;QAC7D,GAAG,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;QACjD,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,iCAAiC,UAAU,IAAI,CAAC,CAAC;IAClF,CAAC,CAAC,CAAC;IAEH,SAAS,aAAa,CAAC,GAAY;QACjC,OAAO,CACL,MAAM,CAAC,SAAS,KAAK,SAAS;YAC9B,YAAY,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CACvE,CAAC;IACJ,CAAC;IAED,iFAAiF;IACjF,SAAS,SAAS,CAAC,GAAY,EAAE,GAAa;QAC5C,IAAI,aAAa,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QACpC,oEAAoE;QACpE,MAAM,QAAQ,GAAG,GAAG,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,uCAAuC,CAAC;QAC9F,GAAG,CAAC,SAAS,CACX,kBAAkB,EAClB,4DAA4D,QAAQ,GAAG,CACxE,CAAC;QACF,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;QAC/C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,+EAA+E;IAC/E,8EAA8E;IAC9E,6EAA6E;IAC7E,4EAA4E;IAC5E,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,GAAY,EAAE,GAAa,EAAE,EAAE;QACjD,KAAK,YAAY,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;YAClC,MAAM,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC;YAC7C,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC;gBAC7B,CAAC,CAAC;oBACE,MAAM;oBACN,OAAO,EAAE,aAAa,EAAE;oBACxB,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC;oBAC1D,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,MAAM,EAAE,MAAM,CAAC,MAAM;oBACrB,QAAQ,EAAE,QAAQ,CAAC,IAAI;iBACxB;gBACH,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;YACf,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;YAC7E,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;IACtD,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAE1B,8EAA8E;IAC9E,2EAA2E;IAC3E,yEAAyE;IACzE,uCAAuC;IACvC,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,GAAG,CAAC,oBAAoB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;SAClF,IAAI,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC;QAAE,GAAG,CAAC,GAAG,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAEzE,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;QACrD,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC;YAAE,OAAO;QAEjC,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAEnC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC/E,IAAI,QAAQ,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBACtD,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;gBAC1B,MAAM,QAAQ,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;gBAC3D,OAAO;YACT,CAAC;YAED,IAAI,CAAC,SAAS,IAAI,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAChD,MAAM,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBAC5B,OAAO;YACT,CAAC;YAED,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,2CAA2C,CAAC,CAAC;QAC9E,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAK,CAAC,CAAC;YACpD,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,uBAAuB,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,KAAK,UAAU,WAAW,CAAC,GAAY,EAAE,GAAa;QACpD,wEAAwE;QACxE,oDAAoD;QACpD,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;YACxB,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,2CAA2C,CAAC,CAAC;YAC5E,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,6BAA6B,CAAC;YAClD,kBAAkB,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE;YACtC,mEAAmE;YACnE,wEAAwE;YACxE,oEAAoE;YACpE,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;gBAClC,CAAC,CAAC,EAAE,4BAA4B,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE;gBAC/E,CAAC,CAAC,EAAE,CAAC;YACP,oBAAoB,EAAE,CAAC,EAAU,EAAE,EAAE;gBACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;YACjC,CAAC;SACF,CAAC,CAAC;QAEH,SAAS,CAAC,OAAO,GAAG,GAAS,EAAE;YAC7B,IAAI,SAAS,CAAC,SAAS;gBAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAChE,CAAC,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAC9C,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QACpD,CAAC;gBAAS,CAAC;YACT,wEAAwE;YACxE,qEAAqE;YACrE,IAAI,SAAS,CAAC,SAAS,KAAK,SAAS;gBAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,EAAE,GAAY,EAAE,GAAa,EAAiB,EAAE;QACrE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC;YAAE,OAAO;QAEjC,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9E,IAAI,SAAS,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YACrD,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,+BAA+B,CAAC,CAAC;YAChE,OAAO;QACT,CAAC;QACD,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC1B,MAAM,OAAO,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAClD,CAAC,CAAC;IAEF,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC3B,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAE9B,8EAA8E;IAC9E,2CAA2C;IAC3C,GAAG,CAAC,GAAG,CAAC,uCAAuC,EAAE,CAAC,GAAY,EAAE,GAAa,EAAE,EAAE;QAC/E,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAC3D,GAAG,CAAC,GAAG,CACL,IAAI,CAAC,SAAS,CAAC;YACb,QAAQ,EAAE,GAAG,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,MAAM;YACrD,wBAAwB,EAAE,CAAC,QAAQ,CAAC;YACpC,sBAAsB,EAAE,+DAA+D;SACxF,CAAC,CACH,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,KAAc,EAAE,IAAa,EAAE,GAAa,EAAE,IAAkB;IACxF,MAAM,MAAM,GACV,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,QAAQ,IAAI,KAAK;QAC9D,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;QACtB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;IAEjB,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,yBAAyB,CAAC,CAAC;QAC1D,OAAO;IACT,CAAC;IACD,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG,EAAE,CAAC;QAClC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,mCAAmC,CAAC,CAAC;QACvE,OAAO;IACT,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,CAAC;AACd,CAAC"}

package/dist/http/auth.d.ts

@@ -0,0 +1,38 @@
+import type { Request, RequestHandler, Response } from 'express';
+import type { HttpConfig } from './config.js';
+/** Bearer tokens, client identity, session ids and the JSON-RPC error envelope. */
+/**
+ * Compare a presented token against the configured one in constant time, so the
+ * endpoint does not leak the token's prefix through response timing.
+ */
+export declare function tokenMatches(presented: string | undefined, expected: string): boolean;
+export declare function bearerToken(header: string | undefined): string | undefined;
+/**
+ * The key a client is rate-limited under.
+ *
+ * `req.ip` is what Express derives after applying the `trust proxy` setting:
+ * the socket address by default, and the forwarded client only when the
+ * operator has said which proxies to believe. Reading `X-Forwarded-For`
+ * directly, as this once did, let any caller mint a fresh quota per request.
+ */
+export declare function clientKey(req: Request): string;
+/**
+ * Node parses a repeated header into an array, so this field is genuinely
+ * `string | string[] | undefined`. Asserting it was always a string meant a
+ * request that sent `Mcp-Session-Id` twice reached `sessions.get()` holding an
+ * array, missed every session, and was reported as an invalid session ID.
+ * Ambiguous is treated as absent: two session IDs identify no session.
+ */
+export declare function sessionIdOf(req: Request): string | undefined;
+export declare function jsonRpcError(res: Response, status: number, code: number, message: string): void;
+/**
+ * The base URL this server publishes in OAuth metadata.
+ *
+ * Configuration first; the request's own view of itself only when a proxy is
+ * trusted to have set it. Reflecting `Host` unconditionally let anyone who
+ * could reach the endpoint choose the address other clients were told to use.
+ */
+export declare function publicBaseUrl(config: HttpConfig, req: Request, port: number): string;
+/** Headers every response carries; none of them cost anything for an API. */
+export declare function securityHeaders(): RequestHandler;
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/http/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,mFAAmF;AAEnF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAarF;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAI1E;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAE9C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG5D;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAI/F;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIpF;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,cAAc,CAQhD"}