youtube-knowledge-mcp 1.1.1 → 2.0.0

package/dist/http.js

@@ -0,0 +1,283 @@
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { formatPreflightReport, runPreflight } from './utils/preflight.js';
+function envList(name) {
+    return (process.env[name] ?? '')
+        .split(',')
+        .map((value) => value.trim())
+        .filter(Boolean);
+}
+function envInt(name, fallback) {
+    const parsed = Number.parseInt(process.env[name] ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+export function readHttpConfig() {
+    return {
+        port: envInt('PORT', 3000),
+        bindHost: process.env.MCP_BIND_HOST ?? '0.0.0.0',
+        // An empty MCP_AUTH_TOKEN must mean "no auth", not "the empty token".
+        authToken: process.env.MCP_AUTH_TOKEN?.trim() === '' ? undefined : process.env.MCP_AUTH_TOKEN,
+        allowedHosts: envList('MCP_ALLOWED_HOSTS'),
+        allowedOrigins: envList('MCP_ALLOWED_ORIGINS'),
+        rateLimit: envInt('MCP_RATE_LIMIT', 60),
+        rateWindowMs: envInt('MCP_RATE_WINDOW_MS', 60_000),
+        sessionIdleMs: envInt('MCP_SESSION_IDLE_MS', 30 * 60_000),
+        maxSessions: envInt('MCP_MAX_SESSIONS', 1000),
+    };
+}
+/** Fixed-window counter, per client. */
+export class RateLimiter {
+    limit;
+    windowMs;
+    hits = new Map();
+    constructor(limit, windowMs) {
+        this.limit = limit;
+        this.windowMs = windowMs;
+    }
+    check(key, now = Date.now()) {
+        const entry = this.hits.get(key);
+        if (!entry || now > entry.resetAt) {
+            this.hits.set(key, { count: 1, resetAt: now + this.windowMs });
+            return { allowed: true, remaining: this.limit - 1, retryAfter: 0 };
+        }
+        entry.count++;
+        const allowed = entry.count <= this.limit;
+        return {
+            allowed,
+            remaining: Math.max(0, this.limit - entry.count),
+            retryAfter: allowed ? 0 : Math.ceil((entry.resetAt - now) / 1000),
+        };
+    }
+    sweep(now = Date.now()) {
+        for (const [key, entry] of this.hits) {
+            if (now > entry.resetAt)
+                this.hits.delete(key);
+        }
+    }
+    get size() {
+        return this.hits.size;
+    }
+}
+/**
+ * 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 function tokenMatches(presented, expected) {
+    if (presented === undefined)
+        return false;
+    const a = Buffer.from(presented);
+    const b = Buffer.from(expected);
+    // timingSafeEqual throws on length mismatch, which would itself be a leak;
+    // hash-free equalisation keeps the comparison constant-time for equal lengths
+    // and constant-result for unequal ones.
+    if (a.length !== b.length) {
+        timingSafeEqual(a, a);
+        return false;
+    }
+    return timingSafeEqual(a, b);
+}
+export function bearerToken(header) {
+    if (!header)
+        return undefined;
+    const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+    return match?.[1];
+}
+export function clientKey(req) {
+    const forwarded = req.headers['x-forwarded-for'];
+    const first = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+    return first?.split(',')[0]?.trim() ?? req.socket.remoteAddress ?? 'unknown';
+}
+/**
+ * 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 function sessionIdOf(req) {
+    const header = req.headers['mcp-session-id'];
+    return typeof header === 'string' ? header : undefined;
+}
+function jsonRpcError(res, status, code, message) {
+    if (res.headersSent)
+        return;
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ jsonrpc: '2.0', error: { code, message }, id: null }));
+}
+export function startHttp(createServer, config = readHttpConfig()) {
+    const app = createMcpExpressApp({
+        host: config.bindHost,
+        ...(config.allowedHosts.length > 0 ? { allowedHosts: config.allowedHosts } : {}),
+    });
+    const limiter = new RateLimiter(config.rateLimit, config.rateWindowMs);
+    const sessions = new Map();
+    // Both timers are unref'd: they must never be the reason the process stays up.
+    const sweeper = setInterval(() => {
+        const now = Date.now();
+        limiter.sweep(now);
+        for (const [id, session] of sessions) {
+            if (now - session.lastSeen > config.sessionIdleMs) {
+                sessions.delete(id);
+                void session.transport.close();
+            }
+        }
+    }, 60_000);
+    sweeper.unref();
+    /** Returns true when the request may proceed; otherwise it has been answered. */
+    function authorize(req, res) {
+        if (!config.authToken)
+            return true;
+        if (!tokenMatches(bearerToken(req.headers.authorization), config.authToken)) {
+            // RFC 9728: point unauthenticated callers at the resource metadata.
+            res.setHeader('WWW-Authenticate', `Bearer realm="youtube-knowledge-mcp", resource_metadata="${resourceMetadataUrl(req)}"`);
+            jsonRpcError(res, 401, -32001, 'Unauthorized');
+            return false;
+        }
+        return true;
+    }
+    function rateLimit(req, res) {
+        const { allowed, remaining, retryAfter } = limiter.check(clientKey(req));
+        res.setHeader('RateLimit-Limit', String(config.rateLimit));
+        res.setHeader('RateLimit-Remaining', String(remaining));
+        if (!allowed) {
+            // 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.`);
+            return false;
+        }
+        return true;
+    }
+    function resourceMetadataUrl(req) {
+        const host = req.headers.host ?? `localhost:${config.port}`;
+        const proto = req.headers['x-forwarded-proto'] ?? 'https';
+        return `${String(proto)}://${host}/.well-known/oauth-protected-resource`;
+    }
+    app.post('/mcp', async (req, res) => {
+        if (!rateLimit(req, res))
+            return;
+        if (!authorize(req, res))
+            return;
+        const sessionId = sessionIdOf(req);
+        try {
+            const existing = sessionId ? sessions.get(sessionId) : undefined;
+            if (existing) {
+                existing.lastSeen = Date.now();
+                await existing.transport.handleRequest(req, res, req.body);
+                return;
+            }
+            if (!sessionId && isInitializeRequest(req.body)) {
+                if (sessions.size >= config.maxSessions) {
+                    jsonRpcError(res, 503, -32000, 'Server is at capacity. Try again shortly.');
+                    return;
+                }
+                const transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    ...(config.allowedHosts.length > 0 || config.allowedOrigins.length > 0
+                        ? {
+                            enableDnsRebindingProtection: true,
+                            allowedHosts: config.allowedHosts,
+                            allowedOrigins: config.allowedOrigins,
+                        }
+                        : {}),
+                    onsessioninitialized: (id) => {
+                        sessions.set(id, { transport, lastSeen: Date.now() });
+                    },
+                });
+                transport.onclose = () => {
+                    if (transport.sessionId)
+                        sessions.delete(transport.sessionId);
+                };
+                await createServer('http').connect(transport);
+                await transport.handleRequest(req, res, req.body);
+                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');
+        }
+    });
+    const bySession = async (req, res) => {
+        if (!authorize(req, res))
+            return;
+        const sessionId = sessionIdOf(req);
+        const session = sessionId ? sessions.get(sessionId) : undefined;
+        if (!session) {
+            jsonRpcError(res, 404, -32001, 'Invalid or missing session ID');
+            return;
+        }
+        session.lastSeen = Date.now();
+        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: `${String(req.headers['x-forwarded-proto'] ?? 'https')}://${req.headers.host ?? ''}/mcp`,
+            bearer_methods_supported: ['header'],
+            resource_documentation: 'https://github.com/teobouancheau/youtube-knowledge-mcp#readme',
+        }));
+    });
+    // Unauthenticated on purpose: platform health probes cannot carry a token.
+    app.get('/health', (_req, res) => {
+        void runPreflight().then((report) => {
+            res.writeHead(report.ok ? 200 : 503, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                status: report.ok ? 'ok' : 'degraded',
+                ytDlp: report.ytDlp,
+                ffmpeg: report.ffmpeg,
+                sessions: sessions.size,
+            }));
+        });
+    });
+    let announceReady = () => undefined;
+    const ready = new Promise((resolve) => {
+        announceReady = resolve;
+    });
+    const httpServer = app.listen(config.port, () => {
+        const address = httpServer.address();
+        const port = typeof address === 'object' && address !== null ? address.port : config.port;
+        announceReady({ port });
+        console.error(`MCP Streamable HTTP server listening on ${config.bindHost}:${port}`);
+        console.error(`MCP endpoint: http://localhost:${port}/mcp`);
+        console.error(config.authToken
+            ? 'Authentication: bearer token required'
+            : 'Authentication: DISABLED — set MCP_AUTH_TOKEN to require a bearer token');
+        if (config.allowedHosts.length === 0 && config.allowedOrigins.length === 0) {
+            console.error('DNS rebinding protection: DISABLED — set MCP_ALLOWED_HOSTS and/or MCP_ALLOWED_ORIGINS to enable');
+        }
+        void runPreflight().then((report) => {
+            if (!report.ok)
+                console.error(formatPreflightReport(report));
+        });
+    });
+    // SIGTERM is what container platforms actually send; only SIGINT was handled.
+    const signals = ['SIGINT', 'SIGTERM'];
+    const onSignal = () => {
+        void close().then(() => process.exit(0));
+    };
+    const close = async () => {
+        // Detach first: a handle that has been closed must not keep the process
+        // alive through a listener, and repeated boots must not accumulate them.
+        for (const signal of signals)
+            process.off(signal, onSignal);
+        clearInterval(sweeper);
+        for (const [id, session] of sessions) {
+            sessions.delete(id);
+            await session.transport.close();
+        }
+        await new Promise((resolve) => httpServer.close(() => {
+            resolve();
+        }));
+    };
+    for (const signal of signals)
+        process.once(signal, onSignal);
+    return { close, ready };
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

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

package/dist/index.d.ts

@@ -1,3 +1,21 @@
 #!/usr/bin/env node
-export {};
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Build a fully configured server.
+ *
+ * Exported so the test suite can drive it over an in-memory transport as a real
+ * MCP client, rather than only testing handlers in isolation.
+ */
+export declare function createServer(mode?: 'stdio' | 'http'): McpServer;
+/** An explicit flag wins over the environment, so a launcher can always override. */
+export declare function getTransportMode(): 'stdio' | 'http';
+/**
+ * Report missing or stale external binaries at boot.
+ *
+ * Deliberately non-fatal: the server still starts and still lists its tools, so
+ * a client can call check_health and be told exactly what to install. Exiting
+ * here would surface as an opaque "server failed to start" in the client.
+ */
+export declare function announcePreflight(): Promise<void>;
+export declare function main(): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA4NpE;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,OAAO,GAAG,MAAgB,GAAG,SAAS,CA2fxE;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,IAAI,OAAO,GAAG,MAAM,CAKnD;AAQD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKvD;AAED,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAS1C"}