# CLAUDE.md — Klar Attribution API MCP Server

## Project goal

Build a Model Context Protocol (MCP) server that wraps the Klar Attribution API
so that any MCP-capable client (Claude Desktop, Claude Code, etc.) can query a
Klar store's attribution data in natural language. The server exposes the
attribution report as typed tools, handles authentication, and absorbs Klar's
API constraints (short-lived tokens, the 31-day window limit, and the rate
limit) so the user never has to think about them.

## Tech stack

- TypeScript + Node.js (Node 20+).
- @modelcontextprotocol/sdk (latest) — use McpServer and StdioServerTransport.
- zod for input validation.
- stdio transport (local), so the server plugs straight into Claude Desktop and
  Claude Code.
- Native fetch (built into Node 20+) — no extra HTTP client needed.

Python is a fine alternative (official mcp / FastMCP SDK). If you go that route,
keep the same tool surface and the same constraint handling.

## Build steps

1. Scaffold the project: "type": "module" in package.json, a tsconfig.json
   targeting NodeNext, output to ./build, and a build script (tsc).
2. Implement a Klar API client module (auth + report) honouring the constraints
   in the API reference below.
3. Implement the MCP server with the tools described under "Tool surface".
4. Compile (npm run build) and confirm it builds cleanly.
5. Write a README that includes the exact claude_desktop_config.json entry.

Do not call the live API during the build. The user supplies a real refresh
token at runtime via an environment variable.

## Klar Attribution API reference

Base URL: https://api.getklar.com

### Authentication — exchange the refresh token for an access token

- Endpoint: POST /public/auth/token
- Request header: token: <KLAR_REFRESH_TOKEN> (the store's static refresh token)
- Success: 201 Created
- Response body: { "accessToken": "eyJ...", "expiresIn": 300000 }

The accessToken is a JWT valid for 5 minutes (300,000 ms). Cache it and reuse it
across calls; only request a new one when the current token is within ~30
seconds of expiry.

The refresh token is one per store/user and is a secret. Read it from the
KLAR_REFRESH_TOKEN environment variable. Never hardcode it and never write it to
logs.

### Report — fetch attribution data

- Endpoint: GET /public/attribution
- Header: Authorization: Bearer <accessToken>

Query parameters:

- startDate (string, required): format yyyy-mm-dd.
- endDate (string, required): format yyyy-mm-dd. EXCLUSIVE — results cover
  [startDate, endDate). Must be within 31 days of startDate.
- metric (string, optional): one of first_touch, last_touch, data_driven,
  linear, any_click, any_click_unique, u_shape, time_decay, marketing_mix.
- window (string, optional): one of unlimited, 1_day, 7_day, 28_day.
- date_breakdown (string, optional): one of order, touch.

A 200 OK returns a JSON array of row objects (schema below).

### Constraints the server MUST enforce

1. Rate limit: 2 requests per 30 seconds. This applies to the API as a whole, so
   budget the auth call into it too. Implement a small token-bucket or queue so
   chunked or back-to-back calls never exceed the limit.
2. 31-day window maximum. For longer ranges, split into consecutive windows of
   <= 31 days (use 30 to leave a safety margin), call each window, and
   concatenate the rows. Because endDate is exclusive, chunk as [d0, d0+30),
   [d0+30, d0+60), ... with no overlap and no gap. Warn the user in the tool
   description that wide ranges take longer because of the rate limit.
3. Token caching as described under Authentication.
4. Logging: on stdio transport, never write to stdout — it corrupts the JSON-RPC
   stream. Use console.error (stderr) only.
5. Errors: catch failures and return
   { isError: true, content: [{ type: "text", text: "..." }] } instead of
   throwing, so a single bad call doesn't kill the client session.

### Response row schema

Dimensions: channelName, date, campaignName, campaignId, adGroupName,
adGroupId, adName, adId.

Metrics: orders, nc, rc, netRevenue, grossRevenue, cost, clicks, impressions,
cm1, cm2, clv_30, clv_60, clv_90, acm2, ncGrossRevenue, rcGrossRevenue,
ncNetRevenue, rcNetRevenue.

## Metric glossary

These are working definitions for the tool descriptions. For authoritative
formulas, see Klar's margin-metrics documentation in the help center.

- orders — attributed orders. Fractional values are expected: attribution
  models distribute partial credit for an order across the touchpoints that led
  to it.
- nc / rc — attributed New-Customer and Returning-Customer orders (also
  fractional).
- grossRevenue / netRevenue — attributed gross and net revenue.
- cost — ad spend for the row. ROAS is netRevenue / cost.
- clicks / impressions — ad engagement.
- cm1 / cm2 — contribution-margin tiers (CM1 after product/variable costs, CM2
  after marketing cost).
- clv_30 / clv_60 / clv_90 — projected customer lifetime value at 30 / 60 / 90
  days.
- acm2 — adjusted CM2.
- ncGrossRevenue / rcGrossRevenue / ncNetRevenue / rcNetRevenue — gross and net
  revenue split by new vs. returning customers.

## Tool surface

Core — build this first:

- get_attribution_report
  - Params: startDate (required, yyyy-mm-dd), endDate (required, yyyy-mm-dd),
    metric (optional enum), window (optional enum), date_breakdown (optional
    enum). Validate with zod and surface the exact accepted values in the schema.
  - Behaviour: auto-chunks any range longer than 31 days, respects the rate
    limit, returns the combined rows.

Optional extensions (add if useful to the user):

- summarize_by_channel — same params; aggregates rows by channelName (sum
  orders, cost, netRevenue, grossRevenue; derive ROAS = netRevenue / cost).
- compare_periods — two date ranges; returns per-channel deltas.

Bake the key interpretation rules — fractional orders, exclusive endDate, ROAS =
netRevenue / cost — into the tool descriptions so the model reads the results
correctly.

## Run & test

- npm run build
- npx @modelcontextprotocol/inspector node ./build/index.js

## README must include

A one-line description; the exact claude_desktop_config.json snippet; the tool
list with one-line descriptions; the required env var (KLAR_REFRESH_TOKEN); and
a short troubleshooting section covering token expiry, rate-limit pauses on wide
date ranges, and the no-stdout-logging rule.

Read CLAUDE.md and build the MCP server it describes. Use TypeScript with
the official MCP SDK and stdio transport. When you're done, run the build
and show me the claude_desktop_config.json entry I need.

{
  "mcpServers": {
    "klar-attribution": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/build/index.js"],
      "env": {
        "KLAR_REFRESH_TOKEN": "your-store-refresh-token"
      }
    }
  }
}