# Web Analytics & Tracking MCP Server

> A production-ready Model Context Protocol (MCP) server for Google Tag Manager (GTM), Google Analytics 4 (GA4) Measurement Protocol, DataLayer schema validation, Meta CAPI auditing, and tracking code snippet generation.

![Build Status](https://img.shields.io/badge/MCP-v1.5.0-blue.svg)
![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)
![License](https://img.shields.io/badge/License-MIT-green)

---

## 📌 Features

- 🎯 **DataLayer Schema Validator**: Automatically validates GTM `dataLayer.push` objects against GA4 e-commerce schemas (`purchase`, `add_to_cart`, `lead`, etc.).
- 🚀 **GA4 Measurement Protocol Event Transmitter**: Transmits server-side events directly to Google Analytics 4 via Measurement Protocol API.
- 🛠️ **Tracking Code Snippet Generator**: Generates production-ready code snippets for GTM `window.dataLayer.push`, GA4 `gtag.js`, and React tracking hooks.
- 📊 **Tracking Quality & EMQ Auditor**: Audits tracking event payloads for GA4 and Meta Conversions API (CAPI), scoring readiness from 0-100 and providing recommendations.
- 📑 **Built-in Specification Resource**: Exposes static GA4 e-commerce standard schemas as an MCP resource (`ga4://spec/ecommerce`).

---

## 🛠️ Quick Start

### 1. Prerequisites
- **Node.js**: v18.0.0 or higher
- **npm**: v9.0.0 or higher

### 2. Installation & Build
```bash
# Clone repository
git clone https://github.com/webanalyticsprobd-maker/tracking-mcp-server.git
cd tracking-mcp-server

# Install dependencies
npm install

# Compile TypeScript
npm run build
```

### 3. Environment Setup (Optional)
Copy `.env.example` to `.env` and fill in your GA4 credentials if you plan to send live server-side Measurement Protocol events:
```env
GA4_MEASUREMENT_ID=G-XXXXXXXXXX
GA4_API_SECRET=your_ga4_api_secret_here
```

---

## ⚙️ How to Connect to MCP Clients

### Cursor IDE Configuration
Add the following snippet to your Cursor **MCP Tools** settings or `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "tracking-analytics-server": {
      "command": "node",
      "args": ["C:/path/to/tracking-mcp-server/dist/index.js"],
      "env": {
        "GA4_MEASUREMENT_ID": "G-XXXXXXXXXX",
        "GA4_API_SECRET": "your_api_secret"
      }
    }
  }
}
```

### Claude Desktop Configuration
Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tracking-analytics-server": {
      "command": "node",
      "args": ["C:/path/to/tracking-mcp-server/dist/index.js"]
    }
  }
}
```

---

## 📄 License
Licensed under the [MIT License](LICENSE).