@fil-technology/appmate-mcp 0.4.0 → 0.5.1

package/README.md

@@ -76,6 +76,24 @@ staging or self-hosted instances.
 | `update_report_draft` | Replace the report draft (categorised). |
 | `publish_report_flow` | Promote the report draft live. |
 | `list_report_submissions` | Paginated, optional `category` filter. |
+| `get_contact_flow` | Read published + draft contact config. |
+| `update_contact_draft` | Replace the contact draft. |
+| `publish_contact_flow` | Promote the contact draft live. |
+| `list_contact_submissions` | Paginated list of contact rows (name + email + message). |
+| `get_onboarding_flow` | Read published + draft onboarding (web-to-app funnel) config. |
+| `update_onboarding_draft` | Replace the onboarding draft (quiz / info / email-capture steps + handoff). |
+| `publish_onboarding_flow` | Promote the onboarding draft live. |
+| `list_onboarding_submissions` | Paginated list of funnel completions (answers + email + claim status). |
+| `export_onboarding_csv` | Return all onboarding completions as a CSV string. |
+| `get_referral_flow` | Read published + draft referral program config. |
+| `update_referral_draft` | Replace the referral draft (rewards, share text, cap, landing). |
+| `publish_referral_flow` | Promote the referral draft live. |
+| `list_referrals` | Paginated referral graph (status, `source` [link or typed-code], referee, reward flags). |
+| `export_referrals_csv` | Return the full referral graph as a CSV string. |
+
+Each referrer gets a unique link **and** a short, human-readable code (e.g.
+`K7Q4-R9XP`); a friend redeems by tapping the link or **typing the code** (no
+clipboard needed). `source` on each referral row records which path was used.
 
 Tools that accept an app reference (`get_app`, `update_cancel_draft`,
 etc.) accept either the cuid `id` or the human-readable `slug` — use
@@ -91,6 +109,10 @@ whichever you have. The full REST shape is documented at
 > *"Export the waitlist for `appmate-pro` as CSV and save it to
 > `~/Downloads/waitlist.csv`."*
 
+> *"Build a 3-question onboarding funnel for `ledgr` that asks the user's
+> goal, captures their email, and hands off to the App Store, then publish
+> it."*
+
 > *"Compare the published and draft cancel configs for `quakemate` and
 > tell me what changed."*
 

package/dist/index.js

@@ -124,6 +124,18 @@ function zodToJsonSchema(schema) {
     if (schema instanceof z.ZodBoolean) {
         return { type: "boolean" };
     }
+    // z.preprocess / z.transform wrap the real schema in ZodEffects — emit the
+    // inner schema's shape so e.g. a preprocessed record still advertises
+    // `type: object` to the host.
+    if (schema instanceof z.ZodEffects) {
+        return zodToJsonSchema(schema._def.schema);
+    }
+    // A record (open-ended object, e.g. a flow `config`) MUST advertise
+    // `type: object` — otherwise hosts may serialize the value to a JSON string
+    // and the server rejects it ("expected object, received string").
+    if (schema instanceof z.ZodRecord) {
+        return { type: "object", additionalProperties: true };
+    }
     if (schema instanceof z.ZodUnknown || schema instanceof z.ZodAny) {
         return {};
     }

package/dist/tools.js

@@ -1,5 +1,35 @@
 import { z } from "zod";
 import { apiFetch, apiFetchText } from "./api-client.js";
+// `config` for the update_*_draft tools is a full flow-config OBJECT. We
+// must advertise it as `type: object` in the JSON schema (see zodToJsonSchema
+// in index.ts) — otherwise an untyped field leads some MCP hosts to serialize
+// it to a JSON string, which the server then rejects with
+// `422: expected object, received string`.
+//
+// Belt-and-braces: we ALSO accept a JSON string and parse it here (via
+// z.preprocess), since a few hosts stringify nested args regardless. Either
+// way the server receives a real object, never `"{...}"`.
+function parseJsonStringConfig(v) {
+    if (typeof v === "string") {
+        const trimmed = v.trim();
+        if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+            try {
+                return JSON.parse(trimmed);
+            }
+            catch {
+                // Not valid JSON — leave it; record validation reports a clear error.
+            }
+        }
+    }
+    return v;
+}
+// Shared input for every update_*_draft tool: an app reference + the full
+// config object. The inner record makes `config` advertise `type: object`;
+// the preprocess tolerates a stringified body.
+const updateDraftInput = z.object({
+    appIdOrSlug: z.string().min(1),
+    config: z.preprocess(parseJsonStringConfig, z.record(z.string(), z.unknown())),
+});
 // ─── Apps ───────────────────────────────────────────────────────────────────
 export const listApps = {
     name: "list_apps",
@@ -46,10 +76,11 @@ export const getCancelFlow = {
     inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
     handler: (input, cfg) => apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/cancel`),
 };
-// Config body is `z.unknown()` so we hand the raw JSON to the server,
-// which has the canonical Zod schema. The server returns 422 with paths
-// on validation errors AND a `warnings` array on success for soft
-// mismatches (e.g. showThanksScreen + a "Contact support" label).
+// `config` is the full flow-config object (advertised as type:object via
+// updateDraftInput so hosts pass structured JSON). The server holds the
+// canonical Zod schema: it returns 422 with paths on validation errors AND a
+// `warnings` array on success for soft mismatches (e.g. showThanksScreen + a
+// "Contact support" label).
 export const updateCancelDraft = {
     name: "update_cancel_draft",
     description: [
@@ -101,10 +132,7 @@ export const updateCancelDraft = {
         "",
         "See https://docs.appmate.cloud/ai-agents for the full do/don't guide and examples.",
     ].join("\n"),
-    inputSchema: z.object({
-        appIdOrSlug: z.string().min(1),
-        config: z.unknown(),
-    }),
+    inputSchema: updateDraftInput,
     handler: (input, cfg) => apiFetch(cfg, "PUT", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/cancel`, input.config),
 };
 export const publishCancelFlow = {
@@ -170,10 +198,7 @@ export const updateWaitlistDraft = {
         "Server returns { ok:true, warnings: [...] } — check warnings before publishing.",
         "Common warnings: partial_cta (label without url, or vice versa).",
     ].join("\n"),
-    inputSchema: z.object({
-        appIdOrSlug: z.string().min(1),
-        config: z.unknown(),
-    }),
+    inputSchema: updateDraftInput,
     handler: (input, cfg) => apiFetch(cfg, "PUT", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/waitlist`, input.config),
 };
 export const publishWaitlistFlow = {
@@ -225,6 +250,7 @@ export const updateFeedbackDraft = {
         "Shape:",
         "  {",
         "    type: 'feedback',",
+        "    layout: 'steps' | 'single',  // optional, default 'steps' (multi-step: rating+message, then email). 'single' = one screen.",
         "    intro: {",
         "      title, subtitle,",
         "      messagePlaceholder,           // textarea placeholder",
@@ -253,10 +279,7 @@ export const updateFeedbackDraft = {
         "",
         "Server returns { ok:true, warnings: [] }. Warning rules will be added later — for now treat any non-empty array as advisory.",
     ].join("\n"),
-    inputSchema: z.object({
-        appIdOrSlug: z.string().min(1),
-        config: z.unknown(),
-    }),
+    inputSchema: updateDraftInput,
     handler: (input, cfg) => apiFetch(cfg, "PUT", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/feedback`, input.config),
 };
 export const publishFeedbackFlow = {
@@ -298,6 +321,7 @@ export const updateReportDraft = {
         "Shape:",
         "  {",
         "    type: 'report',",
+        "    layout: 'steps' | 'single',  // optional, default 'steps' (multi-step: category, then message+email). 'single' = one screen.",
         "    intro: {",
         "      title, subtitle,",
         "      messagePlaceholder,           // textarea placeholder",
@@ -318,10 +342,7 @@ export const updateReportDraft = {
         "",
         "Category ids must be snake_case ([a-z][a-z0-9_]*). The public submit endpoint validates posted category against this list — unknown ids return 422.",
     ].join("\n"),
-    inputSchema: z.object({
-        appIdOrSlug: z.string().min(1),
-        config: z.unknown(),
-    }),
+    inputSchema: updateDraftInput,
     handler: (input, cfg) => apiFetch(cfg, "PUT", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/report`, input.config),
 };
 export const publishReportFlow = {
@@ -351,25 +372,266 @@ export const listReportSubmissions = {
         return apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/report/submissions${tail}`);
     },
 };
+// ─── Contact flow ───────────────────────────────────────────────────────────
+export const getContactFlow = {
+    name: "get_contact_flow",
+    description: "Read the published and draft contact flow configs for an app. Contact flows host a minimal inquiry form (optional name + required/optional email + optional message text) at appmate.cloud/contact/{appSlug}.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/contact`),
+};
+export const updateContactDraft = {
+    name: "update_contact_draft",
+    description: [
+        "Replace the draft contact config. Body MUST be a full contact config object (type: 'contact').",
+        "",
+        "Shape:",
+        "  {",
+        "    type: 'contact',",
+        "    layout: 'steps' | 'single',  // optional, default 'steps' (multi-step: message, then name+email). 'single' = one screen.",
+        "    intro: {",
+        "      title, subtitle,",
+        "      submitLabel,",
+        "      legal?                        // optional small print under the form",
+        "    },",
+        "    nameField?: {                   // OPTIONAL name widget",
+        "      enabled: boolean,",
+        "      placeholder?: 'Your name',",
+        "      required?: boolean",
+        "    },",
+        "    emailField?: {                  // OPTIONAL/REQUIRED email input",
+        "      enabled: boolean,",
+        "      placeholder?: 'you@example.com',",
+        "      required?: boolean",
+        "    },",
+        "    messageField?: {                // OPTIONAL message textarea",
+        "      enabled: boolean,",
+        "      placeholder?: 'What is on your mind?',",
+        "      required?: boolean",
+        "    },",
+        "    success: {",
+        "      title, body,",
+        "      ctaLabel?, ctaUrl?            // optional follow-up button pair",
+        "    },",
+        "    hero?: {                        // dynamic landing theme config",
+        "      theme?: 'minimal' | 'gradient' | 'dark' | 'side_by_side',",
+        "      eyebrow?, accentColor?, titleFont?",
+        "    }",
+        "  }",
+    ].join("\n"),
+    inputSchema: updateDraftInput,
+    handler: (input, cfg) => apiFetch(cfg, "PUT", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/contact`, input.config),
+};
+export const publishContactFlow = {
+    name: "publish_contact_flow",
+    description: "Promote the draft contact config to the live published version. Visitors at appmate.cloud/contact/{appSlug} see the new version live immediately.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "POST", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/contact/publish`),
+};
+export const listContactSubmissions = {
+    name: "list_contact_submissions",
+    description: "Paginated list of contact submissions for an app. Each row: { id, name, email, message, source, country, createdAt }. limit max 200, default 50; pass nextCursor back for next page.",
+    inputSchema: z.object({
+        appIdOrSlug: z.string().min(1),
+        limit: z.number().int().min(1).max(200).optional(),
+        cursor: z.string().optional(),
+    }),
+    handler: (input, cfg) => {
+        const qs = new URLSearchParams();
+        if (input.limit !== undefined)
+            qs.set("limit", String(input.limit));
+        if (input.cursor)
+            qs.set("cursor", input.cursor);
+        const tail = qs.toString() ? `?${qs.toString()}` : "";
+        return apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/contact/submissions${tail}`);
+    },
+};
+// ─── Onboarding flow (web-to-app funnel) ─────────────────────────────────────
+export const getOnboardingFlow = {
+    name: "get_onboarding_flow",
+    description: "Read the published and draft onboarding flow configs for an app. Onboarding flows are web-to-app funnels (intro → quiz/info/email-capture steps → App Store handoff) hosted at appmate.cloud/onboarding/{appSlug}. Answers + email are captured server-side; the iOS SDK recovers them on first launch via a claim token.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/onboarding`),
+};
+export const updateOnboardingDraft = {
+    name: "update_onboarding_draft",
+    description: [
+        "Replace the draft onboarding config. Body MUST be a full onboarding config object (type: 'onboarding').",
+        "",
+        "Shape:",
+        "  {",
+        "    type: 'onboarding',",
+        "    intro: { title, subtitle, startLabel, eyebrow? },",
+        "    steps: [                          // REQUIRED 1–20, ordered",
+        "      // question step — pick one or several options",
+        "      {",
+        "        kind: 'question', id: 'goal',",
+        "        prompt: 'What brings you here?', subtitle?: '…',",
+        "        selectMode?: 'single' | 'multi',   // omit → single",
+        "        autoAdvance?: true,                // single only: tap advances",
+        "        required?: true,",
+        "        options: [ { id: 'save_time', label: 'Save time', emoji?: '⚡' } ]",
+        "      },",
+        "      // info step — copy/image screen, no input",
+        "      { kind: 'info', id: 'value', title: '…', body: '…', imageUrl?, continueLabel? },",
+        "      // email_capture step — the lead-capture moment",
+        "      {",
+        "        kind: 'email_capture', id: 'email',",
+        "        title: '…', subtitle?, placeholder?, submitLabel?,",
+        "        required?: true,                 // omit → required",
+        "        legal?: '…'",
+        "      }",
+        "    ],",
+        "    handoff: {",
+        "      title, body, ctaLabel,",
+        "      appStoreUrl?,                     // App Store / TestFlight URL; omit → no button",
+        "      legal?",
+        "    },",
+        "    hero?: { theme?, eyebrow?, accentColor?, titleFont? }",
+        "  }",
+        "",
+        "Step + option ids must be snake_case ([a-z][a-z0-9_]*) and unique. The server returns { ok:true, warnings:[...] } — warnings flag a missing email_capture step, a handoff with no appStoreUrl, duplicate ids, etc. Treat warnings as advisory.",
+    ].join("\n"),
+    inputSchema: updateDraftInput,
+    handler: (input, cfg) => apiFetch(cfg, "PUT", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/onboarding`, input.config),
+};
+export const publishOnboardingFlow = {
+    name: "publish_onboarding_flow",
+    description: "Promote the draft onboarding config to the live published version. Visitors at appmate.cloud/onboarding/{appSlug} see the new funnel immediately.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "POST", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/onboarding/publish`),
+};
+export const listOnboardingSubmissions = {
+    name: "list_onboarding_submissions",
+    description: "Paginated list of completed onboarding funnels for an app. Each row: { id, answers, email, source, claimed, claimedAt, country, createdAt }. `claimed` is true once the install was matched back to the completion. limit max 200, default 50; pass nextCursor back for the next page.",
+    inputSchema: z.object({
+        appIdOrSlug: z.string().min(1),
+        limit: z.number().int().min(1).max(200).optional(),
+        cursor: z.string().optional(),
+    }),
+    handler: (input, cfg) => {
+        const qs = new URLSearchParams();
+        if (input.limit !== undefined)
+            qs.set("limit", String(input.limit));
+        if (input.cursor)
+            qs.set("cursor", input.cursor);
+        const tail = qs.toString() ? `?${qs.toString()}` : "";
+        return apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/onboarding/submissions${tail}`);
+    },
+};
+export const exportOnboardingCsv = {
+    name: "export_onboarding_csv",
+    description: "Return all completed onboarding funnels for an app as a CSV string (header row + one row per completion, with email + answers JSON + claim status). Useful for hand-off to a spreadsheet or mail merge.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: async (input, cfg) => {
+        const csv = await apiFetchText(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/onboarding/submissions.csv`);
+        return { csv };
+    },
+};
+// ─── Referral flow ───────────────────────────────────────────────────────────
+export const getReferralFlow = {
+    name: "get_referral_flow",
+    description: "Read the published and draft referral program config for an app. Referral is a share-with-a-friend loop: each user gets a link (appmate.cloud/r/{code}) AND a short human-readable code (e.g. K7Q4-R9XP); a friend who taps the link or types the code, then installs, triggers a reward for both sides. Codes + the referral graph live server-side; the iOS SDK mints links/codes, attributes installs on first launch (clipboard handoff) or via a typed code, and reports rewards owed.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/referral`),
+};
+export const updateReferralDraft = {
+    name: "update_referral_draft",
+    description: [
+        "Replace the draft referral config. Body MUST be a full referral config object (type: 'referral').",
+        "",
+        "Shape:",
+        "  {",
+        "    type: 'referral',",
+        "    landing: {                        // the invite page a friend sees at /r/{code}",
+        "      eyebrow?, title, subtitle, ctaLabel,",
+        "      appStoreUrl?,                    // REQUIRED before go-live — the install button target",
+        "      fallback?: 'app_store' | 'website',  // where a not-installed friend goes (default app_store; 'website' uses the app's websiteUrl)",
+        "      legal?",
+        "    },",
+        "    share: { messageTemplate },        // the referrer's share text; the link is appended automatically",
+        "    rewards: {",
+        "      referrerWeeks: 1,                // free weeks the referrer earns per installed friend (1–8)",
+        "      refereeEnabled: true,            // also reward the NEW user on install?",
+        "      refereeWeeks?: 1,                // required when refereeEnabled (1–8)",
+        "      referrerLabel?, refereeLabel?    // human copy shown on the landing + returned to the SDK",
+        "    },",
+        "    maxRewardsPerReferrer?: 10         // lifetime cap per referrer; 0/omit = unlimited (farming risk)",
+        "  }",
+        "",
+        "Reward trigger is the friend's INSTALL (attributed on first launch). The server returns { ok:true, warnings:[...] } — warnings flag a missing/placeholder appStoreUrl, refereeEnabled without refereeWeeks, and an absent cap. Treat warnings as advisory but fix them before publishing.",
+    ].join("\n"),
+    inputSchema: updateDraftInput,
+    handler: (input, cfg) => apiFetch(cfg, "PUT", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/referral`, input.config),
+};
+export const publishReferralFlow = {
+    name: "publish_referral_flow",
+    description: "Promote the draft referral config to the live published version. New share links + the invite landing use the new config immediately.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "POST", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/referral/publish`),
+};
+export const listReferrals = {
+    name: "list_referrals",
+    description: "Paginated list of referrals for an app. Each row: { id, code, referrerUserId, status, source, refereeUserId, attributedAt, referrerRewarded, refereeRewarded, country, createdAt }. status='attributed' means the friend installed; source is 'link' (tapped share link) or 'code' (typed the referrer's code). Optional `status` filter; limit max 200, default 50.",
+    inputSchema: z.object({
+        appIdOrSlug: z.string().min(1),
+        status: z.enum(["pending", "attributed", "expired"]).optional(),
+        limit: z.number().int().min(1).max(200).optional(),
+        cursor: z.string().optional(),
+    }),
+    handler: (input, cfg) => {
+        const qs = new URLSearchParams();
+        if (input.status)
+            qs.set("status", input.status);
+        if (input.limit !== undefined)
+            qs.set("limit", String(input.limit));
+        if (input.cursor)
+            qs.set("cursor", input.cursor);
+        const tail = qs.toString() ? `?${qs.toString()}` : "";
+        return apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/referrals${tail}`);
+    },
+};
+export const exportReferralsCsv = {
+    name: "export_referrals_csv",
+    description: "Return the full referral graph for an app as a CSV string (one row per invite, with code, status, source (link/typed-code), referee, and reward flags).",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: async (input, cfg) => {
+        const csv = await apiFetchText(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/referrals.csv`);
+        return { csv };
+    },
+};
 // Registered alphabetically so `list_tools` reads predictably.
 export const ALL_TOOLS = [
     createApp,
+    exportOnboardingCsv,
+    exportReferralsCsv,
     exportWaitlistCsv,
     getApp,
     getCancelFlow,
+    getContactFlow,
     getFeedbackFlow,
+    getOnboardingFlow,
+    getReferralFlow,
     getReportFlow,
     getWaitlistFlow,
     listApps,
+    listContactSubmissions,
     listFeedbackSubmissions,
+    listOnboardingSubmissions,
+    listReferrals,
     listReportSubmissions,
     listWaitlistSignups,
     publishCancelFlow,
+    publishContactFlow,
     publishFeedbackFlow,
+    publishOnboardingFlow,
+    publishReferralFlow,
     publishReportFlow,
     publishWaitlistFlow,
     updateCancelDraft,
+    updateContactDraft,
     updateFeedbackDraft,
+    updateOnboardingDraft,
+    updateReferralDraft,
     updateReportDraft,
     updateWaitlistDraft,
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fil-technology/appmate-mcp",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Model Context Protocol server for AppMate — lets Claude / Cursor / Codex drive your retention flows via API tokens.",
   "type": "module",
   "bin": {