mcp-headless-youtube-transcript 0.2.0 → 0.3.0

package/README.md

@@ -6,43 +6,115 @@ An MCP (Model Context Protocol) server that extracts YouTube video transcripts u
 
 - Extract transcripts from YouTube videos using video ID or full URL
 - Support for multiple languages
-- Timestamped transcript output
+- Automatic pagination for large transcripts (98k character chunks)
+- Clean text output optimized for LLM consumption
 - Built with TypeScript and the MCP SDK
 
 ## Installation
 
+Install via npm:
+
 ```bash
-npm install
-npm run build
+npm install -g mcp-headless-youtube-transcript
+```
+
+Or use directly with npx:
+
+```bash
+npx mcp-headless-youtube-transcript
 ```
 
-## Usage
+## MCP Configuration
 
-### As an MCP Server
+Add this server to your MCP settings:
 
-This server implements the Model Context Protocol and can be used with MCP clients.
+```json
+{
+  "mcpServers": {
+    "youtube-transcript": {
+      "command": "npx",
+      "args": ["-y", "mcp-headless-youtube-transcript"]
+    }
+  }
+}
+```
 
-### Tools Available
+## Tools Available
 
-#### `get_youtube_transcript`
+### `get_youtube_transcript`
 
-Extracts transcript/captions from a YouTube video.
+Extracts transcript/captions from a YouTube video with automatic pagination for large transcripts.
 
 **Parameters:**
 - `videoId` (required): YouTube video ID or full URL
 - `lang` (optional): Language code for captions (e.g., "en", "es", "ko"). Defaults to "en"
+- `segment` (optional): Segment number to retrieve (1-based). Each segment is ~98k characters. Defaults to 1
 
-**Example:**
+**Examples:**
+
+Basic usage:
+```json
+{
+  "name": "get_youtube_transcript",
+  "arguments": {
+    "videoId": "dQw4w9WgXcQ"
+  }
+}
+```
+
+With language:
 ```json
 {
   "name": "get_youtube_transcript",
   "arguments": {
     "videoId": "dQw4w9WgXcQ",
-    "lang": "en"
+    "lang": "es"
   }
 }
 ```
 
+With pagination:
+```json
+{
+  "name": "get_youtube_transcript",
+  "arguments": {
+    "videoId": "dQw4w9WgXcQ",
+    "segment": 2
+  }
+}
+```
+
+## Response Format
+
+The tool returns the raw transcript text. For large transcripts, the response includes pagination information:
+
+```
+[Segment 1 of 3]
+
+this is the actual transcript text content...
+```
+
+When multiple segments are available, you can retrieve subsequent segments by incrementing the `segment` parameter.
+
+## Caching
+
+The server includes built-in caching to improve performance for paginated requests. The cache behavior can be configured with an environment variable:
+
+- `TRANSCRIPT_CACHE_TTL`: Cache duration in seconds (default: 300 = 5 minutes)
+
+### Cache Features:
+- Full transcripts are cached on first fetch
+- Cache expiration time is updated on each read or write
+- Expired entries are automatically cleaned up after each request
+- Each video+language combination is cached separately
+
+### Setting Cache Duration:
+
+```bash
+# Set cache to 10 minutes
+TRANSCRIPT_CACHE_TTL=600 npx mcp-headless-youtube-transcript
+```
+
 ## Supported URL Formats
 
 - Video ID: `dQw4w9WgXcQ`

package/build/index.js

@@ -4,6 +4,41 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { getSubtitles } from 'headless-youtube-captions';
 import { extractVideoId } from './utils.js';
+// In-memory cache
+const transcriptCache = new Map();
+// Get cache TTL from environment variable (default 5 minutes)
+const CACHE_TTL_SECONDS = parseInt(process.env.TRANSCRIPT_CACHE_TTL || '300');
+// Cache helper functions
+function getCacheKey(videoId, lang) {
+    return `${videoId}:${lang}`;
+}
+function getCachedTranscript(videoId, lang) {
+    const key = getCacheKey(videoId, lang);
+    const entry = transcriptCache.get(key);
+    if (!entry)
+        return null;
+    const now = Date.now();
+    if (now > entry.expiresAt) {
+        transcriptCache.delete(key);
+        return null;
+    }
+    // Update expiration time on read
+    entry.expiresAt = now + (CACHE_TTL_SECONDS * 1000);
+    return entry.transcript;
+}
+function setCachedTranscript(videoId, lang, transcript) {
+    const key = getCacheKey(videoId, lang);
+    const expiresAt = Date.now() + (CACHE_TTL_SECONDS * 1000);
+    transcriptCache.set(key, { transcript, expiresAt });
+}
+function cleanupExpiredCache() {
+    const now = Date.now();
+    for (const [key, entry] of transcriptCache.entries()) {
+        if (now > entry.expiresAt) {
+            transcriptCache.delete(key);
+        }
+    }
+}
 const server = new Server({
     name: 'mcp-headless-youtube-transcript',
     version: '1.0.0',
@@ -54,13 +89,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             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,
-            });
-            // Get the full raw text content
-            const fullTranscript = subtitles.map(s => s.text).join(' ');
+            // Check cache first
+            let fullTranscript = getCachedTranscript(extractedVideoId, lang);
+            if (!fullTranscript) {
+                // Get subtitles using headless-youtube-captions
+                const subtitles = await getSubtitles({
+                    videoID: extractedVideoId,
+                    lang: lang,
+                });
+                // Get the full raw text content
+                fullTranscript = subtitles.map(s => s.text).join(' ');
+                // Cache the full transcript
+                setCachedTranscript(extractedVideoId, lang, fullTranscript);
+            }
             // Split into 98k character chunks
             const chunkSize = 98000;
             const chunks = [];
@@ -106,6 +147,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 isError: true,
             };
         }
+        finally {
+            // Cleanup expired cache entries after each request
+            cleanupExpiredCache();
+        }
     }
     throw new Error(`Unknown tool: ${name}`);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-headless-youtube-transcript",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server for extracting YouTube video transcripts using headless-youtube-captions",
   "main": "build/index.js",
   "bin": {