@absolutejs/mcp 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -6,6 +6,23 @@ This file is generated by `absolute-changelog` from the entries in
 `changelog/`. Edit an entry, not this file — and add new ones under
 `changelog/unreleased/`.
 
+## 0.17.1 — 2026-09-11
+
+### Added
+
+- **Ship a preflight-validated synthetic host canary and record Claude Code and Codex terminal interoperability evidence**
+
+## 0.17.0 — 2026-09-11
+
+### Added
+
+- **Negotiate MCP Apps with persisted capabilities, guarded offline UI resources and reusable SDK-backed billing views**
+- **Preserve remote UI metadata in the client and expose immutable PostgreSQL migration entries**
+
+### Changed
+
+- **Extend McpClientOptions, McpRemoteTool, createSessionRegistry, McpSessionStore, McpServerConfig, McpTool and McpToolResult with optional Apps capability and metadata fields; existing text-only callers remain supported** (`McpClientOptions`, `McpRemoteTool`, `createSessionRegistry`, `McpSessionStore`, `McpServerConfig`, `McpTool`, `McpToolResult`)
+
 ## 0.16.0 — 2026-09-11
 
 ### Added

package/README.md

@@ -433,3 +433,7 @@ on the Change Date.
 `createCheckoutHandoffTool` and `createPurchaseStatusTool` provide account-bound credit checkout and recovery contracts. The issuer must bind server pricing and identity; route these tools through the commerce guard. Checkout is classified as `external_checkout`, so restricted and unverified channels cannot discover or execute it. Status works at zero credits. Never pass card data in tool input. See [host rules](docs/commerce-host-rules.md).
 
 `createBillingReportTools` binds billing status, paginated receipts, and bounded UTC usage reports to authenticated reader callbacks. These non-transactional tools remain available at zero balance. The shared billing projections discard payment/provider secrets and enforce reconciled usage breakdowns. `createBillingManagementTool` returns a fixed HTTPS browser page requiring normal browser authentication; because that page can initiate purchases, it retains `external_checkout` commerce classification. Never label a purchase-capable page informational to bypass host restrictions.
+
+## Interactive MCP Apps
+
+`createBillingApps()` adds reusable read-only credit, usage and receipt views with the official browser SDK. Apps capability negotiation, guarded resources and text fallbacks live in the package. See [MCP Apps](docs/mcp-apps.md) for integration, session migration, CSP restrictions and host validation boundaries.

package/canary/results/2026-09-11-terminal.jsonl

@@ -0,0 +1,20 @@
+{"ready":true,"url":"http://127.0.0.1:4428/mcp","data":"synthetic","payments":false}
+{"method":"server/discover","status":400}
+{"method":"initialize","status":200,"client":"claude-code","version":"2.1.265","requestedProtocol":"2025-11-25","negotiatedProtocol":"2025-06-18","appsMimeTypes":[],"elicitation":true}
+{"method":"notifications/initialized","status":202}
+{"method":"GET","status":405}
+{"method":"tools/list","status":200,"tools":[{"name":"get_billing_status","ui":false},{"name":"list_receipts","ui":false},{"name":"get_usage_report","ui":false}]}
+{"method":"resources/list","status":200}
+{"method":"tools/call","status":200,"tool":"get_billing_status","isError":false}
+{"method":"tools/call","status":200,"tool":"get_usage_report","isError":false}
+{"method":"tools/call","status":200,"tool":"list_receipts","isError":false}
+{"method":"tools/call","status":200,"tool":"list_receipts","isError":false}
+{"method":"initialize","status":200,"client":"codex-mcp-client","version":"0.154.0","requestedProtocol":"2025-06-18","negotiatedProtocol":"2025-06-18","appsMimeTypes":[],"elicitation":true}
+{"method":"notifications/initialized","status":202}
+{"method":"GET","status":405}
+{"method":"tools/list","status":200,"tools":[{"name":"get_billing_status","ui":false},{"name":"list_receipts","ui":false},{"name":"get_usage_report","ui":false}]}
+{"method":"tools/call","status":200,"tool":"get_billing_status","isError":false}
+{"method":"tools/call","status":200,"tool":"get_usage_report","isError":false}
+{"method":"tools/call","status":200,"tool":"list_receipts","isError":false}
+{"method":"tools/call","status":200,"tool":"list_receipts","isError":false}
+{"method":"DELETE","status":204}

package/canary/server.ts

@@ -0,0 +1,154 @@
+/** Synthetic host canary. Never mount this handler in a customer application. */
+import {
+  createMcpHandler,
+  createBillingApps,
+  createBillingReportTools,
+} from "@absolutejs/mcp";
+import { encodeReceiptCursor } from "@absolutejs/billing/reports";
+const apps = createBillingApps();
+const id = "00000000-0000-4000-8000-000000000001";
+const at = "2026-09-01T00:00:00.000Z";
+const readers = createBillingReportTools({
+  status: async () => ({
+    automaticRefill: false,
+    credits: {
+      remaining: 0,
+      reserved: 12,
+      purchased: 0,
+      promotional: 0,
+      debt: 0,
+    },
+    portalAccess: false,
+    subscription: null,
+  }),
+  receipts: async ({ cursor }) => ({
+    receipts: cursor
+      ? []
+      : [
+          {
+            id,
+            issuedAt: at,
+            source: "credit_purchase",
+            amountCents: 1000,
+            refundedAmountCents: 200,
+            currency: "USD",
+            status: "partially_refunded",
+          },
+        ],
+    nextCursor: cursor ? null : encodeReceiptCursor({ at, id }),
+  }),
+  usage: async (range) => ({
+    ...range,
+    creditsConsumed: 8,
+    events: 2,
+    byFeature: [{ feature: "fixture_workflow", credits: 8, events: 2 }],
+    byDay: [{ day: range.from, credits: 8, events: 2 }],
+  }),
+});
+const handler = createMcpHandler({
+  issuer: "http://127.0.0.1:4428",
+  path: "/mcp",
+  serverInfo: { name: "absolute-billing-canary", version: "1" },
+  supportedProtocols: ["2025-06-18"],
+  authorize: async () => ({
+    ok: true,
+    caller: "synthetic-fixture",
+    scopes: [],
+  }),
+  commerce: () => ({ profiles: ["unknown"] }),
+  apps: { resources: apps.resources },
+  tools: () => apps.decorateTools(readers),
+});
+// Fail before accepting a host if synthetic records violate the public contract.
+for (const [name, args] of [
+  ["get_billing_status", {}],
+  ["get_usage_report", { from: "2026-09-01", to: "2026-09-11" }],
+  ["list_receipts", {}],
+  ["list_receipts", { cursor: encodeReceiptCursor({ at, id }) }],
+] as const) {
+  const response = await handler(
+    new Request("http://127.0.0.1:4428/mcp", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "mcp-protocol-version": "2025-06-18",
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name, arguments: args },
+      }),
+    }),
+  );
+  const body = await response?.json();
+  if (!response?.ok || !body?.result || body.error || body.result.isError)
+    throw Error(`Canary preflight failed: ${name}`);
+}
+Bun.serve({
+  hostname: "127.0.0.1",
+  port: 4428,
+  fetch: async (request) => {
+    let rpc;
+    try {
+      if (request.method === "POST") rpc = await request.clone().json();
+    } catch {
+      /* Handler owns malformed input. */
+    }
+    const response =
+      (await handler(request)) ?? new Response("Not found", { status: 404 });
+    let body;
+    if (response.headers.get("content-type")?.includes("application/json")) {
+      try {
+        body = await response.clone().json();
+      } catch {
+        /* No raw response logging. */
+      }
+    }
+    // Only explicit protocol fields: never headers, tokens, session IDs, arguments or report bodies.
+    console.log(
+      JSON.stringify({
+        method: rpc?.method ?? request.method,
+        status: response.status,
+        ...(rpc?.method === "initialize"
+          ? {
+              client: rpc.params?.clientInfo?.name,
+              version: rpc.params?.clientInfo?.version,
+              requestedProtocol: rpc.params?.protocolVersion,
+              negotiatedProtocol: body?.result?.protocolVersion,
+              appsMimeTypes:
+                rpc.params?.capabilities?.extensions?.[
+                  "io.modelcontextprotocol/ui"
+                ]?.mimeTypes ?? [],
+              elicitation: !!rpc.params?.capabilities?.elicitation,
+            }
+          : {}),
+        ...(rpc?.method === "tools/list"
+          ? {
+              tools: body?.result?.tools?.map(
+                (tool: { name: string; _meta?: { ui?: unknown } }) => ({
+                  name: tool.name,
+                  ui: !!tool._meta?.ui,
+                }),
+              ),
+            }
+          : {}),
+        ...(rpc?.method === "tools/call"
+          ? {
+              tool: rpc.params?.name,
+              isError: body?.result?.isError ?? !!body?.error,
+            }
+          : {}),
+      }),
+    );
+    return response;
+  },
+});
+console.log(
+  JSON.stringify({
+    ready: true,
+    url: "http://127.0.0.1:4428/mcp",
+    data: "synthetic",
+    payments: false,
+  }),
+);

package/changelog.json

@@ -2,6 +2,43 @@
   "contract": 1,
   "name": "@absolutejs/mcp",
   "releases": [
+    {
+      "version": "0.17.1",
+      "date": "2026-09-11",
+      "changes": [
+        {
+          "kind": "added",
+          "summary": "Ship a preflight-validated synthetic host canary and record Claude Code and Codex terminal interoperability evidence"
+        }
+      ]
+    },
+    {
+      "version": "0.17.0",
+      "date": "2026-09-11",
+      "changes": [
+        {
+          "kind": "added",
+          "summary": "Negotiate MCP Apps with persisted capabilities, guarded offline UI resources and reusable SDK-backed billing views"
+        },
+        {
+          "kind": "added",
+          "summary": "Preserve remote UI metadata in the client and expose immutable PostgreSQL migration entries"
+        },
+        {
+          "kind": "changed",
+          "summary": "Extend McpClientOptions, McpRemoteTool, createSessionRegistry, McpSessionStore, McpServerConfig, McpTool and McpToolResult with optional Apps capability and metadata fields; existing text-only callers remain supported",
+          "symbols": [
+            "McpClientOptions",
+            "McpRemoteTool",
+            "createSessionRegistry",
+            "McpSessionStore",
+            "McpServerConfig",
+            "McpTool",
+            "McpToolResult"
+          ]
+        }
+      ]
+    },
     {
       "version": "0.16.0",
       "date": "2026-09-11",