Function registerGscQueryTools

packages/mcp/src/tools/gsc/queries.ts:74–149

(
  server: McpServer,
  context: McpAuthContext,
)

}

export function registerGscQueryTools(
  server: McpServer,
  context: McpAuthContext,
) {
  server.tool(
    'gsc_get_top_queries',
    'Get the top search queries driving traffic from Google Search, ranked by clicks. Includes impressions, CTR, and average position for each query.',
    {
      projectId: projectIdSchema(context),
      ...zDateRange,
      limit: z
        .number()
        .min(1)
        .max(1000)
        .default(100)
        .optional()
        .describe('Maximum number of queries to return (1-1000, default 100)'),
    },
    async ({ projectId: inputProjectId, startDate: sd, endDate: ed, limit }) =>
      withErrorHandling(async () => {
        const projectId = await resolveProjectId(context, inputProjectId);
        const { startDate, endDate } = resolveDateRange(sd, ed);
        return getGscQueries(projectId, startDate, endDate, limit ?? 100);
      }),
  );

  server.tool(
    'gsc_get_query_opportunities',
    'Identify low-hanging-fruit SEO opportunities: queries ranking on positions 4-20 with meaningful search volume where small improvements could yield significant traffic gains. Ranked by opportunity score.',
    {
      projectId: projectIdSchema(context),
      ...zDateRange,
      minImpressions: z
        .number()
        .min(1)
        .default(50)
        .optional()
        .describe(
          'Minimum impression threshold to filter out low-volume queries (default: 50)',
        ),
    },
    async ({ projectId: inputProjectId, startDate: sd, endDate: ed, minImpressions }) =>
      withErrorHandling(async () => {
        const projectId = await resolveProjectId(context, inputProjectId);
        const { startDate, endDate } = resolveDateRange(sd, ed);
        const queries = await getGscQueries(projectId, startDate, endDate, 5000);
        const filtered = queries.filter(
          (q) => q.impressions >= (minImpressions ?? 50),
        );
        const opportunities = computeOpportunities(filtered);
        return {
          opportunities,
          total_analyzed: filtered.length,
          min_impressions: minImpressions ?? 50,
        };
      }),
  );