# tracking-stack-mcp

MCP server for an agency's tracking-stack setup: **WhatConverts**, **GA4 Admin**, **GTM**.
Same write-safety contract as `google-ads-mcp`: every mutating tool is a dry-run
by default and executes only with `confirmed: true`; writes are rate-limited and logged
to `~/.local/state/tracking-stack-mcp/actions.jsonl`.

**Create-only by design.** No delete, unlink, user-management, or GTM publish tools
exist here. Removing things and publishing containers stays portal work.

## Tools

| Tool | Type | Description |
|---|---|---|
| `wc_list_accounts` | Read | All WhatConverts accounts + profiles |
| `wc_create_account` | ⚠️ Mutating | New WC account (dupe-name refusal) |
| `wc_create_profile` | ⚠️ Mutating | New profile; refuses if the name exists anywhere in the agency |
| `ga4_list_properties` | Read | GA4 accounts, properties, streams + measurement IDs |
| `ga4_create_property` | ⚠️ Mutating | New GA4 property + web stream; returns `G-` measurement ID |
| `gtm_list_containers` | Read | GTM accounts + containers |
| `gtm_create_container` | ⚠️ Mutating | New web container; returns `GTM-` id; never publishes |

## Credentials — `~/.config/tracking-stack-mcp/.env` (chmod 600)

```
WC_API_TOKEN=...        # canonical copy lives in your secret manager
WC_API_SECRET=...       
GOOGLE_CLIENT_ID=...    # OAuth client (can reuse the google-ads-mcp client)
GOOGLE_CLIENT_SECRET=...
GOOGLE_REFRESH_TOKEN=...  # must carry analytics.edit + tagmanager.edit.containers + tagmanager.readonly
GA4_DEFAULT_TIME_ZONE=America/Los_Angeles   # optional, default UTC
GA4_INDUSTRY_CATEGORY=HOME_AND_GARDEN       # optional, omitted if unset
```

Mint the Google refresh token once with the OAuth playground or the google-ads-mcp
auth-setup pattern, adding the three scopes above. Never commit `.env`; never put these
values in the vault.

## Safety contract

- **Create-only.** No delete, unlink, user-management, or publish tools exist.
- **Dry run by default.** Only a boolean `confirmed: true` executes; `"true"` does not.
- **Validated inputs.** Names are non-empty strings; ids are integers or `accounts/<id>`;
  stream URLs must be `https://`.
- **Duplicate-name refusal** across the whole agency before any create.
- **Rate cap** of 10 writes per rolling hour per process, checked after the confirmed branch.
- **Append-only action log** of every executed write, refusal, and failure; never previews.
- **No tenant values in code.** Time zone and industry category come from env.

## Claude Desktop wiring

```json
"tracking-stack": {
  "command": "node",
  "args": ["/Users/<you>/Documents/Claude/tracking-stack-mcp/dist/index.js"]
}
```

## Build

```
npm install && npm run build
```