@mitr-analytics/mcp 1.1.0 → 1.2.0

package/README.md

@@ -14,37 +14,83 @@ Mitr is cookie-free analytics, so there is no consent banner to wire up and noth
 
 ## Set up (about two minutes)
 
-You need [Node.js](https://nodejs.org) 18 or newer, and a Mitr account.
+You need a Mitr account. Nothing to install if you use the hosted endpoint.
 
-**1. Create an API key.** In the dashboard open **Settings → API keys & AI assistants → Create key**, give it a name (for example "Claude Desktop") and copy it. It is shown **once**.
+**1. Create an API key.** In the dashboard open **Settings → API keys & AI assistants → Create key**, give it a name (for example "Claude Code") and copy it. It is shown **once**.
 
-Keys are **read-only** unless you tick "Can register apps" when creating them (needed only for `add_app`), and they expire after 365 days by default (30, 90, 365 days or never). A key stops working if you leave or are removed from the workspace it was created in.
+Keys are **read-only** unless you tick permissions when creating them: "Can register apps", "Can manage funnels", "Can manage QR campaigns", "Can manage webhooks", and "Can delete" (which also needs one of the manage permissions). They expire after 365 days by default (30, 90, 365 days or never). A key stops working if you leave or are removed from the workspace it was created in.
 
-**2. Add Mitr to your assistant.**
+**2. Connect your assistant.**
 
-*Claude Desktop*: open `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`) and add:
+### Hosted (no install)
+
+Point any client that supports remote MCP servers at `https://mcp.mitranalytics.dev/mcp` and send the key in the `Authorization` header. Never put the key in the URL; the endpoint refuses it.
+
+*Claude Code*:
+
+```bash
+claude mcp add --transport http mitr https://mcp.mitranalytics.dev/mcp --header "Authorization: Bearer mitr_live_..."
+```
+
+*Cursor* (`~/.cursor/mcp.json`):
 
 ```json
 {
   "mcpServers": {
     "mitr": {
-      "command": "npx",
-      "args": ["-y", "@mitr-analytics/mcp"],
-      "env": { "MITR_API_KEY": "mitr_live_..." }
+      "url": "https://mcp.mitranalytics.dev/mcp",
+      "headers": { "Authorization": "Bearer mitr_live_..." }
     }
   }
 }
 ```
 
-*Gemini CLI*: add the same `mcpServers` block to `~/.gemini/settings.json`.
+*VS Code* (`.vscode/mcp.json`):
 
-*Claude Code*:
+```json
+{
+  "servers": {
+    "mitr": {
+      "type": "http",
+      "url": "https://mcp.mitranalytics.dev/mcp",
+      "headers": { "Authorization": "Bearer mitr_live_..." }
+    }
+  }
+}
+```
 
-```bash
-claude mcp add mitr --env MITR_API_KEY=mitr_live_... -- npx -y @mitr-analytics/mcp
+*Gemini CLI* (`~/.gemini/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "mitr": {
+      "httpUrl": "https://mcp.mitranalytics.dev/mcp",
+      "headers": { "Authorization": "Bearer mitr_live_..." }
+    }
+  }
+}
 ```
 
-**3. Restart the assistant** and ask a question. The dashboard shows when the key was last used.
+### Local (npx)
+
+For clients that run a command, such as Claude Desktop. You need [Node.js](https://nodejs.org) 18 or newer. Open `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`) and add:
+
+```json
+{
+  "mcpServers": {
+    "mitr": {
+      "command": "npx",
+      "args": ["-y", "@mitr-analytics/mcp"],
+      "env": { "MITR_API_KEY": "mitr_live_..." }
+    }
+  }
+}
+```
+
+The same works in Claude Code (`claude mcp add mitr --env MITR_API_KEY=mitr_live_... -- npx -y @mitr-analytics/mcp`) and the Gemini CLI if you prefer running it locally.
+
+**3. Ask a question** (restart the assistant first if it's a local setup). The dashboard shows when the key was last used.
 
 ## Tools
 
@@ -57,9 +103,19 @@ claude mcp add mitr --env MITR_API_KEY=mitr_live_... -- npx -y @mitr-analytics/m
 | `get_funnel_results` | Step-by-step conversion and drop-off for one funnel over a date range. |
 | `get_alert_rule` | Your traffic spike/drop alert settings, if you have set one. |
 | `get_billing_usage` | Your plan, subscription status and event usage. |
-| `add_app` | Register a new app. The only tool that changes anything, and it needs a key with "Can register apps". The app's secret key is not returned: copy it from the dashboard. |
-
-There is deliberately no tool to delete anything, edit alerts or webhooks, or manage your team.
+| `get_workspace_overview` | One summary of every app's traffic, webhooks, QR campaigns and funnels, with anything that needs attention. |
+| `list_qr_campaigns` | Your QR campaigns with ids, status, scan totals and your plan's QR limits. |
+| `get_qr_campaign` | One campaign with its codes and per-code scan counts. |
+| `get_webhook_health` | Per webhook endpoint: delivery counts by status and the latest failure. Payloads are never returned. |
+| `add_app` | Register a new app. Needs "Can register apps". The app's secret key is not returned: copy it from the dashboard. |
+| `create_funnel`, `update_funnel` | Create a funnel from ordered page-path or event steps, or replace a funnel's name and steps. Needs "Can manage funnels". |
+| `delete_funnel` | Permanently delete a funnel. Needs "Can manage funnels" and "Can delete". |
+| `create_qr_campaign`, `update_qr_campaign` | Create a campaign that sends scanners to an https URL, or rename it, change the destination, or set its status to active, paused or archived. Needs "Can manage QR campaigns". |
+| `add_qr_code` | Add a printable code to a campaign, labelled by placement. Needs "Can manage QR campaigns". |
+| `create_webhook`, `update_webhook` | Create an https webhook endpoint, or change its URL and event types, or pause it. The signing secret is not returned: copy it from the dashboard. Needs "Can manage webhooks". |
+| `delete_webhook` | Permanently delete a webhook endpoint. Needs "Can manage webhooks" and "Can delete". |
+
+Every change is its own permission on the key, and deletes need "Can delete" as well. Alerts and team management are not available to the assistant.
 
 ## Security and privacy
 
@@ -68,7 +124,7 @@ There is deliberately no tool to delete anything, edit alerts or webhooks, or ma
 - **It sits in your assistant's config file in plain text.** Use a separate key per tool, so you can revoke one without breaking the others.
 - **Your AI provider sees the data you ask about.** Reports and recent events (page paths, UTM tags, device and location summaries, any custom event properties you send) are returned to the assistant, so they are covered by that provider's terms. Mitr itself identifies visitors only by hashed identifiers; see [how we count visitors without cookies](https://mitranalytics.dev/blog/why-we-built-analytics-without-cookies).
 - **Visitor data is marked as untrusted.** Page paths, referrers, UTM tags and event properties are written by your visitors, so anyone can put text in them, including text aimed at an AI. Reports and recent events are cleaned of hidden characters and returned inside an `untrusted_data` envelope telling the assistant to treat them as data, never instructions.
-- **No secrets in the conversation.** `add_app` doesn't return the new app's SDK secret key; copy it from the dashboard.
+- **No secrets in the conversation.** `add_app` doesn't return the new app's SDK secret key, and the webhook tools don't return signing secrets; copy them from the dashboard.
 - The key is only ever sent over HTTPS (plain `http://` is accepted only for `localhost`).
 
 ## Plans
@@ -77,14 +133,15 @@ During early access the MCP server works on every Mitr plan, including Free. Aft
 
 ## Troubleshooting
 
-Run `npx -y @mitr-analytics/mcp --version` in a terminal. If that prints a version, the package works and the problem is in the client config.
+Hosted: open https://mcp.mitranalytics.dev/ in a browser; it should show the server version. Local: run `npx -y @mitr-analytics/mcp --version` in a terminal. If either works, the problem is in the client config.
 
 | You see | What to do |
 |---|---|
 | `MITR_API_KEY is not set` | The `env` block is missing or in the wrong place in the client config. |
 | "Your Mitr API key was rejected" | The key expired, was revoked or was copied wrongly, or you're no longer in its workspace. Create a new one in Settings → API keys. |
-| "missing the 'apps:write' permission" | The key is read-only. Create one with "Can register apps" ticked to use `add_app`. |
+| "missing the 'apps:write' permission" (or `funnels:write`, `qr:write`, `webhooks:write`, `delete`) | The key doesn't have that permission. Create one with it ticked to use the tool. |
 | "early-access period has ended for the Free plan" | Upgrade the workspace; the same key starts working again. |
+| 401 from the hosted endpoint | The `Authorization: Bearer mitr_live_…` header is missing or malformed in the client config. |
 | "Mitr is rate-limiting this key" | Too many requests in a short time. Wait a minute. |
 | `npx: command not found` | Install Node.js 18+, then restart the assistant so it picks up the new PATH. |
 | "Could not reach Mitr" | Check your connection or proxy. Only set `MITR_API_BASE_URL` if you were told to. |

package/dist/client.js

@@ -83,5 +83,8 @@ export function createMitrClient(config, options = {}) {
     return {
         get: (path) => request("GET", path),
         post: (path, body) => request("POST", path, body ?? {}),
+        put: (path, body) => request("PUT", path, body ?? {}),
+        patch: (path, body) => request("PATCH", path, body ?? {}),
+        delete: (path) => request("DELETE", path),
     };
 }

package/dist/server.js

@@ -6,6 +6,8 @@ import { registerAppTools } from "./tools/apps.js";
 import { registerBillingTools } from "./tools/billing.js";
 import { registerFunnelTools } from "./tools/funnels.js";
 import { registerReportTools } from "./tools/reports.js";
+import { registerWorkspaceTools } from "./tools/workspace.js";
+import { registerWriteTools } from "./tools/writes.js";
 export function createServer(client, version) {
     const server = new McpServer({ name: "mitr", version });
     registerAppTools(server, client);
@@ -13,6 +15,8 @@ export function createServer(client, version) {
     registerFunnelTools(server, client);
     registerAlertTools(server, client);
     registerBillingTools(server, client);
+    registerWriteTools(server, client);
+    registerWorkspaceTools(server, client);
     return server;
 }
 export async function startServer(config, version) {

package/dist/tools/workspace.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { runTool, visitorDataResult } from "../toolResult.js";
+// Workspace-wide reads. Visitor-written text (paths, error messages, campaign names) goes through visitorDataResult.
+export function registerWorkspaceTools(server, client) {
+    server.registerTool("get_workspace_overview", {
+        title: "Get the workspace overview",
+        description: "Get one summary of the whole workspace: every app's traffic, plus its webhooks, QR campaigns, funnels, and anything that needs attention. Call this first when the user asks how things are doing overall.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => runTool(async () => visitorDataResult(await client.get("/mcp/overview"))));
+    server.registerTool("list_qr_campaigns", {
+        title: "List QR campaigns",
+        description: "List your QR campaigns with each campaign's id (needed by get_qr_campaign and the QR write tools), name, status, and scan totals. Also returns your plan's QR limits.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => runTool(async () => visitorDataResult(await client.get("/mcp/qr/campaigns"))));
+    server.registerTool("get_qr_campaign", {
+        title: "Get one QR campaign",
+        description: "Get one QR campaign with its codes and per-code scan counts, to see which placement is working. Use the id from list_qr_campaigns.",
+        inputSchema: {
+            campaignId: z.string().uuid().describe("The campaign's id, from list_qr_campaigns."),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ campaignId }) => runTool(async () => visitorDataResult(await client.get(`/mcp/qr/campaigns/${campaignId}`))));
+    server.registerTool("get_webhook_health", {
+        title: "Check webhook delivery health",
+        description: "For each webhook endpoint, show delivery counts by status over its recent deliveries (delivered, pending, failed, exhausted) and the latest failure with its error. Payloads are not returned. Use this when a user says their webhook is not receiving events.",
+        inputSchema: {
+            deliveriesPerEndpoint: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("How many recent deliveries to count per endpoint. Defaults to 50."),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ deliveriesPerEndpoint }) => runTool(async () => {
+        const query = deliveriesPerEndpoint ? `?deliveries_per_endpoint=${deliveriesPerEndpoint}` : "";
+        return visitorDataResult(await client.get(`/mcp/webhooks/health${query}`));
+    }));
+}

package/dist/tools/writes.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { jsonResult, runTool } from "../toolResult.js";
+// Write tools. Each needs its own API key permission (funnels:write, qr:write, webhooks:write); deletes also need
+// "delete". A key without the permission gets a clear error from the server, not a silent no-op.
+const funnelStep = z.object({
+    label: z.string().min(1).max(120).describe("Name of this step, e.g. 'Pricing page'."),
+    matchType: z
+        .enum(["path", "event_type"])
+        .describe("'path' matches a page path such as /pricing; 'event_type' matches a custom event name such as signup."),
+    matchValue: z.string().min(1).describe("The path (e.g. /pricing) or the event name (e.g. signup)."),
+    siteId: z.string().uuid().optional().describe("Limit this step to one app. Leave out to match any app in the workspace."),
+});
+const eventTypes = z.array(z.string().min(1)).describe("Event names this endpoint receives. Empty means none.");
+// Webhook create responses include the signing secret. Hand it to the user from the dashboard instead of putting it in
+// the conversation, the same way add_app withholds the SDK secret.
+function withoutSecret(data) {
+    if (data && typeof data === "object" && "secret" in data) {
+        const { secret: _secret, ...rest } = data;
+        return { ...rest, note: "The signing secret is not shown here. Copy it from Settings → Webhooks in the Mitr dashboard." };
+    }
+    return data;
+}
+export function registerWriteTools(server, client) {
+    server.registerTool("create_funnel", {
+        title: "Create a conversion funnel",
+        description: "Create a funnel of 2 or more ordered steps (each a page path or a custom event) to measure conversion through. Returns the new funnel. Needs an API key with the funnels:write permission.",
+        inputSchema: {
+            name: z.string().min(1).max(120).describe("Name for the funnel, e.g. 'Signup'."),
+            steps: z.array(funnelStep).min(1).max(10),
+            utmCampaign: z.string().max(120).optional().describe("Scope the funnel to one campaign link's utm_campaign key."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async (args) => runTool(async () => jsonResult(await client.post("/mcp/funnels", args))));
+    server.registerTool("update_funnel", {
+        title: "Update a conversion funnel",
+        description: "Replace a funnel's name and steps. This is a full update: send every step, not only the ones that change. Needs funnels:write. Get the funnelId from list_funnels.",
+        inputSchema: {
+            funnelId: z.string().uuid(),
+            name: z.string().min(1).max(120),
+            steps: z.array(funnelStep).min(1).max(10),
+            utmCampaign: z.string().max(120).optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ funnelId, ...body }) => runTool(async () => jsonResult(await client.put(`/mcp/funnels/${funnelId}`, body))));
+    server.registerTool("delete_funnel", {
+        title: "Delete a conversion funnel",
+        description: "Permanently delete a funnel and its results history. Cannot be undone. Needs both funnels:write and delete permissions. Confirm with the user before calling.",
+        inputSchema: { funnelId: z.string().uuid() },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    }, async ({ funnelId }) => runTool(async () => jsonResult(await client.delete(`/mcp/funnels/${funnelId}`))));
+    server.registerTool("create_qr_campaign", {
+        title: "Create a QR campaign",
+        description: "Create a trackable QR campaign that sends scanners to a destination URL. Add codes per placement with add_qr_code. Returns the new campaign. Free plans allow one active campaign. Needs the qr:write permission.",
+        inputSchema: {
+            name: z.string().min(1).max(120).describe("Name for the campaign, e.g. 'Demo day 2026'."),
+            destinationUrl: z.string().url().startsWith("https://").describe("Where scanners land. Must be https."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async (args) => runTool(async () => jsonResult(await client.post("/mcp/qr/campaigns", { ...args, destinationType: "url" }))));
+    server.registerTool("update_qr_campaign", {
+        title: "Update a QR campaign",
+        description: "Rename a QR campaign, change its destination, or change its status: 'active', 'paused' or 'archived'. Archiving stops the campaign's codes from being created and keeps its history; it is reversible with status 'active'. Needs qr:write.",
+        inputSchema: {
+            campaignId: z.string().uuid(),
+            name: z.string().min(1).max(120).optional(),
+            destinationUrl: z.string().url().startsWith("https://").optional(),
+            status: z.enum(["active", "paused", "archived"]).optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ campaignId, ...changes }) => runTool(async () => {
+        const body = Object.fromEntries(Object.entries(changes).filter(([, v]) => v !== undefined));
+        return jsonResult(await client.patch(`/mcp/qr/campaigns/${campaignId}`, body));
+    }));
+    server.registerTool("add_qr_code", {
+        title: "Add a QR code placement to a campaign",
+        description: "Add one printable code to a campaign, labelled by where it will be placed, e.g. 'Poster, main hall'. Each code is counted separately. Needs qr:write.",
+        inputSchema: {
+            campaignId: z.string().uuid(),
+            label: z.string().min(1).max(120).describe("Where this code will be placed."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ campaignId, label }) => runTool(async () => jsonResult(await client.post(`/mcp/qr/campaigns/${campaignId}/codes`, { label }))));
+    server.registerTool("create_webhook", {
+        title: "Create a webhook endpoint",
+        description: "Send tracked events to an https URL you control. Returns the endpoint, without its signing secret, which is copied from the dashboard. Needs webhooks:write.",
+        inputSchema: {
+            url: z.string().url().startsWith("https://"),
+            eventTypes,
+            isActive: z.boolean().optional().describe("Defaults to true."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args) => runTool(async () => jsonResult(withoutSecret(await client.post("/mcp/webhooks", args)))));
+    server.registerTool("update_webhook", {
+        title: "Update a webhook endpoint",
+        description: "Change a webhook's URL, its event types, or switch it on or off with isActive. Needs webhooks:write. Get the endpointId from the dashboard or the webhook health tool.",
+        inputSchema: {
+            endpointId: z.string().uuid(),
+            url: z.string().url().startsWith("https://").optional(),
+            eventTypes: eventTypes.optional(),
+            isActive: z.boolean().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ endpointId, ...changes }) => runTool(async () => {
+        const body = Object.fromEntries(Object.entries(changes).filter(([, v]) => v !== undefined));
+        return jsonResult(withoutSecret(await client.patch(`/mcp/webhooks/${endpointId}`, body)));
+    }));
+    server.registerTool("delete_webhook", {
+        title: "Delete a webhook endpoint",
+        description: "Permanently delete a webhook endpoint and its delivery log. Cannot be undone. Needs both webhooks:write and delete. Confirm with the user before calling; to pause it instead, use update_webhook with isActive false.",
+        inputSchema: { endpointId: z.string().uuid() },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    }, async ({ endpointId }) => runTool(async () => jsonResult(await client.delete(`/mcp/webhooks/${endpointId}`))));
+}

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Same as package.json "version" (a test keeps them equal). The hosted Worker can't read package.json at runtime. */
-export const VERSION = "1.1.0";
+export const VERSION = "1.2.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mitr-analytics/mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "mcpName": "io.github.shiv9thakur/mitr-mcp",
   "description": "Mitr analytics for Claude, Gemini and other MCP clients: list apps, pull reports and funnels, and ask questions about your own data. Cookie-free analytics, one API key.",
   "keywords": [