@attrkit/mcp 0.4.1 → 0.4.3

package/dist/cli.js

@@ -14059,7 +14059,12 @@ async function callApi(config, path, options = {}) {
     return {
       ok: false,
       status: 0,
-      json: { error: { code: "network_error", message: error instanceof Error ? error.message : String(error) } }
+      json: {
+        error: error instanceof Error && error.name === "AbortError" ? {
+          code: "timeout",
+          message: `no response within ${REQUEST_TIMEOUT_MS / 1000}s. The request may still have been applied on the server; retry with the same idempotency_key rather than a new one.`
+        } : { code: "network_error", message: error instanceof Error ? error.message : String(error) }
+      }
     };
   } finally {
     clearTimeout(timer);
@@ -14071,10 +14076,12 @@ function toToolResult(result) {
     const code = envelope?.error?.code ?? `http_${result.status}`;
     const message = envelope?.error?.message ? `: ${envelope.error.message}` : "";
     const retryAfter = result.status === 429 && result.retryAfter ? ` (Retry-After: ${result.retryAfter})` : "";
+    const excerpt = !envelope?.error?.message && result.rawBody ? ` — body: ${result.rawBody.replace(/\s+/g, " ").trim().slice(0, 300)}` : "";
+    const hint = result.status === 401 ? " Check ATTRKIT_API_KEY: this is the same error for a missing, wrong, revoked or expired key." : "";
     return {
       content: [{
         type: "text",
-        text: `AttrKit API error (${result.status || "network"}): ${code}${message}${retryAfter}`
+        text: `AttrKit API error (${result.status || "network"}): ${code}${message}${retryAfter}${excerpt}${hint}`
       }],
       isError: true
     };
@@ -14103,16 +14110,16 @@ ${body}`
     structuredContent: structured
   };
 }
-var SERVER_VERSION = "0.4.1";
+var SERVER_VERSION = "0.4.3";
 var periodSchema = z4.enum(["7d", "30d", "90d", "all"]).describe("Reporting window. Defaults to 30d.").optional();
 var appIdSchema = z4.string().describe("Optional app id to scope the result to one app.").optional();
 var requiredAppIdSchema = z4.string().describe("The AttrKit app id.");
 var idempotencyKeySchema = z4.string().max(255).describe("Stable retry key for this exact mutation.").optional();
 var ownersSchema = z4.record(z4.string(), z4.enum(["attrkit", "revenuecat", "customer"]));
 var spendRowSchema = z4.object({
-  campaign_id: z4.string().optional().describe("Required AttrKit campaign id. Preferred snake_case spelling."),
+  campaign_id: z4.string().optional().describe("The AttrKit campaign UUID, NOT the ad network's own campaign id. It is the opposite of create_campaign_link.campaign_id and is the most common mistake here: read it from list_campaigns. The API rejects a network id by name. Preferred snake_case spelling."),
   campaignId: z4.string().optional().describe("Accepted camelCase alias for campaign_id."),
-  adset_id: z4.string().optional().nullable(),
+  adset_id: z4.string().optional().nullable().describe("Ad set id. Must be sent together with ad_id; either one alone is rejected."),
   adsetId: z4.string().optional().nullable(),
   ad_id: z4.string().optional().nullable(),
   adId: z4.string().optional().nullable(),
@@ -14158,16 +14165,19 @@ function createServer(config, fetchImpl) {
   const server = new McpServer({ name: "attrkit", version: SERVER_VERSION });
   const call = (path, options) => callApi(config, path, { fetchImpl, ...options });
   server.registerTool("whoami", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     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("get_usage_cap", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     title: "Get the workspace usage cap",
     description: "Return the workspace's monthly qualified-install cap, alert email, current billing period and usage. Requires a workspace-scoped read key.",
     inputSchema: {}
   }, async () => toToolResult(await call("/api/v1/workspace/usage-cap")));
   server.registerTool("set_usage_cap", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     title: "Set the workspace usage cap",
     description: "Set a monthly qualified-install cap of at least 10,000 and its alert email. Pass null for both values to clear the cap. Requires a workspace-scoped write key.",
     inputSchema: {
@@ -14199,11 +14209,13 @@ function createServer(config, fetchImpl) {
     }));
   });
   server.registerTool("list_apps", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     title: "List apps",
     description: "List the iOS and Android apps in your AttrKit workspace (id, name, platform, bundle id, store id, status).",
     inputSchema: {}
   }, async () => toToolResult(await call("/api/v1/apps")));
   server.registerTool("create_app", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     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: {
@@ -14236,11 +14248,13 @@ function createServer(config, fetchImpl) {
     }
   })));
   server.registerTool("get_app", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     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", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     title: "Update an app",
     description: "Update app metadata, store destination, timezone or device-matching mode.",
     inputSchema: {
@@ -14275,6 +14289,7 @@ function createServer(config, fetchImpl) {
     }
   })));
   server.registerTool("archive_app", {
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     title: "Archive an app",
     description: "Archive an app and remove it from active customer operations.",
     inputSchema: { app_id: requiredAppIdSchema }
@@ -14282,11 +14297,13 @@ function createServer(config, fetchImpl) {
     method: "DELETE"
   })));
   server.registerTool("get_publishable_key", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     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", {
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     title: "Rotate an app publishable key",
     description: "Issue a new SDK publishable key and return the old-key grace deadline.",
     inputSchema: {
@@ -14295,11 +14312,13 @@ function createServer(config, fetchImpl) {
     }
   }, 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", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     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", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     title: "Create a management key",
     description: "Create a read-only or read/write workspace or app key. The secret is returned once.",
     inputSchema: {
@@ -14314,6 +14333,7 @@ function createServer(config, fetchImpl) {
     body: { label, scopes, app_id: app_id ?? null }
   })));
   server.registerTool("revoke_api_key", {
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     title: "Revoke a management key",
     description: "Immediately revoke a management key by id.",
     inputSchema: { key_id: z4.string().uuid() }
@@ -14321,6 +14341,7 @@ function createServer(config, fetchImpl) {
     method: "DELETE"
   })));
   server.registerTool("list_links", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     title: "List campaign links",
     description: "List tracking links, optionally for one app.",
     inputSchema: {
@@ -14336,11 +14357,13 @@ function createServer(config, fetchImpl) {
     }
   })));
   server.registerTool("list_campaigns", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     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", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     title: "List creative-level ad performance",
     description: "Return ad and ad-set performance, evidence tiers, ROAS, CPA, CPC and modeled remainders.",
     inputSchema: {
@@ -14356,6 +14379,7 @@ function createServer(config, fetchImpl) {
     }
   })));
   server.registerTool("list_recent_events", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     title: "List recent events and installs",
     description: "Return the same recent attribution events and installs visible on the Live dashboard.",
     inputSchema: {
@@ -14369,33 +14393,35 @@ function createServer(config, fetchImpl) {
     }
   })));
   server.registerTool("get_campaign_decision", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     title: "Get campaign decisions (scale / cut / hold)",
     description: "Return AttrKit'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", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     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: z4.string(),
-      call: z4.enum(["scale", "cut", "hold"]),
-      actor: z4.enum(["dashboard", "auto_suggested"]).optional(),
-      p05: z4.number(),
-      p50: z4.number(),
-      p95: z4.number(),
-      spend_minor_units: z4.number().nonnegative(),
-      currency: z4.string().length(3),
-      band_width_pct: z4.number().nonnegative(),
-      threshold: z4.number(),
-      model_version: z4.string(),
-      cost_model_version: z4.number().int().positive().nullable(),
-      revenue_per_install_minor_units: z4.number().nonnegative().nullable(),
+      campaign_id: z4.string().describe("The AttrKit campaign uuid, as returned by list_campaigns or get_campaign_decision. Not the ad network's own campaign id."),
+      call: z4.enum(["scale", "cut", "hold"]).describe("The decision being frozen. Report get_campaign_decision's own call verbatim rather than forming your own."),
+      actor: z4.enum(["dashboard", "auto_suggested"]).optional().describe("Who made the call. Use auto_suggested when an agent proposed it without a human confirming."),
+      p05: z4.number().describe("Low end of the profit range from get_campaign_decision, in minor units. Pass through unchanged."),
+      p50: z4.number().describe("Central profit estimate from get_campaign_decision, in minor units. Pass through unchanged."),
+      p95: z4.number().describe("High end of the profit range from get_campaign_decision, in minor units. Pass through unchanged."),
+      spend_minor_units: z4.number().nonnegative().describe("Spend the decision was taken against, in minor units of `currency`."),
+      currency: z4.string().length(3).describe("ISO 4217 code for spend and revenue on this decision, e.g. USD. Three letters."),
+      band_width_pct: z4.number().nonnegative().describe("Width of the profit band as a percentage, from get_campaign_decision. It is how the maturity check later judges whether the range was tight enough to act on."),
+      threshold: z4.number().describe("The profit threshold the call was made against, in minor units."),
+      model_version: z4.string().describe("Model version string from get_campaign_decision. Recorded so a later evaluation knows which model produced the range."),
+      cost_model_version: z4.number().int().positive().nullable().describe("Cost model version from get_campaign_decision, or null when no cost model applied."),
+      revenue_per_install_minor_units: z4.number().nonnegative().nullable().describe("Revenue per install used in the estimate, in minor units, or null when revenue was unavailable."),
       revenue_per_install_quality: z4.enum([
         "campaign_verified_cohort",
         "app_verified_cohort_fallback",
         "unavailable"
-      ]),
+      ]).describe("How that revenue figure was derived: from this campaign's own verified cohort, from the app-wide fallback, or not at all. Pass through from get_campaign_decision."),
       idempotency_key: idempotencyKeySchema
     }
   }, async ({
@@ -14439,11 +14465,13 @@ function createServer(config, fetchImpl) {
     }
   })));
   server.registerTool("get_attribution_rollup", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     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", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     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: {
@@ -14451,10 +14479,11 @@ function createServer(config, fetchImpl) {
       network: z4.enum(["meta", "google", "tiktok"]).describe("The ad network delivering the campaign."),
       destination_url: z4.string().url().describe("The App Store URL to send users to."),
       campaign_name: z4.string().max(120).optional().describe("Optional human-readable campaign name."),
-      campaign_id: z4.string().optional().describe("Optional external campaign id."),
+      campaign_id: z4.string().optional().describe("Optional external campaign id. This is the AD NETWORK's own campaign id, not an AttrKit uuid; it is the opposite of import_spend.campaign_id, which requires the AttrKit one."),
+      serve_landing: z4.boolean().optional().describe("Serve the interstitial landing bridge on this link. Defaults to true at the API. The bridge is what captures browser-side context for device matching, so turning it off narrows what can be matched."),
       idempotency_key: idempotencyKeySchema
     }
-  }, async ({ app_id, network, destination_url, campaign_name, campaign_id, idempotency_key }) => toToolResult(await call("/api/v1/links", {
+  }, async ({ app_id, network, destination_url, campaign_name, campaign_id, serve_landing, idempotency_key }) => toToolResult(await call("/api/v1/links", {
     method: "POST",
     idempotencyKey: idempotency_key,
     body: {
@@ -14462,10 +14491,12 @@ function createServer(config, fetchImpl) {
       network,
       destinationUrl: destination_url,
       ...campaign_name ? { campaignName: campaign_name } : {},
-      ...campaign_id ? { campaignId: campaign_id } : {}
+      ...campaign_id ? { campaignId: campaign_id } : {},
+      ...serve_landing === undefined ? {} : { serveLanding: serve_landing }
     }
   })));
   server.registerTool("update_link_status", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     title: "Enable or disable a campaign link",
     description: "Change a tracking link between active and disabled.",
     inputSchema: {
@@ -14475,6 +14506,7 @@ function createServer(config, fetchImpl) {
     }
   }, 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", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     title: "Get spend and cost models",
     description: "Return imported ad spend, cost models, completeness and spend freshness.",
     inputSchema: { app_id: appIdSchema }
@@ -14482,6 +14514,7 @@ function createServer(config, fetchImpl) {
     query: { appId: app_id }
   })));
   server.registerTool("import_spend", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     title: "Import ad spend",
     description: "Import campaign or creative-level spend rows.",
     inputSchema: {
@@ -14530,6 +14563,7 @@ function createServer(config, fetchImpl) {
     }
   })));
   server.registerTool("set_cost_model", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     title: "Set an app cost model",
     description: "Version commission, payment fees and variable COGS used in profit decisions.",
     inputSchema: {
@@ -14565,6 +14599,7 @@ function createServer(config, fetchImpl) {
     }
   })));
   server.registerTool("pull_network_spend", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     title: "Pull spend from an ad network",
     description: "Fetch and import creative-level spend from a configured Meta, Google or TikTok connection.",
     inputSchema: {
@@ -14588,18 +14623,20 @@ function createServer(config, fetchImpl) {
     }
   })));
   server.registerTool("list_integrations", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     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", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     title: "Create an ad-network integration",
     description: "Store encrypted network credentials and configure event ownership.",
     inputSchema: {
       network: z4.enum(["meta", "google", "tiktok"]),
       account_ref: z4.string().min(1),
       credential: z4.string().min(1),
-      owners: ownersSchema,
+      owners: ownersSchema.describe("Which destination owns each event family. Enabling a destination requires ALL eight families to be present, or the API rejects the call."),
       enable: z4.boolean().optional(),
       idempotency_key: idempotencyKeySchema
     }
@@ -14609,6 +14646,7 @@ function createServer(config, fetchImpl) {
     body: { network, account_ref, credential, owners, enable: enable ?? false }
   })));
   server.registerTool("update_integration", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     title: "Update an ad-network integration",
     description: "Rotate credentials or enable/disable an integration.",
     inputSchema: {
@@ -14628,21 +14666,24 @@ function createServer(config, fetchImpl) {
     }
   })));
   server.registerTool("delete_integration", {
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     title: "Delete an ad-network integration",
     description: "Delete a disabled integration. Enabled integrations must be disabled first.",
     inputSchema: { connection_id: z4.string() }
   }, async ({ connection_id }) => toToolResult(await call(`/api/v1/integrations/${encodeURIComponent(connection_id)}`, { method: "DELETE" })));
   server.registerTool("get_revenuecat", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     title: "Get RevenueCat configuration",
     description: "Return redacted RevenueCat status and the AttrKit webhook URL.",
     inputSchema: { app_id: requiredAppIdSchema }
   }, async ({ app_id }) => toToolResult(await call(`/api/v1/apps/${encodeURIComponent(app_id)}/revenuecat`)));
   server.registerTool("configure_revenuecat", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     title: "Configure RevenueCat",
     description: "Store the RevenueCat provider app id and encrypted authorization secret for an app.",
     inputSchema: {
       app_id: requiredAppIdSchema,
-      provider_app_id: revenueCatProviderAppIdSchema,
+      provider_app_id: revenueCatProviderAppIdSchema.describe("RevenueCat's PROJECT app id from their dashboard app settings, not the SDK key."),
       authorization_secret: z4.string().min(16).max(1024),
       idempotency_key: idempotencyKeySchema
     }
@@ -14652,11 +14693,13 @@ function createServer(config, fetchImpl) {
     body: { provider_app_id, authorization_secret }
   })));
   server.registerTool("list_webhooks", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     title: "List outbound webhooks",
     description: "List redacted outbound webhook subscriptions.",
     inputSchema: {}
   }, async () => toToolResult(await call("/api/v1/webhooks")));
   server.registerTool("create_webhook", {
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     title: "Create an outbound webhook",
     description: "Create an SSRF-checked webhook subscription. Returns the signing secret once.",
     inputSchema: {
@@ -14677,11 +14720,13 @@ function createServer(config, fetchImpl) {
     }
   })));
   server.registerTool("delete_webhook", {
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     title: "Delete an outbound webhook",
     description: "Delete a webhook subscription.",
     inputSchema: { subscription_id: z4.string().uuid() }
   }, async ({ subscription_id }) => toToolResult(await call(`/api/v1/webhooks/${encodeURIComponent(subscription_id)}`, { method: "DELETE" })));
   server.registerTool("export_events", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     title: "Export events and installs",
     description: "Export one app's events and installs as CSV for an inclusive date range.",
     inputSchema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attrkit/mcp",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "AttrKit's stdio MCP server for its public Management API",
   "keywords": [
     "attrkit",