mcp-context-card 1.7.1 → 1.8.0

package/.well-known/ai-catalog.json

@@ -11,7 +11,7 @@
       "data": {
         "$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
         "name": "io.github.Wolfe-Jam/mcp-context-card",
-        "version": "1.7.1",
+        "version": "1.8.0",
         "title": "MCP Context Card",
         "description": "MCP server for a project's context (AGENTS.md), memory, and identity — base or drop-in extension.",
         "websiteUrl": "https://github.com/Wolfe-Jam/mcp-context-card",

package/.well-known/fafa

@@ -13,7 +13,7 @@ agent:
   # a deployment for your own project uses your domain.
   id: "urn:air:faf.one:agent:mcp-context-card"
   vendor: "io.github.Wolfe-Jam"
-  version: "1.7.1"
+  version: "1.8.0"
   description: >-
     The essential MCP components for a project's context (AGENTS.md),
     cross-session memory, and identity — a base MCP on its own, or a

package/AGENTS.md

@@ -20,8 +20,8 @@ Node 22 or newer. No other system dependencies.
 ## Build
 
 ```bash
-npm run build       # tsc -p tsconfig.build.json  →  dist/
-npm run typecheck   # tsc --noEmit over src/ + test/
+npm run build       # tsc -p tsconfig.build.json, then copy the bundled card script → dist/
+npm run typecheck   # tsc --noEmit over src/ + test/, then the browser script
 ```
 
 ## Test
@@ -50,6 +50,8 @@ code's shape moved without `project.faf`) on Linux.
 | `src/author.ts` | `author_agents_md` — BETTER via `agents-md-facts`, BEST when `project.faf` exists |
 | `src/md.ts` | a minimal dependency-free Markdown → HTML renderer |
 | `src/render-card.ts` | the card — identity + this file + memory + discovery, as one HTML page |
+| `src/browser/card-app.ts` | the card's MCP Apps script (size, inline view), inlined only into the `ui://` resource |
+| `scripts/bundle-card-app.mjs` | bundles the script so the sandbox loads nothing from the network |
 | `src/memory.ts` → `src/faf/parse-fafm.ts` | file-backed `remember` / `recall` / `forget` |
 | `src/identity.ts` | `whoami` (`.fafa` → `package.json` fallback) + the `_meta` context block |
 | `src/catalog-gen.ts` | writes `.well-known/ai-catalog.json` from the same three sources |
@@ -70,7 +72,7 @@ code's shape moved without `project.faf`) on Linux.
 the **same three sources**: this file, `project.fafm`, `.well-known/fafa`.
 Change what one exposes and you must change the others. `npm run catalog:check`
 and `npm run card:check` enforce it in CI — each regenerates its surface and
-fails on any diff.
+fails on any diff. `card:check` also fails if a plain card exceeds 64 KB.
 
 ## Safety
 

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
 
+## 1.8.0
+
+Speaks MCP 2026-07-28 as well as 2025, on the MCP SDK v2, and the card fits a chat panel. Library users: see the breaking note at the end.
+
+- **The card tells the host how big it is.** Hosts that support MCP Apps
+  read `ui://mcp-context-card/card.html`. That resource is the card plus
+  the start-up exchange (`ui/initialize`, then
+  `ui/notifications/initialized`) and `ui/notifications/size-changed`
+  when the document's size changes. The helper is
+  `@modelcontextprotocol/ext-apps` `App` with `autoResize: true`, bundled
+  at build time (`scripts/bundle-card-app.mjs`) into that resource only, so
+  the sandbox still has no CDN and no external request. The tool text for a
+  client without MCP Apps, `save_context_card`, `GET /card`, and the CLI
+  are the plain card, without that script. `card:check` fails if a plain
+  card exceeds 64 KB. The card still works with the script off.
+  `card --stdout` exits 0 when the reader closes the pipe early, and exits
+  1 with a message on any other failed write.
+- **You choose whether the host's card carries the helper.**
+  `MCP_CONTEXT_CARD_APP=helper` (the default) or `plain`. `plain` makes the
+  `ui://` card the plain card (~30 KB, no MCP Apps messages) for hosts where
+  the ~700 KB helper isn't worth it. Only that resource changes.
+  `list_context_sources` reports the active value. Any case is read; an
+  unknown value warns once on stderr and uses `helper`.
+- **An inline view for chat panels.** Inside an MCP Apps host, display mode
+  `inline` or `pip` (`McpUiHostContext.displayMode`) shows a mini card:
+  monogram, name, kind · version, one line, and a counts strip (sections ·
+  facts · identity). One action, "Open full card", calls
+  `requestDisplayMode({ mode: "fullscreen" })` when `availableDisplayModes`
+  includes `fullscreen`. The full card shows when the host is fullscreen, or
+  when there is no host. A host that stays smaller points to
+  `save_context_card`, which writes the full card to `context-card.html`.
+  The card declares the display modes it supports (inline, pip,
+  fullscreen) when it starts, as the MCP Apps spec requires. The mini card
+  is part of the `ui://` resource only, hidden until the host says the
+  panel is inline. The plain card does not include it, and the script off
+  still shows the full card.
+- **Both protocol eras, both transports.** A client that opens with
+  `server/discover` (Claude Code, goose) connects on 2026-07-28; a client
+  that opens with `initialize` gets 2025, unchanged. The Server Card lists
+  2026-07-28 first. See [docs/TRANSPORT.md](docs/TRANSPORT.md#protocol-eras).
+- **Roots on 2026-07-28** are asked in-band (`input_required`), once per
+  connection, since that revision has no server-to-client requests and no
+  `roots/list_changed`. Roots sent with a later call replace the first. A
+  client that declares `roots` but can't answer now fails the tool call on
+  2026-07-28; on 2025 it still falls back to the start directory.
+- **Breaking for library users** (the `mcp-context-card/server` export): it
+  is built on `@modelcontextprotocol/server` 2.x instead of
+  `@modelcontextprotocol/sdk` 1.x. `createServer()` returns a v2 `Server`, so
+  `setRequestHandler(SomeRequestSchema, …)` now throws; register by method
+  string (`setRequestHandler("prompts/list", …)`). The types come from
+  `@modelcontextprotocol/server`, and `zod` 4 comes with it. See the SDK's
+  [upgrade guide](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/migration/upgrade-to-v2.md).
+  New: `serveStdioServer()` serves stdio on both eras; `serve(transport)` is
+  kept and serves 2025. The CLI and the MCP surface are unchanged.
+
 ## 1.7.1
 
 The business card printer is now its own package.

package/README.md

@@ -4,6 +4,7 @@
 [![CI](https://github.com/Wolfe-Jam/mcp-context-card/actions/workflows/ci.yml/badge.svg)](https://github.com/Wolfe-Jam/mcp-context-card/actions/workflows/ci.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![mcp-context-card MCP server](https://glama.ai/mcp/servers/Wolfe-Jam/mcp-context-card/badges/score.svg)](https://glama.ai/mcp/servers/Wolfe-Jam/mcp-context-card)
+[![Business card · Get yours →](https://wolfe-jam.github.io/agent-business-card/badge.svg)](https://wolfe-jam.github.io/agent-business-card/?repo=Wolfe-Jam/mcp-context-card)
 
 **Get one. Or add it to yours.** The essential MCP server for a project's
 context, memory, and identity — discoverable to any MCP client, and
@@ -95,8 +96,22 @@ people: read it, screenshot it, drop it in a PR, put it on a status page.
 
 Flip, tabs and the view switch are plain CSS, so they work with scripts off.
 The one small inline script adds Expand all, opens a `#section` link on the
-back, and opens every section for printing. `--expanded` / `?expand=all`
-renders both faces flat, every section open, for a screenshot or print.
+back, and opens every section for printing. Hosts that support MCP Apps read
+`ui://mcp-context-card/card.html`: this same page, plus a hidden inline view
+and the helper bundled in (`scripts/bundle-card-app.mjs`), so the host can
+fit its frame. Nothing is loaded from the network. The saved
+`context-card.html`, `GET /card`, and the CLI are the plain page, without
+that helper and without the inline view.
+
+In a host, the inline view is a mini card for the panel: monogram, name,
+kind · version, one line, and a strip of counts (sections · facts ·
+identity), with one action, "Open full card". It shows when the host's
+display mode is inline (or picture-in-picture). Fullscreen, and any page
+with no host, is the full card. "Open full card" asks the host for
+fullscreen; a host that stays smaller points to `save_context_card`, which
+writes the full card to `context-card.html`.
+`--expanded` / `?expand=all` renders both faces flat, every section open,
+for a screenshot or print.
 
 ```
 npx mcp-context-card card            # at a terminal: writes context-card.html and opens it
@@ -192,6 +207,13 @@ never serves or lists `project.fafm`, unless you set
 `MCP_CONTEXT_CARD_PUBLISH_MEMORY=1`. Details:
 [docs/TRANSPORT.md](./docs/TRANSPORT.md#security-local-by-default).
 
+In a host that shows MCP Apps (goose, for one), the card comes with the
+official MCP Apps helper, so it reports its size and fits its frame (about
+700 KB, loaded by the host, not the model). For the plain card instead
+(about 30 KB, the host's default frame), set
+`"env": { "MCP_CONTEXT_CARD_APP": "plain" }`. Everywhere else the card is
+plain either way.
+
 If `command: "npx"` fails to spawn (`spawn npx ENOENT` — seen on Cursor, whose
 host process doesn't inherit a shell `PATH`), point `command` at `node` and
 the installed `dist/bin.js` instead — see
@@ -274,7 +296,7 @@ over both transports:
 4. **Discovery** — `list_context_sources()`, then the same server over stateless
    HTTP with its `.well-known` routes and `GET /card`.
 
-210 tests on Linux, macOS, and Windows, coverage‑gated in CI.
+245 tests on Linux, macOS, and Windows, coverage‑gated in CI.
 `npm run wjttc` runs the WJTTC certification suite (seven tiers, from protocol
 and Server Card conformance to stdio/HTTP parity and the shipped package). Two spawn a real
 child process and check a remembered fact survives the restart — one against

package/dist/bin.d.ts

@@ -8,7 +8,7 @@ export interface Launch {
     root: string;
 }
 /** what a bare `--help` / `help` prints. */
-export declare const HELP = "mcp-context-card 1.7.1\nServe a project's context (AGENTS.md), memory, and identity over MCP.\n\nUSAGE\n  mcp-context-card                  stdio MCP server \u2014 what an MCP host spawns (default)\n  mcp-context-card --http           stateless Streamable HTTP on PORT (default 3000)\n  mcp-context-card --stdio          force stdio even when PORT is set\n  mcp-context-card card             this dir's context card \u2014 opens it in your browser\n                                    at a terminal; HTML to stdout when piped ( > f.html )\n                                      --theme light|dark   --accent #hex\n                                      --expanded (all sections open)   --portrait   --stdout\n  mcp-context-card --help           this text\n  mcp-context-card --version        print version\n\nENV\n  MCP_CONTEXT_CARD_ROOT   read AGENTS.md / project.fafm / .well-known/ from here\n  PORT                    if set, run HTTP instead of stdio\n  HOST                    HTTP bind address (default 127.0.0.1, this machine\n                          only); 0.0.0.0 exposes it, e.g. in a container\n  MCP_CONTEXT_CARD_ALLOWED_HOSTS / _ALLOWED_ORIGINS\n                          comma-separated Host names / browser origins to\n                          accept besides this machine's own (reverse proxy, web app)\n  MCP_CONTEXT_CARD_PUBLISH_MEMORY=1\n                          HTTP: serve project.fafm, list it in the AI Catalog,\n                          and show its facts on an exposed /card (off: memory\n                          is session data). HTTP has no auth\n\nA bare run is an stdio server: it waits for a host to speak JSON-RPC on stdin,\nso it looks idle at a terminal. Try `card` (opens your context in a browser) or `--http`.\nhttps://github.com/Wolfe-Jam/mcp-context-card\n";
+export declare const HELP = "mcp-context-card 1.8.0\nServe a project's context (AGENTS.md), memory, and identity over MCP.\n\nUSAGE\n  mcp-context-card                  stdio MCP server \u2014 what an MCP host spawns (default)\n  mcp-context-card --http           stateless Streamable HTTP on PORT (default 3000)\n  mcp-context-card --stdio          force stdio even when PORT is set\n  mcp-context-card card             this dir's context card \u2014 opens it in your browser\n                                    at a terminal; HTML to stdout when piped ( > f.html )\n                                      --theme light|dark   --accent #hex\n                                      --expanded (all sections open)   --portrait   --stdout\n  mcp-context-card --help           this text\n  mcp-context-card --version        print version\n\nENV\n  MCP_CONTEXT_CARD_ROOT   read AGENTS.md / project.fafm / .well-known/ from here\n  PORT                    if set, run HTTP instead of stdio\n  HOST                    HTTP bind address (default 127.0.0.1, this machine\n                          only); 0.0.0.0 exposes it, e.g. in a container\n  MCP_CONTEXT_CARD_ALLOWED_HOSTS / _ALLOWED_ORIGINS\n                          comma-separated Host names / browser origins to\n                          accept besides this machine's own (reverse proxy, web app)\n  MCP_CONTEXT_CARD_PUBLISH_MEMORY=1\n                          HTTP: serve project.fafm, list it in the AI Catalog,\n                          and show its facts on an exposed /card (off: memory\n                          is session data). HTTP has no auth\n\nA bare run is an stdio server: it waits for a host to speak JSON-RPC on stdin,\nso it looks idle at a terminal. Try `card` (opens your context in a browser) or `--http`.\nhttps://github.com/Wolfe-Jam/mcp-context-card\n";
 /**
  * The address the HTTP server binds: `HOST`, else 127.0.0.1. Local by default,
  * as the MCP transports spec recommends; a hosted deploy sets HOST=0.0.0.0.

package/dist/bin.js

@@ -20,9 +20,8 @@
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { NAME, VERSION } from "./constants.js";
-import { ROOT, serve } from "./server.js";
+import { ROOT, serveStdioServer } from "./server.js";
 /** what a bare `--help` / `help` prints. */
 export const HELP = `${NAME} ${VERSION}
 Serve a project's context (AGENTS.md), memory, and identity over MCP.
@@ -133,6 +132,16 @@ if (entryPath && import.meta.url === pathToFileURL(entryPath).href) {
         // Piped / redirected (or --stdout) → raw HTML on stdout, unchanged.
         // A bare run at a terminal → the HTML is noise; write a file and open it.
         if (!process.stdout.isTTY || argv.includes("--stdout")) {
+            // A large project's card can be bigger than a pipe buffer. `head` closes
+            // after the first bytes; the rest of the write is EPIPE, which is the
+            // reader finishing. Any other error (disk full, bad descriptor) is a
+            // failed write: say so and exit 1.
+            process.stdout.on("error", (err) => {
+                if (err.code === "EPIPE")
+                    process.exit(0);
+                process.stderr.write(`${NAME} · card --stdout: ${err.message}\n`);
+                process.exit(1);
+            });
             process.stdout.write(html);
         }
         else {
@@ -168,7 +177,7 @@ if (entryPath && import.meta.url === pathToFileURL(entryPath).href) {
         // With no MCP_CONTEXT_CARD_ROOT, find the user's project: the host's MCP
         // roots, then the start directory. So a host needs no config to show yours.
         const { openInBrowser } = await import("./open.js");
-        await serve(new StdioServerTransport(), root, {
+        serveStdioServer(root, {
             openFile: openInBrowser,
             detectRoot: !process.env.MCP_CONTEXT_CARD_ROOT,
         });