datafast-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# Datafast MCP Server
+
+An MCP (Model Context Protocol) server for the [Datafast](https://datafa.st) analytics API. This server allows AI assistants like Claude to query your website analytics data.
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+Add the server to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "datafast": {
+      "command": "node",
+      "args": ["/path/to/datafast-mcp-server/build/index.js"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Analytics Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_overview` | Get aggregate analytics metrics (visitors, sessions, bounce rate, revenue, conversion rate) |
+| `get_realtime` | Get real-time visitor count (last 5 minutes) |
+| `get_pages` | Get analytics broken down by page path |
+| `get_referrers` | Get analytics by referrer source |
+| `get_countries` | Get analytics by country |
+| `get_regions` | Get analytics by region/state |
+| `get_cities` | Get analytics by city |
+| `get_devices` | Get analytics by device type (desktop, mobile, tablet) |
+| `get_browsers` | Get analytics by browser |
+| `get_operating_systems` | Get analytics by operating system |
+| `get_goals` | Get analytics by custom goals |
+| `get_campaigns` | Get analytics by UTM campaigns |
+
+### Common Parameters
+
+All tools require an `apiKey` parameter. Get your API key from **Website Settings > API** in your Datafast dashboard.
+
+#### Date Range Parameters
+- `startAt`: Start date in ISO 8601 format (e.g., `2024-01-01`)
+- `endAt`: End date in ISO 8601 format (e.g., `2024-01-31`)
+- `timezone`: Timezone for aggregation (e.g., `America/New_York`)
+
+#### Pagination Parameters
+- `limit`: Maximum results (1-1000, default: 100)
+- `offset`: Number of results to skip
+
+#### Filter Parameters
+- `country`: Filter by country name(s)
+- `region`: Filter by region(s)
+- `city`: Filter by city/cities
+- `device`: Filter by device type
+- `browser`: Filter by browser name
+- `os`: Filter by operating system
+- `referrer`: Filter by referrer URL
+- `utm_source`, `utm_medium`, `utm_campaign`: Filter by UTM parameters
+- `page`: Filter by page path
+- `hostname`: Filter by hostname
+
+## Example Usage
+
+Once configured, you can ask Claude:
+
+- "Show me my website's overview analytics for last month"
+- "How many visitors do I have right now?"
+- "What are my top pages by visitors?"
+- "Which countries are my visitors from?"
+- "Show me traffic by device type"
+- "What referrers are driving the most revenue?"
+
+## API Documentation
+
+For more details, see the [Datafast API Documentation](https://datafa.st/docs/api-introduction).
+
+## License
+
+MIT

package/build/index.js

@@ -0,0 +1,457 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const DATAFAST_API_BASE = "https://datafa.st/api/v1";
+// Create server instance
+const server = new McpServer({
+    name: "datafast",
+    version: "1.0.0",
+});
+// Helper function for making Datafast API requests
+async function makeDatafastRequest(endpoint, apiKey, params) {
+    const url = new URL(`${DATAFAST_API_BASE}${endpoint}`);
+    if (params) {
+        Object.entries(params).forEach(([key, value]) => {
+            if (value !== undefined) {
+                url.searchParams.append(key, String(value));
+            }
+        });
+    }
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            Accept: "application/json",
+        },
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new Error(`Datafast API error: ${response.status} - ${error.error?.message || response.statusText}`);
+    }
+    return response.json();
+}
+// Common filter parameters schema
+const filterParams = {
+    country: z
+        .string()
+        .optional()
+        .describe("Filter by country name(s), comma-separated"),
+    region: z.string().optional().describe("Filter by region(s), comma-separated"),
+    city: z.string().optional().describe("Filter by city/cities, comma-separated"),
+    device: z
+        .string()
+        .optional()
+        .describe("Filter by device type (desktop, mobile, tablet)"),
+    browser: z.string().optional().describe("Filter by browser name"),
+    os: z.string().optional().describe("Filter by operating system"),
+    referrer: z.string().optional().describe("Filter by referrer URL"),
+    utm_source: z.string().optional().describe("Filter by UTM source"),
+    utm_medium: z.string().optional().describe("Filter by UTM medium"),
+    utm_campaign: z.string().optional().describe("Filter by UTM campaign"),
+    page: z.string().optional().describe("Filter by page path"),
+    hostname: z.string().optional().describe("Filter by hostname"),
+};
+// Common date/pagination parameters
+const dateParams = {
+    startAt: z
+        .string()
+        .optional()
+        .describe("Start date in ISO 8601 format (e.g., 2024-01-01)"),
+    endAt: z
+        .string()
+        .optional()
+        .describe("End date in ISO 8601 format (e.g., 2024-01-31)"),
+    timezone: z
+        .string()
+        .optional()
+        .describe("Timezone for aggregation (e.g., America/New_York)"),
+};
+const paginationParams = {
+    limit: z
+        .number()
+        .min(1)
+        .max(1000)
+        .optional()
+        .describe("Maximum results to return (1-1000, default: 100)"),
+    offset: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Number of results to skip for pagination"),
+};
+// Register tools
+// Get Overview
+server.registerTool("get_overview", {
+    description: "Get aggregate analytics metrics for your website including visitors, sessions, bounce rate, revenue, and conversion rate",
+    inputSchema: {
+        apiKey: z.string().describe("Your Datafast API key"),
+        fields: z
+            .string()
+            .optional()
+            .describe("Comma-separated fields to return: visitors, sessions, bounce_rate, avg_session_duration, currency, revenue, revenue_per_visitor, conversion_rate"),
+        ...dateParams,
+    },
+}, async ({ apiKey, fields, startAt, endAt, timezone }) => {
+    const data = await makeDatafastRequest("/analytics/overview", apiKey, {
+        fields,
+        startAt,
+        endAt,
+        timezone,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// Get Realtime
+server.registerTool("get_realtime", {
+    description: "Get the count of active visitors on your website in real-time (visitors with activity in the last 5 minutes)",
+    inputSchema: {
+        apiKey: z.string().describe("Your Datafast API key"),
+    },
+}, async ({ apiKey }) => {
+    const data = await makeDatafastRequest("/analytics/realtime", apiKey);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// Get Pages
+server.registerTool("get_pages", {
+    description: "Get analytics data broken down by page with hostname and path information",
+    inputSchema: {
+        apiKey: z.string().describe("Your Datafast API key"),
+        fields: z
+            .string()
+            .optional()
+            .describe("Comma-separated fields to return: hostname, path, visitors, revenue"),
+        ...dateParams,
+        ...paginationParams,
+        ...filterParams,
+    },
+}, async ({ apiKey, fields, startAt, endAt, timezone, limit, offset, ...filters }) => {
+    const data = await makeDatafastRequest("/analytics/pages", apiKey, {
+        fields,
+        startAt,
+        endAt,
+        timezone,
+        limit,
+        offset,
+        ...filters,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// Get Referrers
+server.registerTool("get_referrers", {
+    description: "Get analytics data segmented by referrer source",
+    inputSchema: {
+        apiKey: z.string().describe("Your Datafast API key"),
+        fields: z
+            .string()
+            .optional()
+            .describe("Comma-separated fields to return: referrer, visitors, revenue"),
+        ...dateParams,
+        ...paginationParams,
+        ...filterParams,
+    },
+}, async ({ apiKey, fields, startAt, endAt, timezone, limit, offset, ...filters }) => {
+    const data = await makeDatafastRequest("/analytics/referrers", apiKey, {
+        fields,
+        startAt,
+        endAt,
+        timezone,
+        limit,
+        offset,
+        ...filters,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// Get Countries
+server.registerTool("get_countries", {
+    description: "Get analytics data broken down by country",
+    inputSchema: {
+        apiKey: z.string().describe("Your Datafast API key"),
+        fields: z
+            .string()
+            .optional()
+            .describe("Comma-separated fields to return: country, image, visitors, revenue"),
+        ...dateParams,
+        ...paginationParams,
+        ...filterParams,
+    },
+}, async ({ apiKey, fields, startAt, endAt, timezone, limit, offset, ...filters }) => {
+    const data = await makeDatafastRequest("/analytics/countries", apiKey, {
+        fields,
+        startAt,
+        endAt,
+        timezone,
+        limit,
+        offset,
+        ...filters,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// Get Devices
+server.registerTool("get_devices", {
+    description: "Get analytics data segmented by device type (desktop, mobile, tablet)",
+    inputSchema: {
+        apiKey: z.string().describe("Your Datafast API key"),
+        fields: z
+            .string()
+            .optional()
+            .describe("Comma-separated fields to return: device, visitors, revenue"),
+        ...dateParams,
+        ...paginationParams,
+        ...filterParams,
+    },
+}, async ({ apiKey, fields, startAt, endAt, timezone, limit, offset, ...filters }) => {
+    const data = await makeDatafastRequest("/analytics/devices", apiKey, {
+        fields,
+        startAt,
+        endAt,
+        timezone,
+        limit,
+        offset,
+        ...filters,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// Get Browsers
+server.registerTool("get_browsers", {
+    description: "Get analytics data broken down by browser",
+    inputSchema: {
+        apiKey: z.string().describe("Your Datafast API key"),
+        fields: z
+            .string()
+            .optional()
+            .describe("Comma-separated fields to return: browser, visitors, revenue"),
+        ...dateParams,
+        ...paginationParams,
+        ...filterParams,
+    },
+}, async ({ apiKey, fields, startAt, endAt, timezone, limit, offset, ...filters }) => {
+    const data = await makeDatafastRequest("/analytics/browsers", apiKey, {
+        fields,
+        startAt,
+        endAt,
+        timezone,
+        limit,
+        offset,
+        ...filters,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// Get Operating Systems
+server.registerTool("get_operating_systems", {
+    description: "Get analytics data broken down by operating system",
+    inputSchema: {
+        apiKey: z.string().describe("Your Datafast API key"),
+        fields: z
+            .string()
+            .optional()
+            .describe("Comma-separated fields to return: os, visitors, revenue"),
+        ...dateParams,
+        ...paginationParams,
+        ...filterParams,
+    },
+}, async ({ apiKey, fields, startAt, endAt, timezone, limit, offset, ...filters }) => {
+    const data = await makeDatafastRequest("/analytics/os", apiKey, {
+        fields,
+        startAt,
+        endAt,
+        timezone,
+        limit,
+        offset,
+        ...filters,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// Get Goals
+server.registerTool("get_goals", {
+    description: "Get analytics data broken down by custom goals",
+    inputSchema: {
+        apiKey: z.string().describe("Your Datafast API key"),
+        fields: z
+            .string()
+            .optional()
+            .describe("Comma-separated fields to return: name, completions, visitors"),
+        ...dateParams,
+        ...paginationParams,
+        ...filterParams,
+    },
+}, async ({ apiKey, fields, startAt, endAt, timezone, limit, offset, ...filters }) => {
+    const data = await makeDatafastRequest("/analytics/goals", apiKey, {
+        fields,
+        startAt,
+        endAt,
+        timezone,
+        limit,
+        offset,
+        ...filters,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// Get Regions
+server.registerTool("get_regions", {
+    description: "Get analytics data broken down by region/state",
+    inputSchema: {
+        apiKey: z.string().describe("Your Datafast API key"),
+        fields: z
+            .string()
+            .optional()
+            .describe("Comma-separated fields to return: region, visitors, revenue"),
+        ...dateParams,
+        ...paginationParams,
+        ...filterParams,
+    },
+}, async ({ apiKey, fields, startAt, endAt, timezone, limit, offset, ...filters }) => {
+    const data = await makeDatafastRequest("/analytics/regions", apiKey, {
+        fields,
+        startAt,
+        endAt,
+        timezone,
+        limit,
+        offset,
+        ...filters,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// Get Cities
+server.registerTool("get_cities", {
+    description: "Get analytics data broken down by city",
+    inputSchema: {
+        apiKey: z.string().describe("Your Datafast API key"),
+        fields: z
+            .string()
+            .optional()
+            .describe("Comma-separated fields to return: city, visitors, revenue"),
+        ...dateParams,
+        ...paginationParams,
+        ...filterParams,
+    },
+}, async ({ apiKey, fields, startAt, endAt, timezone, limit, offset, ...filters }) => {
+    const data = await makeDatafastRequest("/analytics/cities", apiKey, {
+        fields,
+        startAt,
+        endAt,
+        timezone,
+        limit,
+        offset,
+        ...filters,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// Get Campaigns (UTM)
+server.registerTool("get_campaigns", {
+    description: "Get analytics data broken down by UTM campaigns",
+    inputSchema: {
+        apiKey: z.string().describe("Your Datafast API key"),
+        fields: z
+            .string()
+            .optional()
+            .describe("Comma-separated fields to return: campaign, source, medium, visitors, revenue"),
+        ...dateParams,
+        ...paginationParams,
+        ...filterParams,
+    },
+}, async ({ apiKey, fields, startAt, endAt, timezone, limit, offset, ...filters }) => {
+    const data = await makeDatafastRequest("/analytics/campaigns", apiKey, {
+        fields,
+        startAt,
+        endAt,
+        timezone,
+        limit,
+        offset,
+        ...filters,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// Run the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Datafast MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "datafast-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Datafast analytics API",
+  "type": "module",
+  "bin": {
+    "datafast-mcp-server": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "dev": "tsc --watch",
+    "start": "node build/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "build"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FujiwaraChoki/datafast-mcp-server.git"
+  },
+  "homepage": "https://github.com/FujiwaraChoki/datafast-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/FujiwaraChoki/datafast-mcp-server/issues"
+  },
+  "author": "FujiwaraChoki",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "datafast",
+    "analytics",
+    "claude",
+    "ai"
+  ],
+  "license": "MIT"
+}