etracker-mcp CLAUDE.md

etracker MCP Server

Project structure

etracker-mcp/          # repo root — Node.js/TypeScript MCP server
  src/
    index.ts           # Express app, session store, /mcp + /health endpoints
    auth.ts            # authMiddleware — X-Api-Key + X-ET-Token headers
    ratelimit.ts       # Three-layer bucket rate limiter (burst / global / per-partner)
    cache.ts           # In-memory TTL cache (5 min), cache keys scoped per token
    analytics-api.ts   # etracker Reporting API client (BASE_URL: ws.etracker.com/api/v7)
    tools.ts           # MCP tool registrations, Zod schemas, column resolution
  helm/                # Helm chart for Kubernetes deployment
    values.yaml
  Dockerfile           # Multi-stage build, node:24-alpine

Commands

# Install
npm install

# Dev (tsx, hot-reload via node --import tsx/esm)
npm run dev

# Build
npm run build        # tsc → dist/

# Production
npm start            # node --env-file=.env dist/index.js

# Docker
docker build -t etracker-mcp .
docker run -p 3000:3000 -e PARTNER_API_KEYS='{"key":"partner-a"}' etracker-mcp

# Helm
helm install etracker-mcp ./helm -f my-values.yaml

Environment variables

Variable	Required	Description
PARTNER_API_KEYS	yes	JSON object: {"<key>":"<partner-id>"} — generate keys with openssl rand -hex 32
PORT	no	HTTP port (default: 3000)
ETRACKER_REPORT_PAGEVIEWS	no	Override default pageviews report ID (default: EATime)
ETRACKER_REPORT_CONVERSIONS	no	Override default conversions report ID (default: EAConversions)
ETRACKER_REPORT_AD	no	Override default ad report ID (default: EAMarketing)

Copy .env.example to .env for local development. The etracker token is not stored in env — partners pass it per request via X-ET-Token.

Authentication model

Every request to /mcp requires two headers:

• X-Api-Key — MCP server access key (validated against PARTNER_API_KEYS, resolves to a partnerId used for rate limiting)
• X-ET-Token — etracker account token (forwarded directly to the etracker API; never stored server-side)