@cross-deck/ai 0.2.0

package/README.md

@@ -0,0 +1,79 @@
+# Crossdeck AI
+
+> Connect Crossdeck to Claude, Cursor, or any MCP client and **ask your app questions in plain English** — and get **rendered charts and dashboards back**, not just numbers. *"Why did revenue drop?" "Who did this crash affect — do they pay us?" "Draw user growth over the last 30 days."*
+
+Crossdeck joins the layers about your users — **identity, revenue, entitlements, errors, analytics, and database read-cost** — into one place, by identity. **Crossdeck AI gives that source-of-truth a voice.** MCP is the transport; the product is *Crossdeck understands your app*, in whatever AI tool you use.
+
+The point isn't "let AI read my data." It's the **crossing**: because Crossdeck owns the identity that ties the layers together, one question can span them — *who* an error hit **and** how many of them pay you. No single-layer analytics or error tool can answer that.
+
+---
+
+## Test it in 10 minutes
+
+### 1. Connect
+
+**Directory / remote (recommended):** add the Crossdeck connector in your client's connector settings and complete the one-click sign-in — you'll authorize Crossdeck and pick a project. No keys to paste. (OAuth 2.0.)
+
+**Local (Claude Desktop / Cursor / Claude Code):** install and pass a secret key from your Crossdeck dashboard → **API keys**:
+
+```bash
+npm install -g @cross-deck/ai
+```
+```json
+{
+  "mcpServers": {
+    "crossdeck": { "command": "crossdeck-ai", "env": { "CROSSDECK_SECRET_KEY": "cd_sk_live_…" } }
+  }
+}
+```
+Use a **secret** key (`cd_sk_`), never a publishable (`cd_pub_`) one — these are server-side reads of private data. `CROSSDECK_API_BASE` overrides the endpoint (e.g. sandbox).
+
+### 2. Try these prompts
+
+| Ask | Tool(s) used | Expected outcome |
+|---|---|---|
+| *"What's our MRR and how many paying customers, split by Stripe/Apple/Google?"* | `get_revenue` | Current MRR in dollars, paying-customer count, and the three-rail split. |
+| *"Draw our user growth over the last 30 days."* | `draw_user_growth` | A **rendered line chart** of unique visitors + page views over time, with totals. |
+| *"This error `a1b2c3` — who did it affect, and do any of them pay us?"* | `get_error_impact` | The issue's type/status/occurrences plus **affected users and how many are paying**. |
+| *"Show me everything about customer `agent_8842`."* | `get_customer` → moat dashboard | A **rendered cross-match**: what they pay × entitlements × read-cost, in one view. |
+| *"What's driving our database reads — per-user vs overhead?"* | `get_read_cost` | The per-user-vs-overhead split + reads by operation. |
+
+### 3. What you'll see
+
+Data tools return clean JSON; the **`draw_user_growth`** and **`open_moat_dashboard`** tools render interactive charts/dashboards inline (in hosts that support MCP Apps; they fall back to a text summary elsewhere).
+
+---
+
+## Tools
+
+| Tool | Title | Answers |
+|---|---|---|
+| `get_revenue` | Get revenue | MRR / paying count / per-rail / trend |
+| `get_read_cost` | Get database read-cost | per-user vs overhead, by operation |
+| `get_error_impact` | Get who an error affected | who it hit + how many pay |
+| `get_customer` | Get a customer's full picture | revenue × entitlements × read-cost |
+| `get_host_analytics` | Get analytics for a host | per-subdomain views + uniques |
+| `get_host_top_pages` | Get top pages/referrers for a host | per-host breakdown |
+| `draw_user_growth` | Draw user growth over time | **rendered chart** |
+| `open_moat_dashboard` | Open the cross-layer dashboard | **rendered cross-match** |
+
+Every tool is **read-only** (`readOnlyHint`), has a human-readable `title`, returns scoped/paginated results, and surfaces actionable errors. All reads are point-reads of maintained ledgers — asking questions never runs up your database bill.
+
+## Known limitations
+
+- **Read-only** in v1 — no writes, no config changes (those are a later, separately-gated stage).
+- Per-host analytics require the host to be a **verified origin** of your project.
+- Rendered charts require an MCP-Apps-capable host; other hosts get a text summary.
+- Reporting reflects data going forward from when Crossdeck was connected (historical backfill is separate).
+
+## Privacy
+
+Crossdeck AI reads only your own project's aggregate data, scoped by your token. It does **not** read your conversation history or local files. Full policy: **https://cross-deck.com/legal/privacy/**.
+
+## Support
+
+**support@cross-deck.com** · docs: **https://cross-deck.com/docs/reporting-api/**
+
+## License
+
+MIT.

package/dist/server.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Crossdeck AI — MCP server (tools).
+ *
+ * The product is "Crossdeck understands your app." This server exposes
+ * cross-layer, job-oriented tools over the live Reporting API. Crossdeck owns
+ * identity, revenue, entitlements, errors, analytics, and read-cost about an
+ * app's users, and joins them BY IDENTITY — so a single tool can answer a
+ * question that crosses layers (who an error affected AND how many of them
+ * pay you), which no single-layer tool can.
+ *
+ * Directory-grade tool metadata: every tool has a `title` and a `readOnlyHint`
+ * annotation; all tools are read-only (no read/write mixing); descriptions are
+ * narrow, accurate, and non-promotional; outputs are scoped and paginated;
+ * errors are actionable. Logs go to stderr (stdout is the MCP wire).
+ *
+ * Transport: stdio here (local/dev — Claude Desktop, Cursor, Claude Code with
+ * a secret key in env). The directory build wraps these same tools in a
+ * Streamable-HTTP + OAuth host (see http.ts / CROSSDECK_AI_MCP_SUBMISSION.md);
+ * the tool layer is shared.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { registerCrossdeckTools } from "./tools.js";
+import { registerCrossdeckUi } from "./ui.js";
+const VERSION = "0.2.0";
+const SECRET_KEY = process.env.CROSSDECK_SECRET_KEY ?? "";
+const API_BASE = process.env.CROSSDECK_API_BASE ?? "https://api.cross-deck.com";
+function log(msg) {
+    process.stderr.write(`[crossdeck-ai] ${msg}\n`);
+}
+const server = new McpServer({ name: "crossdeck-ai", version: VERSION });
+// The stdio build authenticates with a secret key from the environment; the
+// tool layer takes an auth resolver so the HTTP/OAuth build can swap in a
+// per-request token without touching the tools.
+const toolCtx = { apiBase: API_BASE, getToken: () => SECRET_KEY };
+registerCrossdeckTools(server, toolCtx);
+registerCrossdeckUi(server, toolCtx);
+async function main() {
+    await server.connect(new StdioServerTransport());
+    log(`Crossdeck AI v${VERSION} ready (api: ${API_BASE}, key: ${SECRET_KEY ? "set" : "MISSING — set CROSSDECK_SECRET_KEY"})`);
+}
+main().catch((e) => {
+    log(`fatal: ${String(e)}`);
+    process.exit(1);
+});
+export { z };

package/dist/server.test.js

@@ -0,0 +1,77 @@
+/**
+ * Integration test — spawns the built stdio server, runs the MCP handshake,
+ * and asserts the directory-grade contract: tool count, hard-gate metadata
+ * (title + readOnlyHint) on every tool, UI tools linked to ui:// resources,
+ * the resources serve the MCP-Apps mime, and unauthenticated calls fail
+ * closed with an actionable error. Run: `npm run build && npm test`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const SERVER = path.join(path.dirname(fileURLToPath(import.meta.url)), "server.js");
+/** Send a batch of JSON-RPC lines to a fresh server and collect responses by id. */
+function rpc(requests, env = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [SERVER], { env: { ...process.env, CROSSDECK_SECRET_KEY: "cd_sk_test", ...env }, stdio: ["pipe", "pipe", "ignore"] });
+        let buf = "";
+        const out = new Map();
+        const timer = setTimeout(() => { child.kill(); reject(new Error("timeout")); }, 8000);
+        child.stdout.on("data", (d) => {
+            buf += d.toString();
+            let i;
+            while ((i = buf.indexOf("\n")) >= 0) {
+                const line = buf.slice(0, i).trim();
+                buf = buf.slice(i + 1);
+                if (!line)
+                    continue;
+                try {
+                    const m = JSON.parse(line);
+                    if (m.id != null)
+                        out.set(m.id, m);
+                }
+                catch { /* ignore */ }
+            }
+            if (out.size >= requests.filter((r) => r.id != null).length) {
+                clearTimeout(timer);
+                child.kill();
+                resolve(out);
+            }
+        });
+        child.on("error", reject);
+        for (const r of requests)
+            child.stdin.write(JSON.stringify(r) + "\n");
+    });
+}
+const INIT = { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "t", version: "0" } } };
+const INITED = { jsonrpc: "2.0", method: "notifications/initialized" };
+test("every tool has title + readOnlyHint (hard gate)", async () => {
+    const r = await rpc([INIT, INITED, { jsonrpc: "2.0", id: 2, method: "tools/list" }]);
+    const tools = r.get(2).result.tools;
+    assert.equal(tools.length, 8, "expected 8 tools");
+    for (const t of tools) {
+        assert.ok(t.title && t.title.length <= 64, `${t.name} needs a title ≤64`);
+        assert.equal(t.annotations?.readOnlyHint, true, `${t.name} needs readOnlyHint`);
+        assert.ok(t.description && t.description.length > 10, `${t.name} needs a description`);
+        assert.equal(/\bbest\b|amazing|simply|just use|prefer this/i.test(t.description), false, `${t.name} description must be non-promotional`);
+    }
+});
+test("UI tools link to ui:// resources, and resources serve the MCP-Apps mime", async () => {
+    const r = await rpc([INIT, INITED, { jsonrpc: "2.0", id: 2, method: "tools/list" }, { jsonrpc: "2.0", id: 3, method: "resources/list" }]);
+    const tools = r.get(2).result.tools;
+    const ui = tools.filter((t) => t._meta?.ui?.resourceUri);
+    assert.equal(ui.length, 2, "expected 2 UI-linked tools");
+    for (const t of ui)
+        assert.match(t._meta.ui.resourceUri, /^ui:\/\//);
+    const resources = r.get(3).result.resources;
+    assert.equal(resources.length, 2, "expected 2 ui:// resources");
+    for (const res of resources)
+        assert.equal(res.mimeType, "text/html;profile=mcp-app");
+});
+test("unauthenticated tool call fails closed with an actionable message", async () => {
+    const r = await rpc([INIT, INITED, { jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "get_revenue", arguments: {} } }], { CROSSDECK_SECRET_KEY: "" });
+    const res = r.get(2).result;
+    assert.equal(res.isError, true, "no-key call must be an error");
+    assert.match(res.content[0].text, /connect|CROSSDECK_SECRET_KEY|authorize/i);
+});

package/dist/tools.js

@@ -0,0 +1,113 @@
+/**
+ * Crossdeck AI — the shared tool layer.
+ *
+ * Registered identically by the stdio build (server.ts) and the
+ * Streamable-HTTP + OAuth build (http.ts). Auth is injected via `getToken`
+ * so the transport owns credentials, not the tools.
+ *
+ * Every tool: directory-grade metadata (`title` ≤64, `readOnlyHint`),
+ * read-only, narrow/non-promotional description, scoped + paginated output,
+ * actionable errors. The moat is shown by CAPABILITY (cross-layer answers),
+ * never by promotional language.
+ */
+import { z } from "zod";
+function ok(data) {
+    const obj = (data && typeof data === "object" ? data : { value: data });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }], structuredContent: obj };
+}
+function fail(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+/** One scoped GET against the Reporting API. Surfaces the API's typed error
+ *  envelope to the model as an actionable message (never a bare 500/400). */
+async function cdGet(ctx, path, params) {
+    const token = ctx.getToken();
+    if (!token || !token.startsWith("cd_")) {
+        return fail("Not connected to Crossdeck. Authorize the connector (or, for the local build, set CROSSDECK_SECRET_KEY to a cd_sk_ key from your Crossdeck dashboard → API keys).");
+    }
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(params))
+        if (v !== undefined && v !== "")
+            qs.set(k, String(v));
+    const url = `${ctx.apiBase}${path}${qs.toString() ? `?${qs}` : ""}`;
+    try {
+        const res = await fetch(url, { headers: { Authorization: `Bearer ${token}`, Accept: "application/json" } });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            if (res.status === 429)
+                return fail(`Crossdeck rate limit reached. Wait briefly and retry. ${body.error?.message ?? ""}`.trim());
+            if (res.status === 401)
+                return fail("Crossdeck rejected the credentials — reconnect the connector.");
+            if (res.status === 403)
+                return fail(`Not permitted: ${body.error?.message ?? "this resource is outside your project's scope."}`);
+            return fail(`Crossdeck API ${res.status} ${body.error?.code ?? ""}: ${body.error?.message ?? "request failed"}`.trim());
+        }
+        return ok({ data: body.data ?? body, meta: body.meta });
+    }
+    catch {
+        return fail(`Could not reach Crossdeck (${ctx.apiBase}). Check connectivity and retry.`);
+    }
+}
+const RO = { readOnlyHint: true };
+export function registerCrossdeckTools(server, ctx) {
+    server.registerTool("get_revenue", {
+        title: "Get revenue",
+        description: "Get the app's current recurring revenue: MRR (cents), paying-customer count, and the per-rail split across Stripe, Apple, and Google. Pass granularity='day' with a days window for a daily trend. Use for questions about MRR, paying customers, or revenue trend.",
+        inputSchema: {
+            granularity: z.enum(["total", "day"]).optional().describe("'total' (default) for the latest snapshot, or 'day' for a daily series."),
+            days: z.number().int().min(1).max(366).optional().describe("With granularity='day', the trend window (default 90)."),
+        },
+        annotations: RO,
+    }, async ({ granularity, days }) => cdGet(ctx, "/v1/revenue", { granularity, days }));
+    server.registerTool("get_read_cost", {
+        title: "Get database read-cost",
+        description: "Get the app's database read-cost split into per-user reads vs un-attributed overhead, with a breakdown by operation, over the last `days` days. Per-user attribution is possible because Crossdeck joins read-cost to the SDK's identity. Use for questions about what drives database reads or which operation costs the most.",
+        inputSchema: { days: z.number().int().min(1).max(90).optional().describe("Window in days (default 30).") },
+        annotations: RO,
+    }, async ({ days }) => cdGet(ctx, "/v1/buckets", { days }));
+    server.registerTool("get_error_impact", {
+        title: "Get who an error affected",
+        description: "For one error (by fingerprint/issue id), get how many distinct users hit it and how many of those are PAYING customers, plus its type, status, occurrence count, and first/last seen. Joins the error to identity and revenue. Returns counts only — no stack traces, no user identities.",
+        inputSchema: { fingerprint: z.string().min(1).describe("The error's fingerprint / issue id from the Crossdeck Errors view.") },
+        annotations: RO,
+    }, async ({ fingerprint }) => cdGet(ctx, "/v1/errors", { fingerprint }));
+    server.registerTool("get_customer", {
+        title: "Get a customer's full picture",
+        description: "Get one customer across every layer Crossdeck joins by identity: what they pay (monthly cents), their active entitlement count, and their database read-cost. Identify them by any of: your own user id, an anonymous id, a Crossdeck customer id, or a rail transaction id. Use for 'how much does this user pay and what do they cost us?'.",
+        inputSchema: {
+            userId: z.string().optional().describe("Your own user id for this person (what you pass to identify())."),
+            anonymousId: z.string().optional().describe("A pre-login anonymous/device id."),
+            customerId: z.string().optional().describe("A Crossdeck customer id (cdcust_…)."),
+            appleOriginalTransactionId: z.string().optional().describe("Apple StoreKit originalTransactionId."),
+            googlePurchaseToken: z.string().optional().describe("Google Play purchase token."),
+            stripeCustomerId: z.string().optional().describe("Stripe customer id (cus_…)."),
+        },
+        annotations: RO,
+    }, async (args) => {
+        if (!args.userId && !args.anonymousId && !args.customerId && !args.appleOriginalTransactionId && !args.googlePurchaseToken && !args.stripeCustomerId) {
+            return fail("Identify the customer with at least one of: userId, anonymousId, customerId, appleOriginalTransactionId, googlePurchaseToken, or stripeCustomerId.");
+        }
+        return cdGet(ctx, "/v1/crossmatch", { ...args });
+    });
+    server.registerTool("get_host_analytics", {
+        title: "Get analytics for a host",
+        description: "Get page views and unique visitors for one host or subdomain you own (e.g. a tenant's subdomain). Pass granularity='day' for a daily series. The host must be a verified origin of your project, or the request is rejected. Use for per-tenant analytics questions.",
+        inputSchema: {
+            host: z.string().min(1).describe("The host, e.g. 'wes.example.com'. Must belong to your project."),
+            granularity: z.enum(["total", "day"]).optional().describe("'total' (default) or 'day' for a daily series."),
+            days: z.number().int().min(1).max(90).optional().describe("Window in days (default 30)."),
+        },
+        annotations: RO,
+    }, async ({ host, granularity, days }) => cdGet(ctx, "/v1/reporting/metrics", { host, granularity, days }));
+    server.registerTool("get_host_top_pages", {
+        title: "Get top pages or referrers for a host",
+        description: "Get the top pages or top referrers for one host you own, paginated via `limit`. Set dimension='top_referrers' for referrers (default is top pages). The host must belong to your project. Use for 'most-viewed pages on this subdomain' or 'where its traffic comes from'.",
+        inputSchema: {
+            host: z.string().min(1).describe("The host, e.g. 'wes.example.com'. Must belong to your project."),
+            dimension: z.enum(["top_pages", "top_referrers"]).optional().describe("'top_pages' (default) or 'top_referrers'."),
+            days: z.number().int().min(1).max(90).optional().describe("Window in days (default 30)."),
+            limit: z.number().int().min(1).max(100).optional().describe("Max rows (default 25)."),
+        },
+        annotations: RO,
+    }, async ({ host, dimension, days, limit }) => cdGet(ctx, "/v1/reporting/breakdown", { host, dimension, days, limit }));
+}

package/dist/ui/moat-dashboard.html

@@ -0,0 +1,112 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Crossdeck — Customer cross-match</title>
+<style>
+  :root {
+    --bg: var(--color-background-primary, #ffffff);
+    --fg: var(--color-text-primary, #1a1a1a);
+    --muted: var(--color-text-secondary, #6b7280);
+    --grid: var(--color-border-primary, #e5e7eb);
+    --accent: var(--color-accent-primary, #e8552a);
+    --surface: var(--color-background-secondary, #f7f3ec);
+    --good: var(--color-success, #16a34a);
+    font-family: var(--font-family-base, ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif);
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--fg); padding: 16px; }
+  h1 { font-size: 15px; font-weight: 650; margin: 0 0 2px; }
+  .who { color: var(--muted); font-size: 12px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+  .sentence { background: var(--surface); border: 1px solid var(--grid); border-radius: 10px;
+    padding: 12px 14px; margin: 14px 0; font-size: 15px; line-height: 1.5; }
+  .sentence b { font-weight: 680; }
+  .cards { display: grid; grid-template-columns: repeat(3, 1fr); gap: 10px; }
+  .card { background: var(--surface); border: 1px solid var(--grid); border-radius: 10px; padding: 12px 14px; }
+  .card .label { color: var(--muted); font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; }
+  .card .value { font-size: 24px; font-weight: 680; letter-spacing: -0.01em; margin-top: 4px; }
+  .card .note { color: var(--muted); font-size: 11px; margin-top: 3px; }
+  .pill { display: inline-block; font-size: 11px; padding: 1px 8px; border-radius: 999px; border: 1px solid var(--grid); }
+  .pill.paying { color: var(--good); border-color: var(--good); }
+  .foot { color: var(--muted); font-size: 11px; margin-top: 12px; }
+  .empty { color: var(--muted); font-size: 13px; padding: 28px 0; text-align: center; }
+</style>
+</head>
+<body>
+  <h1 id="title">Customer cross-match</h1>
+  <div class="who" id="who"></div>
+  <div id="body"></div>
+
+<script>
+(function () {
+  "use strict";
+  function money(cents) {
+    if (cents == null) return "—";
+    return "$" + (cents / 100).toLocaleString(undefined, { minimumFractionDigits: cents % 100 ? 2 : 0, maximumFractionDigits: 2 });
+  }
+  function num(n) {
+    if (n == null) return "—";
+    if (n >= 1e6) return (n / 1e6).toFixed(1) + "M";
+    if (n >= 1e3) return (n / 1e3).toFixed(1) + "k";
+    return String(n);
+  }
+
+  function render(payload) {
+    var d = (payload && payload.data) ? payload.data : payload || {};
+    var body = document.getElementById("body");
+    if (!d || d === null || (!d.customer && !d.revenue && !d.readCost)) {
+      document.getElementById("who").textContent = "";
+      body.innerHTML = '<div class="empty">No customer matched that identifier.</div>';
+      return;
+    }
+    var cust = d.customer || {};
+    var rev = d.revenue || {};
+    var ent = d.entitlements || {};
+    var rc = d.readCost || null;
+
+    document.getElementById("who").textContent = cust.crossdeckCustomerId || "";
+
+    // The sentence only Crossdeck can produce — the moat, in words.
+    var paysPart = rev.paying ? ("pays <b>" + money(rev.monthlyCents) + "/mo</b>") : "is <b>not paying</b>";
+    var entPart = "holds <b>" + (ent.active != null ? ent.active : 0) + "</b> entitlement" + (ent.active === 1 ? "" : "s");
+    var costPart = rc ? ("cost you <b>" + num(rc.reads) + " reads</b> in the last " + rc.windowDays + " days") : "has no attributed read-cost in range";
+    document.getElementById("title").textContent = "Customer cross-match";
+
+    var sentence = '<div class="sentence">This customer ' + paysPart + ", " + entPart + ", and " + costPart + ".</div>";
+
+    var cards =
+      '<div class="cards">' +
+        '<div class="card"><div class="label">Revenue</div><div class="value">' + money(rev.monthlyCents) +
+          '</div><div class="note">' + (rev.paying ? '<span class="pill paying">paying</span>' : '<span class="pill">free</span>') + '</div></div>' +
+        '<div class="card"><div class="label">Entitlements</div><div class="value">' + (ent.active != null ? ent.active : 0) +
+          '</div><div class="note">active</div></div>' +
+        '<div class="card"><div class="label">Read-cost</div><div class="value">' + (rc ? num(rc.reads) : "—") +
+          '</div><div class="note">' + (rc ? ("last " + rc.windowDays + "d") : "n/a") + '</div></div>' +
+      '</div>';
+
+    body.innerHTML = sentence + cards +
+      '<div class="foot">Revenue × entitlements × read-cost, joined by identity — the cross-layer view only Crossdeck can produce.</div>';
+  }
+
+  function applyTheme(hostContext) {
+    if (!hostContext) return;
+    var vars = (hostContext.styles && hostContext.styles.variables) || {};
+    var root = document.documentElement;
+    Object.keys(vars).forEach(function (k) { root.style.setProperty(k.charAt(0) === "-" ? k : ("--" + k), vars[k]); });
+    if (hostContext.theme) { root.setAttribute("data-theme", hostContext.theme); root.style.colorScheme = hostContext.theme; }
+  }
+  function onResult(r) { render(r && r.structuredContent ? r.structuredContent : r); }
+  window.addEventListener("message", function (ev) {
+    var m = ev.data || {};
+    if (m.result && m.result.hostContext) applyTheme(m.result.hostContext);
+    if (m.method === "ui/notifications/host-context-changed" && m.params) applyTheme(m.params);
+    if (m.method === "ui/notifications/tool-input" && m.params && m.params.structuredContent) onResult(m.params);
+    if (m.method === "ui/notifications/tool-result" && m.params) onResult(m.params);
+  });
+  if (window.__CROSSDECK_DATA__) render(window.__CROSSDECK_DATA__);
+  try { parent.postMessage({ jsonrpc: "2.0", id: 1, method: "ui/initialize", params: { clientInfo: { name: "crossdeck-moat-dashboard", version: "1.0.0" } } }, "*"); } catch (e) {}
+})();
+</script>
+</body>
+</html>

package/dist/ui/user-growth.html

@@ -0,0 +1,135 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Crossdeck — User growth</title>
+<style>
+  /* Theme-aware: use the host's CSS custom properties with safe fallbacks
+     (MCP Apps hosts inject --color-* vars; we degrade gracefully). */
+  :root {
+    --bg: var(--color-background-primary, #ffffff);
+    --fg: var(--color-text-primary, #1a1a1a);
+    --muted: var(--color-text-secondary, #6b7280);
+    --grid: var(--color-border-primary, #e5e7eb);
+    --accent: var(--color-accent-primary, #e8552a);  /* Crossdeck orange */
+    --accent2: var(--color-accent-secondary, #2563eb);
+    --surface: var(--color-background-secondary, #f7f3ec);
+    font-family: var(--font-family-base, ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif);
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--fg); padding: 16px; }
+  .head { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; margin-bottom: 4px; }
+  h1 { font-size: 15px; font-weight: 650; margin: 0; }
+  .sub { color: var(--muted); font-size: 12px; }
+  .totals { display: flex; gap: 18px; margin: 10px 0 14px; }
+  .kpi { display: flex; flex-direction: column; }
+  .kpi b { font-size: 22px; font-weight: 680; letter-spacing: -0.01em; }
+  .kpi span { color: var(--muted); font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; }
+  .legend { display: flex; gap: 14px; font-size: 12px; color: var(--muted); margin-top: 8px; }
+  .legend i { display: inline-block; width: 10px; height: 10px; border-radius: 2px; margin-right: 5px; vertical-align: middle; }
+  svg { width: 100%; height: auto; display: block; }
+  .empty { color: var(--muted); font-size: 13px; padding: 28px 0; text-align: center; }
+  .tip { fill: var(--fg); font-size: 11px; }
+</style>
+</head>
+<body>
+  <div class="head">
+    <h1 id="title">User growth</h1>
+    <span class="sub" id="range"></span>
+  </div>
+  <div class="totals" id="totals"></div>
+  <div id="chart"></div>
+  <div class="legend">
+    <span><i style="background:var(--accent)"></i>Unique visitors</span>
+    <span><i style="background:var(--accent2)"></i>Page views</span>
+  </div>
+
+<script>
+(function () {
+  "use strict";
+
+  function fmt(n) {
+    if (n == null) return "—";
+    if (n >= 1e6) return (n / 1e6).toFixed(1) + "M";
+    if (n >= 1e3) return (n / 1e3).toFixed(1) + "k";
+    return String(n);
+  }
+
+  // Render a two-line SVG chart (unique visitors + page views) over time.
+  function render(data) {
+    var d = (data && data.data) ? data.data : data || {};
+    var series = Array.isArray(d.series) ? d.series : [];
+    var host = d.host || "";
+    var totals = d.totals || {};
+    document.getElementById("title").textContent = host ? ("User growth · " + host) : "User growth";
+    var r = d.range || {};
+    document.getElementById("range").textContent = (r.from && r.to) ? (r.from + " → " + r.to) : "";
+
+    document.getElementById("totals").innerHTML =
+      '<div class="kpi"><b>' + fmt(totals.uniqueVisitors) + '</b><span>Unique visitors</span></div>' +
+      '<div class="kpi"><b>' + fmt(totals.views) + '</b><span>Page views</span></div>';
+
+    var chart = document.getElementById("chart");
+    if (series.length === 0) { chart.innerHTML = '<div class="empty">No analytics yet for this range.</div>'; return; }
+
+    var W = 720, H = 240, padL = 44, padR = 12, padT = 12, padB = 26;
+    var iw = W - padL - padR, ih = H - padT - padB;
+    var n = series.length;
+    var maxY = 1;
+    series.forEach(function (p) { maxY = Math.max(maxY, p.uniqueVisitors || 0, p.views || 0); });
+    // round max up to a "nice" number
+    var pow = Math.pow(10, Math.floor(Math.log10(maxY)));
+    maxY = Math.ceil(maxY / pow) * pow;
+
+    function x(i) { return padL + (n <= 1 ? iw / 2 : (i / (n - 1)) * iw); }
+    function y(v) { return padT + ih - (v / maxY) * ih; }
+    function path(key) {
+      return series.map(function (p, i) { return (i ? "L" : "M") + x(i).toFixed(1) + " " + y(p[key] || 0).toFixed(1); }).join(" ");
+    }
+
+    var grid = "", ticks = 4;
+    for (var g = 0; g <= ticks; g++) {
+      var gy = padT + (g / ticks) * ih, gv = maxY - (g / ticks) * maxY;
+      grid += '<line x1="' + padL + '" y1="' + gy.toFixed(1) + '" x2="' + (W - padR) + '" y2="' + gy.toFixed(1) + '" stroke="var(--grid)" stroke-width="1"/>';
+      grid += '<text x="' + (padL - 6) + '" y="' + (gy + 3).toFixed(1) + '" text-anchor="end" fill="var(--muted)" font-size="10">' + fmt(Math.round(gv)) + '</text>';
+    }
+    // x labels: first, middle, last
+    var xl = "";
+    [0, Math.floor((n - 1) / 2), n - 1].filter(function (v, i, a) { return a.indexOf(v) === i; }).forEach(function (i) {
+      xl += '<text x="' + x(i).toFixed(1) + '" y="' + (H - 8) + '" text-anchor="middle" fill="var(--muted)" font-size="10">' + (series[i].date || "") + '</text>';
+    });
+
+    chart.innerHTML =
+      '<svg viewBox="0 0 ' + W + ' ' + H + '" role="img" aria-label="User growth over time">' +
+        grid + xl +
+        '<path d="' + path("views") + '" fill="none" stroke="var(--accent2)" stroke-width="2" stroke-linejoin="round"/>' +
+        '<path d="' + path("uniqueVisitors") + '" fill="none" stroke="var(--accent)" stroke-width="2.5" stroke-linejoin="round"/>' +
+      '</svg>';
+  }
+
+  // ── MCP Apps host bridge (spec 2026-01-26) ─────────────────────────────
+  // Self-contained JSON-RPC-over-postMessage: send ui/initialize, apply the
+  // host theme from the result's hostContext, then render on the
+  // ui/notifications/tool-result (the CallToolResult — read structuredContent).
+  function applyTheme(hostContext) {
+    if (!hostContext) return;
+    var vars = (hostContext.styles && hostContext.styles.variables) || {};
+    var root = document.documentElement;
+    Object.keys(vars).forEach(function (k) { root.style.setProperty(k.charAt(0) === "-" ? k : ("--" + k), vars[k]); });
+    if (hostContext.theme) { root.setAttribute("data-theme", hostContext.theme); root.style.colorScheme = hostContext.theme; }
+  }
+  function onResult(r) { render(r && r.structuredContent ? r.structuredContent : r); }
+  window.addEventListener("message", function (ev) {
+    var m = ev.data || {};
+    if (m.result && m.result.hostContext) applyTheme(m.result.hostContext);                 // ui/initialize response
+    if (m.method === "ui/notifications/host-context-changed" && m.params) applyTheme(m.params);
+    if (m.method === "ui/notifications/tool-input" && m.params && m.params.structuredContent) onResult(m.params);
+    if (m.method === "ui/notifications/tool-result" && m.params) onResult(m.params);
+  });
+  if (window.__CROSSDECK_DATA__) render(window.__CROSSDECK_DATA__); // local preview
+  try { parent.postMessage({ jsonrpc: "2.0", id: 1, method: "ui/initialize", params: { clientInfo: { name: "crossdeck-user-growth", version: "1.0.0" } } }, "*"); } catch (e) {}
+})();
+</script>
+</body>
+</html>

package/dist/ui.js

@@ -0,0 +1,108 @@
+/**
+ * Crossdeck AI — MCP Apps (rendered UI).
+ *
+ * Two `ui://` HTML resources + two app tools that return data and link to
+ * them. Hosts that support MCP Apps render the chart/dashboard in a sandboxed
+ * iframe (the HTML reads `structuredContent` from the tool result and the host
+ * theme from `hostContext.styles.variables`); other hosts get the text fallback.
+ *
+ * Uses the first-class @modelcontextprotocol/ext-apps helpers
+ * (registerAppResource / registerAppTool / RESOURCE_MIME_TYPE).
+ */
+import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const UI_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "ui");
+function html(name) {
+    try {
+        return fs.readFileSync(path.join(UI_DIR, name), "utf8");
+    }
+    catch {
+        return "<!doctype html><meta charset=utf-8><body style='font:14px system-ui;padding:16px'>Crossdeck UI unavailable.</body>";
+    }
+}
+async function fetchData(ctx, p, params) {
+    const token = ctx.getToken();
+    if (!token || !token.startsWith("cd_"))
+        return { error: "Not connected to Crossdeck — authorize the connector." };
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(params))
+        if (v !== undefined && v !== "")
+            qs.set(k, String(v));
+    try {
+        const res = await fetch(`${ctx.apiBase}${p}${qs.toString() ? `?${qs}` : ""}`, {
+            headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            return { error: body.error?.message ?? `Crossdeck request failed (${res.status}).` };
+        return { data: body.data ?? body };
+    }
+    catch {
+        return { error: `Could not reach Crossdeck (${ctx.apiBase}).` };
+    }
+}
+const RO = { readOnlyHint: true };
+const GROWTH_URI = "ui://crossdeck/user-growth";
+const MOAT_URI = "ui://crossdeck/moat-dashboard";
+export function registerCrossdeckUi(server, ctx) {
+    // ── User-growth chart ──────────────────────────────────────────────────
+    registerAppResource(server, GROWTH_URI, GROWTH_URI, { mimeType: RESOURCE_MIME_TYPE }, async () => ({
+        contents: [{ uri: GROWTH_URI, mimeType: RESOURCE_MIME_TYPE, text: html("user-growth.html") }],
+    }));
+    registerAppTool(server, "draw_user_growth", {
+        title: "Draw user growth over time",
+        description: "Render an interactive line chart of unique visitors and page views over time for a host you own. Use when asked to chart, graph, draw, or visualize growth or traffic for a subdomain. The host must be a verified origin of your project.",
+        inputSchema: {
+            host: z.string().min(1).describe("The host, e.g. 'wes.example.com'."),
+            days: z.number().int().min(1).max(90).optional().describe("Window in days (default 30)."),
+        },
+        _meta: { ui: { resourceUri: GROWTH_URI } },
+        annotations: RO,
+    }, async ({ host, days }) => {
+        const r = await fetchData(ctx, "/v1/reporting/metrics", { host, granularity: "day", days: days ?? 30 });
+        if (r.error)
+            return { content: [{ type: "text", text: r.error }], isError: true };
+        const d = (r.data ?? {});
+        const t = d.totals ?? {};
+        return {
+            content: [{ type: "text", text: `User growth for ${host}: ${t.uniqueVisitors ?? 0} unique visitors, ${t.views ?? 0} page views over the range.` }],
+            structuredContent: d,
+        };
+    });
+    // ── Cross-layer customer dashboard (the moat, rendered) ────────────────
+    registerAppResource(server, MOAT_URI, MOAT_URI, { mimeType: RESOURCE_MIME_TYPE }, async () => ({
+        contents: [{ uri: MOAT_URI, mimeType: RESOURCE_MIME_TYPE, text: html("moat-dashboard.html") }],
+    }));
+    registerAppTool(server, "open_moat_dashboard", {
+        title: "Open the cross-layer dashboard",
+        description: "Render a customer's cross-layer dashboard — what they pay, their active entitlements, and their database read-cost, joined by identity. Identify the customer by any of userId, anonymousId, customerId, or a rail transaction id.",
+        inputSchema: {
+            userId: z.string().optional(),
+            anonymousId: z.string().optional(),
+            customerId: z.string().optional(),
+            appleOriginalTransactionId: z.string().optional(),
+            googlePurchaseToken: z.string().optional(),
+            stripeCustomerId: z.string().optional(),
+        },
+        _meta: { ui: { resourceUri: MOAT_URI } },
+        annotations: RO,
+    }, async (args) => {
+        if (!Object.values(args).some(Boolean)) {
+            return { content: [{ type: "text", text: "Identify the customer with at least one of: userId, anonymousId, customerId, appleOriginalTransactionId, googlePurchaseToken, stripeCustomerId." }], isError: true };
+        }
+        const r = await fetchData(ctx, "/v1/crossmatch", { ...args });
+        if (r.error)
+            return { content: [{ type: "text", text: r.error }], isError: true };
+        const d = (r.data ?? {});
+        const rev = d.revenue ?? {};
+        const ent = d.entitlements ?? {};
+        const rc = d.readCost;
+        const summary = d.revenue || d.readCost
+            ? `Pays ${rev.monthlyCents != null ? "$" + (rev.monthlyCents / 100).toFixed(2) : "—"}/mo, ${ent.active ?? 0} entitlements${rc ? `, ${rc.reads} reads / ${rc.windowDays}d` : ""}.`
+            : "No customer matched that identifier.";
+        return { content: [{ type: "text", text: summary }], structuredContent: (d ?? {}) };
+    });
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@cross-deck/ai",
+  "version": "0.2.0",
+  "description": "Crossdeck AI — the MCP connector that lets Claude, Cursor, and any AI tool query and operate your Crossdeck app. The product is 'Crossdeck understands your app'; MCP is just the transport.",
+  "type": "module",
+  "bin": {
+    "crossdeck-ai": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').cpSync('ui','dist/ui',{recursive:true})\"",
+    "start": "node dist/server.js",
+    "test": "node --test dist/*.test.js",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "crossdeck",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "claude",
+    "cursor",
+    "analytics",
+    "revenue",
+    "entitlements"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.4",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5.5.0"
+  }
+}