gsc_sitemap_list

Instructions

Implementation Reference

• src/tools/gsc/sitemap-list.ts:17-62 (handler)

  The main handler function that authenticates via OAuth2, calls the GSC sitemaps.list API, formats the sitemap data into a human-readable text response, and returns the result.

  handler: async (args, config) => {
    const auth = getOAuth2Client();
    const sc = google.searchconsole({ version: "v1", auth });
  
    const siteUrl = args.site_url ?? config.gsc?.default_site;
    if (!siteUrl) {
      throw new Error(
        "site_url is required. Pass it as an argument or set gsc.default_site in ~/.seo-mcp/config.json"
      );
    }
  
    const res = await sc.sitemaps.list({ siteUrl });
    const sitemaps = res.data.sitemap ?? [];
  
    if (sitemaps.length === 0) {
      return { content: [{ type: "text", text: `No sitemaps found for ${siteUrl}.` }] };
    }
  
    const lines = sitemaps.map((sm) => {
      const submitted = sm.lastSubmitted ?? "—";
      const downloaded = sm.lastDownloaded ?? "—";
      const warnings = Number(sm.warnings ?? 0);
      const errors = Number(sm.errors ?? 0);
  
      const countSummary = (sm.contents ?? [])
        .map((c) => `${c.type}: ${c.submitted ?? 0} submitted, ${c.indexed ?? 0} indexed`)
        .join(" | ");
  
      const statusParts = [];
      if (errors > 0) statusParts.push(`${errors} errors`);
      if (warnings > 0) statusParts.push(`${warnings} warnings`);
      const status = statusParts.length > 0 ? statusParts.join(", ") : "OK";
  
      return [
        `Path: ${sm.path}`,
        `  Type: ${sm.type ?? "—"} | Status: ${status}`,
        `  Submitted: ${submitted} | Downloaded: ${downloaded}`,
        countSummary ? `  Counts: ${countSummary}` : "",
      ]
        .filter(Boolean)
        .join("\n");
    });
  
    const header = `Sitemaps for ${siteUrl} (${sitemaps.length} total):\n`;
    return { content: [{ type: "text", text: header + lines.join("\n\n") }] };
  },

• src/tools/gsc/sitemap-list.ts:6-10 (schema)

  Zod schema defining the input: an optional site_url string (defaults to config's gsc.default_site).

  const schema = z.object({
    site_url: z.string().optional().describe(
      "Site URL in GSC format, e.g. 'sc-domain:example.com'. Uses config default if omitted."
    ),
  });

• src/tools/gsc/index.ts:9-16 (registration)

  The gscSitemapList tool is registered as part of the gscTools array, exported for integration into the MCP server.

  export const gscTools: ToolDefinition[] = [
    gscSearchPerformance as unknown as ToolDefinition,
    gscStrikingDistance as unknown as ToolDefinition,
    gscTrafficDrop as unknown as ToolDefinition,
    gscUrlInspection as unknown as ToolDefinition,
    gscSitemapList as unknown as ToolDefinition,
    gscBrandNonbrand as unknown as ToolDefinition,
  ];

• src/auth/gsc.ts:12-39 (helper)

  getOAuth2Client helper that reads credentials and tokens, sets up the Google OAuth2 client used by the sitemap list handler.

  export function getOAuth2Client() {
    const clientId = process.env.GSC_CLIENT_ID;
    const clientSecret = process.env.GSC_CLIENT_SECRET;
  
    if (!clientId || !clientSecret) {
      throw new Error(
        "GSC_CLIENT_ID and GSC_CLIENT_SECRET must be set.\n" +
        "Run: npx @patchwindow/seo-mcp auth gsc\n" +
        "See README for Google Cloud Console setup instructions."
      );
    }
  
    const oauth2 = new google.auth.OAuth2(clientId, clientSecret, GSC_REDIRECT_URI);
  
    const tokens = readTokens();
    if (!tokens) {
      throw new Error(
        "GSC not authenticated. Run: npx @patchwindow/seo-mcp auth gsc"
      );
    }
  
    oauth2.setCredentials(tokens);
    oauth2.on("tokens", (newTokens) => {
      writeTokens({ ...tokens, ...newTokens });
    });
  
    return oauth2;
  }

• src/types/tool.ts:12-17 (helper)

  ToolDefinition interface that defines the shape (name, description, schema, handler) which the gscSitemapList export conforms to.

  export interface ToolDefinition<T extends AnyZodObject = AnyZodObject> {
    name: string;
    description: string;
    schema: T;
    handler: (args: z.infer<T>, config: Config) => Promise<ToolResult>;
  }