youtube-analytics-mcp 1.0.0

package/README.md

@@ -0,0 +1,237 @@
+# YouTube Analytics MCP Server
+
+A Model Context Protocol (MCP) server for YouTube Analytics data access with demographics and discovery tools, built with a scalable config-driven architecture.
+
+## Core Features
+
+- **Channel Analytics**: Get comprehensive channel overview, growth patterns, and vital signs
+- **Video Performance**: Analyze individual video metrics, audience retention, and drop-off points
+- **Viewer Demographics**: Access age/gender breakdowns and geographic distribution data
+- **Discovery Insights**: Understand traffic sources and search terms driving views
+- **Engagement Metrics**: Track likes, comments, shares, and viewer interaction patterns
+- **Audience Retention**: Identify exact moments where viewers drop off for content optimization
+- **Performance Comparison**: Compare metrics between different time periods
+- **Public Channel Analysis**: Research competitor channels and trending content
+
+## Core Architecture Principles
+
+This MCP server follows a **config-driven architecture** that provides:
+
+- **Maintainability**: Clear separation between tool definitions and implementation
+- **Scalability**: Easy to add new tools without modifying core server logic
+- **Consistency**: Standardized error handling and response formatting
+- **Readability**: Clean, declarative configuration that serves as documentation
+
+## Setup
+
+### 1. Google API Credentials
+
+To use this YouTube Analytics MCP server, you need to set up Google API credentials:
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select an existing one
+3. Enable the YouTube Analytics API and YouTube Data API v3
+4. Go to "Credentials" and create a new OAuth 2.0 Client ID
+5. Download the credentials as JSON
+6. Save the file as `credentials.json` in the `src/auth/` directory
+
+**Privacy Note**: All data processing happens locally on your computer. Your credentials and analytics data never leave your machine - the server runs entirely locally and connects directly to Google's APIs from your system.
+
+### 2. Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run in development mode
+npm run dev
+
+# Inspect with MCP Inspector
+npm run inspect
+```
+
+## Architecture Overview
+
+## Project Structure
+
+```
+src/
+├── index.ts                 # Main server entry point (config-driven)
+├── tool-configs.ts         # Central tool configuration aggregator
+├── types.ts                # TypeScript interfaces and types
+├── auth/
+│   ├── tool-configs.ts     # Authentication tool configurations
+│   └── ...
+├── server/
+│   ├── info-configs.ts     # Server info tool configurations
+│   └── ...
+└── youtube/tools/
+    ├── channel-configs.ts  # Channel analysis tool configurations
+    ├── health-configs.ts   # Channel health tool configurations
+    ├── audience-configs.ts # Audience demographics tool configurations
+    ├── discovery-configs.ts # Traffic source tool configurations
+    ├── performance-configs.ts # Performance analysis tool configurations
+    └── engagement-configs.ts # Engagement metrics tool configurations
+```
+
+## Tool Configuration Structure
+
+Each tool is defined by a configuration object:
+
+```typescript
+interface ToolConfig<T = any> {
+  name: string;           // Tool name
+  description: string;    // Tool description
+  schema: any;           // Zod schema for validation
+  handler: (params: T, context: ToolContext) => Promise<ToolResult>;
+  category?: string;      // Optional grouping
+}
+```
+
+## Available Tools
+
+### Authentication Tools
+- `check_auth_status` - Check YouTube authentication status
+- `revoke_auth` - Revoke authentication and clear tokens
+
+### Channel Tools
+- `get_channel_info` - Get basic channel information
+- `get_channel_videos` - Get list of channel videos with filters
+
+### Health Tools
+- `get_channel_overview` - Get channel vital signs and growth patterns
+- `get_comparison_metrics` - Compare metrics between time periods
+- `get_average_view_percentage` - Get average view percentage
+
+### Audience Tools
+- `get_video_demographics` - Get age/gender breakdown
+- `get_geographic_distribution` - Get viewer geographic distribution
+- `get_subscriber_analytics` - Get subscriber vs non-subscriber analytics
+
+### Discovery Tools
+- `get_traffic_sources` - Get traffic source analysis
+- `get_search_terms` - Get search terms for SEO insights
+
+### Performance Tools
+- `get_audience_retention` - Track viewer retention patterns
+- `get_retention_dropoff_points` - Find exact drop-off moments
+
+### Engagement Tools
+- `get_engagement_metrics` - Analyze likes, comments, and shares
+
+## Adding New Tools
+
+To add a new tool, simply create a configuration object and add it to the appropriate config file:
+
+```typescript
+// In src/youtube/tools/new-category-configs.ts
+export const newCategoryToolConfigs: ToolConfig[] = [
+  {
+    name: "new_tool_name",
+    description: "Description of what the tool does",
+    category: "new_category",
+    schema: z.object({
+      // Define your parameters here
+      param1: z.string().describe("Description of parameter 1"),
+      param2: z.number().optional().describe("Optional parameter 2"),
+    }),
+    handler: async ({ param1, param2 }, { getYouTubeClient }: ToolContext) => {
+      try {
+        const youtubeClient = await getYouTubeClient();
+        // Your tool implementation here
+        
+        return {
+          content: [{
+            type: "text",
+            text: "Tool result here"
+          }]
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text",
+            text: `Error: ${error instanceof Error ? error.message : String(error)}`
+          }],
+          isError: true
+        };
+      }
+    },
+  },
+];
+
+// Then add to src/tool-configs.ts
+export const allToolConfigs = [
+  // ... existing configs
+  ...newCategoryToolConfigs,
+];
+```
+
+## Benefits of Config-Driven Architecture
+
+1. **Clean Separation**: Tool definitions are separate from server setup
+2. **Type Safety**: Full TypeScript support for schemas and handlers
+3. **Documentation**: Config serves as living documentation
+4. **Testing**: Easier to unit test individual tools
+5. **Extensibility**: Simple to add new tool categories
+6. **Maintainability**: Consistent patterns across all tools
+7. **Scalability**: Easy to manage many tools without cluttering main file
+
+## Server Registration Pattern
+
+The server automatically registers all tools from configuration:
+
+```typescript
+// Automatic registration from configs - no manual server.tool() calls needed
+allToolConfigs.forEach((toolConfig) => {
+  server.tool(
+    toolConfig.name,           // Tool name from config
+    toolConfig.description,    // Description from config
+    toolConfig.schema,         // Zod schema from config  
+    async (params: any) => {   // Handler wrapper
+      return toolConfig.handler(params, { 
+        authManager, 
+        getYouTubeClient, 
+        clearYouTubeClientCache 
+      });
+    }
+  );
+});
+```
+
+## Error Handling
+
+All tools follow a consistent error handling pattern:
+
+```typescript
+try {
+  // Tool implementation
+  return {
+    content: [{ type: "text", text: "Success result" }]
+  };
+} catch (error) {
+  return {
+    content: [{ 
+      type: "text", 
+      text: `Error: ${error instanceof Error ? error.message : String(error)}` 
+    }],
+    isError: true
+  };
+}
+```
+
+## Context Injection
+
+Tools receive a context object with shared dependencies:
+
+```typescript
+interface ToolContext {
+  authManager: AuthManager;
+  getYouTubeClient: () => Promise<YouTubeClient>;
+  clearYouTubeClientCache: () => void;
+}
+```
+
+This architecture makes the codebase more maintainable, scalable, and easier to extend while preserving all existing functionality.

package/build/auth/auth-manager.js

@@ -0,0 +1,176 @@
+import { authenticate } from '@google-cloud/local-auth';
+import { promises as fs } from 'fs';
+import { OAuth2Client } from 'google-auth-library';
+import path from 'path';
+import { AuthenticationError, TokenExpiredError } from './types.js';
+export class AuthManager {
+    AUTH_DIR = path.join(process.cwd(), 'src', 'auth');
+    CREDENTIALS_PATH = path.join(this.AUTH_DIR, 'credentials.json');
+    TOKEN_PATH = path.join(this.AUTH_DIR, 'token.json');
+    SCOPES = [
+        'https://www.googleapis.com/auth/youtube.readonly',
+        'https://www.googleapis.com/auth/yt-analytics.readonly',
+        'https://www.googleapis.com/auth/youtubepartner'
+    ];
+    authClient = null;
+    constructor() {
+    }
+    async getAuthClient() {
+        // Return cached client if available and valid
+        if (this.authClient) {
+            try {
+                await this.refreshTokenIfNeeded(this.authClient);
+                return this.authClient;
+            }
+            catch (error) {
+                console.log('Cached auth client invalid, creating new one...');
+                this.authClient = null;
+            }
+        }
+        try {
+            // Try to load existing token
+            const content = await fs.readFile(this.TOKEN_PATH, 'utf8');
+            const tokenData = JSON.parse(content);
+            // Load credentials to get client_id and client_secret
+            const credentialsContent = await fs.readFile(this.CREDENTIALS_PATH, 'utf8');
+            const credentials = JSON.parse(credentialsContent);
+            // Create OAuth2Client with proper credentials
+            this.authClient = new OAuth2Client(credentials.web.client_id, credentials.web.client_secret, credentials.web.redirect_uris[0]);
+            // Set the stored tokens
+            this.authClient.setCredentials({
+                access_token: tokenData.access_token,
+                refresh_token: tokenData.refresh_token,
+                expiry_date: tokenData.expiry_date
+            });
+            // Refresh token if needed
+            await this.refreshTokenIfNeeded(this.authClient);
+            return this.authClient;
+        }
+        catch (error) {
+            // If no token exists or loading fails, trigger authentication
+            console.log('No valid token found, initiating authentication flow...');
+            this.authClient = null;
+            return await this.authenticate();
+        }
+    }
+    async authenticate() {
+        try {
+            // Check if credentials file exists
+            try {
+                await fs.access(this.CREDENTIALS_PATH);
+            }
+            catch {
+                throw new AuthenticationError(`Credentials file not found at ${this.CREDENTIALS_PATH}. ` +
+                    'Please place your Google OAuth credentials in src/auth/credentials.json');
+            }
+            console.log('Auth manager CREDENTIALS_PATH', this.CREDENTIALS_PATH);
+            // Trigger OAuth flow using local-auth
+            const client = await authenticate({
+                scopes: this.SCOPES,
+                keyfilePath: this.CREDENTIALS_PATH,
+            });
+            // Save tokens
+            if (client.credentials) {
+                this.authClient = client;
+                await this.saveToken(this.authClient);
+                console.log('Authentication successful! Tokens saved.');
+            }
+            return this.authClient || client;
+        }
+        catch (error) {
+            if (error instanceof AuthenticationError) {
+                throw error;
+            }
+            throw new AuthenticationError(`Authentication failed: ${error}`);
+        }
+    }
+    async refreshTokenIfNeeded(auth) {
+        try {
+            // Check if token is expired or about to expire (within 5 minutes)
+            const now = Date.now();
+            const expiryDate = auth.credentials.expiry_date;
+            const fiveMinutesFromNow = now + (5 * 60 * 1000);
+            if (!expiryDate || expiryDate <= fiveMinutesFromNow) {
+                console.log('Token expired or expiring soon, refreshing...');
+                // Ensure we have a refresh token
+                if (!auth.credentials.refresh_token) {
+                    console.error('No refresh token available');
+                    throw new TokenExpiredError('No refresh token available');
+                }
+                const { credentials } = await auth.refreshAccessToken();
+                auth.setCredentials(credentials);
+                // Update stored token with new access token
+                await this.updateStoredToken(auth);
+                console.log('Token refreshed successfully');
+            }
+        }
+        catch (error) {
+            console.error('Token refresh failed:', error);
+            // Clear the cached client so we don't keep using invalid tokens
+            this.authClient = null;
+            throw new TokenExpiredError('Token refresh failed - please re-authenticate');
+        }
+    }
+    async saveToken(client) {
+        try {
+            // Read credentials to get client_id and client_secret
+            const credentialsContent = await fs.readFile(this.CREDENTIALS_PATH, 'utf8');
+            const credentials = JSON.parse(credentialsContent);
+            const tokenData = {
+                type: 'authorized_user',
+                client_id: credentials.web.client_id,
+                client_secret: credentials.web.client_secret,
+                refresh_token: client.credentials.refresh_token,
+                access_token: client.credentials.access_token || undefined,
+                expiry_date: client.credentials.expiry_date || undefined
+            };
+            await fs.writeFile(this.TOKEN_PATH, JSON.stringify(tokenData, null, 2));
+            // Set restrictive permissions on token file
+            await fs.chmod(this.TOKEN_PATH, 0o600);
+        }
+        catch (error) {
+            throw new AuthenticationError(`Failed to save token: ${error}`);
+        }
+    }
+    async updateStoredToken(auth) {
+        try {
+            const content = await fs.readFile(this.TOKEN_PATH, 'utf8');
+            const tokenData = JSON.parse(content);
+            // Update with new access token and expiry
+            tokenData.access_token = auth.credentials.access_token || undefined;
+            tokenData.expiry_date = auth.credentials.expiry_date || undefined;
+            await fs.writeFile(this.TOKEN_PATH, JSON.stringify(tokenData, null, 2));
+        }
+        catch (error) {
+            throw new AuthenticationError(`Failed to update stored token: ${error}`);
+        }
+    }
+    async revokeToken() {
+        try {
+            const auth = await this.getAuthClient();
+            await auth.revokeCredentials();
+            // Clear cached client
+            this.authClient = null;
+            // Remove stored token file
+            try {
+                await fs.unlink(this.TOKEN_PATH);
+                console.log('Token revoked and removed successfully');
+            }
+            catch (error) {
+                console.warn('Failed to remove token file:', error);
+            }
+        }
+        catch (error) {
+            throw new AuthenticationError(`Failed to revoke token: ${error}`);
+        }
+    }
+    async isAuthenticated() {
+        try {
+            const auth = await this.getAuthClient();
+            return !!auth.credentials.access_token;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/build/auth/tool-configs.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+export const authTools = [
+    {
+        name: "check_auth_status",
+        description: "Check if the user is authenticated with YouTube",
+        category: "authentication",
+        schema: z.object({}),
+        handler: async (_, { authManager }) => {
+            try {
+                const isAuthenticated = await authManager.isAuthenticated();
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Authentication Status: ${isAuthenticated ? 'Authenticated' : 'Not Authenticated'}`
+                        }]
+                };
+            }
+            catch (error) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Error checking auth status: ${error instanceof Error ? error.message : String(error)}`
+                        }],
+                    isError: true
+                };
+            }
+        },
+    },
+    {
+        name: "revoke_auth",
+        description: "Revoke YouTube authentication and remove stored tokens",
+        category: "authentication",
+        schema: z.object({}),
+        handler: async (_, { authManager, clearYouTubeClientCache }) => {
+            try {
+                await authManager.revokeToken();
+                // Clear YouTube client cache
+                clearYouTubeClientCache();
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Authentication revoked successfully. You will need to re-authenticate to use YouTube tools."
+                        }]
+                };
+            }
+            catch (error) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Error revoking auth: ${error instanceof Error ? error.message : String(error)}`
+                        }],
+                    isError: true
+                };
+            }
+        },
+    },
+];

package/build/auth/types.js

@@ -0,0 +1,27 @@
+// Error types
+export class AuthenticationError extends Error {
+    account;
+    constructor(message, account) {
+        super(message);
+        this.account = account;
+        this.name = 'AuthenticationError';
+    }
+}
+export class TokenExpiredError extends AuthenticationError {
+    constructor(account) {
+        super(`Token expired for account ${account}`, account);
+        this.name = 'TokenExpiredError';
+    }
+}
+export class QuotaExceededError extends Error {
+    constructor(quotaType) {
+        super(`YouTube API quota exceeded: ${quotaType}`);
+        this.name = 'QuotaExceededError';
+    }
+}
+export class RateLimitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RateLimitError';
+    }
+}

package/build/index.js

@@ -0,0 +1,115 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { AuthManager } from './auth/auth-manager.js';
+import { AuthenticationError } from './auth/types.js';
+import { allTools } from './tool-configs.js';
+import { allPrompts } from './prompt-configs.js';
+import { YouTubeClient } from './youtube/youtube-client.js';
+// Create server instance
+const server = new McpServer({
+    name: "youtube-analytics-mcp",
+    version: "1.0.0",
+    capabilities: {
+        resources: {},
+        tools: {},
+        prompts: {},
+    },
+});
+// Initialize auth manager
+const authManager = new AuthManager();
+// Cache for YouTube client
+let youtubeClientCache = null;
+// Helper function to get YouTube client
+async function getYouTubeClient() {
+    try {
+        // Return cached client if available
+        if (youtubeClientCache) {
+            return youtubeClientCache;
+        }
+        const auth = await authManager.getAuthClient();
+        youtubeClientCache = new YouTubeClient(auth);
+        return youtubeClientCache;
+    }
+    catch (error) {
+        // Clear cache on error
+        youtubeClientCache = null;
+        if (error instanceof AuthenticationError) {
+            throw new Error(`Authentication failed: ${error.message}`);
+        }
+        throw new Error(`Failed to get YouTube client: ${error}`);
+    }
+}
+// Helper function to clear YouTube client cache
+function clearYouTubeClientCache() {
+    youtubeClientCache = null;
+}
+// Register all tools
+allTools.forEach((toolConfig) => {
+    console.error(`Registering tool: ${toolConfig.name}`);
+    server.registerTool(toolConfig.name, {
+        description: toolConfig.description,
+        inputSchema: toolConfig.schema?.shape || {},
+    }, async (params) => {
+        try {
+            console.error(`Executing tool: ${toolConfig.name}`);
+            return await toolConfig.handler(params, {
+                authManager,
+                getYouTubeClient,
+                clearYouTubeClientCache
+            });
+        }
+        catch (error) {
+            console.error(`Error in tool ${toolConfig.name}:`, error);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Error executing ${toolConfig.name}: ${error instanceof Error ? error.message : String(error)}`
+                    }],
+                isError: true
+            };
+        }
+    });
+});
+console.error(`Total tools registered: ${allTools.length}`);
+// Register all prompts
+allPrompts.forEach((promptConfig) => {
+    console.error(`Registering prompt: ${promptConfig.name}`);
+    server.registerPrompt(promptConfig.name, {
+        title: promptConfig.title,
+        description: promptConfig.description,
+        argsSchema: promptConfig.argsSchema,
+    }, async (args) => {
+        try {
+            console.error(`Executing prompt: ${promptConfig.name}`);
+            return await promptConfig.handler(args);
+        }
+        catch (error) {
+            console.error(`Error in prompt ${promptConfig.name}:`, error);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Error executing ${promptConfig.name}: ${error instanceof Error ? error.message : String(error)}`
+                    }],
+                isError: true
+            };
+        }
+    });
+});
+console.error(`Total prompts registered: ${allPrompts.length}`);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("YouTube Analytics MCP Server running on stdio");
+}
+process.on('SIGINT', async () => {
+    console.error("Shutting down server...");
+    process.exit(0);
+});
+process.on('SIGTERM', async () => {
+    console.error("Shutting down server...");
+    process.exit(0);
+});
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});