@pipeworx/mcp-youtube 0.1.2 → 0.2.0
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 +103 -21
- package/bin/cli.js +55 -11
- package/lib/index.js +333 -0
- package/package.json +17 -16
- package/server.json +1 -1
- package/tools.json +178 -0
- package/src/index.ts +0 -1131
- package/src/server.ts +0 -45
- package/tsconfig.json +0 -18
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 1857+ 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 1857+ 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
|
|
|
@@ -66,10 +143,12 @@ reaches all of them from either one.
|
|
|
66
143
|
|
|
67
144
|
This pack takes your own API key (`_apiKey`) — we don't front one for it, so there's no curl here that would run without it. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/yt_search`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.
|
|
68
145
|
|
|
69
|
-
##
|
|
146
|
+
## Run it from npm
|
|
70
147
|
|
|
71
|
-
|
|
72
|
-
|
|
148
|
+
`@pipeworx/mcp-youtube` is a local stdio bridge to the Pipeworx gateway: your MCP client
|
|
149
|
+
starts it with `npx`, and it forwards every call to the same
|
|
150
|
+
`https://gateway.pipeworx.io/youtube/mcp` endpoint shown above. It needs network access;
|
|
151
|
+
there is no offline mode.
|
|
73
152
|
|
|
74
153
|
```json
|
|
75
154
|
{
|
|
@@ -82,15 +161,18 @@ gateway round-trip:
|
|
|
82
161
|
}
|
|
83
162
|
```
|
|
84
163
|
|
|
85
|
-
|
|
164
|
+
Without a key it calls anonymously, capped at 50 calls a day. A free account
|
|
165
|
+
raises that to 200 a day: get a key at https://pipeworx.io/signup and add
|
|
166
|
+
`"env": { "PIPEWORX_API_KEY": "<your key>" }` to the server entry.
|
|
167
|
+
The key is sent as a Bearer token, the same way a hosted connection sends it,
|
|
168
|
+
so calls are metered and billed exactly as they are there.
|
|
86
169
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
```
|
|
170
|
+
It lists **only** this pack's tools by default. Set `PIPEWORX_META_TOOLS=1` to
|
|
171
|
+
also list `ask_pipeworx` and the other gateway-wide tools.
|
|
90
172
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
173
|
+
Behind an HTTPS proxy: Node's built-in `fetch` does not read `HTTPS_PROXY` by
|
|
174
|
+
default. Newer Node releases honour it when `NODE_USE_ENV_PROXY=1` is set; check
|
|
175
|
+
your Node version's documentation.
|
|
94
176
|
|
|
95
177
|
## Using with ask_pipeworx
|
|
96
178
|
|
package/bin/cli.js
CHANGED
|
@@ -1,17 +1,61 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
+
// Entry point for `npx @pipeworx/mcp-<slug>` in gateway mode (bin/cli.js).
|
|
2
3
|
//
|
|
3
|
-
//
|
|
4
|
+
// A stdio MCP server that relays every message to the Pipeworx gateway's
|
|
5
|
+
// /<slug>/mcp endpoint -- fleet #3759, docs/standalone-via-gateway-plan.md.
|
|
6
|
+
// It carries no pack code and has no local mode. The relay itself lives in
|
|
7
|
+
// ../lib/index.js (copied from scripts/templates/standalone-gateway-lib.js);
|
|
8
|
+
// this file only owns stdin/stdout.
|
|
4
9
|
//
|
|
5
|
-
//
|
|
6
|
-
//
|
|
7
|
-
// per-pack
|
|
8
|
-
// registers tsx's ESM loader programmatically, then hands off to src/server.ts,
|
|
9
|
-
// which wraps the pack's {tools, callTool} export in a stdio MCP server.
|
|
10
|
+
// Copied VERBATIM into every gateway-mode package by scripts/publish-pack.sh.
|
|
11
|
+
// Edit scripts/templates/standalone-gateway-cli.js in the monorepo, never a
|
|
12
|
+
// per-pack copy. Zero dependencies, Node 18+.
|
|
10
13
|
//
|
|
11
|
-
//
|
|
12
|
-
//
|
|
13
|
-
|
|
14
|
+
// stdout carries newline-delimited JSON-RPC and nothing else; every diagnostic
|
|
15
|
+
// goes to stderr, because a single stray line on stdout breaks the host's
|
|
16
|
+
// parser.
|
|
17
|
+
import { createInterface } from 'node:readline';
|
|
18
|
+
import { relay, bridgeConfig } from '../lib/index.js';
|
|
14
19
|
|
|
15
|
-
|
|
20
|
+
const cfg = bridgeConfig();
|
|
21
|
+
const warn = (line) => process.stderr.write(`${line}\n`);
|
|
22
|
+
const write = (msg) => { if (msg) process.stdout.write(`${JSON.stringify(msg)}\n`); };
|
|
16
23
|
|
|
17
|
-
|
|
24
|
+
const pending = new Set();
|
|
25
|
+
function track(p) {
|
|
26
|
+
pending.add(p);
|
|
27
|
+
p.finally(() => pending.delete(p));
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
async function handleLine(line) {
|
|
31
|
+
const text = line.trim();
|
|
32
|
+
if (!text) return;
|
|
33
|
+
let message;
|
|
34
|
+
try {
|
|
35
|
+
message = JSON.parse(text);
|
|
36
|
+
} catch {
|
|
37
|
+
write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
|
|
38
|
+
return;
|
|
39
|
+
}
|
|
40
|
+
// A JSON-RPC batch: relay each member, answer with the non-notification replies.
|
|
41
|
+
if (Array.isArray(message)) {
|
|
42
|
+
const replies = (await Promise.all(message.map((m) => relay(m, { cfg, warn })))).filter(Boolean);
|
|
43
|
+
if (replies.length) write(replies);
|
|
44
|
+
return;
|
|
45
|
+
}
|
|
46
|
+
write(await relay(message, { cfg, warn }));
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
// Requests are handled concurrently and answered as they finish: JSON-RPC ids
|
|
50
|
+
// let the host match them, and a slow tool call must not hold up a ping.
|
|
51
|
+
const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
|
|
52
|
+
rl.on('line', (line) => {
|
|
53
|
+
track(handleLine(line).catch((err) => warn(`pipeworx-standalone: ${err && err.stack ? err.stack : err}`)));
|
|
54
|
+
});
|
|
55
|
+
rl.on('close', async () => {
|
|
56
|
+
// stdin closed: finish what is in flight, then exit.
|
|
57
|
+
while (pending.size) await Promise.allSettled([...pending]);
|
|
58
|
+
// Exit only once stdout has flushed: on a pipe that is not synchronous
|
|
59
|
+
// everywhere, and a bare exit can drop the last reply.
|
|
60
|
+
process.stdout.write('', () => process.exit(0));
|
|
61
|
+
});
|
package/lib/index.js
ADDED
|
@@ -0,0 +1,333 @@
|
|
|
1
|
+
// @pipeworx/mcp-<slug> -- library half of the gateway bridge (lib/index.js).
|
|
2
|
+
//
|
|
3
|
+
// Copied VERBATIM into every gateway-mode pack package by scripts/publish-pack.sh
|
|
4
|
+
// (fleet #3759, docs/standalone-via-gateway-plan.md section 1). There is no
|
|
5
|
+
// per-pack templating: the slug and version are read from this package's own
|
|
6
|
+
// package.json (`pipeworx.slug`, `version`) at load time, so the same bytes
|
|
7
|
+
// ship in every package and the source hash can cover them once. Edit this
|
|
8
|
+
// file in the monorepo (scripts/templates/standalone-gateway-lib.js), never a
|
|
9
|
+
// per-pack copy.
|
|
10
|
+
//
|
|
11
|
+
// What it is: a relay. Every JSON-RPC message goes to
|
|
12
|
+
// ${PIPEWORX_GATEWAY_URL:-https://gateway.pipeworx.io}/<slug>/mcp, the same
|
|
13
|
+
// endpoint a hosted MCP client uses, so tiers, rate limits and credits apply
|
|
14
|
+
// exactly as they do there. There is no local mode: the pack's code is not in
|
|
15
|
+
// this package.
|
|
16
|
+
//
|
|
17
|
+
// Zero dependencies, plain ESM, Node 18+ (global fetch). Nothing here writes
|
|
18
|
+
// to stdout -- bin/cli.js owns stdout and it carries JSON-RPC only.
|
|
19
|
+
//
|
|
20
|
+
// Environment:
|
|
21
|
+
// PIPEWORX_API_KEY sent as `Authorization: Bearer <key>`. Never as
|
|
22
|
+
// X-API-Key: the gateway reads a pwx_ key sent that way
|
|
23
|
+
// as an unvalidated BYO string with no account.
|
|
24
|
+
// PIPEWORX_GATEWAY_URL gateway base URL (no path), default the public gateway.
|
|
25
|
+
// PIPEWORX_META_TOOLS=1 list the gateway-wide tools (ask_pipeworx, ...) too.
|
|
26
|
+
// PIPEWORX_TIMEOUT_MS per-request timeout, default 120000.
|
|
27
|
+
|
|
28
|
+
import { readFileSync } from 'node:fs';
|
|
29
|
+
|
|
30
|
+
const readJson = (rel) => JSON.parse(readFileSync(new URL(rel, import.meta.url), 'utf8'));
|
|
31
|
+
|
|
32
|
+
const PKG = readJson('../package.json');
|
|
33
|
+
export const SLUG = PKG.pipeworx && PKG.pipeworx.slug;
|
|
34
|
+
if (typeof SLUG !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/.test(SLUG)) {
|
|
35
|
+
throw new Error(`${PKG.name}: package.json carries no valid pipeworx.slug -- this package was built wrong`);
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* The pack's slug on the GATEWAY: the /<slug>/mcp route and the `_meta.pack`
|
|
39
|
+
* every listed tool carries. Usually the same as `slug` (the npm/directory
|
|
40
|
+
* name), but 14 packs differ -- `hex-pm` is `hex_pm` on the gateway -- and
|
|
41
|
+
* filtering tools/list on the npm slug would match none of their tools
|
|
42
|
+
* (fleet #3761). publish-pack.sh stamps it from the gateway manifest.
|
|
43
|
+
*/
|
|
44
|
+
export const GATEWAY_SLUG = (PKG.pipeworx && PKG.pipeworx.gatewaySlug) || SLUG;
|
|
45
|
+
if (typeof GATEWAY_SLUG !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/.test(GATEWAY_SLUG)) {
|
|
46
|
+
throw new Error(`${PKG.name}: package.json carries an invalid pipeworx.gatewaySlug -- this package was built wrong`);
|
|
47
|
+
}
|
|
48
|
+
export const PACKAGE_NAME = PKG.name;
|
|
49
|
+
export const VERSION = PKG.version;
|
|
50
|
+
|
|
51
|
+
/** The pack's own tool definitions at publish time (the offline tools/list answer). */
|
|
52
|
+
export const tools = readJson('../tools.json');
|
|
53
|
+
|
|
54
|
+
const DEFAULT_GATEWAY = 'https://gateway.pipeworx.io';
|
|
55
|
+
const DEFAULT_TIMEOUT_MS = 120_000;
|
|
56
|
+
const SIGNUP_URL = 'https://pipeworx.io/signup';
|
|
57
|
+
const VIA = '(via pipeworx-standalone)';
|
|
58
|
+
|
|
59
|
+
/** Resolve the bridge's settings. Exported for the tests and for callTool. */
|
|
60
|
+
export function bridgeConfig(env = process.env, overrides = {}) {
|
|
61
|
+
const base = String(overrides.gatewayUrl || env.PIPEWORX_GATEWAY_URL || DEFAULT_GATEWAY).trim().replace(/\/+$/, '');
|
|
62
|
+
const apiKey = String(overrides.apiKey ?? env.PIPEWORX_API_KEY ?? '').trim();
|
|
63
|
+
const t = Number(overrides.timeoutMs ?? env.PIPEWORX_TIMEOUT_MS);
|
|
64
|
+
return {
|
|
65
|
+
endpoint: `${base}/${GATEWAY_SLUG}/mcp`,
|
|
66
|
+
apiKey,
|
|
67
|
+
timeoutMs: Number.isFinite(t) && t > 0 ? t : DEFAULT_TIMEOUT_MS,
|
|
68
|
+
metaTools: (overrides.metaTools ?? env.PIPEWORX_META_TOOLS) === '1' || overrides.metaTools === true,
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function requestHeaders(cfg) {
|
|
73
|
+
const h = {
|
|
74
|
+
'Content-Type': 'application/json',
|
|
75
|
+
Accept: 'application/json',
|
|
76
|
+
// Stable per package version: the gateway remembers a client's name by
|
|
77
|
+
// identifier + User-Agent (workers/gateway/src/client-identity.ts).
|
|
78
|
+
'User-Agent': `pipeworx-standalone/${VERSION} (${PACKAGE_NAME})`,
|
|
79
|
+
// Analytics label only (blob11 = 'standalone'). It never changes tier,
|
|
80
|
+
// limits or price -- anyone can send it.
|
|
81
|
+
'X-Pipeworx-Surface': 'standalone',
|
|
82
|
+
};
|
|
83
|
+
if (cfg.apiKey) h.Authorization = `Bearer ${cfg.apiKey}`;
|
|
84
|
+
return h;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Parse a gateway body: JSON, or the last JSON `data:` frame of an SSE stream. */
|
|
88
|
+
function parseBody(text, contentType) {
|
|
89
|
+
if (/text\/event-stream/i.test(contentType || '')) {
|
|
90
|
+
let last = null;
|
|
91
|
+
for (const line of text.split(/\r?\n/)) {
|
|
92
|
+
if (!line.startsWith('data:')) continue;
|
|
93
|
+
try { last = JSON.parse(line.slice(5).trim()); } catch { /* keep-alive or partial frame */ }
|
|
94
|
+
}
|
|
95
|
+
return last;
|
|
96
|
+
}
|
|
97
|
+
try { return JSON.parse(text); } catch { return null; }
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* POST one JSON-RPC message. Never throws: the outcome is one of
|
|
102
|
+
* { kind: 'http', status, headers, body, text } the gateway answered
|
|
103
|
+
* { kind: 'network', detail } DNS, TLS, refused, reset
|
|
104
|
+
* { kind: 'timeout' } no answer in cfg.timeoutMs
|
|
105
|
+
*/
|
|
106
|
+
export async function postToGateway(message, cfg) {
|
|
107
|
+
const ac = new AbortController();
|
|
108
|
+
const timer = setTimeout(() => ac.abort(), cfg.timeoutMs);
|
|
109
|
+
try {
|
|
110
|
+
const res = await fetch(cfg.endpoint, {
|
|
111
|
+
method: 'POST',
|
|
112
|
+
headers: requestHeaders(cfg),
|
|
113
|
+
body: JSON.stringify(message),
|
|
114
|
+
signal: ac.signal,
|
|
115
|
+
});
|
|
116
|
+
const text = await res.text();
|
|
117
|
+
return { kind: 'http', status: res.status, headers: res.headers, body: parseBody(text, res.headers.get('content-type')), text };
|
|
118
|
+
} catch (err) {
|
|
119
|
+
if (ac.signal.aborted || (err && (err.name === 'AbortError' || err.name === 'TimeoutError'))) return { kind: 'timeout' };
|
|
120
|
+
const cause = err && err.cause;
|
|
121
|
+
const detail = (cause && (cause.code || cause.message)) || (err && err.message) || String(err);
|
|
122
|
+
return { kind: 'network', detail };
|
|
123
|
+
} finally {
|
|
124
|
+
clearTimeout(timer);
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
// ── The key-not-accepted warning (one per process) ──────────────────
|
|
129
|
+
|
|
130
|
+
let warnedKeyIgnored = false;
|
|
131
|
+
const KEY_IGNORED = 'PIPEWORX_API_KEY was not accepted, calling anonymously.';
|
|
132
|
+
|
|
133
|
+
/** True when a key was sent but the gateway still served the call as anonymous. */
|
|
134
|
+
function keyIgnored(out, cfg) {
|
|
135
|
+
return !!cfg.apiKey && out.kind === 'http' && (out.headers.get('x-ratelimit-tier') || '').toLowerCase() === 'anonymous';
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
function noteTier(out, cfg, warn) {
|
|
139
|
+
if (!keyIgnored(out, cfg) || warnedKeyIgnored) return;
|
|
140
|
+
warnedKeyIgnored = true;
|
|
141
|
+
warn(`${PACKAGE_NAME}: ${KEY_IGNORED} Check the key at ${SIGNUP_URL}.`);
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** Test hook: forget that the warning was printed. */
|
|
145
|
+
export function _resetWarnings() { warnedKeyIgnored = false; }
|
|
146
|
+
|
|
147
|
+
// ── Results the host shows to the model ─────────────────────────────
|
|
148
|
+
|
|
149
|
+
function errorResult(text, detail) {
|
|
150
|
+
const result = { content: [{ type: 'text', text }], isError: true };
|
|
151
|
+
if (detail) result._meta = { pipeworx_standalone: detail };
|
|
152
|
+
return result;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
const rpcResult = (id, result) => ({ jsonrpc: '2.0', id, result });
|
|
156
|
+
const rpcError = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
|
|
157
|
+
|
|
158
|
+
function firstLine(text) {
|
|
159
|
+
const line = String(text || '').split(/\r?\n/).map((l) => l.trim()).find(Boolean) || '(empty body)';
|
|
160
|
+
return line.length > 200 ? `${line.slice(0, 200)}...` : line;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
function unreachableText(cfg, out) {
|
|
164
|
+
if (out.kind === 'timeout') {
|
|
165
|
+
return `The Pipeworx gateway at ${cfg.endpoint} did not answer within ${Math.round(cfg.timeoutMs / 1000)}s, so this call timed out. `
|
|
166
|
+
+ `${PACKAGE_NAME} forwards every call to the Pipeworx gateway and has no local mode. Try again; a call that keeps timing out is worth reporting.`;
|
|
167
|
+
}
|
|
168
|
+
return `Could not reach the Pipeworx gateway at ${cfg.endpoint} (${out.detail}). `
|
|
169
|
+
+ `${PACKAGE_NAME} forwards every call to the Pipeworx gateway and has no local mode, so it needs network access.`;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
function isAuthRequired(body) {
|
|
173
|
+
return !!body && (body.error_code === 'authentication_required'
|
|
174
|
+
|| (body.error && body.error.data && body.error.data.reason === 'authentication_required'));
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** Map a tools/call outcome to the JSON-RPC response the host gets. */
|
|
178
|
+
function toolsCallResponse(id, out, cfg) {
|
|
179
|
+
if (out.kind !== 'http') return rpcResult(id, errorResult(unreachableText(cfg, out), { reason: out.kind }));
|
|
180
|
+
const { status, body } = out;
|
|
181
|
+
|
|
182
|
+
// Anonymous daily cap: the gateway answers 401 with a JSON-RPC error whose
|
|
183
|
+
// message is the offer. Hosts often swallow protocol errors, so hand it over
|
|
184
|
+
// as a tool result the model actually reads.
|
|
185
|
+
if (status === 401 && isAuthRequired(body)) {
|
|
186
|
+
const data = (body.error && body.error.data) || {};
|
|
187
|
+
const parts = [body.error && body.error.message ? body.error.message : 'The anonymous daily allowance is used up.'];
|
|
188
|
+
if (data.resets_at) parts.push(`The anonymous allowance resets at ${data.resets_at}.`);
|
|
189
|
+
parts.push(cfg.apiKey
|
|
190
|
+
? `${KEY_IGNORED} Check the key, or get a free one at ${SIGNUP_URL}.`
|
|
191
|
+
: `To keep going now, set PIPEWORX_API_KEY in this MCP server's environment; a free key is at ${SIGNUP_URL}.`);
|
|
192
|
+
return rpcResult(id, errorResult(parts.join('\n\n'), { status, reason: 'authentication_required', resets_at: data.resets_at ?? null }));
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
// A keyed tier over its cap: today the gateway answers 429 with a RESULT
|
|
196
|
+
// that has no isError, which reads as a success (fleet #3760). Mark it.
|
|
197
|
+
if (status === 429 && body && body.result && typeof body.result === 'object') {
|
|
198
|
+
const result = { ...body.result, isError: true };
|
|
199
|
+
if (cfg.apiKey && keyIgnored(out, cfg)) {
|
|
200
|
+
result.content = [...(Array.isArray(result.content) ? result.content : []), { type: 'text', text: KEY_IGNORED }];
|
|
201
|
+
}
|
|
202
|
+
return rpcResult(id, result);
|
|
203
|
+
}
|
|
204
|
+
if ((status === 401 || status === 429) && body && body.error) {
|
|
205
|
+
const extra = keyIgnored(out, cfg) ? ` ${KEY_IGNORED}` : '';
|
|
206
|
+
return rpcResult(id, errorResult(`${body.error.message || `HTTP ${status}`}${extra}`, { status }));
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
// A real JSON-RPC answer (result or protocol error): relay it verbatim,
|
|
210
|
+
// structuredContent and _meta (cost, tier, provenance) included.
|
|
211
|
+
if (body && body.jsonrpc === '2.0' && (body.result !== undefined || body.error !== undefined) && status < 500) {
|
|
212
|
+
return { ...body, id };
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
// 5xx, an HTML edge page, or anything else that is not JSON-RPC.
|
|
216
|
+
return rpcResult(id, errorResult(`The Pipeworx gateway returned HTTP ${status}: ${firstLine(out.text)}`, { status }));
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
function localInitialize(params) {
|
|
220
|
+
return {
|
|
221
|
+
protocolVersion: (params && params.protocolVersion) || '2025-06-18',
|
|
222
|
+
capabilities: { tools: {} },
|
|
223
|
+
serverInfo: { name: PACKAGE_NAME, version: VERSION },
|
|
224
|
+
};
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
const scopedInstructions = () =>
|
|
228
|
+
`${PACKAGE_NAME} forwards to the Pipeworx gateway and lists only the ${SLUG} pack's tools. `
|
|
229
|
+
+ 'Set PIPEWORX_META_TOOLS=1 to also list ask_pipeworx and the other gateway-wide tools.';
|
|
230
|
+
|
|
231
|
+
/** `<host name> (via pipeworx-standalone)`. The slug stays OUT of the name: the
|
|
232
|
+
* gateway's scanner-name check substring-matches words like poll/watch/index. */
|
|
233
|
+
export function bridgedClientName(name) {
|
|
234
|
+
const n = typeof name === 'string' && name.trim() ? name.trim() : 'unknown';
|
|
235
|
+
return n.includes(VIA) ? n : `${n} ${VIA}`;
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/**
|
|
239
|
+
* Relay one JSON-RPC message to the gateway and return the response to write
|
|
240
|
+
* back, or null for a notification. Never throws.
|
|
241
|
+
*
|
|
242
|
+
* @param {object} message a parsed JSON-RPC request or notification
|
|
243
|
+
* @param {{cfg?: object, warn?: (line: string) => void}} [opts]
|
|
244
|
+
*/
|
|
245
|
+
export async function relay(message, opts = {}) {
|
|
246
|
+
const cfg = opts.cfg || bridgeConfig();
|
|
247
|
+
const warn = opts.warn || ((line) => process.stderr.write(`${line}\n`));
|
|
248
|
+
if (!message || typeof message !== 'object' || message.jsonrpc !== '2.0' || typeof message.method !== 'string') {
|
|
249
|
+
const id = message && typeof message === 'object' && 'id' in message ? message.id : null;
|
|
250
|
+
return rpcError(id ?? null, -32600, 'Invalid Request');
|
|
251
|
+
}
|
|
252
|
+
const isNotification = !('id' in message) || message.id === undefined;
|
|
253
|
+
const id = message.id;
|
|
254
|
+
|
|
255
|
+
if (isNotification) {
|
|
256
|
+
const out = await postToGateway(message, cfg);
|
|
257
|
+
if (out.kind !== 'http') warn(`${PACKAGE_NAME}: notification ${message.method} not delivered: ${unreachableText(cfg, out)}`);
|
|
258
|
+
return null;
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
if (message.method === 'initialize') {
|
|
262
|
+
const params = { ...(message.params || {}) };
|
|
263
|
+
params.clientInfo = { ...(params.clientInfo || {}), name: bridgedClientName(params.clientInfo && params.clientInfo.name) };
|
|
264
|
+
if (!params.clientInfo.version) params.clientInfo.version = '0';
|
|
265
|
+
const out = await postToGateway({ ...message, params }, cfg);
|
|
266
|
+
noteTier(out, cfg, warn);
|
|
267
|
+
if (out.kind === 'http' && out.body && out.body.result && typeof out.body.result === 'object') {
|
|
268
|
+
const result = { ...out.body.result, serverInfo: { name: PACKAGE_NAME, version: VERSION } };
|
|
269
|
+
if (!cfg.metaTools) result.instructions = scopedInstructions();
|
|
270
|
+
return rpcResult(id, result);
|
|
271
|
+
}
|
|
272
|
+
// The host must still start: answer locally and let the calls report the
|
|
273
|
+
// gateway problem when they happen.
|
|
274
|
+
warn(`${PACKAGE_NAME}: initialize answered locally -- ${out.kind === 'http' ? `gateway HTTP ${out.status}` : unreachableText(cfg, out)}`);
|
|
275
|
+
return rpcResult(id, { ...localInitialize(message.params), instructions: scopedInstructions() });
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
if (message.method === 'tools/list') {
|
|
279
|
+
const out = await postToGateway(message, cfg);
|
|
280
|
+
noteTier(out, cfg, warn);
|
|
281
|
+
const listed = out.kind === 'http' && out.body && out.body.result && Array.isArray(out.body.result.tools)
|
|
282
|
+
? out.body.result : null;
|
|
283
|
+
if (listed) {
|
|
284
|
+
if (cfg.metaTools) return rpcResult(id, listed);
|
|
285
|
+
const own = listed.tools.filter((t) => t && t._meta && (t._meta.pack === GATEWAY_SLUG || t._meta.pack === SLUG));
|
|
286
|
+
if (own.length > 0) return rpcResult(id, { ...listed, tools: own });
|
|
287
|
+
warn(`${PACKAGE_NAME}: the gateway listed no ${SLUG} tools; serving the tool list bundled with this package`);
|
|
288
|
+
} else {
|
|
289
|
+
warn(`${PACKAGE_NAME}: tools/list served from the snapshot bundled with this package -- ${out.kind === 'http' ? `gateway HTTP ${out.status}` : unreachableText(cfg, out)}`);
|
|
290
|
+
}
|
|
291
|
+
return rpcResult(id, { tools });
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
if (message.method === 'tools/call') {
|
|
295
|
+
const out = await postToGateway(message, cfg);
|
|
296
|
+
noteTier(out, cfg, warn);
|
|
297
|
+
return toolsCallResponse(id, out, cfg);
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
// Everything else (ping, resources/*, prompts/*, ...): relay as-is.
|
|
301
|
+
const out = await postToGateway(message, cfg);
|
|
302
|
+
noteTier(out, cfg, warn);
|
|
303
|
+
if (out.kind === 'http' && out.body && out.body.jsonrpc === '2.0') return { ...out.body, id };
|
|
304
|
+
if (message.method === 'ping') return rpcResult(id, {});
|
|
305
|
+
return rpcError(id, -32603, out.kind === 'http'
|
|
306
|
+
? `The Pipeworx gateway returned HTTP ${out.status}: ${firstLine(out.text)}`
|
|
307
|
+
: unreachableText(cfg, out));
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
/**
|
|
311
|
+
* Call one of this pack's tools through the gateway -- the `{tools, callTool}`
|
|
312
|
+
* shape earlier versions of this package exported. Resolves with the tool's
|
|
313
|
+
* structured result; rejects with the gateway's message on any error.
|
|
314
|
+
*
|
|
315
|
+
* @param {string} name
|
|
316
|
+
* @param {Record<string, unknown>} [args]
|
|
317
|
+
* @param {{apiKey?: string, gatewayUrl?: string, timeoutMs?: number}} [opts]
|
|
318
|
+
* apiKey defaults to process.env.PIPEWORX_API_KEY.
|
|
319
|
+
*/
|
|
320
|
+
export async function callTool(name, args = {}, opts = {}) {
|
|
321
|
+
const cfg = bridgeConfig(process.env, opts);
|
|
322
|
+
const res = await relay({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } }, { cfg });
|
|
323
|
+
if (res.error) throw new Error(res.error.message);
|
|
324
|
+
const result = res.result || {};
|
|
325
|
+
const text = Array.isArray(result.content)
|
|
326
|
+
? result.content.filter((c) => c && c.type === 'text').map((c) => c.text).join('\n')
|
|
327
|
+
: '';
|
|
328
|
+
if (result.isError) throw new Error(text || `${name} failed`);
|
|
329
|
+
if (result.structuredContent !== undefined) return result.structuredContent;
|
|
330
|
+
try { return JSON.parse(text); } catch { return text; }
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
export default { tools, callTool };
|
package/package.json
CHANGED
|
@@ -1,32 +1,33 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pipeworx/mcp-youtube",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "YouTube MCP — wraps the YouTube Data API v3 (BYO API key)",
|
|
5
5
|
"type": "module",
|
|
6
|
-
"main": "
|
|
7
|
-
"
|
|
6
|
+
"main": "lib/index.js",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": "./lib/index.js",
|
|
9
|
+
"./tools.json": "./tools.json",
|
|
10
|
+
"./package.json": "./package.json"
|
|
11
|
+
},
|
|
8
12
|
"bin": {
|
|
9
13
|
"mcp-youtube": "bin/cli.js"
|
|
10
14
|
},
|
|
15
|
+
"files": ["bin/", "lib/", "tools.json", "server.json"],
|
|
16
|
+
"engines": {
|
|
17
|
+
"node": ">=18"
|
|
18
|
+
},
|
|
11
19
|
"keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "youtube"],
|
|
12
20
|
"license": "MIT",
|
|
13
21
|
"repository": {
|
|
14
22
|
"type": "git",
|
|
15
23
|
"url": "git+https://github.com/pipeworx-io/mcp-youtube.git"
|
|
16
24
|
},
|
|
17
|
-
"
|
|
18
|
-
"typecheck": "tsc --noEmit"
|
|
19
|
-
},
|
|
20
|
-
"dependencies": {
|
|
21
|
-
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
22
|
-
"tsx": "^4.19.0"
|
|
23
|
-
},
|
|
24
|
-
"devDependencies": {
|
|
25
|
-
"typescript": "^5.9.3",
|
|
26
|
-
"@cloudflare/workers-types": "^4.20260405.1"
|
|
27
|
-
},
|
|
25
|
+
"mcpName": "io.github.pipeworx-io/youtube",
|
|
28
26
|
"pipeworx": {
|
|
29
|
-
"
|
|
30
|
-
"
|
|
27
|
+
"mode": "gateway",
|
|
28
|
+
"slug": "youtube",
|
|
29
|
+
"gatewaySlug": "youtube",
|
|
30
|
+
"sourceHash": "v1-2a0ffba204d9179068424cbc9f17e12d2717af069a4a2c2ab65340c2c584833b",
|
|
31
|
+
"sourceCommit": "98853f34516646cb7c4c1460f09249b262c0269e"
|
|
31
32
|
}
|
|
32
33
|
}
|
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.
|
|
6
|
+
"version": "0.2.0",
|
|
7
7
|
"websiteUrl": "https://pipeworx.io/packs/youtube",
|
|
8
8
|
"repository": {
|
|
9
9
|
"url": "https://github.com/pipeworx-io/mcp-youtube",
|