@absolutejs/mcp 0.17.0 → 0.17.2

package/CHANGELOG.md

@@ -6,6 +6,18 @@ 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.2 — 2026-09-11
+
+### Added
+
+- **Record verified Claude web rendering, refresh, pagination and narrow-viewport host canary evidence**
+
+## 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

package/canary/results/2026-09-11-claude-web.json

@@ -0,0 +1,30 @@
+{
+  "date": "2026-09-11",
+  "runtimePackage": "@absolutejs/mcp@0.17.1",
+  "host": "Claude web custom connector",
+  "browser": "Windows Chrome 152.0.7977.83",
+  "data": "synthetic only",
+  "protocol": "2025-06-18",
+  "appsMimeType": "text/html;profile=mcp-app",
+  "successfulCalls": {
+    "get_billing_status": 2,
+    "get_usage_report": 2,
+    "list_receipts": 2
+  },
+  "observed": [
+    "Three native report views rendered",
+    "Balance refresh succeeded",
+    "Usage refresh and daily row expansion succeeded",
+    "Receipt pagination ended with empty page and hidden Older receipts button",
+    "No extra tool calls from initial rendering or page reload",
+    "390px desktop viewport: app widths 322px; no horizontal document overflow"
+  ],
+  "notVerified": [
+    "Native mobile application",
+    "OAuth login",
+    "Account isolation",
+    "Expired-session reconnect",
+    "IDE hosts"
+  ],
+  "cleanup": "Temporary connector and development route removed"
+}

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,26 @@
   "contract": 1,
   "name": "@absolutejs/mcp",
   "releases": [
+    {
+      "version": "0.17.2",
+      "date": "2026-09-11",
+      "changes": [
+        {
+          "kind": "added",
+          "summary": "Record verified Claude web rendering, refresh, pagination and narrow-viewport host canary evidence"
+        }
+      ]
+    },
+    {
+      "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",

package/docs/host-canaries.md

@@ -0,0 +1,70 @@
+# Repeatable MCP host canaries
+
+The package ships `canary/server.ts`: a loopback-only, synthetic billing endpoint using the built package handler, report tools and Apps resources. It requires Bun. It has no customer database, authentication credentials, checkout tool or payment mutations. Never mount this unauthenticated fixture in an application or expose it as a production endpoint.
+
+From an installed package, run `bun node_modules/@absolutejs/mcp/canary/server.ts`. From this repository, build first, then `bun run canary`. The fixed endpoint is `http://127.0.0.1:4428/mcp`. Startup validates all four report calls before listening. Stop it with Ctrl-C after the test. A port conflict fails startup rather than replacing another service.
+
+The JSONL log records protocol methods, status, client name/version, negotiated protocol, advertised Apps MIME types and tool success. It omits headers, session IDs, tool arguments and report bodies. Keep host transcripts local: host logs can contain unrelated account or environment information. Commit only reviewed evidence.
+
+## Host connections
+
+Claude Code supports a per-invocation config, so testing need not modify an existing connector:
+
+```sh
+claude --strict-mcp-config --mcp-config '{"mcpServers":{"billing_canary":{"type":"http","url":"http://127.0.0.1:4428/mcp"}}}'
+```
+
+Codex CLI supports invocation-scoped configuration:
+
+```sh
+codex --config 'mcp_servers.billing_canary.url="http://127.0.0.1:4428/mcp"' --config 'mcp_servers.billing_canary.required=true'
+```
+
+For VS Code, use an isolated test workspace with this `.vscode/mcp.json`, then start the server from the MCP configuration UI:
+
+```json
+{
+  "servers": {
+    "billing_canary": { "type": "http", "url": "http://127.0.0.1:4428/mcp" }
+  }
+}
+```
+
+These commands describe connection setup, not proof that a host renders Apps. Conversational services that require an externally reachable endpoint need a dedicated synthetic staging endpoint and a signed-in test account. The loopback fixture is not directly reachable from those hosted services; do not point them at a customer's billing account to substitute for this test.
+
+## Test sequence and acceptance
+
+Ask the host to call `get_billing_status`, `get_usage_report` with `from=2026-09-01` and `to=2026-09-11`, `list_receipts`, then `list_receipts` with the returned `nextCursor`.
+
+Expected: zero available credits, 12 reserved, no subscription or portal access; 8 credits consumed across 2 events; one USD receipt for 1000 cents with 200 refunded; an empty final page and null cursor. All four calls must succeed. Check actual tool results and server logs, not just the model's success statement.
+
+Record the exact host version/surface, transport, requested and negotiated protocol, Apps MIME capability, tool discovery metadata, tool-call results, and visible rendering. If MIME negotiation is absent, all three tools must omit UI metadata and remain usable as text/structured results. If present, check the three views, refresh, pagination, narrow widths and absence of extra initial tool calls. Separately exercise expired-session reconnect and account isolation against an authenticated staging deployment; the synthetic endpoint does not certify OAuth, tenant isolation, payment permission or migration behavior.
+
+## Observed September 11, 2026
+
+Terminal tests ran against the built `0.17.0` runtime. The later Claude web test used the published `0.17.1` canary.
+
+| Host                                             | Negotiation                                                              | Observed result                                                                                            |
+| ------------------------------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| Claude Code 2.1.265, print mode, Streamable HTTP | Requested 2025-11-25; accepted server 2025-06-18; no Apps MIME extension | Four read calls passed, including cursor pagination; text/structured fallback; no embedded rendering claim |
+| Codex CLI 0.154.0, exec mode, Streamable HTTP    | Requested and accepted 2025-06-18; no Apps MIME extension                | Four read calls passed, including cursor pagination; text/structured fallback; no embedded rendering claim |
+| Claude web, Windows Chrome 152.0.7977.83         | Apps MIME advertised; accepted 2025-06-18                                | Three native views, refresh and pagination passed                                                          |
+| VS Code 1.135.0                                  | Installed version confirmed                                              | Interactive Copilot/MCP Apps UI not exercised                                                              |
+| Cursor, Gemini CLI, goose                        | Executables unavailable in this environment                              | Not tested                                                                                                 |
+| ChatGPT hosted surfaces                          | No host canary performed                                                 | Not tested                                                                                                 |
+
+Both tested terminal clients tolerated GET 405 (no standalone SSE stream) and discovered all three tools. Claude Code also sent a `server/discover` probe that received 400 before successful initialization. These observations do not establish support in other versions or distributions. Initial fixture-development attempts failed receipt validation; the final fixture uses the billing package cursor encoder, supplies a valid receipt ID, and validates its records before listening.
+
+The remaining release gates are other host surfaces including IDE rendering, authenticated staging reconnect/isolation, then the product's migration and commerce approval gates. This evidence does not enable any host commerce profile.
+
+Sources: [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), [VS Code MCP servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers), and the installed `claude --help` / `claude mcp --help` output. Host observations above come from actual local runs, not documentation claims.
+
+## Claude web rendering evidence
+
+The signed-in custom-connector test used the published 0.17.1 synthetic canary and native Windows Chrome 152.0.7977.83. Claude identified the reports as three interactive tools. All three HTML resource reads and initial tool calls succeeded. There were exactly three initial report calls; loading/reloading the views did not issue extra tool calls. Explicit balance refresh, usage refresh and Older receipts produced three further successful read calls. Daily usage expanded correctly. The final receipt page was empty and the Older receipts button disappeared. At a 390-pixel desktop viewport the embedded views had 322-pixel widths and no horizontal document overflow. This is not a native mobile-app check.
+
+A temporary public tunnel allowed discovery but failed tool execution before reaching the handler. The passing run used a dedicated HTTPS development endpoint forwarding to the unchanged synthetic fixture. The temporary connector and route were removed afterward. No production application, billing data, OAuth grants or commerce profiles were changed. Reviewed aggregate evidence is in `canary/results/2026-09-11-claude-web.json`; it includes no endpoint addresses, headers, session IDs, credentials or chat transcripts. Patch 0.17.2 distributes this evidence; report runtime code is unchanged.
+
+For Windows/WSL testing, a headed Linux browser may not appear on the Windows desktop. Use a native Windows test browser with a separate persistent profile and loopback CDP endpoint. Reuse one Playwright CDP connection. If existing cross-origin frames are missing from automation, reload with that connection established; Claude uses a wrapper frame and a nested `about:blank` app frame. Never commit browser profiles or credentials.
+
+Conversational rendering is verified for this exact surface. VS Code/Cursor interactive rendering and authenticated staging reconnect/account-isolation remain separate open gates.

package/docs/mcp-apps.md

@@ -54,3 +54,7 @@ Protocol tests cover negotiation, text fallback, spoofed later capabilities, aut
 Passing this fixture does not certify a particular conversational, IDE or terminal host. Real-host capability/refresh/session-expiry checks remain required before activation. Rendering support never supplies checkout permission; apply [commerce-host-rules.md](commerce-host-rules.md) independently.
 
 Primary references checked September 11, 2026: [stable Apps specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx), [official quickstart](https://apps.extensions.modelcontextprotocol.io/api/documents/quickstart.html), [App SDK](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html), [AppBridge SDK](https://apps.extensions.modelcontextprotocol.io/api/classes/app-bridge.AppBridge.html).
+
+## Real-host canaries
+
+See [the reusable host canary and observed results](host-canaries.md) for isolated connection instructions, acceptance criteria and remaining rollout gates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "author": "Alex Kahn",
-  "description": "Serve a remote Model Context Protocol endpoint (streamable HTTP, stateless) from a tool/prompt/resource registry \u2014 OAuth bearer auth, RFC 9728 discovery, and per-call guards are yours to wire, the JSON-RPC protocol is done correctly by construction.",
+  "description": "Serve a remote Model Context Protocol endpoint (streamable HTTP, stateless) from a tool/prompt/resource registry — OAuth bearer auth, RFC 9728 discovery, and per-call guards are yours to wire, the JSON-RPC protocol is done correctly by construction.",
   "devDependencies": {
     "@absolutejs/agency": "0.7.1",
     "@absolutejs/changelog": "^0.6.0",
@@ -69,7 +69,9 @@
     "dist",
     "docs/commerce-host-rules.md",
     "docs/mcp-apps.md",
-    "docs/third-party"
+    "docs/third-party",
+    "canary",
+    "docs/host-canaries.md"
   ],
   "scripts": {
     "build": "bun run build:apps && rm -rf dist && bun build src/index.ts src/manifest.ts src/commerce.ts src/apps.ts --outdir dist --root ./src --target=bun --external @absolutejs/agency --external '@absolutejs/agency/*' --external elysia && tsc --emitDeclarationOnly --project tsconfig.json && absolute-manifest emit",
@@ -77,10 +79,12 @@
     "release": "bun run format && bun run test && bun run build && bun publish",
     "test": "bun run build:apps && bun test",
     "typecheck": "bun run build:apps && tsc --noEmit --project tsconfig.json",
-    "check:package": "bun run typecheck && bun run test && bun run build && absolute-changelog check",
+    "check:package": "bun run typecheck && bun run test && bun run build && bun run check:canary && absolute-changelog check",
     "prepublishOnly": "bun run check:package",
-    "build:apps": "bun scripts/build-apps.ts"
+    "build:apps": "bun scripts/build-apps.ts",
+    "canary": "bun canary/server.ts",
+    "check:canary": "tsc --noEmit --strict --skipLibCheck --moduleResolution bundler --module esnext --target esnext --types bun canary/server.ts"
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.17.0"
+  "version": "0.17.2"
 }