@pipeworx/mcp-youtube 0.1.2 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -11
- package/package.json +3 -3
- package/server.json +1 -1
- package/src/index.ts +280 -0
- package/src/server.ts +1 -1
package/README.md
CHANGED
|
@@ -1,18 +1,95 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @pipeworx/youtube
|
|
2
2
|
|
|
3
|
-
YouTube
|
|
3
|
+
YouTube videos, channels, comments and transcripts: search, video and channel
|
|
4
|
+
metadata with view/like counts, comment threads, and the caption text of a video.
|
|
4
5
|
|
|
5
|
-
Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to
|
|
6
|
+
Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1763+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.
|
|
6
7
|
|
|
7
8
|
## Tools
|
|
8
9
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
10
|
+
- `yt_search(query, type?, …)` — videos, channels or playlists matching a term.
|
|
11
|
+
- `yt_video_details(video_id)` — title, description, duration, view/like/comment counts, tags.
|
|
12
|
+
- `yt_channel_details(channel_id | username)` — subscriber, video and view counts.
|
|
13
|
+
- `yt_channel_videos(channel_id, …)` — a channel's recent uploads.
|
|
14
|
+
- `yt_video_comments(video_id, …)` — top-level comment threads.
|
|
15
|
+
- `yt_video_transcript(video_id, lang?, start_seconds?, max_chars?)` — the
|
|
16
|
+
video's captions as timestamped segments plus the joined text, the track
|
|
17
|
+
language, and whether it is auto-generated. Accepts a bare ID or a
|
|
18
|
+
youtube.com / youtu.be URL. Long videos are paged: the response carries
|
|
19
|
+
`truncated` and `next_start_seconds`; pass that back as `start_seconds`.
|
|
20
|
+
|
|
21
|
+
## Auth
|
|
22
|
+
|
|
23
|
+
- `yt_video_transcript` — **keyless.**
|
|
24
|
+
- Everything else — **BYO only**: a YouTube Data API v3 key from Google Cloud
|
|
25
|
+
Console, passed as `_apiKey`. Pipeworx does not front a shared key.
|
|
26
|
+
|
|
27
|
+
## Data sources
|
|
28
|
+
|
|
29
|
+
- <https://www.googleapis.com/youtube/v3> — the Data API (all tools except the transcript).
|
|
30
|
+
- <https://www.youtube.com/youtubei/v1/player> — YouTube's own player endpoint,
|
|
31
|
+
called with the ANDROID client context; its `captionTracks[].baseUrl` is then
|
|
32
|
+
fetched with `fmt=json3` for the transcript.
|
|
33
|
+
|
|
34
|
+
**The transcript upstream is fragile.** It is an undocumented endpoint, not a
|
|
35
|
+
published API, and YouTube can change it without notice. What we know as of
|
|
36
|
+
2026-10-09 (edge-probed from a Worker, fleet #2846):
|
|
37
|
+
|
|
38
|
+
- The **WEB** watch page lists the same caption tracks, but their URLs carry
|
|
39
|
+
`exp=xpe` and need a PO token: fetched bare they answer **200 with a 0-byte
|
|
40
|
+
body**. That is a silent empty transcript, so the WEB route is not used.
|
|
41
|
+
The ANDROID client's track URLs fetch without one.
|
|
42
|
+
- YouTube **intermittently** answers datacenter IPs with `LOGIN_REQUIRED`
|
|
43
|
+
"Sign in to confirm you're not a bot". It lands per request rather than per
|
|
44
|
+
video: through the live gateway it hit 7 of 10 consecutive calls with a
|
|
45
|
+
single attempt, and then let the same videos through. So the tool tries the
|
|
46
|
+
ANDROID client, then IOS (both give caption URLs that need no PO token;
|
|
47
|
+
ANDROID_VR does not qualify, it was bot-checked on every probe). If both are
|
|
48
|
+
refused it opens the public watch page. If that page shows the video plays
|
|
49
|
+
and has no caption tracks, the answer is `captions_unavailable`. Otherwise
|
|
50
|
+
both clients are retried carrying the visitor ID and cookies the page handed
|
|
51
|
+
out. Only after all four are refused does the call fail `upstream_down`,
|
|
52
|
+
saying that YouTube is blocking our servers. It never returns an empty
|
|
53
|
+
transcript. The watch page itself answers 429 from some egress IPs, and in
|
|
54
|
+
that case it is skipped.
|
|
55
|
+
- Translation (`&tlang=`) answers **429** from a datacenter IP, so a language
|
|
56
|
+
the video has no track for is refused (`captions_unavailable`, listing the
|
|
57
|
+
tracks it does have) rather than machine-translated.
|
|
58
|
+
- A video with no caption tracks fails `captions_unavailable`. A private,
|
|
59
|
+
removed or region-blocked video fails `not_found` with YouTube's own reason.
|
|
60
|
+
|
|
61
|
+
If this starts failing for every video, check the ANDROID `clientVersion` in
|
|
62
|
+
`src/index.ts` first — YouTube retires old client versions.
|
|
63
|
+
|
|
64
|
+
**The egress relay is NOT the fallback after that. Measured and ruled out
|
|
65
|
+
2026-10-09 (fleet #2877).** It was the obvious next move and it is strictly
|
|
66
|
+
worse than what we have. Probed from a throwaway function on the relay's own
|
|
67
|
+
Supabase edge infra, against `www.youtube.com`:
|
|
68
|
+
|
|
69
|
+
| Leg the transcript needs | Through the relay | Residential control |
|
|
70
|
+
|---|---|---|
|
|
71
|
+
| `POST /youtubei/v1/player` | **403, 10/10** — Google's "Sorry… your computer or network may be sending automated queries" page, an identical 1,103 bytes on every call, across 5 different videos | 200 `OK`, 3/3, 2 caption tracks |
|
|
72
|
+
| `GET /watch?v=` | 200, 5/5, visitor ID present | — |
|
|
73
|
+
| `GET /api/timedtext` (signed) | 200, 3/3, 79,833 bytes — byte-identical to residential | 200, 79,833 bytes |
|
|
74
|
+
|
|
75
|
+
So the block is scoped to **exactly one endpoint** — the innertube player call —
|
|
76
|
+
and that is the only leg that fails on Cloudflare today. The relay refuses it
|
|
77
|
+
**100%** of the time; Cloudflare egress refuses it **40%** (8 of 20 live
|
|
78
|
+
`yt_video_transcript` calls across 10 videos, 2026-10-09). Routing the player
|
|
79
|
+
call through the relay would take the tool from partly working to never working,
|
|
80
|
+
which is why `www.youtube.com` is deliberately absent from the relay's
|
|
81
|
+
`ALLOWED_HOSTS` (there is a note there saying so). The two legs that *do* pass
|
|
82
|
+
the relay are not the ones that need help.
|
|
83
|
+
|
|
84
|
+
Measuring the 40% needs care: the gateway caches tool responses, so a probe that
|
|
85
|
+
repeats identical arguments reads far too healthy. An un-busted run of the same
|
|
86
|
+
10 videos scored 14/16; varying `max_chars` per call to defeat the cache gave
|
|
87
|
+
12/20. Vary an argument or you will measure the cache.
|
|
88
|
+
|
|
89
|
+
What is actually left, none of it tried: a residential/mobile proxy (costs
|
|
90
|
+
money, so it is Bruce's call), a PO-token minter so the WEB route's `exp=xpe`
|
|
91
|
+
URLs stop answering 0 bytes, or accepting the 40% and making the retry advice in
|
|
92
|
+
the error message the answer.
|
|
16
93
|
|
|
17
94
|
## Quick Start
|
|
18
95
|
|
|
@@ -58,7 +135,7 @@ directly, instead of just this one's:
|
|
|
58
135
|
}
|
|
59
136
|
```
|
|
60
137
|
|
|
61
|
-
Both URLs reach the same gateway and the same
|
|
138
|
+
Both URLs reach the same gateway and the same 1763+ data sources. The
|
|
62
139
|
only difference is which pack's tools are listed **directly**; `ask_pipeworx`
|
|
63
140
|
reaches all of them from either one.
|
|
64
141
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pipeworx/mcp-youtube",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"description": "YouTube MCP — wraps the YouTube Data API v3 (BYO API key)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "src/index.ts",
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"@cloudflare/workers-types": "^4.20260405.1"
|
|
27
27
|
},
|
|
28
28
|
"pipeworx": {
|
|
29
|
-
"sourceHash": "v1-
|
|
30
|
-
"sourceCommit": "
|
|
29
|
+
"sourceHash": "v1-3a9451cbeb4277203c701eda5f0f85e1bab523481c5a480d9605f8403bb8120b",
|
|
30
|
+
"sourceCommit": "051ee2039fc96224cb5b7358fd69d525bced13a6"
|
|
31
31
|
}
|
|
32
32
|
}
|
package/server.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"name": "io.github.pipeworx-io/youtube",
|
|
4
4
|
"title": "Youtube",
|
|
5
5
|
"description": "YouTube MCP — wraps the YouTube Data API v3 (BYO API key)",
|
|
6
|
-
"version": "0.1.
|
|
6
|
+
"version": "0.1.3",
|
|
7
7
|
"websiteUrl": "https://pipeworx.io/packs/youtube",
|
|
8
8
|
"repository": {
|
|
9
9
|
"url": "https://github.com/pipeworx-io/mcp-youtube",
|
package/src/index.ts
CHANGED
|
@@ -679,6 +679,8 @@ function collapse(s: string): string {
|
|
|
679
679
|
* - yt_channel_details: get channel info and stats
|
|
680
680
|
* - yt_channel_videos: list videos from a channel
|
|
681
681
|
* - yt_video_comments: get comments on a video
|
|
682
|
+
* - yt_video_transcript: caption track (timestamped segments + joined text) —
|
|
683
|
+
* KEYLESS, via YouTube's own player endpoint, not the Data API
|
|
682
684
|
*/
|
|
683
685
|
|
|
684
686
|
|
|
@@ -691,6 +693,32 @@ async function pwFetch(url: string | URL, init?: RequestInit): Promise<Response>
|
|
|
691
693
|
}
|
|
692
694
|
|
|
693
695
|
const BASE = 'https://www.googleapis.com/youtube/v3';
|
|
696
|
+
const PLAYER_URL = 'https://www.youtube.com/youtubei/v1/player?prettyPrint=false';
|
|
697
|
+
// The ANDROID / IOS innertube clients are the ones whose caption baseUrls fetch
|
|
698
|
+
// without a PO token. The WEB watch page lists the same tracks, but its URLs carry
|
|
699
|
+
// `exp=xpe` and answer 200 with a ZERO-byte body when fetched bare — a silent
|
|
700
|
+
// empty transcript, which is the exact failure this tool must never return.
|
|
701
|
+
// Edge-probed from a Worker 2026-10-09 (fleet #2846).
|
|
702
|
+
// YouTube's datacenter bot-check ("Sign in to confirm you're not a bot") lands
|
|
703
|
+
// per request, not per video: measured live through the gateway 2026-10-09 it
|
|
704
|
+
// hit 7 of 10 consecutive calls and then let the same videos through. So the
|
|
705
|
+
// player call rotates through two clients whose caption URLs need no PO token
|
|
706
|
+
// (ANDROID_VR does NOT qualify — it is bot-checked on every probe), then
|
|
707
|
+
// repeats both carrying the visitor id the public watch page hands out.
|
|
708
|
+
const PLAYER_CLIENTS: { context: Record<string, unknown>; ua: string }[] = [
|
|
709
|
+
{
|
|
710
|
+
context: { clientName: 'ANDROID', clientVersion: '20.10.38', androidSdkVersion: 34, hl: 'en' },
|
|
711
|
+
ua: 'com.google.android.youtube/20.10.38 (Linux; U; Android 14) gzip',
|
|
712
|
+
},
|
|
713
|
+
{
|
|
714
|
+
context: { clientName: 'IOS', clientVersion: '20.10.4', deviceMake: 'Apple', deviceModel: 'iPhone16,2', osName: 'iPhone', osVersion: '18.3.2.22D82', hl: 'en' },
|
|
715
|
+
ua: 'com.google.ios.youtube/20.10.4 (iPhone16,2; U; CPU iOS 18_3_2 like Mac OS X;)',
|
|
716
|
+
},
|
|
717
|
+
];
|
|
718
|
+
const BROWSER_UA =
|
|
719
|
+
'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36';
|
|
720
|
+
const TRANSCRIPT_MAX_CHARS_DEFAULT = 50_000;
|
|
721
|
+
const TRANSCRIPT_MAX_CHARS_CAP = 200_000;
|
|
694
722
|
|
|
695
723
|
// ── Tool definitions ──────────────────────────────────────────────────
|
|
696
724
|
|
|
@@ -807,6 +835,34 @@ const tools: McpToolExport['tools'] = [
|
|
|
807
835
|
required: ['_apiKey', 'video_id'],
|
|
808
836
|
},
|
|
809
837
|
},
|
|
838
|
+
{
|
|
839
|
+
name: 'yt_video_transcript',
|
|
840
|
+
description:
|
|
841
|
+
'Get the transcript (captions) of a YouTube video: timestamped segments plus the joined text, the caption language, and whether the track is auto-generated. No API key needed. Use it to summarize, quote or search what is said in a video. Long videos are paged: pass the returned next_start_seconds as start_seconds to continue. A video with no captions returns a captions_unavailable error, never an empty transcript.',
|
|
842
|
+
inputSchema: {
|
|
843
|
+
type: 'object' as const,
|
|
844
|
+
properties: {
|
|
845
|
+
video_id: {
|
|
846
|
+
type: 'string',
|
|
847
|
+
description: 'YouTube video ID (e.g. "dQw4w9WgXcQ") or a full youtube.com / youtu.be URL',
|
|
848
|
+
},
|
|
849
|
+
lang: {
|
|
850
|
+
type: 'string',
|
|
851
|
+
description:
|
|
852
|
+
'Caption language code (e.g. "en", "fr", "pt-BR"). "en" also matches "en-US". Default: the video\'s default caption track. If the video has no track in this language the error lists the ones it has.',
|
|
853
|
+
},
|
|
854
|
+
start_seconds: {
|
|
855
|
+
type: 'number',
|
|
856
|
+
description: 'Skip segments that start before this many seconds (for paging through long videos). Default 0.',
|
|
857
|
+
},
|
|
858
|
+
max_chars: {
|
|
859
|
+
type: 'number',
|
|
860
|
+
description: `Stop after this many characters of transcript text (default ${TRANSCRIPT_MAX_CHARS_DEFAULT}, max ${TRANSCRIPT_MAX_CHARS_CAP}).`,
|
|
861
|
+
},
|
|
862
|
+
},
|
|
863
|
+
required: ['video_id'],
|
|
864
|
+
},
|
|
865
|
+
},
|
|
810
866
|
];
|
|
811
867
|
|
|
812
868
|
// ── Helpers ───────────────────────────────────────────────────────────
|
|
@@ -1084,9 +1140,233 @@ async function videoComments(key: string, videoId: string, maxResults?: number,
|
|
|
1084
1140
|
};
|
|
1085
1141
|
}
|
|
1086
1142
|
|
|
1143
|
+
// ── Transcript (keyless) ─────────────────────────────────────────────
|
|
1144
|
+
|
|
1145
|
+
interface CaptionTrack {
|
|
1146
|
+
baseUrl: string;
|
|
1147
|
+
languageCode: string;
|
|
1148
|
+
kind?: string;
|
|
1149
|
+
name?: { simpleText?: string; runs?: { text: string }[] };
|
|
1150
|
+
}
|
|
1151
|
+
|
|
1152
|
+
interface PlayerResponse {
|
|
1153
|
+
playabilityStatus?: { status?: string; reason?: string };
|
|
1154
|
+
videoDetails?: { videoId?: string; title?: string; author?: string; channelId?: string; lengthSeconds?: string };
|
|
1155
|
+
captions?: {
|
|
1156
|
+
playerCaptionsTracklistRenderer?: {
|
|
1157
|
+
captionTracks?: CaptionTrack[];
|
|
1158
|
+
audioTracks?: { captionTrackIndices?: number[]; defaultCaptionTrackIndex?: number }[];
|
|
1159
|
+
};
|
|
1160
|
+
};
|
|
1161
|
+
}
|
|
1162
|
+
|
|
1163
|
+
function parseVideoId(input: string): string {
|
|
1164
|
+
const raw = String(input ?? '').trim();
|
|
1165
|
+
if (/^[A-Za-z0-9_-]{11}$/.test(raw)) return raw;
|
|
1166
|
+
const m =
|
|
1167
|
+
raw.match(/[?&]v=([A-Za-z0-9_-]{11})/) ??
|
|
1168
|
+
raw.match(/youtu\.be\/([A-Za-z0-9_-]{11})/) ??
|
|
1169
|
+
raw.match(/\/(?:shorts|embed|live|v)\/([A-Za-z0-9_-]{11})/);
|
|
1170
|
+
if (m) return m[1];
|
|
1171
|
+
throw new Error(`user_error: "${raw}" is not a YouTube video ID or URL. A video ID is 11 characters, e.g. "dQw4w9WgXcQ".`);
|
|
1172
|
+
}
|
|
1173
|
+
|
|
1174
|
+
async function playerCall(
|
|
1175
|
+
videoId: string,
|
|
1176
|
+
client: (typeof PLAYER_CLIENTS)[number],
|
|
1177
|
+
visitor?: WatchPage,
|
|
1178
|
+
): Promise<PlayerResponse> {
|
|
1179
|
+
const headers: Record<string, string> = { 'content-type': 'application/json', 'user-agent': client.ua };
|
|
1180
|
+
let context = client.context;
|
|
1181
|
+
if (visitor) {
|
|
1182
|
+
headers['x-goog-visitor-id'] = visitor.visitorData;
|
|
1183
|
+
if (visitor.cookie) headers.cookie = visitor.cookie;
|
|
1184
|
+
context = { ...context, visitorData: visitor.visitorData };
|
|
1185
|
+
}
|
|
1186
|
+
const res = await pwFetch(PLAYER_URL, { method: 'POST', headers, body: JSON.stringify({ context: { client: context }, videoId }) });
|
|
1187
|
+
if (res.status === 429) throw new Error('upstream_throttled: YouTube rate-limited the transcript lookup (HTTP 429). Retry in a minute.');
|
|
1188
|
+
if (!res.ok) throw new Error(`upstream_down: YouTube player endpoint returned HTTP ${res.status} for video ${videoId}.`);
|
|
1189
|
+
return (await res.json()) as PlayerResponse;
|
|
1190
|
+
}
|
|
1191
|
+
|
|
1192
|
+
interface WatchPage {
|
|
1193
|
+
visitorData: string;
|
|
1194
|
+
cookie: string;
|
|
1195
|
+
/** The page itself says the video plays and lists no caption tracks. */
|
|
1196
|
+
noCaptions: boolean;
|
|
1197
|
+
title: string | null;
|
|
1198
|
+
}
|
|
1199
|
+
|
|
1200
|
+
// The public watch page: no login, no forged identity — what any browser that
|
|
1201
|
+
// opened the video would get. It yields the visitor id + cookies a retry
|
|
1202
|
+
// carries, and it states on its own whether the video has caption tracks,
|
|
1203
|
+
// which settles captions_unavailable even when every player call is
|
|
1204
|
+
// bot-checked. Null when the page itself is refused (it answers 429 from some
|
|
1205
|
+
// egress IPs) — then it has told us nothing.
|
|
1206
|
+
async function fetchWatchPage(videoId: string): Promise<WatchPage | null> {
|
|
1207
|
+
const res = await pwFetch(`https://www.youtube.com/watch?v=${videoId}`, {
|
|
1208
|
+
headers: { 'user-agent': BROWSER_UA, 'accept-language': 'en' },
|
|
1209
|
+
});
|
|
1210
|
+
if (!res.ok) return null;
|
|
1211
|
+
const html = await res.text();
|
|
1212
|
+
const visitorData = html.match(/"VISITOR_DATA":"([^"]+)"/)?.[1];
|
|
1213
|
+
if (!visitorData) return null;
|
|
1214
|
+
const setCookies = (res.headers as Headers & { getSetCookie?: () => string[] }).getSetCookie?.() ?? [];
|
|
1215
|
+
const playable = html.match(/"playabilityStatus":\{"status":"([A-Z_]+)"/)?.[1] === 'OK';
|
|
1216
|
+
const rawTitle = html.match(/<meta name="title" content="([^"]*)"/)?.[1];
|
|
1217
|
+
const title = rawTitle
|
|
1218
|
+
? rawTitle.replace(/"/g, '"').replace(/'/g, "'").replace(/</g, '<').replace(/>/g, '>').replace(/&/g, '&')
|
|
1219
|
+
: null;
|
|
1220
|
+
return {
|
|
1221
|
+
visitorData,
|
|
1222
|
+
cookie: setCookies.map((c) => c.split(';')[0]).join('; '),
|
|
1223
|
+
noCaptions: playable && !html.includes('"captionTracks"'),
|
|
1224
|
+
title,
|
|
1225
|
+
};
|
|
1226
|
+
}
|
|
1227
|
+
|
|
1228
|
+
function isBotCheck(p: PlayerResponse): boolean {
|
|
1229
|
+
return p.playabilityStatus?.status === 'LOGIN_REQUIRED' && /bot/i.test(p.playabilityStatus?.reason ?? '');
|
|
1230
|
+
}
|
|
1231
|
+
|
|
1232
|
+
function captionsUnavailable(videoId: string, title: string | null | undefined): Error {
|
|
1233
|
+
return new Error(
|
|
1234
|
+
`not_found: captions_unavailable — video ${videoId}${title ? ` ("${title}")` : ''} has no captions: the uploader disabled them or YouTube generated none. There is no transcript to return.`,
|
|
1235
|
+
);
|
|
1236
|
+
}
|
|
1237
|
+
|
|
1238
|
+
async function resolvePlayer(videoId: string): Promise<PlayerResponse> {
|
|
1239
|
+
let last: PlayerResponse | undefined;
|
|
1240
|
+
for (const client of PLAYER_CLIENTS) {
|
|
1241
|
+
last = await playerCall(videoId, client);
|
|
1242
|
+
if (!isBotCheck(last)) return last;
|
|
1243
|
+
}
|
|
1244
|
+
const page = await fetchWatchPage(videoId);
|
|
1245
|
+
if (page?.noCaptions) throw captionsUnavailable(videoId, page.title);
|
|
1246
|
+
if (page) {
|
|
1247
|
+
for (const client of PLAYER_CLIENTS) {
|
|
1248
|
+
last = await playerCall(videoId, client, page);
|
|
1249
|
+
if (!isBotCheck(last)) return last;
|
|
1250
|
+
}
|
|
1251
|
+
}
|
|
1252
|
+
throw new Error(
|
|
1253
|
+
`upstream_down: YouTube refused the transcript lookup from our servers ("${last?.playabilityStatus?.reason ?? 'bot check'}") on ${page ? 4 : 2} attempts. This is YouTube blocking datacenter traffic, not a problem with video ${videoId} — retry shortly.`,
|
|
1254
|
+
);
|
|
1255
|
+
}
|
|
1256
|
+
|
|
1257
|
+
function trackLabel(t: CaptionTrack): string {
|
|
1258
|
+
return t.name?.simpleText ?? t.name?.runs?.map((r) => r.text).join('') ?? t.languageCode;
|
|
1259
|
+
}
|
|
1260
|
+
|
|
1261
|
+
function pickTrack(player: PlayerResponse, lang: string | undefined): CaptionTrack {
|
|
1262
|
+
const r = player.captions?.playerCaptionsTracklistRenderer;
|
|
1263
|
+
const tracks = r?.captionTracks ?? [];
|
|
1264
|
+
if (lang) {
|
|
1265
|
+
const want = lang.toLowerCase();
|
|
1266
|
+
const exact = tracks.filter((t) => t.languageCode.toLowerCase() === want);
|
|
1267
|
+
const prefix = tracks.filter((t) => t.languageCode.toLowerCase().split('-')[0] === want.split('-')[0]);
|
|
1268
|
+
const pool = exact.length ? exact : prefix;
|
|
1269
|
+
// A human-made track beats the auto-generated one in the same language.
|
|
1270
|
+
const hit = pool.find((t) => t.kind !== 'asr') ?? pool[0];
|
|
1271
|
+
if (hit) return hit;
|
|
1272
|
+
throw new Error(
|
|
1273
|
+
`not_found: captions_unavailable — video ${player.videoDetails?.videoId ?? ''} has no caption track in "${lang}". ` +
|
|
1274
|
+
`Available: ${tracks.map((t) => `${t.languageCode}${t.kind === 'asr' ? ' (auto-generated)' : ''}`).join(', ')}. Call again with one of those as lang.`,
|
|
1275
|
+
);
|
|
1276
|
+
}
|
|
1277
|
+
const audio = r?.audioTracks?.[0];
|
|
1278
|
+
const idx = audio?.defaultCaptionTrackIndex ?? audio?.captionTrackIndices?.[0];
|
|
1279
|
+
if (idx !== undefined && tracks[idx]) return tracks[idx];
|
|
1280
|
+
return tracks.find((t) => t.kind !== 'asr') ?? tracks[0];
|
|
1281
|
+
}
|
|
1282
|
+
|
|
1283
|
+
async function videoTranscript(input: string, lang?: string, startSeconds?: number, maxChars?: number) {
|
|
1284
|
+
const videoId = parseVideoId(input);
|
|
1285
|
+
const player = await resolvePlayer(videoId);
|
|
1286
|
+
const status = player.playabilityStatus?.status;
|
|
1287
|
+
const reason = player.playabilityStatus?.reason ?? '';
|
|
1288
|
+
if (status !== 'OK') {
|
|
1289
|
+
// Private, removed, age-gated or region-blocked — the caller named a video
|
|
1290
|
+
// whose captions nobody without a login can read.
|
|
1291
|
+
throw new Error(`not_found: YouTube video ${videoId} is not publicly playable (${status ?? 'no status'}${reason ? `: ${reason}` : ''}).`);
|
|
1292
|
+
}
|
|
1293
|
+
const tracks = player.captions?.playerCaptionsTracklistRenderer?.captionTracks ?? [];
|
|
1294
|
+
if (tracks.length === 0) throw captionsUnavailable(videoId, player.videoDetails?.title);
|
|
1295
|
+
const track = pickTrack(player, lang);
|
|
1296
|
+
const url = `${track.baseUrl.replace(/&fmt=[^&]*/, '')}&fmt=json3`;
|
|
1297
|
+
const res = await pwFetch(url, { headers: { 'user-agent': BROWSER_UA } });
|
|
1298
|
+
if (res.status === 429) throw new Error('upstream_throttled: YouTube rate-limited the caption download (HTTP 429). Retry in a minute.');
|
|
1299
|
+
if (!res.ok) throw new Error(`upstream_down: YouTube caption endpoint returned HTTP ${res.status} for video ${videoId}.`);
|
|
1300
|
+
const body = await res.text();
|
|
1301
|
+
if (!body.trim()) {
|
|
1302
|
+
throw new Error(`upstream_down: YouTube returned an empty caption file for video ${videoId} (${track.languageCode}) — the track exists but the download was refused.`);
|
|
1303
|
+
}
|
|
1304
|
+
const data = JSON.parse(body) as { events?: { tStartMs?: number; dDurationMs?: number; segs?: { utf8?: string }[] }[] };
|
|
1305
|
+
|
|
1306
|
+
const all = (data.events ?? [])
|
|
1307
|
+
.filter((e) => e.segs)
|
|
1308
|
+
.map((e) => ({
|
|
1309
|
+
start: (e.tStartMs ?? 0) / 1000,
|
|
1310
|
+
duration: (e.dDurationMs ?? 0) / 1000,
|
|
1311
|
+
text: (e.segs ?? []).map((g) => g.utf8 ?? '').join('').replace(/\s+/g, ' ').trim(),
|
|
1312
|
+
}))
|
|
1313
|
+
.filter((s) => s.text);
|
|
1314
|
+
if (all.length === 0) {
|
|
1315
|
+
throw new Error(`not_found: captions_unavailable — the ${track.languageCode} caption track of video ${videoId} contains no text.`);
|
|
1316
|
+
}
|
|
1317
|
+
|
|
1318
|
+
const from = Math.max(0, Number(startSeconds) || 0);
|
|
1319
|
+
const cap = Math.min(Math.max(1000, Number(maxChars) || TRANSCRIPT_MAX_CHARS_DEFAULT), TRANSCRIPT_MAX_CHARS_CAP);
|
|
1320
|
+
const segments: { start_seconds: number; duration_seconds: number; text: string }[] = [];
|
|
1321
|
+
let chars = 0;
|
|
1322
|
+
let nextStart: number | null = null;
|
|
1323
|
+
for (const s of all) {
|
|
1324
|
+
if (s.start < from) continue;
|
|
1325
|
+
if (chars + s.text.length > cap && segments.length > 0) {
|
|
1326
|
+
nextStart = s.start;
|
|
1327
|
+
break;
|
|
1328
|
+
}
|
|
1329
|
+
segments.push({ start_seconds: Math.round(s.start * 100) / 100, duration_seconds: Math.round(s.duration * 100) / 100, text: s.text });
|
|
1330
|
+
chars += s.text.length + 1;
|
|
1331
|
+
}
|
|
1332
|
+
if (segments.length === 0) {
|
|
1333
|
+
throw new Error(`user_error: start_seconds ${from} is past the end of the transcript (last segment starts at ${Math.floor(all[all.length - 1].start)}s).`);
|
|
1334
|
+
}
|
|
1335
|
+
|
|
1336
|
+
const v = player.videoDetails ?? {};
|
|
1337
|
+
return {
|
|
1338
|
+
video_id: videoId,
|
|
1339
|
+
title: v.title ?? null,
|
|
1340
|
+
channel: v.author ?? null,
|
|
1341
|
+
channel_id: v.channelId ?? null,
|
|
1342
|
+
length_seconds: v.lengthSeconds ? Number(v.lengthSeconds) : null,
|
|
1343
|
+
language: track.languageCode,
|
|
1344
|
+
language_name: trackLabel(track),
|
|
1345
|
+
auto_generated: track.kind === 'asr',
|
|
1346
|
+
available_tracks: tracks.map((t) => ({ language: t.languageCode, name: trackLabel(t), auto_generated: t.kind === 'asr' })),
|
|
1347
|
+
segment_count: segments.length,
|
|
1348
|
+
total_segments: all.length,
|
|
1349
|
+
truncated: nextStart !== null,
|
|
1350
|
+
next_start_seconds: nextStart,
|
|
1351
|
+
text: segments.map((s) => s.text).join(' '),
|
|
1352
|
+
segments,
|
|
1353
|
+
source: `https://www.youtube.com/watch?v=${videoId}`,
|
|
1354
|
+
};
|
|
1355
|
+
}
|
|
1356
|
+
|
|
1087
1357
|
// ── callTool dispatcher ──────────────────────────────────────────────
|
|
1088
1358
|
|
|
1089
1359
|
async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
|
|
1360
|
+
// Keyless: reads YouTube's public player + caption endpoints, not the Data API.
|
|
1361
|
+
if (name === 'yt_video_transcript') {
|
|
1362
|
+
return videoTranscript(
|
|
1363
|
+
args.video_id as string,
|
|
1364
|
+
args.lang as string | undefined,
|
|
1365
|
+
args.start_seconds as number | undefined,
|
|
1366
|
+
args.max_chars as number | undefined,
|
|
1367
|
+
);
|
|
1368
|
+
}
|
|
1369
|
+
|
|
1090
1370
|
const apiKey = extractKey(args);
|
|
1091
1371
|
|
|
1092
1372
|
switch (name) {
|
package/src/server.ts
CHANGED
|
@@ -9,7 +9,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
|
|
|
9
9
|
import pack from './index.js';
|
|
10
10
|
|
|
11
11
|
const server = new Server(
|
|
12
|
-
{ name: '@pipeworx/mcp-youtube', version: '0.1.
|
|
12
|
+
{ name: '@pipeworx/mcp-youtube', version: '0.1.3' },
|
|
13
13
|
{ capabilities: { tools: {} } },
|
|
14
14
|
);
|
|
15
15
|
|