# JP Agent Tracking Bridge MCP

The **JP Agent Tracking Bridge MCP** lets a compatible AI agent (Hermes, Claude, Codex)
work with **Google Analytics** and **Google Tag Manager** through
**JP Agent Tracking Bridge** — using *your* Google account, never a service account.

```
AI agent
   └─ jptb-google-tools (this MCP server)
        └─ HTTPS → JP Agent Tracking Bridge Google Tools gateway (jpro.studio)
                      ├─ validates your active Bridge session
                      ├─ uses YOUR Google OAuth connection (encrypted server-side)
                      └─ Google Analytics + Google Tag Manager
```

The agent never sees your Google tokens, your client secret, or any encryption key.

## Requirements

- A licensed, installed **JP Agent Tracking Bridge** site (WordPress or Joomla).
- A Google account with access to the site's GA4 property and GTM container.
- A compatible agent (Hermes, Claude Desktop, or Codex).

**No service account, no JSON credentials, no Google Cloud setup.**

## The 5-step customer story

1. **Install/register this MCP once** (below).
2. **Connect Google** in the site's JP Agent Tracking Bridge admin.
3. **Start Tagging** to open a temporary agent connection.
4. **Give the agent the connection** (connection id + session token).
5. **Talk to the agent normally** — it inspects and configures tracking, and asks before
   publishing anything to GTM.

## Start or install

This command downloads and starts the MCP server:

```bash
uvx --from 'git+https://github.com/joomlapro/jp-agent-tracking-bridge-mcp.git' jptb-google-tools
```

The process intentionally stays open while the server waits for its MCP client. If you
run it manually to verify the setup, press **Ctrl+C** after the startup banner appears.
Your MCP client normally starts and stops this command for you.

For a standalone installation that returns to the prompt, use:

```bash
uv tool install 'git+https://github.com/joomlapro/jp-agent-tracking-bridge-mcp.git'
```

Then register it in your agent. See `docs/HERMES.md`, `docs/CLAUDE.md`, or `docs/CODEX.md`
for the exact per-agent setup.

## Configuration

The server needs two values for a given job (also passable per tool call):

```bash
export JPTB_CONNECTION_ID="<connection id from 'Connect Google'>"
export JPTB_SESSION_TOKEN="<session token from 'Start Tagging'>"
```

Both are shown/generated in the site's JP Agent Tracking Bridge admin and via the Bridge
API. The `session_token` is revoked by **Stop Tagging**, which immediately blocks all Google
operations through the MCP.

## What the agent can do

- **GTM read** — list accounts/containers/workspaces/tags/triggers/variables/versions.
- **GTM write** — create/update JPTB tags, triggers, variables; create a container version.
- **GTM publish** — publish a prepared version (approval-gated; the agent asks first).
- **GA4 read-only** — list accounts/properties, property details, realtime and standard reports.

## Verification — GA4 realtime latency

GA4 **realtime is minutes-slow, not seconds-slow**. An empty realtime report
is *not* proof an event was dropped. Before declaring an event "dropped":

1. Wait at least **5 minutes** after the last browser event you expect to see.
2. Or calibrate with a unique direct `/g/collect` canary hit (this measures the
   current latency instead of guessing).

See [docs/GA4-LATENCY.md](docs/GA4-LATENCY.md) for the full checklist and the
"never do this" rules (no Custom HTML `gtag('event', same-name)` recursion, no
dual GA4 loaders, no blaming consent before proving routing).

## Security model

- **Session-bound** — Google access is tied to an active Bridge session; **Stop Tagging** revokes it.
- **No secrets to the model** — tokens, client secret, and the encryption key stay server-side.
- **No service account** — the customer's own Google OAuth authorization is the only credential.

## License

[MIT](LICENSE).