@attrkit/mcp 0.4.2 → 0.4.4

package/README.md

@@ -33,7 +33,7 @@ Install Node.js 18 or newer. The `npx -y @attrkit/mcp` command downloads and
 starts the server automatically, so no global install is required.
 
 Create the first workspace management key under
-[Dashboard → Settings → API keys](https://attrikit.io/en/dashboard/settings/api-keys).
+[Dashboard → Settings → API keys & MCP](https://attrikit.io/en/dashboard/settings/api-keys).
 This one-time bootstrap requires the dashboard.
 
 After that first key exists, a workspace-scoped read/write key can manage every

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,13 @@ 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 redact = (text) => text.replace(/\b(?:mk|pk|sk|rk)_[A-Za-z0-9_-]{8,}/g, "[redacted-key]").replace(/\b[Bb]earer\s+[A-Za-z0-9._-]{8,}/g, "Bearer [redacted]").replace(/\bAttriKit-(?:Management|Publishable)\s+\S+/g, "AttriKit-$1 [redacted]").replace(/([?&](?:token|secret|key|password|code|signature)=)[^&\s]+/gi, "$1[redacted]");
+    const excerpt = !envelope?.error?.message && result.rawBody ? ` — body: ${redact(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
     };
@@ -14083,7 +14091,8 @@ function toToolResult(result) {
   const isEmptySuccess = result.status === 204 && (result.rawBody === undefined || result.rawBody === "");
   const isJsonEnvelope = result.json !== null && typeof result.json === "object" && !Array.isArray(result.json) && Object.hasOwn(result.json, "data");
   const contentType = (result.contentType ?? "").toLowerCase();
-  const isExpectedText = expectedResponse === "text" && typeof result.json === "string" && (contentType.includes("text/csv") || contentType.includes("application/csv"));
+  const looksLikeMarkup = typeof result.json === "string" && /^\s*<(?:!doctype|html|head|body)\b/i.test(result.json);
+  const isExpectedText = expectedResponse === "text" && typeof result.json === "string" && !contentType.includes("text/html") && !looksLikeMarkup;
   if (!isEmptySuccess && !isJsonEnvelope && !isExpectedText) {
     const reportedContentType = result.contentType ?? "unknown content type";
     const received = result.json === null ? "an empty body" : Array.isArray(result.json) ? "a JSON array" : typeof result.json === "object" ? "a JSON object without a data field" : `a ${typeof result.json} body`;
@@ -14103,16 +14112,16 @@ ${body}`
     structuredContent: structured
   };
 }
-var SERVER_VERSION = "0.4.2";
+var SERVER_VERSION = "0.4.4";
 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(),
@@ -14397,24 +14406,24 @@ function createServer(config, fetchImpl) {
     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 ({
@@ -14629,7 +14638,7 @@ function createServer(config, fetchImpl) {
       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
     }
@@ -14676,7 +14685,7 @@ function createServer(config, fetchImpl) {
     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
     }

package/package.json

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