Tracking Plan MCP Server

Beginner-friendly Model Context Protocol (MCP) server built with TypeScript + Node.js to create, list, inspect, and validate tracking plans for Ecommerce and Lead-Generation / Service Businesses.

---

📌 Project Overview

The Tracking Plan MCP Server allows AI assistants (such as Cursor, Claude Desktop, and Antigravity) to manage analytics tracking specifications locally.

It supports two distinct business models out-of-the-box:

1. Ecommerce Businesses: Product views, cart activity, checkout steps, payment info, revenue, and purchase transactions.
2. Lead Generation & Service Businesses: Service views, form starts, form submissions, lead generation, phone clicks, email clicks, WhatsApp clicks, appointment bookings, and quote requests.

---

🏛️ Architecture & Data Flow

AI Assistant (Cursor / Claude Desktop / Antigravity)
      ↓
MCP Client
      ↓
MCP Server (stdio transport)
      ↓
MCP Tools (create_tracking_plan, get_tracking_plan, list_tracking_plans, validate_tracking_event)
      ↓
Tracking Plan Service (Business logic & Validation)
      ↓
JSON Storage (fs/promises)
      ↓
data/tracking-plans.json

---

💼 Supported Business Types

🛒 1. Ecommerce

Tracks:

• Product page views (view_item)
• Cart interactions (add_to_cart, remove_from_cart, view_cart)
• Checkout flow (begin_checkout, add_payment_info)
• Purchases & revenue (purchase)

Purchase Event Required Parameters: transaction_id, value, currency, items.

📞 2. Lead Generation / Service Businesses

Tracks:

• Service page views (view_service)
• Form interactions (form_start, form_submit)
• Lead submissions (generate_lead)
• Direct contacts (contact, phone_click, email_click, whatsapp_click)
• Appointment bookings (appointment_start, appointment_booked)
• Quote requests (quote_request)

Lead Submission Required Parameters: form_id, form_name.

---

🛠️ MCP Tools Reference

Tool Name	Parameters	Description
create_tracking_plan	id, name, description, business_type, platform, events	Creates a new tracking plan after validating business_type and checking duplicate IDs.
get_tracking_plan	plan_id	Retrieves complete tracking plan definition.
list_tracking_plans	business_type (optional)	Lists all tracking plans, optionally filtered by ecommerce or lead_generation.
validate_tracking_event	plan_id, event	Validates a tracking payload against plan schemas, returning errors and warnings.

---

📂 Project Structure

tracking-plan-mcp/
├── data/
│   └── tracking-plans.json            # JSON persistence storage
├── dist/                              # Compiled JavaScript output
├── src/
│   ├── index.ts                       # MCP Server entry point & tool registration
│   ├── models/
│   │   └── tracking.ts                # TypeScript types, Zod schemas, & ErrorCodes
│   ├── services/
│   │   └── trackingPlanService.ts     # Business logic & event validator
│   ├── storage/
│   │   └── jsonStorage.ts             # Safe JSON storage reader/writer
│   └── tools/
│       ├── createTrackingPlan.ts      # create_tracking_plan tool handler
│       ├── getTrackingPlan.ts         # get_tracking_plan tool handler
│       ├── listTrackingPlans.ts       # list_tracking_plans tool handler
│       └── validateTrackingEvent.ts   # validate_tracking_event tool handler
├── tests/
│   ├── createTrackingPlan.test.ts
│   ├── getTrackingPlan.test.ts
│   ├── listTrackingPlans.test.ts
│   └── validateTrackingEvent.test.ts
├── .gitignore
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md

---

🚀 Quick Start & Development

1. Installation

npm install

2. Run Vitest Unit Tests

npm test

3. Build Project

npm run build

4. Start Server

npm start

---

⚙️ MCP Client Configuration

Cursor IDE Configuration

Add to .cursor/mcp.json or Cursor MCP settings:

{
  "mcpServers": {
    "tracking-plan-mcp": {
      "command": "node",
      "args": ["C:/Users/FLS/.gemini/antigravity/scratch/tracking-plan-mcp/dist/index.js"]
    }
  }
}

Antigravity Configuration

Add to .gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "tracking-plan-mcp": {
      "command": "node",
      "args": ["C:/Users/FLS/.gemini/antigravity/scratch/tracking-plan-mcp/dist/index.js"]
    }
  }
}

---

💬 Example AI Prompts

• "Create an ecommerce GA4 tracking plan."
• "Create a lead generation tracking plan for an HVAC business."
• "Show me all ecommerce tracking plans."
• "Show me all lead generation tracking plans."
• "Validate this purchase event against the ecommerce tracking plan: { name: 'purchase', value: 99.99, currency: 'USD' }"
• "Validate this lead form submission against the lead generation tracking plan: { name: 'generate_lead', form_id: 'f1', form_name: 'Contact Form' }"

---

📄 License

Licensed under the MIT License.