@fil-technology/appmate-mcp 0.3.0 → 0.5.0

package/README.md

@@ -68,6 +68,28 @@ staging or self-hosted instances.
 | `publish_waitlist_flow` | Promote the waitlist draft live. |
 | `list_waitlist_signups` | Paginated list (cursor + nextCursor). |
 | `export_waitlist_csv` | Return the full waitlist as a CSV string. |
+| `get_feedback_flow` | Read published + draft feedback config. |
+| `update_feedback_draft` | Replace the feedback draft. |
+| `publish_feedback_flow` | Promote the feedback draft live. |
+| `list_feedback_submissions` | Paginated list of feedback rows (rating + message + email). |
+| `get_report_flow` | Read published + draft report config. |
+| `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, referee, reward flags). |
+| `export_referrals_csv` | Return the full referral graph as a CSV string. |
 
 Tools that accept an app reference (`get_app`, `update_cancel_draft`,
 etc.) accept either the cuid `id` or the human-readable `slug` — use
@@ -83,6 +105,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 = {
@@ -125,27 +153,52 @@ export const updateWaitlistDraft = {
     description: [
         "Replace the draft waitlist config. Body MUST be a full waitlist config object (type: 'waitlist').",
         "",
-        "Required shape:",
+        "The public URL at signup.appmate.cloud/{slug} renders a FULL landing",
+        "page — not just a form. The `hero` block drives the visual treatment;",
+        "omit it for the minimal/legacy look.",
+        "",
+        "Full shape:",
         "  {",
         "    type: 'waitlist',",
         "    intro: {",
-        "      title, subtitle,",
-        "      emailPlaceholder, submitLabel,",
-        "      legal? (small print, optional)",
+        "      title,            // h1 on the landing",
+        "      subtitle,         // lede paragraph",
+        "      emailPlaceholder, // input placeholder, e.g. 'you@example.com'",
+        "      submitLabel,      // button text, e.g. 'Notify me'",
+        "      legal?            // small print under the form (optional)",
         "    },",
         "    success: {",
-        "      title, body,",
-        "      ctaLabel?, ctaUrl?    // both-or-neither: ctaLabel without ctaUrl renders nothing",
-        "    }",
+        "      title, body,      // shown after signup",
+        "      ctaLabel?, ctaUrl?   // both-or-neither — partial pair renders nothing",
+        "    },",
+        "    hero?: {              // ALL fields optional; omit `hero` entirely for minimal",
+        "      theme?: 'minimal' | 'gradient' | 'dark' | 'side_by_side',",
+        "      eyebrow?: string,   // short chip above title, e.g. 'Coming soon · Q1 2026'",
+        "      accentColor?: string, // hex '#rrggbb'; tints button + chip + gradient blob",
+        "      bullets?: [           // 0–5 value-prop cards under the form",
+        "        { icon?: '✨', title: 'Fast', body?: 'Sub-second responses' }",
+        "      ],",
+        "      showCount?: boolean,  // renders '{N} on the waitlist' pill (hides if <3 signups)",
+        "      heroImage?: string,   // optional URL of a hero image",
+        "    },",
+        "    templateId?: string     // analytics tag if seeded from a template",
         "  }",
         "",
+        "Theme picker guide — pick from intent:",
+        "  - minimal       → no brand, conservative B2B. Default.",
+        "  - gradient      → marketing-launch energy. Pastel blobs + accent color.",
+        "  - dark          → premium / product-reveal vibe. Dark hero + accent glow.",
+        "  - side_by_side  → desktop-first 2-column (story left, form right).",
+        "                    Collapses to minimal on phone — fine for landing-pageiness.",
+        "",
+        "Starter templates available (see /examples?kind=waitlist):",
+        "  minimal_email_only, feature_tease, launching_soon, pro_upsell,",
+        "  private_beta, early_access_referral.",
+        "",
         "Server returns { ok:true, warnings: [...] } — check warnings before publishing.",
-        "Common: partial_cta (label without url, or vice versa).",
+        "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 = {
@@ -182,17 +235,399 @@ export const exportWaitlistCsv = {
         return { csv };
     },
 };
+// ─── Feedback flow ──────────────────────────────────────────────────────────
+export const getFeedbackFlow = {
+    name: "get_feedback_flow",
+    description: "Read the published and draft feedback flow configs for an app. Feedback flows host an open-ended message form (optional 1–5 star rating + optional reply email) at appmate.cloud/feedback/{appSlug}.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/feedback`),
+};
+export const updateFeedbackDraft = {
+    name: "update_feedback_draft",
+    description: [
+        "Replace the draft feedback config. Body MUST be a full feedback config object (type: 'feedback').",
+        "",
+        "Shape:",
+        "  {",
+        "    type: 'feedback',",
+        "    intro: {",
+        "      title, subtitle,",
+        "      messagePlaceholder,           // textarea placeholder",
+        "      submitLabel,",
+        "      legal?                        // small print under the form (optional)",
+        "    },",
+        "    rating?: {                      // OPTIONAL 1–5 star widget",
+        "      enabled: true,",
+        "      prompt?: 'How would you rate your experience?',",
+        "      required?: false              // when true, blocks submit until picked",
+        "    },",
+        "    emailField?: {                  // OPTIONAL reply-to email field",
+        "      enabled: true,",
+        "      placeholder?: 'you@example.com (optional)',",
+        "      required?: false",
+        "    },",
+        "    success: {",
+        "      title, body,",
+        "      ctaLabel?, ctaUrl?            // both-or-neither follow-up CTA",
+        "    },",
+        "    hero?: {                        // visual treatment, matches waitlist hero",
+        "      theme?: 'minimal' | 'gradient' | 'dark' | 'side_by_side',",
+        "      eyebrow?, accentColor?, titleFont?",
+        "    }",
+        "  }",
+        "",
+        "Server returns { ok:true, warnings: [] }. Warning rules will be added later — for now treat any non-empty array as advisory.",
+    ].join("\n"),
+    inputSchema: updateDraftInput,
+    handler: (input, cfg) => apiFetch(cfg, "PUT", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/feedback`, input.config),
+};
+export const publishFeedbackFlow = {
+    name: "publish_feedback_flow",
+    description: "Promote the draft feedback config to the live published version. Visitors at appmate.cloud/feedback/{appSlug} see the new version immediately.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "POST", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/feedback/publish`),
+};
+export const listFeedbackSubmissions = {
+    name: "list_feedback_submissions",
+    description: "Paginated list of feedback submissions for an app. Each row: { id, message, rating, email, source, createdAt }. 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)}/feedback/submissions${tail}`);
+    },
+};
+// ─── Report flow ────────────────────────────────────────────────────────────
+export const getReportFlow = {
+    name: "get_report_flow",
+    description: "Read the published and draft report flow configs for an app. Report flows host a categorised bug/abuse/spam form (required category picker + message + optional reply email) at appmate.cloud/report/{appSlug}.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/report`),
+};
+export const updateReportDraft = {
+    name: "update_report_draft",
+    description: [
+        "Replace the draft report config. Body MUST be a full report config object (type: 'report').",
+        "",
+        "Shape:",
+        "  {",
+        "    type: 'report',",
+        "    intro: {",
+        "      title, subtitle,",
+        "      messagePlaceholder,           // textarea placeholder",
+        "      submitLabel,",
+        "      legal?                        // optional small print",
+        "    },",
+        "    categories: [                   // REQUIRED 1–10 entries",
+        "      { id: 'bug',   label: 'Bug or crash',       emoji?: '🐞', hint?: '…' },",
+        "      { id: 'abuse', label: 'Harassment or abuse', emoji?: '🚫' },",
+        "      { id: 'spam',  label: 'Spam',                emoji?: '🧹' },",
+        "      { id: 'privacy', label: 'Privacy concern',   emoji?: '🔒' },",
+        "      { id: 'other', label: 'Something else',      emoji?: '💬' }",
+        "    ],",
+        "    emailField?: { enabled, placeholder?, required? },",
+        "    success: { title, body, ctaLabel?, ctaUrl? },",
+        "    hero?: { theme?, eyebrow?, accentColor?, titleFont? }",
+        "  }",
+        "",
+        "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: updateDraftInput,
+    handler: (input, cfg) => apiFetch(cfg, "PUT", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/report`, input.config),
+};
+export const publishReportFlow = {
+    name: "publish_report_flow",
+    description: "Promote the draft report config to the live published version. Visitors at appmate.cloud/report/{appSlug} see the new version immediately.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "POST", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/report/publish`),
+};
+export const listReportSubmissions = {
+    name: "list_report_submissions",
+    description: "Paginated list of report submissions for an app. Each row: { id, message, category, email, source, createdAt }. Pass `category` to scope to one bucket (e.g. 'bug') for triage.",
+    inputSchema: z.object({
+        appIdOrSlug: z.string().min(1),
+        limit: z.number().int().min(1).max(200).optional(),
+        cursor: z.string().optional(),
+        category: 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);
+        if (input.category)
+            qs.set("category", input.category);
+        const tail = qs.toString() ? `?${qs.toString()}` : "";
+        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',",
+        "    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",
+        "      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.3.0",
+  "version": "0.5.0",
   "description": "Model Context Protocol server for AppMate — lets Claude / Cursor / Codex drive your retention flows via API tokens.",
   "type": "module",
   "bin": {