impactdotcom-mcp CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A local stdio MCP server wrapping the Impact.com partner REST API. Built because Impact.com's hosted MCP can't be used from Claude Code (its OAuth server has no Dynamic Client Registration). Primary purpose: diagnose publisher tracking problems — specifically "clicks but no revenue" — by exposing the click → action → revenue funnel.

Commands

• npm run build — compile TypeScript to dist/.
• npm run dev — watch-mode run via tsx.
• npm run inspect — build + open the MCP Inspector against the server (primary manual test loop).
• npm run typecheck / npm run lint — must pass; lint enforces no stray console.log.
• npm run check:secrets — run before every commit. Fails if any tracked file contains a real Account SID/Auth Token.

Architecture

• src/index.ts — entry; loads .env, validates config, registers tools, connects stdio.
• src/config.ts — env validation; computes basePath and Basic-auth header.
• src/client.ts — the only module that talks HTTP (impactGet, impactGetAll, impactWrite, runAsyncJob). Add new endpoints here, not ad-hoc fetch in tools.
• src/diagnostics.ts — encodes Impact's attribution rules + reversal codes; powers diagnose_tracking.
• src/tools/* — one file per domain; each exports a register* function. tools/index.ts wires them up and gates writes.

Non-obvious rules (get these wrong and it breaks)

• stdout is reserved for JSON-RPC. Never console.log. Log via src/logger.ts (log.info/warn/error → stderr, with secret redaction).
• Persona prefix: all paths are under /{IMPACT_ACCOUNT_TYPE}/{AccountSID} (default Mediapartners). If every call 403s/404s, the account type is probably wrong (Mediapartners vs Advertisers).
• JSON, not XML: the API defaults to XML; the client always sends Accept: application/json. Don't remove that header.
• Tool inputs are YYYY-MM-DD, but date encoding differs by endpoint (verified live): the /Actions endpoint rejects bare dates — it needs full ISO‑8601 datetimes (2026-05-27T00:00:00Z), so the Actions tools convert via toStartOfDayIso/toEndOfDayIso. Reports take bare YYYY-MM-DD. The /Actions endpoint also has max 45-day range, ~3-year-back limit, default last 7 days, no Page/PageSize (paginate via @nextpageuri), and no OrderId filter — trace an order via find_action_by_order.
• Report params differ per report (verified live): Performance by Brand = partner_performance_by_program (filters START_DATE/END_DATE); Advanced Action Listing = mp_action_listing_sku (filters Start Date/End Date, with spaces). Don't assume a uniform param name — call get_report_metadata first.
• get_account hits the persona root (/Mediapartners/{SID}), not /Accounts — the latter is 403 for scoped Mediapartner tokens. Similarly the single /Clicks/{id} resource may be 403 for a scoped token even when ClickExport works.
• Writes are gated: create_tracking_link and impact_api_request only register when IMPACT_ENABLE_WRITES=true. create_tracking_link/TrackingLinks path casing is the one write not yet exercised live.
• Rate limits are real: the API has an hourly quota and exports (ClickExport, ReportExport) are expensive — bursting parallel exports exhausts it (retry-after can be hours). The client caps concurrency (IMPACT_MAX_CONCURRENCY, default 4) and fails fast on a 429 whose reset is >30s out (reset time included in the error) instead of hanging. Don't loop exports across many days without spacing.