gsc-mcp-server copilot-instructions.md

GSC-MCP Copilot Instructions

Project Overview

This is a Model Context Protocol (MCP) server that provides Google Search Console (GSC) API access to AI clients (Claude, Cursor, VS Code Copilot). It's distributed as a CLI tool via npm (gsc-mcp) with OAuth/service account authentication.

Architecture

src/
├── index.ts          # Public exports for programmatic use
├── types.ts          # Zod schemas & TypeScript types (single source of truth)
├── cli/              # Commander-based CLI (`gsc-mcp init|doctor|run`)
├── server/           # MCP server implementation
│   ├── index.ts      # Server factory with stdio/HTTP transports
│   ├── tools/        # MCP tools organized by domain (searchAnalytics, sitemaps, etc.)
│   └── resources/    # MCP resources
├── gsc/client.ts     # GSC API wrapper with retry logic & pagination
├── auth/             # OAuth2 + service account auth, token storage (keytar/file)
└── cache/sqlite.ts   # SQLite cache with TTL for query results

Key data flows:

1. CLI commands → createServer() → MCP transport (stdio for clients, HTTP for debugging)
2. Tool calls → handleToolCall() routes to domain handlers → GSCClient → Google API
3. Tokens stored via keytar (OS keychain) with file fallback; config in env-paths directories

Development Commands

npm run build      # tsup build (ESM, Node 18+)
npm run dev        # Watch mode
npm run typecheck  # tsc --noEmit
npm run lint       # eslint src/
gsc-mcp run --http 3333  # Debug server with HTTP endpoints

Code Conventions

Adding New MCP Tools

1. Create tool definition in src/server/tools/<domain>.ts following the pattern:
   • Export <domain>Tools array with name, description, inputSchema
   • Export handle<Domain>Tool(name, args) handler function
2. Register in src/server/tools/index.ts by adding to getAllTools() and routing in handleToolCall()
3. Tool names use dot notation: searchanalytics.query, opportunities.lowCtrHighPos