search_analytics

Instructions

Implementation Reference

• src/search-console.ts:60-66 (handler)

  Core handler function that executes the Google Search Console search analytics API query, handling site URL normalization and permissions.

  async searchAnalytics(siteUrl: string, requestBody: SearchanalyticsQueryRequest) {
    const webmasters = await this.getWebmasters();
    return this.handlePermissionError(
      () => webmasters.searchanalytics.query({ siteUrl, requestBody }),
      () => webmasters.searchanalytics.query({ siteUrl: this.normalizeUrl(siteUrl), requestBody }),
    );
  }

• src/index.ts:219-277 (handler)

  MCP tool call handler for 'search_analytics' that validates input with schema, builds the API request body with filters, calls SearchConsoleService.searchAnalytics, and formats the response.

  case 'search_analytics': {
    const args = SearchAnalyticsSchema.parse(request.params.arguments);
    const siteUrl = args.siteUrl;
  
    // --- 动态构建请求体 ---
    const requestBody: any = {
      startDate: args.startDate,
      endDate: args.endDate,
      dimensions: args.dimensions,
      searchType: args.type,
      aggregationType: args.aggregationType,
      rowLimit: args.rowLimit,
    };
  
    const filters = [];
    if (args.pageFilter) {
      filters.push({
        dimension: 'page',
        operator: args.filterOperator,
        expression: args.pageFilter,
      });
    }
    if (args.queryFilter) {
      filters.push({
        dimension: 'query',
        operator: args.filterOperator,
        expression: args.queryFilter,
      });
    }
    if (args.countryFilter) {
        filters.push({
          dimension: 'country',
          operator: 'equals', // Country filter only supports 'equals'
          expression: args.countryFilter,
        });
    }
    if (args.deviceFilter) {
        filters.push({
          dimension: 'device',
          operator: 'equals', // Device filter only supports 'equals'
          expression: args.deviceFilter,
        });
    }
  
    if (filters.length > 0) {
      requestBody.dimensionFilterGroups = [{ filters }];
    }
    // --- 构建结束 ---
  
    const response = await searchConsole.searchAnalytics(siteUrl, requestBody);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(response.data, null, 2),
        },
      ],
    };
  }

• src/schemas.ts:11-43 (schema)

  Zod schema defining the input parameters for the search_analytics tool, including dates, dimensions, filters, and validation.

  export const SearchAnalyticsSchema = GSCBaseSchema.extend({
    startDate: z.string().describe('Start date in YYYY-MM-DD format'),
    endDate: z.string().describe('End date in YYYY-MM-DD format'),
    dimensions: z
      .string()
      .transform((val) => val.split(','))
      .refine((val) =>
        val.every((d) => ['query', 'page', 'country', 'device', 'searchAppearance'].includes(d)),
      )
      .optional()
      .describe(
        'Comma-separated list of dimensions to break down results by, such as query, page, country, device, searchAppearance',
      ),
    type: z
      .enum(['web', 'image', 'video', 'news'])
      .optional()
      .describe('Type of search to filter by, such as web, image, video, news'),
    aggregationType: z
      .enum(['auto', 'byNewsShowcasePanel', 'byProperty', 'byPage'])
      .optional()
      .describe('Type of aggregation, such as auto, byNewsShowcasePanel, byProperty, byPage'),
    rowLimit: z.number().min(1).max(25000).default(1000).describe('Maximum number of rows to return (up to 25,000 for enhanced performance)'),
    pageFilter: z.string().optional().describe('Filter by a specific page URL. Use with filterOperator.'),
    queryFilter: z.string().optional().describe('Filter by a specific query string. Use with filterOperator.'),
    countryFilter: z.string().optional().describe('Filter by a country using ISO 3166-1 alpha-3 code (e.g., USA, CHN).'),
    deviceFilter: z.enum(['DESKTOP', 'MOBILE', 'TABLET']).optional().describe('Filter by device type.'),
    filterOperator: z
      .enum(['equals', 'contains', 'notEquals', 'notContains', 'includingRegex', 'excludingRegex'])
      .default('equals')
      .optional()
      .describe('Operator for page and query filters. Defaults to "equals". Enhanced with regex support.'),
    regexFilter: z.string().optional().describe('Advanced regex filter for intelligent query matching'),
  });

• src/index.ts:48-52 (registration)

  Registration of the search_analytics tool in the list_tools handler, providing name, description, and input schema.

  {
    name: 'search_analytics',
    description: 'Get search performance data from Google Search Console',
    inputSchema: zodToJsonSchema(SearchAnalyticsSchema),
  },