@absolutejs/mcp 0.17.0 → 0.17.1

package/CHANGELOG.md

@@ -6,6 +6,12 @@ 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

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,16 @@
   "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",

package/docs/host-canaries.md

@@ -0,0 +1,60 @@
+# 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
+
+Tests ran against the built `0.17.0` runtime, with the reusable canary distributed starting in `0.17.1`.
+
+| 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                                       | Browser redirected to sign-in                                            | Not tested; requires signed-in test session and reachable synthetic staging endpoint                       |
+| 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 real conversational/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.

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.1"
 }