@wwhat/mcp-stdio-client 1.0.0

package/README.md

@@ -0,0 +1,99 @@
+# @wwhat/mcp-stdio-client
+
+Stdio wrapper for the wwhat MCP server - enables Cursor and Claude Desktop integration.
+
+## Installation
+
+```bash
+cd packages/mcp-stdio-client
+bun install
+bun run build
+```
+
+## Usage
+
+### Environment Variables
+
+- `WWHAT_API_KEY` (required) - Your wwhat API key
+- `WWHAT_MCP_URL` (optional) - MCP server URL (defaults to `https://app.wwhat.ai/mcp`)
+
+### Cursor Configuration
+
+Add to your Cursor MCP settings (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "wwhat": {
+      "command": "node",
+      "args": ["/path/to/wwhat/packages/mcp-stdio-client/dist/index.js"],
+      "env": {
+        "WWHAT_API_KEY": "your-api-key-here",
+        "WWHAT_MCP_URL": "https://app.wwhat.ai/mcp"
+      }
+    }
+  }
+}
+```
+
+For local development:
+
+```json
+{
+  "mcpServers": {
+    "wwhat-local": {
+      "command": "node",
+      "args": ["/path/to/wwhat/packages/mcp-stdio-client/dist/index.js"],
+      "env": {
+        "WWHAT_API_KEY": "your-api-key-here",
+        "WWHAT_MCP_URL": "http://localhost:8787/mcp"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop Configuration
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):
+
+```json
+{
+  "mcpServers": {
+    "wwhat": {
+      "command": "node",
+      "args": ["/path/to/wwhat/packages/mcp-stdio-client/dist/index.js"],
+      "env": {
+        "WWHAT_API_KEY": "your-api-key-here",
+        "WWHAT_MCP_URL": "https://app.wwhat.ai/mcp"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_weekly_insights` | Get weekly analytics insights including traffic changes and recommendations |
+| `query_analytics_metrics` | Query metrics with trend comparisons (W1, L4WAVG, LY4WAVG) |
+| `list_sources` | List available GA4 properties |
+| `trigger_analytics_workflow` | Trigger analytics processing for a week |
+| `get_workflow_status` | Check workflow status |
+| `get_ga4_data` | Get GA4 data for specific dimensions |
+
+## Testing
+
+Run directly:
+
+```bash
+WWHAT_API_KEY=your-key WWHAT_MCP_URL=http://localhost:8787/mcp node dist/index.js
+```
+
+## Development
+
+```bash
+bun run dev  # Watch mode
+bun run build  # Build for production
+```

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * wwhat MCP Stdio Client
+ *
+ * Bridges Cursor/Claude Desktop (stdio) to the wwhat HTTP MCP server.
+ *
+ * Usage:
+ *   WWHAT_API_KEY=your-key WWHAT_MCP_URL=https://app.wwhat.ai/mcp npx @wwhat/mcp-stdio-client
+ *
+ * Or in Cursor/Claude Desktop config:
+ *   {
+ *     "mcpServers": {
+ *       "wwhat": {
+ *         "command": "npx",
+ *         "args": ["@wwhat/mcp-stdio-client"],
+ *         "env": {
+ *           "WWHAT_API_KEY": "your-api-key",
+ *           "WWHAT_MCP_URL": "https://app.wwhat.ai/mcp"
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * wwhat MCP Stdio Client
+ *
+ * Bridges Cursor/Claude Desktop (stdio) to the wwhat HTTP MCP server.
+ *
+ * Usage:
+ *   WWHAT_API_KEY=your-key WWHAT_MCP_URL=https://app.wwhat.ai/mcp npx @wwhat/mcp-stdio-client
+ *
+ * Or in Cursor/Claude Desktop config:
+ *   {
+ *     "mcpServers": {
+ *       "wwhat": {
+ *         "command": "npx",
+ *         "args": ["@wwhat/mcp-stdio-client"],
+ *         "env": {
+ *           "WWHAT_API_KEY": "your-api-key",
+ *           "WWHAT_MCP_URL": "https://app.wwhat.ai/mcp"
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+const MCP_URL = process.env.WWHAT_MCP_URL || 'https://app.wwhat.ai/mcp';
+const API_KEY = process.env.WWHAT_API_KEY;
+if (!API_KEY) {
+    console.error('Error: WWHAT_API_KEY environment variable is required');
+    process.exit(1);
+}
+/**
+ * Make an MCP JSON-RPC request to the HTTP server
+ */
+async function mcpRequest(method, params) {
+    const response = await fetch(MCP_URL, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'X-API-Key': API_KEY,
+        },
+        body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: crypto.randomUUID(),
+            method,
+            params,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+    }
+    const result = await response.json();
+    if (result.error) {
+        throw new Error(result.error.message);
+    }
+    return result.result;
+}
+/**
+ * Create and start the stdio MCP server
+ */
+async function main() {
+    const server = new McpServer({
+        name: 'wwhat-analytics',
+        version: '1.0.0',
+    });
+    // Tool 1: get_weekly_insights
+    server.tool('get_weekly_insights', 'Get weekly analytics insights including traffic changes, landing page drops, and actionable recommendations for a specific week.', {
+        source_id: z.string().describe('The analytics source/property ID'),
+        week_start_date: z.string().describe('Start date of the week (ISO format, e.g., 2025-01-13)'),
+        include_lp_explainers: z.boolean().default(true).describe('Include landing page drop explainers'),
+        significance_filter: z
+            .enum(['all', 'critical', 'significant', 'moderate', 'minor'])
+            .default('all')
+            .describe('Filter insights by significance level'),
+    }, async (params) => {
+        const result = await mcpRequest('tools/call', {
+            name: 'get_weekly_insights',
+            arguments: params,
+        });
+        return {
+            content: result.content.map((c) => ({ type: 'text', text: c.text })),
+        };
+    });
+    // Tool 2: query_analytics_metrics
+    server.tool('query_analytics_metrics', 'Query processed analytics metrics with trend comparisons (W1, L4WAVG, LY4WAVG). Supports filtering, sorting, and aggregation.', {
+        source_id: z.string().describe('The analytics source/property ID'),
+        period_start: z.string().describe('Period start date (ISO format)'),
+        period_end: z.string().optional().describe('Period end date (defaults to 7 days after start)'),
+        metric: z
+            .enum(['sessions', 'totalUsers', 'newUsers', 'bounceRate', 'conversions', 'revenue'])
+            .default('sessions')
+            .describe('Primary metric to analyze'),
+        comparison_type: z
+            .enum(['W1', 'L4WAVG', 'LY4WAVG', 'all'])
+            .default('all')
+            .describe('Type of comparison to include'),
+        filter: z
+            .object({
+            dimension_values: z.record(z.string()).optional().describe('Filter by dimension values'),
+            min_value: z.number().optional().describe('Minimum metric value to include'),
+            min_change_percent: z.number().optional().describe('Minimum absolute change percentage'),
+            only_drops: z.boolean().optional().describe('Only include negative changes'),
+            only_gains: z.boolean().optional().describe('Only include positive changes'),
+        })
+            .optional()
+            .describe('Filtering options'),
+        sort_by: z
+            .enum(['value', 'change_w1', 'change_l4wavg', 'change_ly4wavg', 'z_score'])
+            .default('value')
+            .describe('Sort results by this field'),
+        sort_order: z.enum(['asc', 'desc']).default('desc'),
+        limit: z.number().min(1).max(100).default(20).describe('Maximum number of results'),
+    }, async (params) => {
+        const result = await mcpRequest('tools/call', {
+            name: 'query_analytics_metrics',
+            arguments: params,
+        });
+        return {
+            content: result.content.map((c) => ({ type: 'text', text: c.text })),
+        };
+    });
+    // Tool 3: list_sources
+    server.tool('list_sources', 'List all analytics sources (GA4 properties) available to the authenticated user.', {
+        include_details: z
+            .boolean()
+            .default(false)
+            .describe('Include additional details like last processed date and data availability'),
+    }, async (params) => {
+        const result = await mcpRequest('tools/call', {
+            name: 'list_sources',
+            arguments: params,
+        });
+        return {
+            content: result.content.map((c) => ({ type: 'text', text: c.text })),
+        };
+    });
+    // Tool 4: trigger_analytics_workflow
+    server.tool('trigger_analytics_workflow', 'Trigger the analytics agent workflow to process a specific week. Returns immediately with a workflow ID that can be polled for status.', {
+        source_id: z.string().describe('The analytics source/property ID'),
+        week_start_date: z.string().describe('Start date of the week to process (ISO format)'),
+        force_refresh: z.boolean().default(false).describe('Force re-processing even if data already exists'),
+        wait_for_completion: z.boolean().default(false).describe('If true, poll until workflow completes'),
+        timeout_seconds: z.number().max(600).default(300).describe('Maximum time to wait if wait_for_completion is true'),
+    }, async (params) => {
+        const result = await mcpRequest('tools/call', {
+            name: 'trigger_analytics_workflow',
+            arguments: params,
+        });
+        return {
+            content: result.content.map((c) => ({ type: 'text', text: c.text })),
+        };
+    });
+    // Tool 5: get_workflow_status
+    server.tool('get_workflow_status', 'Check the status of a running analytics workflow triggered by trigger_analytics_workflow.', {
+        invocation_id: z.string().describe('The invocation ID returned by trigger_analytics_workflow'),
+        source_id: z.string().describe('The analytics source/property ID (for validation)'),
+    }, async (params) => {
+        const result = await mcpRequest('tools/call', {
+            name: 'get_workflow_status',
+            arguments: params,
+        });
+        return {
+            content: result.content.map((c) => ({ type: 'text', text: c.text })),
+        };
+    });
+    // Tool 6: get_ga4_data
+    server.tool('get_ga4_data', 'Get Google Analytics 4 data for specific pages, segments, or dimensions. Fetches from database if available, otherwise retrieves from GA4 API.', {
+        source_id: z.string().describe('The analytics source/property ID'),
+        date_range: z
+            .object({
+            start_date: z.string().describe('Start date (ISO format)'),
+            end_date: z.string().describe('End date (ISO format)'),
+        })
+            .describe('Date range to fetch data for'),
+        dimensions: z
+            .array(z.enum([
+            'landingPage',
+            'deviceCategory',
+            'country',
+            'sessionDefaultChannelGrouping',
+            'sessionSource',
+            'newVsReturning',
+            'browser',
+            'city',
+            'region',
+        ]))
+            .optional()
+            .describe('Dimensions to break down the data by'),
+        filters: z.record(z.string()).optional().describe('Key-value pairs to filter data'),
+        metrics: z
+            .array(z.enum([
+            'sessions',
+            'totalUsers',
+            'newUsers',
+            'bounceRate',
+            'avgSessionDuration',
+            'screenPageViews',
+            'engagedSessions',
+            'conversions',
+            'totalRevenue',
+        ]))
+            .default(['sessions', 'totalUsers'])
+            .describe('Metrics to retrieve'),
+        fetch_if_missing: z.boolean().default(true).describe('If true, fetch from GA4 API when data not in database'),
+    }, async (params) => {
+        const result = await mcpRequest('tools/call', {
+            name: 'get_ga4_data',
+            arguments: params,
+        });
+        return {
+            content: result.content.map((c) => ({ type: 'text', text: c.text })),
+        };
+    });
+    // Connect to stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr (stdout is used for MCP protocol)
+    console.error(`wwhat MCP client connected to ${MCP_URL}`);
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@wwhat/mcp-stdio-client",
+  "version": "1.0.0",
+  "description": "Stdio wrapper for wwhat MCP server - enables Cursor/Claude Desktop integration",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "wwhat-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wwhat-ai/wwhat"
+  },
+  "author": "wwhat.ai",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "cursor",
+    "claude-desktop",
+    "analytics",
+    "ga4"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ]
+}