Better Google Search Console

Instructions

Implementation Reference

• src/tools/get-overview.ts:38-157 (handler)

  Main handler function that executes the get_overview tool logic. Fetches all GSC properties, queries SQLite databases for each property's metrics (clicks, impressions, CTR, position), calculates percentage changes vs prior period, generates sparkline data, and sorts results by the specified criteria.

  export async function getOverviewData(
    gscClient: GscClient,
    params: OverviewParams
  ): Promise<OverviewData> {
    const { dateRange = '28d', sortBy = 'alpha', search } = params;
    const { current, prior } = getPeriodDates(dateRange);
    const dataDir = getDataDir();
  
    // Get all properties from GSC API
    const allProperties = await gscClient.listProperties();
    const properties: PropertyOverview[] = [];
  
    const pctChange = (curr: number, prev: number): number | null =>
      prev === 0 ? null : Math.round(((curr - prev) / prev) * 1000) / 10;
  
    for (const prop of allProperties) {
      const dbFilename = sanitizeSiteUrl(prop.siteUrl) + '.db';
      const dbPath = join(dataDir, dbFilename);
  
      // Skip properties without synced data
      if (!existsSync(dbPath)) continue;
  
      // Extract clean domain
      let domain = prop.siteUrl
        .replace(/^sc-domain:/, '')
        .replace(/^https?:\/\//, '')
        .replace(/\/+$/, '');
  
      // Filter by search substring
      if (search && !domain.toLowerCase().includes(search.toLowerCase())) continue;
  
      const db = new Database(dbPath);
      try {
        // Summary for current period
        const currentSummary = db.queryOne(`
          SELECT
            COALESCE(SUM(clicks), 0) as clicks,
            COALESCE(SUM(impressions), 0) as impressions,
            ROUND(CAST(SUM(clicks) AS REAL) / NULLIF(SUM(impressions), 0), 4) as ctr,
            ROUND(AVG(position), 1) as avg_position
          FROM search_analytics
          WHERE date BETWEEN ? AND ?
        `, [current.startDate, current.endDate]);
  
        // Summary for prior period
        const priorSummary = db.queryOne(`
          SELECT
            COALESCE(SUM(clicks), 0) as clicks,
            COALESCE(SUM(impressions), 0) as impressions,
            ROUND(CAST(SUM(clicks) AS REAL) / NULLIF(SUM(impressions), 0), 4) as ctr,
            ROUND(AVG(position), 1) as avg_position
          FROM search_analytics
          WHERE date BETWEEN ? AND ?
        `, [prior.startDate, prior.endDate]);
  
        // Skip if no data at all
        if (currentSummary.clicks === 0 && currentSummary.impressions === 0 &&
            priorSummary.clicks === 0 && priorSummary.impressions === 0) continue;
  
        // Daily sparkline data
        const sparkline = db.query(`
          SELECT date,
            SUM(clicks) as clicks,
            SUM(impressions) as impressions
          FROM search_analytics
          WHERE date BETWEEN ? AND ?
          GROUP BY date
          ORDER BY date ASC
        `, [current.startDate, current.endDate]);
  
        // Last synced
        const meta = db.getPropertyMeta(prop.siteUrl);
  
        properties.push({
          siteUrl: prop.siteUrl,
          domain,
          lastSyncedAt: meta?.lastSyncedAt ?? null,
          current: {
            clicks: currentSummary.clicks,
            impressions: currentSummary.impressions,
            ctr: currentSummary.ctr ?? 0,
            avgPosition: currentSummary.avg_position ?? null,
          },
          changes: {
            clicksPct: pctChange(currentSummary.clicks, priorSummary.clicks),
            impressionsPct: pctChange(currentSummary.impressions, priorSummary.impressions),
            ctrPct: pctChange(currentSummary.ctr ?? 0, priorSummary.ctr ?? 0),
            avgPositionPct: (currentSummary.avg_position != null && priorSummary.avg_position != null)
              ? pctChange(currentSummary.avg_position, priorSummary.avg_position)
              : null,
          },
          sparkline,
        });
      } finally {
        db.close();
      }
    }
  
    // Sort
    switch (sortBy) {
      case 'clicks':
        properties.sort((a, b) => b.current.clicks - a.current.clicks);
        break;
      case 'impressions':
        properties.sort((a, b) => b.current.impressions - a.current.impressions);
        break;
      case 'ctr':
        properties.sort((a, b) => b.current.ctr - a.current.ctr);
        break;
      case 'position':
        properties.sort((a, b) => (a.current.avgPosition ?? 999) - (b.current.avgPosition ?? 999)); // lower is better, null sorts last
        break;
      case 'alpha':
      default:
        properties.sort((a, b) => a.domain.localeCompare(b.domain));
        break;
    }
  
    return { dateRange, sortBy, properties };
  }

• src/server.ts:151-176 (registration)

  Registration of the get_overview tool with the MCP server. Defines the tool name, description, input schema (dateRange, sortBy, search parameters), and wraps the handler function with error handling and response formatting.

  registerAppTool(
    server,
    'get_overview',
    {
      title: 'All Properties Overview',
      description: 'See all your sites at a glance. Shows an interactive grid of every synced GSC property with clicks, impressions, CTR, position, percentage changes, and sparkline trends. Click any property card to open its full dashboard. If no data appears, run setup first to sync your properties.',
      inputSchema: {
        dateRange: z.string().optional().describe('Date range: "7d", "28d", "3m", "6m", "12m", "16m". Default: "28d".'),
        sortBy: z.enum(['alpha', 'clicks', 'impressions', 'ctr', 'position']).optional().describe('Sort order for property cards. Default: "alpha".'),
        search: z.string().optional().describe('Filter properties by domain name substring.'),
      },
      _meta: { ui: { resourceUri: overviewResourceUri } },
    },
    async (args) => {
      try {
        const data = await getOverviewData(gscClient, args);
  
        if (data.properties.length === 0) {
          return {
            content: [{
              type: 'text',
              text: 'No synced properties found. Run setup to connect and sync your Google Search Console properties.',
            }],
            structuredContent: data as any,
          };
        }

• src/tools/get-overview.ts:7-36 (schema)

  Type definitions for the get_overview tool: OverviewParams (input parameters), PropertyOverview (per-property metrics including current stats, percentage changes, and sparkline data), and OverviewData (complete response structure).

  export interface OverviewParams {
    dateRange?: string;
    sortBy?: 'alpha' | 'clicks' | 'impressions' | 'ctr' | 'position';
    search?: string;
  }
  
  interface PropertyOverview {
    siteUrl: string;
    domain: string;
    lastSyncedAt: string | null;
    current: {
      clicks: number;
      impressions: number;
      ctr: number;
      avgPosition: number | null;
    };
    changes: {
      clicksPct: number | null;
      impressionsPct: number | null;
      ctrPct: number | null;
      avgPositionPct: number | null;
    };
    sparkline: Array<{ date: string; clicks: number; impressions: number }>;
  }
  
  interface OverviewData {
    dateRange: string;
    sortBy: string;
    properties: PropertyOverview[];
  }

• src/tools/helpers.ts:120-211 (helper)

  Helper function getPeriodDates used by get_overview to calculate current and prior period date ranges for comparison metrics. Supports multiple comparison modes and handles edge cases like leap years and month overflow.

  export function getPeriodDates(
    range: string,
    referenceDate?: Date,
    comparisonMode: ComparisonMode = 'previous_period',
    matchWeekdays: boolean = false
  ): {
    current: { startDate: string; endDate: string };
    prior: { startDate: string; endDate: string };
  } {
    const current = parseDateRange(range, referenceDate);
  
    if (comparisonMode === 'disabled') {
      // Return empty prior period — callers should check for this
      return {
        current,
        prior: { startDate: current.startDate, endDate: current.startDate },
      };
    }
  
    const startMs = new Date(current.startDate).getTime();
    const endMs = new Date(current.endDate).getTime();
    const DAY = 24 * 60 * 60 * 1000;
    const durationMs = endMs - startMs;
  
    let priorStart: Date;
    let priorEnd: Date;
  
    switch (comparisonMode) {
      case 'year_over_year': {
        const s = new Date(current.startDate);
        const e = new Date(current.endDate);
        const sDay = s.getDate();
        const eDay = e.getDate();
        s.setFullYear(s.getFullYear() - 1);
        // Handle leap year: Feb 29 → Feb 28 (setFullYear may roll to Mar 1)
        if (s.getDate() !== sDay) s.setDate(0); // last day of previous month
        e.setFullYear(e.getFullYear() - 1);
        if (e.getDate() !== eDay) e.setDate(0);
        priorStart = s;
        priorEnd = e;
        break;
      }
      case 'previous_month': {
        const s = new Date(current.startDate);
        const e = new Date(current.endDate);
        const sMonth = (s.getMonth() - 1 + 12) % 12;
        const eMonth = (e.getMonth() - 1 + 12) % 12;
        s.setMonth(s.getMonth() - 1);
        // Handle day overflow: e.g. Mar 31 → setMonth(-1) → "Feb 31" → Mar 3
        if (s.getMonth() !== sMonth) s.setDate(0); // last day of intended month
        e.setMonth(e.getMonth() - 1);
        if (e.getMonth() !== eMonth) e.setDate(0);
        priorStart = s;
        priorEnd = e;
        break;
      }
      case 'previous_period':
      default: {
        priorEnd = new Date(startMs - DAY);
        priorStart = new Date(priorEnd.getTime() - durationMs);
        break;
      }
    }
  
    // Match weekdays: shift prior period so that the start day-of-week matches
    if (matchWeekdays) {
      const currentStartDay = new Date(current.startDate).getDay();
      const priorStartDay = priorStart.getDay();
      let diff = currentStartDay - priorStartDay;
      // Find the closest shift that aligns weekdays (within ±3 days)
      if (diff > 3) diff -= 7;
      if (diff < -3) diff += 7;
      priorStart = new Date(priorStart.getTime() + diff * DAY);
      priorEnd = new Date(priorEnd.getTime() + diff * DAY);
  
      // Safety: ensure prior period never overlaps with current period
      const currentStartMs = new Date(current.startDate).getTime();
      if (priorEnd.getTime() >= currentStartMs) {
        const overshoot = priorEnd.getTime() - currentStartMs + DAY;
        priorStart = new Date(priorStart.getTime() - overshoot);
        priorEnd = new Date(priorEnd.getTime() - overshoot);
      }
    }
  
    return {
      current,
      prior: {
        startDate: formatDate(priorStart),
        endDate: formatDate(priorEnd),
      },
    };
  }