@attrkit/mcp 0.2.0

package/README.md

@@ -0,0 +1,67 @@
+# @attrkit/mcp
+
+A stdio [MCP](https://modelcontextprotocol.io) server that lets you drive [AttriKit](https://attrikit.io)
+from Codex, Cursor, Gemini, or another MCP client. It is a thin client over AttriKit's public API — it
+holds no database access; your tenant scope is resolved from your secret management key.
+
+## What it exposes
+
+| Area | Tools |
+|---|---|
+| Key scope | `whoami` |
+| Apps | `list_apps`, `create_app`, `get_app`, `update_app`, `archive_app` |
+| SDK keys | `get_publishable_key`, `rotate_publishable_key` |
+| Management keys | `list_api_keys`, `create_api_key`, `revoke_api_key` |
+| Campaign links | `list_links`, `create_campaign_link`, `update_link_status` |
+| Decisions and reporting | `list_campaigns`, `list_ads`, `list_recent_events`, `get_campaign_decision`, `record_campaign_decision`, `get_attribution_rollup` |
+| Spend and costs | `get_spend`, `import_spend`, `set_cost_model`, `pull_network_spend` |
+| Ad integrations | `list_integrations`, `create_integration`, `update_integration`, `delete_integration` |
+| RevenueCat | `get_revenuecat`, `configure_revenuecat` |
+| Outbound webhooks | `list_webhooks`, `create_webhook`, `delete_webhook` |
+| Data export | `export_events` |
+
+`get_campaign_decision` returns the engine's call **verbatim** — the model reports it, it does not recompute it.
+
+## Setup
+
+1. Obtain one workspace management key (`sk_…`). Once you have that bootstrap key, all operational
+   setup—including apps and delegated app keys—can be completed through MCP without the web dashboard.
+   Keep `write` only on agents that should mutate the workspace.
+2. Add the server to your client config:
+
+```json
+{
+  "mcpServers": {
+    "attrkit": {
+      "command": "npx",
+      "args": ["-y", "@attrkit/mcp"],
+      "env": {
+        "ATTRKIT_API_KEY": "sk_your_key_here",
+        "ATTRKIT_API_URL": "https://attrikit.io"
+      }
+    }
+  }
+}
+```
+
+`ATTRKIT_API_URL` is optional (defaults to `https://attrikit.io`).
+
+## Test it locally
+
+```bash
+ATTRKIT_API_KEY=sk_... npx @modelcontextprotocol/inspector npx -y @attrkit/mcp
+```
+
+The Inspector lists the tools and lets you invoke them against your live workspace.
+
+## Notes
+
+- stdio only — no network listener, no port bind.
+- Key scopes gate reads vs writes; a read-only key gets `403 forbidden_scope` on every mutation.
+- App-scoped keys cannot create other apps, reach sibling apps, or manage workspace-wide integrations.
+- App creation, management-key creation, and webhook creation return secret values once. Capture them
+  from the tool result; list tools only return masked metadata.
+- Mutation tools accept an optional `idempotency_key`. Reuse the same value only for an exact retry;
+  one-time secret responses are encrypted at rest and safely replayed.
+- Management keys are protected by distributed per-key global, mutation, and expensive-operation limits.
+- All diagnostics go to stderr (stdout is the MCP transport).

package/dist/cli.js

@@ -0,0 +1,616 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+function readConfig(env = process.env) {
+  const apiKey = env.ATTRKIT_API_KEY;
+  if (!apiKey) {
+    throw new Error("ATTRKIT_API_KEY is required (create one in AttriKit → Settings → API keys).");
+  }
+  const apiUrl = (env.ATTRKIT_API_URL ?? "https://attrikit.io").replace(/\/+$/, "");
+  return { apiKey, apiUrl };
+}
+var REQUEST_TIMEOUT_MS = 15000;
+async function callApi(config, path, options = {}) {
+  const doFetch = options.fetchImpl ?? fetch;
+  const url = new URL(`${config.apiUrl}${path}`);
+  for (const [key, value] of Object.entries(options.query ?? {})) {
+    if (value !== undefined && value !== "")
+      url.searchParams.set(key, value);
+  }
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const response = await doFetch(url.toString(), {
+      method: options.method ?? "GET",
+      headers: {
+        authorization: `AttriKit-Management ${config.apiKey}`,
+        "content-type": "application/json",
+        ...options.idempotencyKey ? { "idempotency-key": options.idempotencyKey } : {}
+      },
+      ...options.body !== undefined ? { body: JSON.stringify(options.body) } : {},
+      signal: controller.signal
+    });
+    const text = await response.text();
+    let json = null;
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = text;
+      }
+    }
+    return { ok: response.ok, status: response.status, json };
+  } catch (error) {
+    return {
+      ok: false,
+      status: 0,
+      json: { error: { code: "network_error", message: error instanceof Error ? error.message : String(error) } }
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function toToolResult(result) {
+  if (!result.ok) {
+    const envelope = result.json;
+    const code = envelope?.error?.code ?? `http_${result.status}`;
+    const message = envelope?.error?.message ? `: ${envelope.error.message}` : "";
+    return {
+      content: [{ type: "text", text: `AttriKit API error (${result.status || "network"}): ${code}${message}` }],
+      isError: true
+    };
+  }
+  const structured = result.json && typeof result.json === "object" ? result.json : { value: result.json };
+  return {
+    content: [{ type: "text", text: JSON.stringify(result.json, null, 2) }],
+    structuredContent: structured
+  };
+}
+var periodSchema = z.enum(["7d", "30d", "90d", "all"]).describe("Reporting window. Defaults to 30d.").optional();
+var appIdSchema = z.string().describe("Optional app id to scope the result to one app.").optional();
+var requiredAppIdSchema = z.string().describe("The AttriKit app id.");
+var idempotencyKeySchema = z.string().max(255).describe("Stable retry key for this exact mutation.").optional();
+var ownersSchema = z.record(z.string(), z.enum(["attrkit", "revenuecat", "customer"]));
+var spendRowSchema = z.object({
+  campaignId: z.string(),
+  adsetId: z.string().optional().nullable(),
+  adId: z.string().optional().nullable(),
+  adsetName: z.string().optional().nullable(),
+  adName: z.string().optional().nullable(),
+  metricDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+  clicks: z.number().int().nonnegative().optional(),
+  impressions: z.number().int().nonnegative().optional(),
+  spendMinorUnits: z.number().int().nonnegative()
+});
+function createServer(config, fetchImpl) {
+  const server = new McpServer({ name: "attrkit", version: "0.2.0" });
+  const call = (path, options) => callApi(config, path, { fetchImpl, ...options });
+  server.registerTool("whoami", {
+    title: "Inspect management-key scope",
+    description: "Return the authenticated workspace, plan, app restriction and read/write scopes.",
+    inputSchema: {}
+  }, async () => toToolResult(await call("/api/v1/whoami")));
+  server.registerTool("list_apps", {
+    title: "List apps",
+    description: "List the iOS and Android apps in your AttriKit workspace (id, name, platform, bundle id, store id, status).",
+    inputSchema: {}
+  }, async () => toToolResult(await call("/api/v1/apps")));
+  server.registerTool("create_app", {
+    title: "Create an app",
+    description: "Create an iOS or Android app without the web UI. Returns the publishable key and a one-time app-scoped management key.",
+    inputSchema: {
+      name: z.string().min(1).max(80),
+      bundle_id: z.string().min(3).max(255),
+      platform: z.enum(["iOS", "Android"]),
+      store_url: z.string().url(),
+      timezone: z.string().max(64).optional(),
+      device_matching_mode: z.enum(["on", "strict"]).optional(),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({
+    name,
+    bundle_id,
+    platform,
+    store_url,
+    timezone,
+    device_matching_mode,
+    idempotency_key
+  }) => toToolResult(await call("/api/v1/apps", {
+    method: "POST",
+    idempotencyKey: idempotency_key,
+    body: {
+      name,
+      bundleId: bundle_id,
+      platform,
+      storeUrl: store_url,
+      ...timezone ? { timezone } : {},
+      ...device_matching_mode ? { deviceMatchingMode: device_matching_mode } : {}
+    }
+  })));
+  server.registerTool("get_app", {
+    title: "Get an app",
+    description: "Return one app's configuration.",
+    inputSchema: { app_id: requiredAppIdSchema }
+  }, async ({ app_id }) => toToolResult(await call(`/api/v1/apps/${encodeURIComponent(app_id)}`)));
+  server.registerTool("update_app", {
+    title: "Update an app",
+    description: "Update app metadata, store destination, timezone or device-matching mode.",
+    inputSchema: {
+      app_id: requiredAppIdSchema,
+      name: z.string().min(1).max(80).optional(),
+      bundle_id: z.string().min(3).max(255).optional(),
+      platform: z.enum(["iOS", "Android"]).optional(),
+      store_url: z.string().url().optional(),
+      timezone: z.string().max(64).optional(),
+      device_matching_mode: z.enum(["on", "strict"]).optional(),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({
+    app_id,
+    name,
+    bundle_id,
+    platform,
+    store_url,
+    timezone,
+    device_matching_mode,
+    idempotency_key
+  }) => toToolResult(await call(`/api/v1/apps/${encodeURIComponent(app_id)}`, {
+    method: "PATCH",
+    idempotencyKey: idempotency_key,
+    body: {
+      ...name ? { name } : {},
+      ...bundle_id ? { bundleId: bundle_id } : {},
+      ...platform ? { platform } : {},
+      ...store_url ? { storeUrl: store_url } : {},
+      ...timezone ? { timezone } : {},
+      ...device_matching_mode ? { deviceMatchingMode: device_matching_mode } : {}
+    }
+  })));
+  server.registerTool("archive_app", {
+    title: "Archive an app",
+    description: "Archive an app and remove it from active customer operations.",
+    inputSchema: { app_id: requiredAppIdSchema }
+  }, async ({ app_id }) => toToolResult(await call(`/api/v1/apps/${encodeURIComponent(app_id)}`, {
+    method: "DELETE"
+  })));
+  server.registerTool("get_publishable_key", {
+    title: "Get an app publishable key",
+    description: "Reveal the recoverable SDK publishable key for an app.",
+    inputSchema: { app_id: requiredAppIdSchema }
+  }, async ({ app_id }) => toToolResult(await call(`/api/v1/apps/${encodeURIComponent(app_id)}/publishable-key`)));
+  server.registerTool("rotate_publishable_key", {
+    title: "Rotate an app publishable key",
+    description: "Issue a new SDK publishable key and return the old-key grace deadline.",
+    inputSchema: {
+      app_id: requiredAppIdSchema,
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({ app_id, idempotency_key }) => toToolResult(await call(`/api/v1/apps/${encodeURIComponent(app_id)}/publishable-key`, { method: "POST", idempotencyKey: idempotency_key })));
+  server.registerTool("list_api_keys", {
+    title: "List management keys",
+    description: "List masked workspace and app management keys. Secret plaintext is never returned.",
+    inputSchema: {}
+  }, async () => toToolResult(await call("/api/v1/api-keys")));
+  server.registerTool("create_api_key", {
+    title: "Create a management key",
+    description: "Create a read-only or read/write workspace or app key. The secret is returned once.",
+    inputSchema: {
+      label: z.string().min(1).max(80),
+      scopes: z.array(z.enum(["read", "write"])).min(1).max(2),
+      app_id: z.string().uuid().optional().nullable(),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({ label, scopes, app_id, idempotency_key }) => toToolResult(await call("/api/v1/api-keys", {
+    method: "POST",
+    idempotencyKey: idempotency_key,
+    body: { label, scopes, app_id: app_id ?? null }
+  })));
+  server.registerTool("revoke_api_key", {
+    title: "Revoke a management key",
+    description: "Immediately revoke a management key by id.",
+    inputSchema: { key_id: z.string().uuid() }
+  }, async ({ key_id }) => toToolResult(await call(`/api/v1/api-keys/${encodeURIComponent(key_id)}`, {
+    method: "DELETE"
+  })));
+  server.registerTool("list_links", {
+    title: "List campaign links",
+    description: "List tracking links, optionally for one app.",
+    inputSchema: {
+      app_id: appIdSchema,
+      cursor: z.string().optional(),
+      limit: z.number().int().min(1).max(200).optional()
+    }
+  }, async ({ app_id, cursor, limit }) => toToolResult(await call("/api/v1/links", {
+    query: {
+      appId: app_id,
+      cursor,
+      limit: limit === undefined ? undefined : String(limit)
+    }
+  })));
+  server.registerTool("list_campaigns", {
+    title: "List campaigns",
+    description: "List ad campaigns with their honest profit surface: the scale/cut/hold call, profit p05/p50/p95, spend, retention, and payback. Use this to see how campaigns are performing.",
+    inputSchema: { app_id: appIdSchema, period: periodSchema }
+  }, async ({ app_id, period }) => toToolResult(await call("/api/v1/reports/campaigns", { query: { appId: app_id, period } })));
+  server.registerTool("list_ads", {
+    title: "List creative-level ad performance",
+    description: "Return ad and ad-set performance, evidence tiers, ROAS, CPA, CPC and modeled remainders.",
+    inputSchema: {
+      app_id: appIdSchema,
+      period: periodSchema,
+      limit: z.number().int().min(1).max(200).optional()
+    }
+  }, async ({ app_id, period, limit }) => toToolResult(await call("/api/v1/reports/ads", {
+    query: {
+      appId: app_id,
+      period,
+      limit: limit === undefined ? undefined : String(limit)
+    }
+  })));
+  server.registerTool("list_recent_events", {
+    title: "List recent events and installs",
+    description: "Return the same recent attribution events and installs visible on the Live dashboard.",
+    inputSchema: {
+      app_id: appIdSchema,
+      limit: z.number().int().min(1).max(50).optional()
+    }
+  }, async ({ app_id, limit }) => toToolResult(await call("/api/v1/events", {
+    query: {
+      appId: app_id,
+      limit: limit === undefined ? undefined : String(limit)
+    }
+  })));
+  server.registerTool("get_campaign_decision", {
+    title: "Get campaign decisions (scale / cut / hold)",
+    description: "Return AttriKit's profit DECISIONS for your campaigns: the scale/cut/hold call and confidence, computed by the attribution engine. Report the `call` VERBATIM — do not recompute or override it; when it says not_enough_data, say so. This is the tool to drive budget automation.",
+    inputSchema: { app_id: appIdSchema }
+  }, async ({ app_id }) => toToolResult(await call("/api/v1/decisions", { query: { appId: app_id } })));
+  server.registerTool("record_campaign_decision", {
+    title: "Record a campaign decision",
+    description: "Freeze a scale/cut/hold decision and its exact model inputs for later maturity evaluation.",
+    inputSchema: {
+      app_id: requiredAppIdSchema,
+      campaign_id: z.string(),
+      call: z.enum(["scale", "cut", "hold"]),
+      actor: z.enum(["dashboard", "auto_suggested"]).optional(),
+      p05: z.number(),
+      p50: z.number(),
+      p95: z.number(),
+      spend_minor_units: z.number().nonnegative(),
+      currency: z.string().length(3),
+      band_width_pct: z.number().nonnegative(),
+      threshold: z.number(),
+      model_version: z.string(),
+      cost_model_version: z.number().int().positive().nullable(),
+      revenue_per_install_minor_units: z.number().nonnegative().nullable(),
+      revenue_per_install_quality: z.enum([
+        "campaign_verified_cohort",
+        "app_verified_cohort_fallback",
+        "unavailable"
+      ]),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({
+    app_id,
+    campaign_id,
+    call: decisionCall,
+    actor,
+    p05,
+    p50,
+    p95,
+    spend_minor_units,
+    currency,
+    band_width_pct,
+    threshold,
+    model_version,
+    cost_model_version,
+    revenue_per_install_minor_units,
+    revenue_per_install_quality,
+    idempotency_key
+  }) => toToolResult(await call("/api/v1/decisions", {
+    method: "POST",
+    idempotencyKey: idempotency_key,
+    body: {
+      appId: app_id,
+      campaignId: campaign_id,
+      call: decisionCall,
+      ...actor ? { actor } : {},
+      inputs: {
+        p05,
+        p50,
+        p95,
+        spend_minor_units,
+        currency,
+        band_width_pct,
+        threshold,
+        model_version,
+        cost_model_version,
+        revenue_per_install_minor_units,
+        revenue_per_install_quality
+      }
+    }
+  })));
+  server.registerTool("get_attribution_rollup", {
+    title: "Get attribution rollup",
+    description: "Return the account-level attribution overview: installs accounted-for by evidence class (verified / device-matched / modeled / organic), MER, revenue and data freshness.",
+    inputSchema: { app_id: appIdSchema, period: periodSchema }
+  }, async ({ app_id, period }) => toToolResult(await call("/api/v1/reports/overview", { query: { appId: app_id, period } })));
+  server.registerTool("create_campaign_link", {
+    title: "Create a campaign tracking link",
+    description: "Create a web-to-app tracking link for an ad campaign. Requires a write-scoped API key. Returns the link id and url.",
+    inputSchema: {
+      app_id: z.string().describe("The app id the link belongs to."),
+      network: z.enum(["meta", "google", "tiktok"]).describe("The ad network delivering the campaign."),
+      destination_url: z.string().url().describe("The App Store URL to send users to."),
+      campaign_name: z.string().max(120).optional().describe("Optional human-readable campaign name."),
+      campaign_id: z.string().optional().describe("Optional external campaign id."),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({ app_id, network, destination_url, campaign_name, campaign_id, idempotency_key }) => toToolResult(await call("/api/v1/links", {
+    method: "POST",
+    idempotencyKey: idempotency_key,
+    body: {
+      appId: app_id,
+      network,
+      destinationUrl: destination_url,
+      ...campaign_name ? { campaignName: campaign_name } : {},
+      ...campaign_id ? { campaignId: campaign_id } : {}
+    }
+  })));
+  server.registerTool("update_link_status", {
+    title: "Enable or disable a campaign link",
+    description: "Change a tracking link between active and disabled.",
+    inputSchema: {
+      link_id: z.string().uuid(),
+      status: z.enum(["active", "disabled"]),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({ link_id, status, idempotency_key }) => toToolResult(await call(`/api/v1/links/${encodeURIComponent(link_id)}`, { method: "PATCH", idempotencyKey: idempotency_key, body: { status } })));
+  server.registerTool("get_spend", {
+    title: "Get spend and cost models",
+    description: "Return imported ad spend, cost models, completeness and spend freshness.",
+    inputSchema: { app_id: appIdSchema }
+  }, async ({ app_id }) => toToolResult(await call("/api/v1/spend", {
+    query: { appId: app_id }
+  })));
+  server.registerTool("import_spend", {
+    title: "Import ad spend",
+    description: "Import campaign or creative-level spend rows.",
+    inputSchema: {
+      app_id: requiredAppIdSchema,
+      network: z.enum(["meta", "google", "tiktok", "apple_ads"]),
+      source: z.enum(["network_api", "csv", "manual"]).optional(),
+      account_ref: z.string().optional(),
+      currency: z.string().length(3),
+      report_timezone: z.string().optional(),
+      covers_from: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+      covers_to: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+      completeness: z.enum(["partial", "final"]).optional(),
+      notes: z.string().optional(),
+      rows: z.array(spendRowSchema).min(1).max(5000),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({
+    app_id,
+    network,
+    source,
+    account_ref,
+    currency,
+    report_timezone,
+    covers_from,
+    covers_to,
+    completeness,
+    notes,
+    rows,
+    idempotency_key
+  }) => toToolResult(await call("/api/v1/spend", {
+    method: "POST",
+    idempotencyKey: idempotency_key,
+    body: {
+      kind: "spend",
+      appId: app_id,
+      network,
+      ...source ? { source } : {},
+      ...account_ref ? { accountRef: account_ref } : {},
+      currency,
+      ...report_timezone ? { reportTimezone: report_timezone } : {},
+      coversFrom: covers_from,
+      coversTo: covers_to,
+      ...completeness ? { completeness } : {},
+      ...notes ? { notes } : {},
+      rows
+    }
+  })));
+  server.registerTool("set_cost_model", {
+    title: "Set an app cost model",
+    description: "Version commission, payment fees and variable COGS used in profit decisions.",
+    inputSchema: {
+      app_id: requiredAppIdSchema,
+      effective_at: z.string(),
+      store_commission_bps: z.number().int().min(0).max(1e4),
+      payment_fee_bps: z.number().int().min(0).max(1e4),
+      variable_cogs_kind: z.enum(["bps", "per_unit_minor"]),
+      variable_cogs_value: z.number().nonnegative(),
+      assumptions: z.record(z.string(), z.unknown()).optional(),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({
+    app_id,
+    effective_at,
+    store_commission_bps,
+    payment_fee_bps,
+    variable_cogs_kind,
+    variable_cogs_value,
+    assumptions,
+    idempotency_key
+  }) => toToolResult(await call("/api/v1/spend", {
+    method: "POST",
+    idempotencyKey: idempotency_key,
+    body: {
+      kind: "cost_model",
+      appId: app_id,
+      effectiveAt: effective_at,
+      storeCommissionBps: store_commission_bps,
+      paymentFeeBps: payment_fee_bps,
+      variableCogs: { kind: variable_cogs_kind, value: variable_cogs_value },
+      ...assumptions ? { assumptions } : {}
+    }
+  })));
+  server.registerTool("pull_network_spend", {
+    title: "Pull spend from an ad network",
+    description: "Fetch and import creative-level spend from a configured Meta, Google or TikTok connection.",
+    inputSchema: {
+      app_id: requiredAppIdSchema,
+      network: z.enum(["meta", "google", "tiktok"]),
+      connection_id: z.string().optional(),
+      covers_from: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+      covers_to: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({ app_id, network, connection_id, covers_from, covers_to, idempotency_key }) => toToolResult(await call("/api/v1/spend", {
+    method: "POST",
+    idempotencyKey: idempotency_key,
+    body: {
+      kind: "network_pull",
+      appId: app_id,
+      network,
+      ...connection_id ? { connectionId: connection_id } : {},
+      coversFrom: covers_from,
+      coversTo: covers_to
+    }
+  })));
+  server.registerTool("list_integrations", {
+    title: "List ad-network integrations",
+    description: "List redacted ad-network connections and their readiness.",
+    inputSchema: {}
+  }, async () => toToolResult(await call("/api/v1/integrations")));
+  server.registerTool("create_integration", {
+    title: "Create an ad-network integration",
+    description: "Store encrypted network credentials and configure event ownership.",
+    inputSchema: {
+      network: z.enum(["meta", "google", "tiktok"]),
+      account_ref: z.string().min(1),
+      credential: z.string().min(1),
+      owners: ownersSchema,
+      enable: z.boolean().optional(),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({ network, account_ref, credential, owners, enable, idempotency_key }) => toToolResult(await call("/api/v1/integrations", {
+    method: "POST",
+    idempotencyKey: idempotency_key,
+    body: { network, account_ref, credential, owners, enable: enable ?? false }
+  })));
+  server.registerTool("update_integration", {
+    title: "Update an ad-network integration",
+    description: "Rotate credentials or enable/disable an integration.",
+    inputSchema: {
+      connection_id: z.string(),
+      action: z.enum(["rotate", "disable", "enable"]),
+      credential: z.string().optional(),
+      owners: ownersSchema.optional(),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({ connection_id, action, credential, owners, idempotency_key }) => toToolResult(await call(`/api/v1/integrations/${encodeURIComponent(connection_id)}`, {
+    method: "PATCH",
+    idempotencyKey: idempotency_key,
+    body: {
+      action,
+      ...credential ? { credential } : {},
+      ...owners ? { owners } : {}
+    }
+  })));
+  server.registerTool("delete_integration", {
+    title: "Delete an ad-network integration",
+    description: "Delete a disabled integration. Enabled integrations must be disabled first.",
+    inputSchema: { connection_id: z.string() }
+  }, async ({ connection_id }) => toToolResult(await call(`/api/v1/integrations/${encodeURIComponent(connection_id)}`, { method: "DELETE" })));
+  server.registerTool("get_revenuecat", {
+    title: "Get RevenueCat configuration",
+    description: "Return redacted RevenueCat status and the AttriKit webhook URL.",
+    inputSchema: { app_id: requiredAppIdSchema }
+  }, async ({ app_id }) => toToolResult(await call(`/api/v1/apps/${encodeURIComponent(app_id)}/revenuecat`)));
+  server.registerTool("configure_revenuecat", {
+    title: "Configure RevenueCat",
+    description: "Store the RevenueCat provider app id and encrypted authorization secret for an app.",
+    inputSchema: {
+      app_id: requiredAppIdSchema,
+      provider_app_id: z.string().min(1).max(255),
+      authorization_secret: z.string().min(16).max(1024),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({ app_id, provider_app_id, authorization_secret, idempotency_key }) => toToolResult(await call(`/api/v1/apps/${encodeURIComponent(app_id)}/revenuecat`, {
+    method: "PUT",
+    idempotencyKey: idempotency_key,
+    body: { provider_app_id, authorization_secret }
+  })));
+  server.registerTool("list_webhooks", {
+    title: "List outbound webhooks",
+    description: "List redacted outbound webhook subscriptions.",
+    inputSchema: {}
+  }, async () => toToolResult(await call("/api/v1/webhooks")));
+  server.registerTool("create_webhook", {
+    title: "Create an outbound webhook",
+    description: "Create an SSRF-checked webhook subscription. Returns the signing secret once.",
+    inputSchema: {
+      url: z.string().url(),
+      event_types: z.array(z.enum(["install", "event", "decision", "fraud"])).min(1).max(4),
+      description: z.string().max(500).optional(),
+      app_id: z.string().uuid().optional(),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({ url, event_types, description, app_id, idempotency_key }) => toToolResult(await call("/api/v1/webhooks", {
+    method: "POST",
+    idempotencyKey: idempotency_key,
+    body: {
+      url,
+      event_types,
+      ...description ? { description } : {},
+      ...app_id ? { app_id } : {}
+    }
+  })));
+  server.registerTool("delete_webhook", {
+    title: "Delete an outbound webhook",
+    description: "Delete a webhook subscription.",
+    inputSchema: { subscription_id: z.string().uuid() }
+  }, async ({ subscription_id }) => toToolResult(await call(`/api/v1/webhooks/${encodeURIComponent(subscription_id)}`, { method: "DELETE" })));
+  server.registerTool("export_events", {
+    title: "Export events and installs",
+    description: "Export one app's events and installs as CSV for an inclusive date range.",
+    inputSchema: {
+      app_id: requiredAppIdSchema,
+      from: z.string().describe("ISO date or timestamp"),
+      to: z.string().describe("ISO date or timestamp")
+    }
+  }, async ({ app_id, from, to }) => toToolResult(await call("/api/v1/export", {
+    query: { appId: app_id, from, to }
+  })));
+  return server;
+}
+
+// src/cli.ts
+async function main() {
+  let config;
+  try {
+    config = readConfig();
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(1);
+    return;
+  }
+  const server = createServer(config);
+  const transport = new StdioServerTransport;
+  await server.connect(transport);
+  process.stderr.write(`attrkit-mcp connected (api=${config.apiUrl})
+`);
+}
+main().catch((error) => {
+  process.stderr.write(`attrkit-mcp failed to start: ${error instanceof Error ? error.stack ?? error.message : String(error)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@attrkit/mcp",
+  "version": "0.2.0",
+  "description": "AttriKit's stdio MCP server for its public management API",
+  "type": "module",
+  "bin": {
+    "attrkit-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build ./src/cli.ts --outdir ./dist --target=node --format=esm --external @modelcontextprotocol/sdk --external zod",
+    "typecheck": "../../node_modules/typescript-7/bin/tsc --noEmit",
+    "test": "cd ../.. && vitest run packages/mcp/src/index.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@attrkit/shared": "workspace:*",
+    "@types/node": "26.1.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  }
+}