@fil-technology/appmate-mcp 0.5.0 → 0.6.0

package/README.md

@@ -88,8 +88,15 @@ staging or self-hosted instances.
 | `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). |
+| `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. |
+| `get_link_page_flow` | Read published + draft link-page (link-in-bio) config. |
+| `update_link_page_draft` | Replace the link-page draft (header, icon links, link list, theme). |
+| `publish_link_page_flow` | Promote the link-page draft live (appmate.cloud/p/{appSlug}). |
+
+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

package/dist/tools.js

@@ -175,7 +175,7 @@ export const updateWaitlistDraft = {
         "      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",
+        "      bullets?: [           // 0–5 value-prop cards, stacked one per row under the form",
         "        { icon?: '✨', title: 'Fast', body?: 'Sub-second responses' }",
         "      ],",
         "      showCount?: boolean,  // renders '{N} on the waitlist' pill (hides if <3 signups)",
@@ -250,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",
@@ -320,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",
@@ -385,6 +387,7 @@ export const updateContactDraft = {
         "Shape:",
         "  {",
         "    type: 'contact',",
+        "    layout: 'steps' | 'single',  // optional, default 'steps' (multi-step: message, then name+email). 'single' = one screen.",
         "    intro: {",
         "      title, subtitle,",
         "      submitLabel,",
@@ -424,6 +427,46 @@ export const publishContactFlow = {
     inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
     handler: (input, cfg) => apiFetch(cfg, "POST", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/contact/publish`),
 };
+// ─── Link page (link-in-bio) ────────────────────────────────────────────────
+export const getLinkPageFlow = {
+    name: "get_link_page_flow",
+    description: "Read the published and draft link-page configs for an app. A link page is a shareable 'link-in-bio' page (app logo + title/description, a row of icon links, and a list of labeled links) at appmate.cloud/p/{appSlug} — drop it in an Instagram/TikTok bio.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/link-page`),
+};
+export const updateLinkPageDraft = {
+    name: "update_link_page_draft",
+    description: [
+        "Replace the draft link-page config. Body MUST be a full link_page config object (type: 'link_page').",
+        "",
+        "Shape:",
+        "  {",
+        "    type: 'link_page',",
+        "    header: { title, description? },     // logo comes from the app record",
+        "    iconLinks: [                         // top row of compact icon buttons (<=6)",
+        "      { icon: 'ri:instagram', label: 'Instagram', url: 'https://…' }   // icon = a brand 'ri:<key>' (instagram/tiktok/x/youtube/…), a lucide name (e.g. 'Globe'), or an emoji",
+        "    ],",
+        "    links: [                            // main list of labeled links (<=25)",
+        "      { label: 'Download on the App Store', sublabel?: 'iPhone & iPad', url: 'https://…' }",
+        "    ],",
+        "    legal?: string,                     // small print at the bottom",
+        "    hero?: {                            // visual treatment",
+        "      theme?: 'minimal' | 'gradient' | 'dark' | 'side_by_side',",
+        "      eyebrow?, accentColor?, titleFont?",
+        "    }",
+        "  }",
+        "",
+        "No submissions — a link page is a published, versioned page. Publish with publish_link_page_flow.",
+    ].join("\n"),
+    inputSchema: updateDraftInput,
+    handler: (input, cfg) => apiFetch(cfg, "PUT", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/link-page`, input.config),
+};
+export const publishLinkPageFlow = {
+    name: "publish_link_page_flow",
+    description: "Promote the draft link-page config to the live published version. Visitors at appmate.cloud/p/{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/link-page/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.",
@@ -542,6 +585,7 @@ export const updateReferralDraft = {
         "    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",
@@ -595,20 +639,188 @@ export const exportReferralsCsv = {
         return { csv };
     },
 };
+// ─── Wishlist flow (feature-request board) ──────────────────────────────────
+//
+// Unlike every other flow (write-only), the wishlist is an INTERACTIVE board:
+// ideas are read back, upvoted, commented on, and moderated. Beyond the usual
+// get/update/publish trio it exposes moderation tools (set status, delete idea,
+// reply, delete comment) — the first MUTATING admin tools in the set.
+export const getWishlistFlow = {
+    name: "get_wishlist_flow",
+    description: "Read the published and draft wishlist (feature-request board) configs for an app. The board lives at appmate.cloud/wishlist/{appSlug}; visitors submit ideas, upvote, and comment, and the owner moderates status.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/wishlist`),
+};
+export const updateWishlistDraft = {
+    name: "update_wishlist_draft",
+    description: [
+        "Replace the draft wishlist config. Body MUST be a full wishlist config object (type: 'wishlist').",
+        "",
+        "Shape:",
+        "  {",
+        "    type: 'wishlist',",
+        "    intro: { title, subtitle, submitLabel, legal? },",
+        "    identity?: {                     // who can participate + vote dedup",
+        "      mode: 'anonymous' | 'email',   // default 'anonymous' (dedup by cookie+IP)",
+        "      requireEmailToSubmit?, requireEmailToVote?, requireEmailToComment?  // email mode only",
+        "    },",
+        "    categories?: [                   // OPTIONAL tags (0–12)",
+        "      { id: 'feature', label: 'New feature', emoji?: '✨', hint?: '…' }",
+        "    ],",
+        "    statusLabels?: {                 // rename lifecycle stages on the board",
+        "      open?, planned?, in_progress?, done?, declined?",
+        "    },",
+        "    submitForm?: { titlePlaceholder?, bodyPlaceholder? },",
+        "    moderation?: { autoApprove?: false },  // false (default) = new ideas start pending/hidden",
+        "    success: { title, body, ctaLabel?, ctaUrl? },",
+        "    hero?: { theme?, eyebrow?, accentColor?, titleFont? }",
+        "  }",
+        "",
+        "Server returns { ok:true, warnings: [] }.",
+    ].join("\n"),
+    inputSchema: updateDraftInput,
+    handler: (input, cfg) => apiFetch(cfg, "PUT", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/wishlist`, input.config),
+};
+export const publishWishlistFlow = {
+    name: "publish_wishlist_flow",
+    description: "Promote the draft wishlist config to the live published version. Visitors at appmate.cloud/wishlist/{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/wishlist/publish`),
+};
+export const listWishlistIdeas = {
+    name: "list_wishlist_ideas",
+    description: "Paginated list of wishlist ideas for an app — ALL statuses (including pending review). Each row: { id, title, body, category, status, voteCount, commentCount, pinned, author, email, source, country, createdAt }. Optional status ('pending'|'open'|'planned'|'in_progress'|'done'|'declined') + category filters; sort 'votes' (default 'new'). limit max 200, default 50; pass nextCursor back for the next page.",
+    inputSchema: z.object({
+        appIdOrSlug: z.string().min(1),
+        status: z.string().optional(),
+        category: z.string().optional(),
+        sort: z.enum(["votes", "new"]).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.category)
+            qs.set("category", input.category);
+        if (input.sort)
+            qs.set("sort", input.sort);
+        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)}/wishlist/ideas${tail}`);
+    },
+};
+export const createWishlistIdea = {
+    name: "create_wishlist_idea",
+    description: "Seed an idea onto the board as the app owner (so it isn't empty for early visitors — they can then upvote/comment). Defaults to status 'open' (visible). Use a category id from the flow config when set.",
+    inputSchema: z.object({
+        appIdOrSlug: z.string().min(1),
+        title: z.string().min(1).max(120),
+        body: z.string().max(4000).optional(),
+        category: z.string().optional(),
+        status: z
+            .enum(["pending", "open", "planned", "in_progress", "done", "declined"])
+            .optional(),
+    }),
+    handler: (input, cfg) => apiFetch(cfg, "POST", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/wishlist/ideas`, {
+        title: input.title,
+        body: input.body,
+        category: input.category,
+        status: input.status,
+    }),
+};
+export const setWishlistIdeaStatus = {
+    name: "set_wishlist_idea_status",
+    description: "Moderate an idea: set its status and/or pin it. 'pending' hides it from the public board; 'open' approves it. Statuses: pending | open | planned | in_progress | done | declined.",
+    inputSchema: z.object({
+        appIdOrSlug: z.string().min(1),
+        ideaId: z.string().min(1),
+        status: z.enum(["pending", "open", "planned", "in_progress", "done", "declined"]),
+        pinned: z.boolean().optional(),
+    }),
+    handler: (input, cfg) => apiFetch(cfg, "PATCH", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/wishlist/ideas/${encodeURIComponent(input.ideaId)}`, { status: input.status, ...(input.pinned !== undefined ? { pinned: input.pinned } : {}) }),
+};
+export const deleteWishlistIdea = {
+    name: "delete_wishlist_idea",
+    description: "Permanently delete an idea AND all of its votes and comments. IRREVERSIBLE — there is no undo. Prefer set_wishlist_idea_status with 'declined' to reject an idea while keeping it (and the decision) visible.",
+    inputSchema: z.object({
+        appIdOrSlug: z.string().min(1),
+        ideaId: z.string().min(1),
+    }),
+    handler: (input, cfg) => apiFetch(cfg, "DELETE", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/wishlist/ideas/${encodeURIComponent(input.ideaId)}`),
+};
+export const listWishlistComments = {
+    name: "list_wishlist_comments",
+    description: "Paginated comments on an idea (oldest-first, excludes deleted). Each row: { id, body, author, isOwner, isOfficial, createdAt }. limit max 200, default 50; pass nextCursor back for more.",
+    inputSchema: z.object({
+        appIdOrSlug: z.string().min(1),
+        ideaId: 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)}/wishlist/ideas/${encodeURIComponent(input.ideaId)}/comments${tail}`);
+    },
+};
+export const postWishlistComment = {
+    name: "post_wishlist_comment",
+    description: "Post an OWNER reply on an idea (shown with a Team badge). Set official:true to mark it an authoritative response. Use this to answer or expand on a user's idea.",
+    inputSchema: z.object({
+        appIdOrSlug: z.string().min(1),
+        ideaId: z.string().min(1),
+        body: z.string().min(1).max(2000),
+        official: z.boolean().optional(),
+    }),
+    handler: (input, cfg) => apiFetch(cfg, "POST", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/wishlist/ideas/${encodeURIComponent(input.ideaId)}/comments`, { body: input.body, official: input.official ?? false }),
+};
+export const deleteWishlistComment = {
+    name: "delete_wishlist_comment",
+    description: "Soft-delete a comment (hidden from the public board, thread continuity preserved). Use for moderation.",
+    inputSchema: z.object({
+        appIdOrSlug: z.string().min(1),
+        commentId: z.string().min(1),
+    }),
+    handler: (input, cfg) => apiFetch(cfg, "DELETE", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/wishlist/comments/${encodeURIComponent(input.commentId)}`),
+};
+export const exportWishlistCsv = {
+    name: "export_wishlist_csv",
+    description: "Return all wishlist ideas for an app as a CSV string (one row per idea, every status: created_at, status, title, votes, comments, category, email, author, country, body).",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: async (input, cfg) => {
+        const csv = await apiFetchText(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/wishlist/ideas.csv`);
+        return { csv };
+    },
+};
 // Registered alphabetically so `list_tools` reads predictably.
 export const ALL_TOOLS = [
     createApp,
+    createWishlistIdea,
+    deleteWishlistComment,
+    deleteWishlistIdea,
     exportOnboardingCsv,
     exportReferralsCsv,
     exportWaitlistCsv,
+    exportWishlistCsv,
     getApp,
     getCancelFlow,
     getContactFlow,
     getFeedbackFlow,
+    getLinkPageFlow,
     getOnboardingFlow,
     getReferralFlow,
     getReportFlow,
     getWaitlistFlow,
+    getWishlistFlow,
     listApps,
     listContactSubmissions,
     listFeedbackSubmissions,
@@ -616,18 +828,26 @@ export const ALL_TOOLS = [
     listReferrals,
     listReportSubmissions,
     listWaitlistSignups,
+    listWishlistComments,
+    listWishlistIdeas,
+    postWishlistComment,
     publishCancelFlow,
     publishContactFlow,
     publishFeedbackFlow,
+    publishLinkPageFlow,
     publishOnboardingFlow,
     publishReferralFlow,
     publishReportFlow,
     publishWaitlistFlow,
+    publishWishlistFlow,
+    setWishlistIdeaStatus,
     updateCancelDraft,
     updateContactDraft,
     updateFeedbackDraft,
+    updateLinkPageDraft,
     updateOnboardingDraft,
     updateReferralDraft,
     updateReportDraft,
     updateWaitlistDraft,
+    updateWishlistDraft,
 ];

package/package.json

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