youtube-mcp: Instructions file for GitHub Copilot

Copilot Instructions

Build, test, and lint commands

• npm install installs dependencies.
• npm run build compiles the TypeScript source in src/ to dist/. This is the main verification command currently configured in the repo.
• npm start runs the built MCP server over stdio from dist/index.js.
• npm run start:http runs the built server in Streamable HTTP mode. node dist/index.js --http is equivalent.
• npm run dev and npm run dev:http do a one-time tsc build and then start the server; they are not watch-mode commands.
• npm run check runs npm test plus the release checks: check:release (package, lockfile, and server.json versions agree; workflow policy), check:package (packed file allow-list), and check:install (installs the packed tarball and lists tools over stdio). CI runs it on Node 22.21.0 and 24.
• Releases follow RELEASE.md: a pushed v* tag publishes npm, then the MCP Registry, then a GitHub release. Never create or push a release tag without explicit approval of the version and commit. Keep the version in package.json, package-lock.json, and server.json in sync, and add docs/release-notes-vX.Y.Z.md plus a CHANGELOG.md entry.
• npm test builds and runs the offline suite in test/*.test.mjs with Node's built-in test runner against dist/. Tests replace globalThis.fetch with fakes from test/helpers.mjs; they never touch the network. Run one file with npm run build && node --test test/transcript.test.mjs.
• There is no lint script.

High-level architecture

• src/index.ts is the only entrypoint. It builds an McpServer, registers all tools, and then selects the transport:
  • stdio by default via StdioServerTransport
  • HTTP when --http is passed or TRANSPORT=http is set
• In HTTP mode, src/index.ts builds an Express app through the MCP SDK, adds optional bearer-token auth with API_TOKEN, rate-limits /mcp, and keeps a Map<string, StreamableHTTPServerTransport> so each MCP session can continue across requests.
• Each tool lives in src/tools/ and follows the same pattern:
  • export a Zod schema
  • export an output schema for structuredContent
  • export an async handler
  • register the tool in createServer() using inputSchema: schema.shape and outputSchema
  • wrap the handler with withLogging(...)
• Shared YouTube access lives in src/utils/youtube-api.ts. That module owns:
  • the singleton youtubei.js Innertube client
  • TTL caches for video info, comment pages, and search results
  • per-call deadlines via runWithDeadline (src/utils/abort.ts), linked to the MCP request's extra.signal
• src/utils/abort.ts keeps the current call's AbortSignal in AsyncLocalStorage. contextFetch is passed to youtubei.js as its fetch, and the transcript library's videoFetch/playerFetch/transcriptFetch hooks also use it, so cancellation aborts real HTTP requests. It turns HTTP 403/429 into ACCESS_BLOCKED before a library can relabel them.
• src/utils/config.ts reads the YT_* limits once at startup.
• Transcript features are the notable exception to the youtubei.js path:
  • get_video_transcript and get_transcript_languages use youtube-transcript-plus
  • metadata, comments, and search use the selected provider (youtubei.js by default, or the official YouTube Data API v3 with YT_PROVIDER=api)
• src/utils/parse-video-id.ts is the normalization layer for every tool that accepts a URL or ID. It supports watch URLs, youtu.be, embed URLs, shorts, live URLs, and raw 11-character IDs.