mcp-headless-youtube-transcript 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:github.com)",
+      "Bash(mkdir:*)",
+      "Bash(npm install)",
+      "Bash(npm run build:*)",
+      "Bash(rm:*)",
+      "Bash(npm run test:run:*)",
+      "Bash(timeout 5s npm start)",
+      "Bash(npm view:*)"
+    ],
+    "deny": []
+  }
+}

package/README.md

@@ -0,0 +1,94 @@
+# MCP Headless YouTube Transcript
+
+An MCP (Model Context Protocol) server that extracts YouTube video transcripts using the `headless-youtube-captions` library.
+
+## Features
+
+- Extract transcripts from YouTube videos using video ID or full URL
+- Support for multiple languages
+- Timestamped transcript output
+- Built with TypeScript and the MCP SDK
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Usage
+
+### As an MCP Server
+
+This server implements the Model Context Protocol and can be used with MCP clients.
+
+### Tools Available
+
+#### `get_youtube_transcript`
+
+Extracts transcript/captions from a YouTube video.
+
+**Parameters:**
+- `videoId` (required): YouTube video ID or full URL
+- `lang` (optional): Language code for captions (e.g., "en", "es", "ko"). Defaults to "en"
+
+**Example:**
+```json
+{
+  "name": "get_youtube_transcript",
+  "arguments": {
+    "videoId": "dQw4w9WgXcQ",
+    "lang": "en"
+  }
+}
+```
+
+## Supported URL Formats
+
+- Video ID: `dQw4w9WgXcQ`
+- YouTube URLs:
+  - `https://www.youtube.com/watch?v=dQw4w9WgXcQ`
+  - `https://youtu.be/dQw4w9WgXcQ`
+  - `https://www.youtube.com/embed/dQw4w9WgXcQ`
+  - `https://www.youtube.com/v/dQw4w9WgXcQ`
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Build for production
+npm run build
+
+# Start the server
+npm start
+
+# Run tests
+npm test
+
+# Run tests once (CI mode)
+npm run test:run
+```
+
+## Testing
+
+The project includes comprehensive tests:
+
+- **Unit tests**: Test helper functions like URL parsing and time formatting
+- **Integration tests**: Test the core transcript extraction logic with mocked APIs
+- **Manual tests**: Optional tests that call real YouTube APIs (skipped by default)
+
+All tests use Vitest and include mocking of the headless-youtube-captions library to ensure reliable testing without external API dependencies.
+
+## Dependencies
+
+- `@modelcontextprotocol/sdk`: MCP SDK for building servers
+- `headless-youtube-captions`: Library for extracting YouTube captions
+
+## License
+
+MIT

package/build/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { getSubtitles } from 'headless-youtube-captions';
+import { extractVideoId, formatTime } from './utils.js';
+const server = new Server({
+    name: 'mcp-headless-youtube-transcript',
+    version: '1.0.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Tool definitions
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'get_youtube_transcript',
+                description: 'Extract transcript/captions from a YouTube video',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        videoId: {
+                            type: 'string',
+                            description: 'YouTube video ID or full URL',
+                        },
+                        lang: {
+                            type: 'string',
+                            description: 'Language code for captions (e.g., "en", "es", "ko"). Defaults to "en"',
+                            default: 'en',
+                        },
+                    },
+                    required: ['videoId'],
+                },
+            },
+        ],
+    };
+});
+// Tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (name === 'get_youtube_transcript') {
+        try {
+            const { videoId, lang = 'en' } = args;
+            // Extract video ID from URL if a full URL is provided
+            const extractedVideoId = extractVideoId(videoId);
+            if (!extractedVideoId) {
+                throw new Error('Invalid YouTube video ID or URL');
+            }
+            // Get subtitles using headless-youtube-captions
+            const subtitles = await getSubtitles({
+                videoID: extractedVideoId,
+                lang: lang,
+            });
+            // Format the transcript
+            const transcript = subtitles
+                .map((subtitle) => `[${formatTime(subtitle.start)}] ${subtitle.text}`)
+                .join('\n');
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `YouTube Transcript for video ID: ${extractedVideoId}\nLanguage: ${lang}\n\n${transcript}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error getting YouTube transcript: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    throw new Error(`Unknown tool: ${name}`);
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('MCP Headless YouTube Transcript server running on stdio');
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/utils.d.ts

@@ -0,0 +1,3 @@
+export declare function extractVideoId(input: string): string | null;
+export declare function formatTime(seconds: number): string;
+//# sourceMappingURL=utils.d.ts.map

package/build/utils.js

@@ -0,0 +1,26 @@
+// Helper function to extract video ID from YouTube URL
+export function extractVideoId(input) {
+    // If it's already just a video ID (11 characters), return it
+    if (/^[a-zA-Z0-9_-]{11}$/.test(input)) {
+        return input;
+    }
+    // Extract from various YouTube URL formats
+    const patterns = [
+        /(?:youtube\.com\/watch\?.*v=|youtu\.be\/|youtube\.com\/embed\/)([a-zA-Z0-9_-]{11})/,
+        /youtube\.com\/v\/([a-zA-Z0-9_-]{11})/,
+    ];
+    for (const pattern of patterns) {
+        const match = input.match(pattern);
+        if (match) {
+            return match[1];
+        }
+    }
+    return null;
+}
+// Helper function to format time from seconds to MM:SS format
+export function formatTime(seconds) {
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = Math.floor(seconds % 60);
+    return `${minutes.toString().padStart(2, '0')}:${remainingSeconds.toString().padStart(2, '0')}`;
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "mcp-headless-youtube-transcript",
+  "version": "0.1.0",
+  "description": "MCP server for extracting YouTube video transcripts using headless-youtube-captions",
+  "main": "build/index.js",
+  "bin": {
+    "mcp-headless-youtube-transcript": "build/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node build/index.js",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "prepublishOnly": "npm run build && npm run test:run"
+  },
+  "keywords": [
+    "mcp",
+    "server",
+    "youtube",
+    "transcript",
+    "captions"
+  ],
+  "author": "Andrew Lewin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrewlwn77/mcp-headless-youtube-transcript.git"
+  },
+  "bugs": {
+    "url": "https://github.com/andrewlwn77/mcp-headless-youtube-transcript/issues"
+  },
+  "homepage": "https://github.com/andrewlwn77/mcp-headless-youtube-transcript#readme",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "headless-youtube-captions": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0",
+    "@vitest/ui": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}