@fil-technology/appmate-mcp 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fil Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# appmate-mcp
+
+Model Context Protocol server for [AppMate](https://appmate.cloud) — lets
+Claude Desktop, Claude Code, Cursor, Codex, or any other MCP-aware client
+drive AppMate via typed tools. List apps, edit cancel flows, publish,
+export waitlists — without leaving the chat.
+
+```bash
+npx -y @fil-technology/appmate-mcp
+```
+
+## Setup (1 minute)
+
+1. Issue a token at <https://flow.appmate.cloud/admin/api-tokens>. Copy the
+   `amk_…` string — it's only shown once.
+2. Add the server to your MCP host's config (examples below).
+3. Restart the host and ask your agent: *"list my appmate apps"*.
+
+### Claude Desktop / Claude Code
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (on
+macOS) or the equivalent on your platform:
+
+```json
+{
+  "mcpServers": {
+    "appmate": {
+      "command": "npx",
+      "args": ["-y", "@fil-technology/appmate-mcp"],
+      "env": {
+        "APPMATE_TOKEN": "amk_…",
+        "APPMATE_API_URL": "https://flow.appmate.cloud"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Codex (`.mcp.json` in your project)
+
+```json
+{
+  "mcpServers": {
+    "appmate": {
+      "command": "npx",
+      "args": ["-y", "@fil-technology/appmate-mcp"],
+      "env": { "APPMATE_TOKEN": "amk_…" }
+    }
+  }
+}
+```
+
+`APPMATE_API_URL` defaults to `https://flow.appmate.cloud`. Override for
+staging or self-hosted instances.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `list_apps` | List every app the token can see. |
+| `get_app` | Fetch one app by id or slug. |
+| `create_app` | Create a new app. |
+| `get_cancel_flow` | Read published + draft cancel config. |
+| `update_cancel_draft` | Replace the draft with new config JSON. |
+| `publish_cancel_flow` | Promote the draft live. |
+| `get_waitlist_flow` | Read published + draft waitlist config. |
+| `update_waitlist_draft` | Replace the waitlist draft. |
+| `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. |
+
+Tools that accept an app reference (`get_app`, `update_cancel_draft`,
+etc.) accept either the cuid `id` or the human-readable `slug` — use
+whichever you have. The full REST shape is documented at
+<https://docs.appmate.cloud/api-reference>.
+
+## Example agent prompts
+
+> *"Create an AppMate app called `Ledgr` with bundle id
+> `com.acme.ledgr`, then publish a simple cancel flow that offers a 20%
+> discount for the `too_expensive` reason."*
+
+> *"Export the waitlist for `appmate-pro` as CSV and save it to
+> `~/Downloads/waitlist.csv`."*
+
+> *"Compare the published and draft cancel configs for `quakemate` and
+> tell me what changed."*
+
+## Local development
+
+```bash
+pnpm install
+pnpm dev    # tsx src/index.ts — talks MCP over stdio
+pnpm build  # emits dist/index.js
+```
+
+## Security
+
+- Tokens are bcrypt-hashed server-side and only shown once on creation.
+- Revoke from the dashboard the moment a token leaks.
+- All calls go over TLS to `flow.appmate.cloud`. No data sits on disk in
+  the MCP process beyond what your MCP host logs.
+
+## License
+
+MIT. See `LICENSE`.

package/dist/api-client.js

@@ -0,0 +1,64 @@
+// Thin fetch wrapper for the AppMate REST surface. Each tool builds the
+// path + body and hands it off here. Centralizing the Bearer header + base
+// URL + error parsing keeps each tool definition focused on its inputs
+// and the response shape.
+export class AppMateApiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`AppMate API error ${status}: ${typeof body === "object" && body && "error" in body
+            ? String(body.error)
+            : JSON.stringify(body)}`);
+        this.status = status;
+        this.body = body;
+    }
+}
+export async function apiFetch(cfg, method, path, body) {
+    const url = `${cfg.baseUrl.replace(/\/$/, "")}${path}`;
+    const headers = {
+        Authorization: `Bearer ${cfg.token}`,
+        Accept: "application/json",
+    };
+    if (body !== undefined) {
+        headers["Content-Type"] = "application/json";
+    }
+    const res = await fetch(url, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    if (!res.ok) {
+        let payload;
+        try {
+            payload = await res.json();
+        }
+        catch {
+            payload = await res.text().catch(() => "");
+        }
+        throw new AppMateApiError(res.status, payload);
+    }
+    // Empty 204s are rare here but harmless to handle.
+    const text = await res.text();
+    if (!text)
+        return undefined;
+    return JSON.parse(text);
+}
+// Helper for CSV endpoints — returns the raw body string instead of JSON.
+export async function apiFetchText(cfg, method, path) {
+    const url = `${cfg.baseUrl.replace(/\/$/, "")}${path}`;
+    const res = await fetch(url, {
+        method,
+        headers: { Authorization: `Bearer ${cfg.token}` },
+    });
+    if (!res.ok) {
+        let payload;
+        try {
+            payload = await res.json();
+        }
+        catch {
+            payload = await res.text().catch(() => "");
+        }
+        throw new AppMateApiError(res.status, payload);
+    }
+    return res.text();
+}

package/dist/index.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { ALL_TOOLS } from "./tools.js";
+import { AppMateApiError } from "./api-client.js";
+// stdio MCP entry. Install: `npx -y @fil-technology/appmate-mcp`.
+//
+// Auth: APPMATE_TOKEN env var (or --token CLI flag). Base URL defaults to
+// https://flow.appmate.cloud — override with APPMATE_API_URL for staging
+// or self-hosted setups.
+function parseCli() {
+    let token = process.env.APPMATE_TOKEN ?? null;
+    let apiUrl = process.env.APPMATE_API_URL ?? "https://flow.appmate.cloud";
+    const argv = process.argv.slice(2);
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--token" && argv[i + 1]) {
+            token = argv[i + 1] ?? null;
+            i++;
+        }
+        else if (a?.startsWith("--token=")) {
+            token = a.slice("--token=".length);
+        }
+        else if (a === "--api-url" && argv[i + 1]) {
+            apiUrl = argv[i + 1] ?? apiUrl;
+            i++;
+        }
+        else if (a?.startsWith("--api-url=")) {
+            apiUrl = a.slice("--api-url=".length);
+        }
+    }
+    return { token, apiUrl };
+}
+async function main() {
+    const { token, apiUrl } = parseCli();
+    if (!token) {
+        // Emit on stderr — stdout is reserved for the MCP wire protocol.
+        process.stderr.write([
+            "appmate-mcp: missing token. Set APPMATE_TOKEN or pass --token amk_...",
+            "",
+            "Issue a token at https://flow.appmate.cloud/admin/api-tokens.",
+            "",
+        ].join("\n"));
+        process.exit(1);
+    }
+    const cfg = { baseUrl: apiUrl, token };
+    const server = new Server({ name: "appmate-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: ALL_TOOLS.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: zodToJsonSchema(t.inputSchema),
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        // Type-erase at the registration boundary: each tool has its own
+        // inputSchema/handler input type, but the union of handlers expects
+        // the *intersection* of input types, not the union. Cast to a loose
+        // shape — the per-tool zod schema is what actually validates input.
+        const tool = ALL_TOOLS.find((t) => t.name === req.params.name);
+        if (!tool) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown tool: ${req.params.name}`,
+                    },
+                ],
+            };
+        }
+        try {
+            const parsed = tool.inputSchema.parse(req.params.arguments ?? {});
+            const result = await tool.handler(parsed, cfg);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof AppMateApiError
+                ? `AppMate API ${err.status}: ${JSON.stringify(err.body, null, 2)}`
+                : err instanceof Error
+                    ? err.message
+                    : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: msg }],
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+function zodToJsonSchema(schema) {
+    if (schema instanceof z.ZodObject) {
+        const shape = schema.shape;
+        const properties = {};
+        const required = [];
+        for (const [k, v] of Object.entries(shape)) {
+            const inner = unwrapOptional(v);
+            properties[k] = zodToJsonSchema(inner.schema);
+            if (!inner.optional)
+                required.push(k);
+        }
+        const out = {
+            type: "object",
+            properties,
+            additionalProperties: false,
+        };
+        if (required.length)
+            out.required = required;
+        return out;
+    }
+    if (schema instanceof z.ZodString) {
+        return { type: "string" };
+    }
+    if (schema instanceof z.ZodNumber) {
+        return { type: "number" };
+    }
+    if (schema instanceof z.ZodBoolean) {
+        return { type: "boolean" };
+    }
+    if (schema instanceof z.ZodUnknown || schema instanceof z.ZodAny) {
+        return {};
+    }
+    return {};
+}
+function unwrapOptional(schema) {
+    if (schema instanceof z.ZodOptional) {
+        return { schema: schema._def.innerType, optional: true };
+    }
+    return { schema, optional: false };
+}
+main().catch((err) => {
+    process.stderr.write(`appmate-mcp: fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/tools.js

@@ -0,0 +1,198 @@
+import { z } from "zod";
+import { apiFetch, apiFetchText } from "./api-client.js";
+// ─── Apps ───────────────────────────────────────────────────────────────────
+export const listApps = {
+    name: "list_apps",
+    description: "List every AppMate app the API token can see. Returns id, slug, name, bundleId, deepLinkScheme, logoUrl, timestamps.",
+    inputSchema: z.object({}),
+    handler: (_input, cfg) => apiFetch(cfg, "GET", "/api/v1/apps"),
+};
+export const getApp = {
+    name: "get_app",
+    description: "Fetch a single AppMate app by its cuid id or slug. Use list_apps first if you don't know either.",
+    inputSchema: z.object({
+        appIdOrSlug: z
+            .string()
+            .min(1)
+            .describe("Either the app's cuid id or its slug."),
+    }),
+    handler: (input, cfg) => apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}`),
+};
+export const createApp = {
+    name: "create_app",
+    description: "Create a new AppMate app. The slug auto-derives from the name when omitted.",
+    inputSchema: z.object({
+        name: z.string().min(1).max(120),
+        slug: z
+            .string()
+            .min(1)
+            .max(80)
+            .regex(/^[a-z0-9-]+$/)
+            .optional(),
+        bundleId: z.string().max(200).optional(),
+        deepLinkScheme: z
+            .string()
+            .max(40)
+            .regex(/^[a-z][a-z0-9+.-]*$/)
+            .optional(),
+        logoUrl: z.string().url().optional(),
+    }),
+    handler: (input, cfg) => apiFetch(cfg, "POST", "/api/v1/apps", input),
+};
+// ─── Pre-cancel flow ────────────────────────────────────────────────────────
+export const getCancelFlow = {
+    name: "get_cancel_flow",
+    description: "Read the published and draft cancel flow configs for an app.",
+    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).
+export const updateCancelDraft = {
+    name: "update_cancel_draft",
+    description: [
+        "Replace the draft cancel flow config. Body MUST be a full cancel config object (type: 'cancel').",
+        "",
+        "Required shape (paste-and-fill):",
+        "  {",
+        "    type: 'cancel',",
+        "    intro: { title, subtitle, primaryButton, secondaryButton },",
+        "    reasonScreen: {",
+        "      title, subtitle,",
+        "      reasons: [ { id: snake_case, label, iconName? (lucide name), emoji? (one char) } ],",
+        "      autoAdvance?: boolean,",
+        "      selectMode?: 'single' (default) | 'multi'   // multi skips response screens",
+        "    },",
+        "    responses: {",
+        "      <reasonId>: {",
+        "        title, body,",
+        "        primaryButton: { label, action, ...actionParams },",
+        "        secondaryButton?: { label, action, ...actionParams },",
+        "        showThanksScreen?: boolean       // true = no deep link, lands on thanks",
+        "      }",
+        "    },",
+        "    showBackButton?: boolean (default true)",
+        "  }",
+        "",
+        "Action types and their params:",
+        "  return_to_app                                     close flow, back to app",
+        "  manage_subscription                               open Apple subs UI (escape hatch)",
+        "  open_offer        { offerId: string }             iOS app applies a StoreKit promo",
+        "  open_premium      { paywallId?: string }          iOS paywall (optional variant id)",
+        "  open_support      { supportTopic?, message? }     iOS support inbox",
+        "  open_feature      { featureId: string }           deep-link an in-app screen",
+        "  external_url      { url: https://… }              open URL in browser",
+        "  none                                              record click, do nothing",
+        "",
+        "CRITICAL gotcha — showThanksScreen suppresses the deep link.",
+        "  Set showThanksScreen:true ONLY when the click itself IS the signal you want.",
+        "  Label the button feedback-shaped: 'Send feedback', 'Tell us why'.",
+        "  DO NOT pair showThanksScreen:true with destination-shaped labels like",
+        "  'Contact support', 'Claim 20% off', 'Open tutorial' — the user taps,",
+        "  lands on a generic thanks screen, and the promise the label made silently breaks.",
+        "",
+        "The server returns { ok:true, warnings: [...] } on success — ALWAYS check warnings",
+        "and re-PUT a corrected config before publishing if any are returned.",
+        "Common warning codes:",
+        "  thanks_screen_blocks_navigation, missing_response, responses_unused_in_multi_mode,",
+        "  placeholder_offer_id, placeholder_feature_id, placeholder_external_url",
+        "",
+        "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(),
+    }),
+    handler: (input, cfg) => apiFetch(cfg, "PUT", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/cancel`, input.config),
+};
+export const publishCancelFlow = {
+    name: "publish_cancel_flow",
+    description: "Promote the draft cancel config to the live published version. The live cancel URL flips on success. ALWAYS review the warnings array returned from the most recent update_cancel_draft call and fix any reported issues BEFORE publishing — publishing locks the broken flow in front of real users.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "POST", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/cancel/publish`),
+};
+// ─── Waitlist flow ──────────────────────────────────────────────────────────
+export const getWaitlistFlow = {
+    name: "get_waitlist_flow",
+    description: "Read the published and draft waitlist flow configs for an app.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "GET", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/waitlist`),
+};
+export const updateWaitlistDraft = {
+    name: "update_waitlist_draft",
+    description: [
+        "Replace the draft waitlist config. Body MUST be a full waitlist config object (type: 'waitlist').",
+        "",
+        "Required shape:",
+        "  {",
+        "    type: 'waitlist',",
+        "    intro: {",
+        "      title, subtitle,",
+        "      emailPlaceholder, submitLabel,",
+        "      legal? (small print, optional)",
+        "    },",
+        "    success: {",
+        "      title, body,",
+        "      ctaLabel?, ctaUrl?    // both-or-neither: ctaLabel without ctaUrl renders nothing",
+        "    }",
+        "  }",
+        "",
+        "Server returns { ok:true, warnings: [...] } — check warnings before publishing.",
+        "Common: partial_cta (label without url, or vice versa).",
+    ].join("\n"),
+    inputSchema: z.object({
+        appIdOrSlug: z.string().min(1),
+        config: z.unknown(),
+    }),
+    handler: (input, cfg) => apiFetch(cfg, "PUT", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/waitlist`, input.config),
+};
+export const publishWaitlistFlow = {
+    name: "publish_waitlist_flow",
+    description: "Promote the draft waitlist config to the live published version.",
+    inputSchema: z.object({ appIdOrSlug: z.string().min(1) }),
+    handler: (input, cfg) => apiFetch(cfg, "POST", `/api/v1/apps/${encodeURIComponent(input.appIdOrSlug)}/flows/waitlist/publish`),
+};
+// ─── Waitlist signups ───────────────────────────────────────────────────────
+export const listWaitlistSignups = {
+    name: "list_waitlist_signups",
+    description: "Paginated list of waitlist signups for an app. Returns up to `limit` rows (max 200, default 50) and a `nextCursor` to pass 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)}/waitlist/signups${tail}`);
+    },
+};
+export const exportWaitlistCsv = {
+    name: "export_waitlist_csv",
+    description: "Return the full waitlist for an app as a CSV string (header row + one row per signup). Useful for hand-off to 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)}/waitlist/signups.csv`);
+        return { csv };
+    },
+};
+// Registered alphabetically so `list_tools` reads predictably.
+export const ALL_TOOLS = [
+    createApp,
+    exportWaitlistCsv,
+    getApp,
+    getCancelFlow,
+    getWaitlistFlow,
+    listApps,
+    listWaitlistSignups,
+    publishCancelFlow,
+    publishWaitlistFlow,
+    updateCancelDraft,
+    updateWaitlistDraft,
+];

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@fil-technology/appmate-mcp",
+  "version": "0.3.0",
+  "description": "Model Context Protocol server for AppMate — lets Claude / Cursor / Codex drive your retention flows via API tokens.",
+  "type": "module",
+  "bin": {
+    "appmate-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.2",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fil-technology/appmate-mcp.git"
+  },
+  "homepage": "https://docs.appmate.cloud/api-reference",
+  "license": "MIT",
+  "keywords": [
+    "appmate",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "claude",
+    "retention",
+    "subscription"
+  ]
+}