groupon-mcp: Instructions file for Claude Code

groupon-mcp

MCP server for Groupon. Reads Groupon's public consumer GraphQL endpoint and exposes deal search/browse tools to Claude over stdio. Read-only: no API key, no account, no cookies.

Status: read-path MVP. This phase establishes the Groupon identity and a minimal, compiling stdio skeleton (runMcp with an empty tool set). The deal-read client and tools land in later phases. Purchase / cookie-session / hosted-credential paths are intentionally out of scope and were stripped from the scaffold — they return later.

Commands

npm run build          # tsc + esbuild bundle → dist/index.js + dist/bundle.js
npm test               # tsc typecheck + vitest run
npm run test:watch     # vitest watch
npm run test:coverage  # tsc typecheck + vitest run --coverage (v8 reporter, no thresholds)

Run locally (requires built dist/):

node dist/index.js

Tool naming

All tools are prefixed groupon_ (e.g. groupon_search_deals). None are registered yet in this phase.

Architecture

src/
  version.ts   # single source of truth for VERSION (x-release-please-version)
  index.ts     # MCP server entry — runMcp({ name, version, banner, tools: [] })

Each future tool file exports a register<Domain>Tools(server, deps) function that calls server.registerTool(name, { description, annotations, inputSchema }, handler) (high-level McpServer API with zod schemas) and returns results via textResult(...). index.ts wires them through runMcp from @chrischall/mcp-utils.

Groupon read endpoint (for the next phases)

Groupon deal reads use a consumer GraphQL endpoint reachable from a plain server-side fetch with no cookies, no auth, no bot wall:

POST https://www.groupon.com/mobilenextapi/graphql
headers: { 'content-type': 'application/json', 'apollographql-client-name': 'mobilenextapi' }

The body is a batched array of Apollo Automatic-Persisted-Query (APQ) ops. Introspection is disabled and the server masks all GraphQL errors as opaque 400 HTML, so do not hand-author queries — use Groupon's own persisted-query hash.