@disruptorganic/mcp-google-search-console 1.0.0

package/dist/tools/get-top-queries.js

@@ -0,0 +1,254 @@
+import { listProperties, matchProperty, generatePropertyMatchError } from '../gsc/properties.js';
+import { executeTopNQuery } from '../gsc/queries.js';
+import { getTopQueriesParamsSchema } from '../utils/validators.js';
+import { logger } from '../utils/logger.js';
+export const getTopQueriesTool = {
+    name: 'get_top_queries',
+    description: 'Quickly retrieves top performing search queries for a property. Returns the most impactful keywords sorted by clicks, impressions, CTR, or position. Ideal for quick insights into what drives traffic. Supports filtering by minimum thresholds (e.g., min 100 clicks), position ranges (e.g., positions 1-10), and date ranges. No chunking needed - results fit within token limits. IMPORTANT: Use list_properties first to get the correct property identifier.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            property: {
+                type: 'string',
+                description: 'Property identifier from list_properties (e.g., "sc-domain:example.com")',
+            },
+            startDate: {
+                type: 'string',
+                description: 'Start date in ISO 8601 format (YYYY-MM-DD)',
+                pattern: '^\\d{4}-\\d{2}-\\d{2}$',
+            },
+            endDate: {
+                type: 'string',
+                description: 'End date in ISO 8601 format (YYYY-MM-DD)',
+                pattern: '^\\d{4}-\\d{2}-\\d{2}$',
+            },
+            limit: {
+                type: 'number',
+                description: 'Number of top queries to return (1-1000, default: 20)',
+                minimum: 1,
+                maximum: 1000,
+                default: 20,
+            },
+            sortBy: {
+                type: 'string',
+                enum: ['clicks', 'impressions', 'ctr', 'position'],
+                description: 'Metric to sort by (default: clicks)',
+                default: 'clicks',
+            },
+            sortOrder: {
+                type: 'string',
+                enum: ['asc', 'desc'],
+                description: 'Sort order (default: desc)',
+                default: 'desc',
+            },
+            searchType: {
+                type: 'string',
+                enum: ['web', 'image', 'video', 'news', 'discover', 'googleNews'],
+                description: 'Search type filter (default: web)',
+                default: 'web',
+            },
+            minClicks: {
+                type: 'number',
+                description: 'Minimum clicks threshold (optional)',
+                minimum: 0,
+            },
+            minImpressions: {
+                type: 'number',
+                description: 'Minimum impressions threshold (optional)',
+                minimum: 0,
+            },
+            positionRange: {
+                type: 'object',
+                properties: {
+                    min: {
+                        type: 'number',
+                        description: 'Minimum position (e.g., 1)',
+                        minimum: 1,
+                    },
+                    max: {
+                        type: 'number',
+                        description: 'Maximum position (e.g., 10)',
+                        minimum: 1,
+                    },
+                },
+                required: ['min', 'max'],
+                description: 'Filter by position range (optional)',
+            },
+            deviceType: {
+                type: 'string',
+                enum: ['desktop', 'mobile', 'tablet'],
+                description: 'Filter by device type (optional)',
+            },
+            country: {
+                type: 'string',
+                description: '3-letter country code (e.g., "usa", "gbr") (optional)',
+                pattern: '^[a-z]{3}$',
+            },
+        },
+        required: ['property', 'startDate', 'endDate'],
+    },
+};
+export async function handleGetTopQueries(params, client) {
+    try {
+        logger.info('Handling get_top_queries request', {
+            propertyInput: params.property,
+            limit: params.limit || 20,
+            sortBy: params.sortBy || 'clicks',
+            dateRange: params.startDate && params.endDate ? `${params.startDate} to ${params.endDate}` : 'not provided',
+        });
+        const validationResult = getTopQueriesParamsSchema.safeParse(params);
+        if (!validationResult.success) {
+            const errorMessages = validationResult.error.issues.map(issue => {
+                const path = issue.path.length > 0 ? `${issue.path.join('.')}: ` : '';
+                return `${path}${issue.message}`;
+            }).join('; ');
+            logger.error('Input validation failed', {
+                errors: errorMessages,
+                params,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: 'Input validation failed',
+                            details: errorMessages,
+                        }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+        const validated = validationResult.data;
+        const { property, startDate, endDate, limit = 20, sortBy = 'clicks', sortOrder = 'desc', searchType = 'web', minClicks, minImpressions, positionRange, deviceType, country, } = validated;
+        logger.debug('Fetching available properties');
+        const availableProperties = await listProperties(client);
+        if (availableProperties.length === 0) {
+            logger.warn('No properties found for this account');
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: 'No properties found',
+                            details: 'No Google Search Console properties are accessible with this account. Please verify your account has access to at least one property.',
+                        }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+        const matchResult = matchProperty(property, availableProperties);
+        if (!matchResult.matched) {
+            const errorMessage = generatePropertyMatchError(matchResult, availableProperties);
+            logger.error('Property matching failed', {
+                searchInput: property,
+                matchType: matchResult.matchType,
+                alternativeCount: matchResult.alternatives?.length || 0,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: 'Property not found or ambiguous',
+                            details: errorMessage,
+                        }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+        const matchedProperty = matchResult.matched;
+        logger.info('Property matched successfully', {
+            searchInput: property,
+            matched: matchedProperty.propertyUrl,
+            matchType: matchResult.matchType,
+        });
+        logger.info('Executing top queries query', {
+            property: matchedProperty.propertyUrl,
+            limit,
+            dateRange: `${startDate} to ${endDate}`,
+        });
+        const results = await executeTopNQuery(client, matchedProperty.propertyUrl, startDate, endDate, 'query', {
+            limit,
+            sortBy: sortBy,
+            sortOrder: sortOrder,
+            searchType,
+            minClicks,
+            minImpressions,
+            positionRange,
+            deviceType,
+            country,
+        });
+        const topQueries = results.map((row) => ({
+            query: row.keys[0] || '',
+            clicks: row.clicks,
+            impressions: row.impressions,
+            ctr: row.ctr,
+            position: row.position,
+        }));
+        const filters = {};
+        if (minClicks !== undefined)
+            filters.minClicks = minClicks;
+        if (minImpressions !== undefined)
+            filters.minImpressions = minImpressions;
+        if (positionRange)
+            filters.positionRange = positionRange;
+        if (deviceType)
+            filters.deviceType = deviceType;
+        if (country)
+            filters.country = country;
+        const responseObject = {
+            property: matchedProperty.propertyUrl,
+            topQueries,
+            totalQueries: topQueries.length,
+            ...(Object.keys(filters).length > 0 && { filters }),
+            sortBy,
+            sortOrder,
+            searchType,
+            dateRange: {
+                start: startDate,
+                end: endDate,
+            },
+        };
+        logger.info('Get top queries completed successfully', {
+            property: matchedProperty.propertyUrl,
+            queriesReturned: topQueries.length,
+            limit,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(responseObject, null, 2),
+                }],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorStack = error instanceof Error ? error.stack : undefined;
+        logger.error('Get top queries handler failed', {
+            error: errorMessage,
+            stack: errorStack,
+            params,
+        });
+        let userFriendlyMessage = errorMessage;
+        if (errorMessage.includes('permission') || errorMessage.includes('Permission')) {
+            userFriendlyMessage = `Permission denied for property ${params.property}. Use list_properties to see accessible properties.`;
+        }
+        else if (errorMessage.includes('not found') || errorMessage.includes('Not Found')) {
+            userFriendlyMessage = `Property ${params.property} not found. Use list_properties to get valid property identifiers.`;
+        }
+        else if (errorMessage.includes('date') || errorMessage.includes('Date')) {
+            userFriendlyMessage = `Invalid date range. ${errorMessage}`;
+        }
+        else if (errorMessage.includes('rate limit') || errorMessage.includes('Rate limit')) {
+            userFriendlyMessage = 'Rate limit exceeded. Please wait a moment and try again.';
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: 'Get top queries execution failed',
+                        details: userFriendlyMessage,
+                    }, null, 2),
+                }],
+            isError: true,
+        };
+    }
+}
+//# sourceMappingURL=get-top-queries.js.map

package/dist/tools/get-top-queries.js.map

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

package/dist/tools/health-check.d.ts

@@ -0,0 +1,12 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { GSCClient } from '../gsc/client.js';
+export interface ToolResponse {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export declare const healthCheckTool: Tool;
+export declare function handleHealthCheck(_params: any, client: GSCClient): Promise<ToolResponse>;
+//# sourceMappingURL=health-check.d.ts.map

package/dist/tools/health-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-check.d.ts","sourceRoot":"","sources":["../../src/tools/health-check.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAS7C,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAKD,eAAO,MAAM,eAAe,EAAE,IAS7B,CAAC;AASF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,GAAG,EACZ,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,YAAY,CAAC,CA6GvB"}

package/dist/tools/health-check.js

@@ -0,0 +1,107 @@
+import { getToolStats } from './index.js';
+import { propertyCache } from '../utils/cache.js';
+import { logger } from '../utils/logger.js';
+import { config, getEnvironment } from '../config/index.js';
+export const healthCheckTool = {
+    name: 'health_check',
+    description: 'Check MCP server health and status. Returns authentication status, rate limiter statistics, cache statistics, tool availability, and system information. Useful for monitoring and debugging.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+};
+export async function handleHealthCheck(_params, client) {
+    try {
+        logger.debug('Health check requested');
+        const rateLimitStatus = client.getRateLimitStatus();
+        const cacheStats = propertyCache.getStats();
+        const toolStats = getToolStats();
+        let authenticationStatus = 'authenticated';
+        let authenticationError;
+        try {
+            const isValid = await client.validateConnection();
+            if (!isValid) {
+                authenticationStatus = 'error';
+                authenticationError = 'Connection validation failed';
+            }
+        }
+        catch (error) {
+            authenticationStatus = 'error';
+            authenticationError =
+                error instanceof Error ? error.message : String(error);
+        }
+        const health = {
+            status: authenticationStatus === 'authenticated' ? 'healthy' : 'degraded',
+            timestamp: new Date().toISOString(),
+            server: {
+                name: 'google-search-console-mcp',
+                version: '1.0.0',
+                uptime: process.uptime(),
+                nodeVersion: process.version,
+                platform: process.platform,
+                environment: getEnvironment(),
+            },
+            authentication: {
+                status: authenticationStatus,
+                error: authenticationError,
+                tokenPath: config.tokenPath,
+            },
+            rateLimiter: {
+                ...rateLimitStatus,
+                description: 'Token bucket rate limiter (18 queries/second, 1,080/minute)',
+            },
+            cache: {
+                ...cacheStats,
+                description: 'Property list cache (24-hour TTL)',
+            },
+            tools: {
+                total: toolStats.total,
+                available: toolStats.names,
+                details: toolStats.tools.map((t) => ({
+                    name: t.name,
+                    requiredParams: t.requiredParams,
+                    optionalParams: t.optionalParams,
+                })),
+            },
+            memory: {
+                heapUsed: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
+                heapTotal: Math.round(process.memoryUsage().heapTotal / 1024 / 1024),
+                rss: Math.round(process.memoryUsage().rss / 1024 / 1024),
+                unit: 'MB',
+            },
+        };
+        logger.info('Health check completed', {
+            status: health.status,
+            authStatus: health.authentication.status,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(health, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error('Health check failed', {
+            error: errorMessage,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: 'error',
+                        timestamp: new Date().toISOString(),
+                        error: errorMessage,
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+//# sourceMappingURL=health-check.js.map

package/dist/tools/health-check.js.map

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