mcp-context-card 1.4.0 → 1.6.0

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

@@ -6,33 +6,55 @@
   },
   "entries": [
     {
-      "identifier": "urn:air:mcp-context-card:context",
+      "identifier": "urn:air:faf.one:mcp:mcp-context-card",
+      "type": "application/mcp-server-card+json",
+      "data": {
+        "$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
+        "name": "io.github.Wolfe-Jam/mcp-context-card",
+        "version": "1.6.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",
+        "repository": {
+          "url": "https://github.com/Wolfe-Jam/mcp-context-card",
+          "source": "github"
+        },
+        "_meta": {
+          "io.github.Wolfe-Jam.mcp-context-card/context": {
+            "source": "AGENTS.md",
+            "mediaType": "text/markdown"
+          },
+          "io.github.Wolfe-Jam.mcp-context-card/memory": {
+            "source": "project.fafm",
+            "mediaType": "application/vnd.fafm+yaml",
+            "iana": "https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml",
+            "note": "no de-facto standard for agent memory yet — this is one instantiation"
+          },
+          "io.github.Wolfe-Jam.mcp-context-card/identity": {
+            "source": ".well-known/fafa",
+            "mediaType": "application/vnd.fafa+yaml",
+            "iana": "https://www.iana.org/assignments/media-types/application/vnd.fafa+yaml"
+          }
+        }
+      }
+    },
+    {
+      "identifier": "urn:air:faf.one:context:mcp-context-card",
       "displayName": "mcp-context-card — project context (AGENTS.md)",
       "type": "text/markdown",
-      "mediaType": "text/markdown",
       "description": "Agent instructions for this project — 9 section(s): Setup, Build, Test, Layout, Conventions, The invariant, ….",
       "url": "./AGENTS.md"
     },
     {
-      "identifier": "urn:air:mcp-context-card:memory",
-      "displayName": "mcp-context-card — persistent memory (.fafm)",
-      "type": "application/vnd.fafm+yaml",
-      "mediaType": "application/vnd.fafm+yaml",
-      "description": "Cross-session memory — 4 fact(s), profile \"knowledge\". Recall survives a process restart. No de-facto standard for this concern yet.",
-      "url": "./project.fafm",
-      "_meta": {
-        "io.github.Wolfe-Jam.mcp-context-card/iana": "https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml"
-      }
-    },
-    {
-      "identifier": "urn:air:mcp-context-card:identity",
+      "identifier": "urn:air:faf.one:identity:mcp-context-card",
       "displayName": "mcp-context-card — agent identity (.fafa)",
       "type": "application/vnd.fafa+yaml",
-      "mediaType": "application/vnd.fafa+yaml",
       "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 drop-in extension for any existing MCP server, discoverable through the Server Card _meta block and a self-published ai-catalog.json.",
       "url": "./.well-known/fafa",
-      "_meta": {
-        "io.github.Wolfe-Jam.mcp-context-card/iana": "https://www.iana.org/assignments/media-types/application/vnd.fafa+yaml"
+      "extensions": {
+        "io.github.Wolfe-Jam.mcp-context-card": {
+          "iana": "https://www.iana.org/assignments/media-types/application/vnd.fafa+yaml"
+        }
       }
     }
   ]

package/.well-known/fafa

@@ -8,8 +8,12 @@ version: "1.0"
 agent:
   name: "mcp-context-card"
   displayName: "mcp-context-card"
+  # Publisher identity in AI Catalog form, as `faf card init` writes it:
+  # urn:air:{your domain}:agent:{short name}. This example publishes as faf.one;
+  # 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.4.0"
+  version: "1.6.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
@@ -17,3 +21,8 @@ agent:
     Server Card _meta block and a self-published ai-catalog.json.
   status: "published"
   license: "MIT"
+metadata:
+  cards:
+    packages:
+      - registryType: "npm"
+        identifier: "mcp-context-card"

package/CHANGELOG.md

@@ -2,6 +2,92 @@
 
 All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
 
+## 1.6.0
+
+The card is a business card.
+
+`npx mcp-context-card card` used to open a technical page. It now opens a
+**business card**: what you'd hand someone on the front, and the full detail
+one flip away.
+
+- **Front:** a monogram logo (the first letters of the name: **MC**), the
+  name, a title, and a one-liner.
+  - The **title** says what it is and its version ("MCP server · v1.6.0",
+    "A2A agent · v0.3.0"), from where the project's `.fafa` says it runs
+    (`endpoints`, or `metadata.cards.packages`). With nothing declared, it
+    claims nothing.
+  - The **one-liner** is the start of the description, stopping at its first
+    natural pause rather than mid-phrase.
+  - Domain, publisher, status and licence sit along the bottom.
+- **Back:** tabs for About (the identity in full), Skills (when the `.fafa`
+  lists capabilities), Context (AGENTS.md), Memory and Discovery. Long content
+  scrolls inside the card, including by mouse wheel or trackpad on macOS.
+- **Controls:** the same two on both faces. **(i)** top-right explains
+  Business Cards for Agents; the outline flip button bottom-right (↻ on the
+  front, ↺ on the back) has an instant tooltip.
+- **Views:** ▭ ▯ switches landscape or portrait (`--portrait`,
+  `?layout=portrait`, `layout` on the tools). ◐ switches the **card** between
+  light and dark. `--theme` / `?theme=` set the card's starting colour, and
+  the page around it follows your OS on its own.
+- **Works with scripts off:** flip, tabs and both toggles are CSS. The one
+  small script adds Expand all, `#section` links on the back, and printing.
+  `--expanded` and print lay both faces out flat.
+- **The `.fafa` reader** now reads `endpoints`, `capabilities` and
+  `metadata.cards.packages`, as `faf card init` writes them. This repo's own
+  `.fafa` declares its npm package.
+- **Read and render are separate:** `readCard` turns a project's files into a
+  neutral business card; `renderBusinessCard` draws any card, so a person's
+  card or an A2A Agent Card needs no renderer change.
+- The saved file is still `context-card.html`: underneath, it's the project's
+  context.
+
+No tool or protocol change. 209 tests, all green.
+
+## 1.5.0
+
+MCP Server Cards (SEP-2127, Final) and the AI Catalog (specVersion 1.0), and HTTP that is local by default.
+
+**Breaking for exposed deploys:** HTTP mode now binds `127.0.0.1`. A container or
+hosted deploy must set `HOST=0.0.0.0` (`examples/Dockerfile` does). Local use is
+unchanged.
+
+- **Server Card (SEP-2127, Final).** Served at `GET /mcp/server-card`
+  (`<streamable-http-url>/server-card`). The 1.x `/.well-known/mcp/server-card`
+  still answers with the same card. The card validates against the official v1
+  schema: `$schema`, a reverse-DNS `name` (`io.github.Wolfe-Jam/mcp-context-card`,
+  as in `server.json`), `title`, `description`, `websiteUrl`, `repository`, and a
+  `streamable-http` remote when served over HTTP. `serverInfo` reports the same
+  name, title and version.
+- **Discovery hosting.** The card, catalog and `.well-known/fafa` carry the
+  spec's CORS (`Access-Control-Allow-Origin: *`, GET, `Content-Type` and
+  `If-None-Match` allowed, `ETag` exposed), `Cache-Control: public,
+  max-age=3600`, and an `ETag` answered with `304 Not Modified`.
+- **AI Catalog (specVersion 1.0).** The Server Card is the first entry. Entries use `type`,
+  custom data sits in `extensions`, and identifiers are
+  `urn:air:{domain}:{namespace}:{name}` with the domain taken from the project's
+  own `.fafa` (none is ever invented). `/AGENTS.md` is served, so every catalog
+  link resolves with its declared type.
+- **Memory stays private over HTTP.** `project.fafm` is session data, so it is
+  not served or listed in the AI Catalog, and an exposed `/card` shows only how
+  many facts there are, unless `MCP_CONTEXT_CARD_PUBLISH_MEMORY=1`. Local
+  surfaces (the CLI card, the MCP App, the tools, a local `/card`) are unchanged.
+- **Local by default (MCP transports spec).** A foreign browser `Origin` gets
+  403 with a JSON-RPC error. A local server serves loopback `Host` names only,
+  so a DNS name rebound to this machine is refused. The server binds
+  `127.0.0.1` unless `HOST` is set. `MCP_CONTEXT_CARD_ALLOWED_HOSTS` and
+  `MCP_CONTEXT_CARD_ALLOWED_ORIGINS` admit a reverse proxy or a web app. The
+  startup line says whether the server is local or exposed, and now prints
+  once the socket is listening.
+- **WJTTC suite (`npm run wjttc`).** Seven tiers: Protocol, Server Card,
+  Hosting, AI Catalog, Security, stdio/HTTP Parity, Ship. Tiers 2 to 4 and the
+  transport checks run `src/conformance/discovery.ts`, a self-contained checker
+  for any server URL that reports each requirement as MUST or SHOULD, worded
+  as the specs word it.
+- Dependencies: `@modelcontextprotocol/sdk` 1.32.1 (GHSA-6qxp-vccf-f47h) and
+  `hono` 4.13.13. `npm audit` reports 0 vulnerabilities.
+
+No tool change. 200 tests, all green.
+
 ## 1.4.0
 
 The card reads the `.fafa` that `faf card init` writes, and shows the agent's ID.

package/README.md

@@ -11,10 +11,11 @@ rendered as one card you can read.
 
 | Light | Dark |
 |---|---|
-| ![the context card, light theme](./docs/img/card-light.png) | ![the context card, dark theme](./docs/img/card-dark.png) |
+| ![the business card front, light theme: name, title, one-liner](./docs/img/card-light.png) | ![the business card front, dark theme](./docs/img/card-dark.png) |
 
-**See your own project's card** — run this in its folder. It writes
-`context-card.html` and opens it in your browser:
+**See your own project's business card** — run this in its folder. It writes
+`context-card.html` and opens it in your browser. The front is the card: name,
+title, one-liner. Flip it for the back: About, Context, Memory, Discovery.
 
 ```
 npx mcp-context-card card
@@ -22,15 +23,15 @@ npx mcp-context-card card
 
 **context** — the project's `AGENTS.md`, served whole or one section at a time.
 
-![the card's context section — AGENTS.md, section nav, read_agents_md](./docs/img/card-context.png)
+![the back's Context tab — AGENTS.md, section nav, read_agents_md](./docs/img/card-context.png)
 
 **memory** — facts that persist across sessions, in a file.
 
-![the card's memory section — a real, tagged, verified fact](./docs/img/card-memory.png)
+![the back's Memory tab — real, tagged, verified facts](./docs/img/card-memory.png)
 
 **identity** — what this server is, from its own `.fafa` (`agent.fafa`, else `.well-known/fafa`).
 
-![the card's identity — name and pills](./docs/img/card-identity.png)
+![the back's About tab — the identity in full](./docs/img/card-identity.png)
 
 Discovery goes through two surfaces already in the ecosystem: the Server Card
 `_meta` block and `ai-catalog.json` sibling entries.
@@ -76,23 +77,34 @@ no search.
 
 ## The card
 
-The screenshot at the top of this page is exactly this — the same three
-sources rendered as one self‑contained HTML page: identity, `AGENTS.md`,
-memory, and how a machine fetches it. The view for people: read it, screenshot
-it, drop it in a PR, put it on a status page.
-
-`AGENTS.md` sections are collapsed by default, so the card scans in one screen;
-a sticky index jumps to any section, **Expand all** opens everything. Sections
-toggle natively — the one small inline script only adds the bulk button and the
-print handler. `--expanded` / `?expand=all` renders it fully open, script-free,
-for a screenshot.
+The screenshot at the top of this page is exactly this: the same sources
+rendered as a **business card** in one self‑contained HTML page. The view for
+people: read it, screenshot it, drop it in a PR, put it on a status page.
+
+- **Front:** the name, a title (what it is and its version: "MCP server", "A2A
+  agent", from where the project's `.fafa` says it runs) and a one-liner (the
+  start of its description).
+- **Back (Flip):** tabs for **About** (the identity in full),
+  **Skills** (when the `.fafa` lists capabilities), **Context** (`AGENTS.md`),
+  **Memory** and **Discovery**. Long content scrolls inside the card.
+- **Landscape or portrait:** the ▭ ▯ button switches the view; `--portrait` /
+  `?layout=portrait` sets it.
+- **Light or dark card:** the card's colour is its own, like a printed card.
+  `--theme` / `?theme=` sets it (default: follow your OS), and ◐ switches it.
+  The page around it always follows your OS.
+
+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.
 
 ```
 npx mcp-context-card card            # at a terminal: writes context-card.html and opens it
-npx mcp-context-card card --expanded # every section open
+npx mcp-context-card card --portrait # the tall view
+npx mcp-context-card card --expanded # both faces flat, every section open
 npx mcp-context-card card > x.html   # piped/redirected: raw HTML to stdout
 GET /card                            # live, on the HTTP transport
-GET /card?expand=all&theme=light&accent=%230066cc
+GET /card?layout=portrait&theme=light&accent=%230066cc
 ```
 
 In a chat, hosts that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps)
@@ -167,6 +179,16 @@ reports which project it picked and how. To pin one project instead, set
 wins. Identity is optional. Over HTTP instead:
 `PORT=8080 npx mcp-context-card`. Requires Node ≥20.
 
+HTTP mode is local by default, as the MCP transports spec asks: it binds
+`127.0.0.1`, refuses foreign browser origins with 403, and refuses DNS names
+rebound to this machine. `HOST=0.0.0.0` exposes it (a container or hosted
+deploy). There is no authentication or rate limiting, so put an exposed server
+behind your own.
+Memory is session data: an exposed server shows only its count on `/card`, and
+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).
+
 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
@@ -178,6 +200,19 @@ Extending an MCP you already run: most hosts accept more than one
 `server-git`, or your own, and every agent in that host gains context,
 memory, and identity discovery without anything else changing.
 
+### Your identifiers
+
+The AI Catalog names each entry `urn:air:{domain}:{namespace}:{name}`, and
+the domain is yours. It comes from your project's `.fafa`: run
+`npx faf-cli card init` (or `--domain example.com`), and it writes
+`agent.id: urn:air:example.com:agent:<short-name>`. Your catalog then publishes
+`urn:air:example.com:context:<short-name>` and so on, with no code to change.
+This repo's own `.fafa` says `faf.one`; that's our example, and yours says yours.
+
+With no `.fafa`, no domain is invented: the served catalog uses the host it's
+served from (`localhost` when you run it locally), and the static
+`.well-known/ai-catalog.json` uses plain `<short-name>:<namespace>` IDs.
+
 ## Why
 
 `AGENTS.md` is the de-facto standard for telling a coding agent how to work in a
@@ -190,9 +225,10 @@ grows its own shape.
 
 1. **Server Card `_meta`** ([SEP‑2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127)) —
    one reverse‑DNS‑namespaced key per concern, readable in‑band as an MCP
-   resource and at `GET /.well-known/mcp/server-card`.
-2. **`ai-catalog.json`** — sibling entries keyed by media type, at
-   `GET /.well-known/ai-catalog.json`.
+   resource and at `GET /mcp/server-card` (the 1.x `/.well-known/mcp/server-card`
+   still answers).
+2. **`ai-catalog.json`** — the Server Card plus sibling entries keyed by media
+   type, at `GET /.well-known/ai-catalog.json`.
 
 The context concern points at `AGENTS.md` (`text/markdown`). Memory and identity
 have no de‑facto standard yet, so the examples here use
@@ -235,11 +271,15 @@ over both transports:
 4. **Discovery** — `list_context_sources()`, then the same server over stateless
    HTTP with its `.well-known` routes and `GET /card`.
 
-140 tests on Linux, macOS, and Windows, coverage‑gated in CI. Two spawn a real
+209 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
 an existing `project.fafm`, one starting from a project that has never had
 one; another checks the stdio and HTTP tool surfaces match, and another checks
 every tool's title and behaviour hints against what it actually does.
+`src/conformance/discovery.ts` checks any server's Server Card, AI Catalog and
+transport security against the specs, one MUST or SHOULD at a time.
 
 ## Layout
 
@@ -252,8 +292,11 @@ every tool's title and behaviour hints against what it actually does.
 | `src/render-card.ts` | the card — identity + `AGENTS.md` + memory + discovery, as one HTML page |
 | `src/memory.ts` | file‑backed `remember` / `recall` / `forget` |
 | `src/identity.ts` | `whoami` (`.fafa` → `package.json` fallback) + the `_meta` block |
-| `src/catalog-gen.ts` | writes `ai-catalog.json` from the same three sources |
+| `src/server-card.ts` | the MCP Server Card (SEP-2127, schema v1) |
+| `src/catalog-gen.ts` | writes `ai-catalog.json`: the Server Card + its sibling entries |
 | `src/transport/http.ts` | the stateless Streamable HTTP app (Hono) |
+| `src/transport/guard.ts` | Origin and Host checks (DNS-rebinding protection) |
+| `src/conformance/discovery.ts` | a portable Server Card / AI Catalog / transport checker |
 | `src/bin.ts` | the entry point — `stdio` · `--http` · `card` · `--help` · `--version` |
 
 ## Related

package/dist/bin.d.ts

@@ -8,7 +8,12 @@ export interface Launch {
     root: string;
 }
 /** what a bare `--help` / `help` prints. */
-export declare const HELP = "mcp-context-card 1.4.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)   --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\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.6.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.
+ */
+export declare function bindHost(env?: NodeJS.ProcessEnv): string;
 /**
  * Decide how to launch, from argv + env. Pure — so the mode matrix is unit
  * tested without spawning a process.

package/dist/bin.js

@@ -10,7 +10,7 @@
  *                                   writes context-card.html and opens it. Piped
  *                                   or redirected: HTML to stdout ( > card.html ).
  *                                   --theme light|dark · --accent #hex
- *                                   --expanded (all sections open) · --stdout
+ *                                   --expanded (all sections open) · --portrait · --stdout
  *   mcp-context-card --help       → usage
  *   mcp-context-card --version    → version
  *
@@ -34,18 +34,34 @@ USAGE
   mcp-context-card card             this dir's context card — opens it in your browser
                                     at a terminal; HTML to stdout when piped ( > f.html )
                                       --theme light|dark   --accent #hex
-                                      --expanded (all sections open)   --stdout
+                                      --expanded (all sections open)   --portrait   --stdout
   mcp-context-card --help           this text
   mcp-context-card --version        print version
 
 ENV
   MCP_CONTEXT_CARD_ROOT   read AGENTS.md / project.fafm / .well-known/ from here
   PORT                    if set, run HTTP instead of stdio
+  HOST                    HTTP bind address (default 127.0.0.1, this machine
+                          only); 0.0.0.0 exposes it, e.g. in a container
+  MCP_CONTEXT_CARD_ALLOWED_HOSTS / _ALLOWED_ORIGINS
+                          comma-separated Host names / browser origins to
+                          accept besides this machine's own (reverse proxy, web app)
+  MCP_CONTEXT_CARD_PUBLISH_MEMORY=1
+                          HTTP: serve project.fafm, list it in the AI Catalog,
+                          and show its facts on an exposed /card (off: memory
+                          is session data). HTTP has no auth
 
 A bare run is an stdio server: it waits for a host to speak JSON-RPC on stdin,
 so it looks idle at a terminal. Try \`card\` (opens your context in a browser) or \`--http\`.
 https://github.com/Wolfe-Jam/mcp-context-card
 `;
+/**
+ * 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.
+ */
+export function bindHost(env = process.env) {
+    return env.HOST?.trim() || "127.0.0.1";
+}
 /**
  * Decide how to launch, from argv + env. Pure — so the mode matrix is unit
  * tested without spawning a process.
@@ -112,6 +128,7 @@ if (entryPath && import.meta.url === pathToFileURL(entryPath).href) {
             theme: theme === "light" || theme === "dark" ? theme : "auto",
             accent: safeAccent(flagValue(argv, "--accent")),
             expanded: argv.includes("--expanded"),
+            layout: argv.includes("--portrait") ? "portrait" : "landscape",
         });
         // 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.
@@ -131,9 +148,17 @@ if (entryPath && import.meta.url === pathToFileURL(entryPath).href) {
     else if (mode === "http") {
         const { httpApp } = await import("./transport/http.js");
         const { serve: serveHttp } = await import("@hono/node-server");
-        serveHttp({ fetch: httpApp(root).fetch, port });
+        const { isLoopbackBind } = await import("./transport/guard.js");
+        const host = bindHost();
+        const local = isLoopbackBind(host);
+        // The startup line prints once the socket is listening, so anything waiting
+        // for it (a test, a supervisor) can connect straight away.
+        serveHttp({ fetch: httpApp(root, { exposure: local ? "local" : "exposed" }).fetch, port, hostname: host }, () => 
         // stderr, not stdout — stdout is the MCP wire in stdio mode.
-        console.error(`${NAME} · http · :${port}  (POST /mcp · GET /card · GET /.well-known/*)`);
+        console.error(`${NAME} · http · ${host.includes(":") ? `[${host}]` : host}:${port}  (POST /mcp · GET /card · GET /.well-known/*)` +
+            (local
+                ? "  · local only (HOST=0.0.0.0 to expose)"
+                : "  · EXPOSED beyond this machine, no authentication: put it behind your own")));
     }
     else {
         // stderr so it never touches the JSON-RPC wire on stdout; a bare run at a

package/dist/catalog-gen.d.ts

@@ -1,26 +1,77 @@
-export declare function buildCatalog(root: string): {
+export interface CatalogOptions {
+    /** Public origin the catalog is served from, e.g. `https://ctx.example.com`. */
+    origin?: string;
+    /** List the memory file (`project.fafm`). Default: off. */
+    publishMemory?: boolean;
+}
+export declare function buildCatalog(root: string, opts?: CatalogOptions): {
     specVersion: string;
     host: {
         displayName: string;
         identifier: string;
     };
     entries: ({
+        url: string;
+        identifier: string;
+        type: string;
+        displayName?: undefined;
+        description?: undefined;
+    } | {
+        data: {
+            _meta: {
+                readonly "io.github.Wolfe-Jam.mcp-context-card/context": {
+                    readonly source: "AGENTS.md";
+                    readonly mediaType: "text/markdown";
+                };
+                readonly "io.github.Wolfe-Jam.mcp-context-card/memory": {
+                    readonly source: "project.fafm";
+                    readonly mediaType: "application/vnd.fafm+yaml";
+                    readonly iana: string;
+                    readonly note: "no de-facto standard for agent memory yet — this is one instantiation";
+                };
+                readonly "io.github.Wolfe-Jam.mcp-context-card/identity": {
+                    readonly source: ".well-known/fafa";
+                    readonly mediaType: "application/vnd.fafa+yaml";
+                    readonly iana: string;
+                };
+            };
+            remotes?: {
+                type: "streamable-http";
+                url: string;
+                supportedProtocolVersions: string[];
+            }[] | undefined;
+            $schema: string;
+            name: string;
+            version: string;
+            title: string;
+            description: string;
+            websiteUrl: string;
+            repository: {
+                url: string;
+                source: string;
+            };
+        };
+        identifier: string;
+        type: string;
+        displayName?: undefined;
+        description?: undefined;
+        url?: undefined;
+    } | {
         identifier: string;
         displayName: string;
         type: string;
-        mediaType: string;
         description: string;
         url: string;
-        _meta?: undefined;
     } | {
+        extensions: {
+            "io.github.Wolfe-Jam.mcp-context-card": {
+                iana: string;
+            };
+        };
         identifier: string;
         displayName: string;
         type: string;
-        mediaType: string;
         description: string;
         url: string;
-        _meta: {
-            "io.github.Wolfe-Jam.mcp-context-card/iana": string;
-        };
     })[];
 };

package/dist/catalog-gen.js

@@ -1,11 +1,25 @@
 /**
- * catalog-gen — write `.well-known/ai-catalog.json` FROM the three sources
- * (`AGENTS.md`, `project.fafm`, `.well-known/fafa`) that also back the Server
- * Card `_meta` block. Same three artifacts, second exposure mechanism.
+ * catalog-gen — the AI Catalog (`application/ai-catalog+json`, spec 1.0) for
+ * this server: its MCP Server Card, plus the sources that also back the Server
+ * Card `_meta` block: `AGENTS.md` and `.fafa`, and `project.fafm` only when the
+ * project opts in ({@link CatalogOptions.publishMemory}). Memory is written
+ * during sessions, and SEP-2127 rules user- or session-specific data out of
+ * public discovery documents, so it is left out by default.
+ *
+ * Identifiers follow `urn:air:{publisher}:{namespace}:{name}`, with the
+ * publisher domain and short name taken from the project's own `.fafa`
+ * ({@link catalogPublisher}). Served over HTTP without a `.fafa` domain, the
+ * request host is the publisher (whoever serves it controls that domain). The
+ * committed static file with no domain uses plain `{name}:{namespace}` ids:
+ * the spec treats unknown schemes as opaque, and no domain is ever invented.
+ *
+ * Served (an origin is known): entries point at absolute URLs and the card
+ * entry links `<origin>/mcp/server-card`. Static: relative URLs and the card
+ * inline as `data` (no remotes, since no origin is known).
  *
  * Descriptions are derived from real file content (section count, fact count,
- * the agent's own description) — not hand-written blurbs that drift. The CI
- * job `catalog:check` regenerates this and fails on any diff.
+ * the agent's own description), not hand-written blurbs that drift. The CI
+ * job `catalog:check` regenerates the static file and fails on any diff.
  */
 import { writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -13,14 +27,21 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { parseAgentsMd } from "./agents-md.js";
 import { parseFafm } from "./faf/parse-fafm.js";
 import { parseFafa } from "./faf/parse-fafa.js";
-import { META_NS, fafaFile } from "./identity.js";
+import { META_NS, catalogPublisher, fafaFile } from "./identity.js";
+import { SERVER_CARD_MEDIA_TYPE, SERVER_CARD_PATH } from "./constants.js";
+import { serverCard } from "./server-card.js";
 const iana = (t) => `https://www.iana.org/assignments/media-types/${t}`;
-export function buildCatalog(root) {
+export function buildCatalog(root, opts = {}) {
     const agents = parseAgentsMd(join(root, "AGENTS.md"));
     const fafm = parseFafm(join(root, "project.fafm"));
     const file = fafaFile(root);
     const fafa = file ? parseFafa(file) : null;
-    const host = fafa?.name ?? "mcp-context-card";
+    const { domain, handle } = catalogPublisher(root);
+    const publisher = domain ?? (opts.origin ? new URL(opts.origin).hostname.toLowerCase() : undefined);
+    const id = (namespace) => publisher ? `urn:air:${publisher}:${namespace}:${handle}` : `${handle}:${namespace}`;
+    const at = (path) => (opts.origin ? `${opts.origin}/${path}` : `./${path}`);
+    const ext = (type) => ({ extensions: { [META_NS]: { iana: iana(type) } } });
+    const host = fafa?.displayName ?? fafa?.name ?? "mcp-context-card";
     return {
         specVersion: "1.0",
         host: {
@@ -29,10 +50,16 @@ export function buildCatalog(root) {
         },
         entries: [
             {
-                identifier: `urn:air:${host}:context`,
+                // The card carries its own title, description and version, so the
+                // entry repeats none of them (AI Catalog: avoid drift).
+                identifier: id("mcp"),
+                type: SERVER_CARD_MEDIA_TYPE,
+                ...(opts.origin ? { url: `${opts.origin}${SERVER_CARD_PATH}` } : { data: serverCard() }),
+            },
+            {
+                identifier: id("context"),
                 displayName: `${host} — project context (AGENTS.md)`,
                 type: "text/markdown",
-                mediaType: "text/markdown",
                 description: agents
                     ? (() => {
                         const h = agents.sections.filter((s) => s.level > 1).map((s) => s.heading);
@@ -41,33 +68,31 @@ export function buildCatalog(root) {
                             .join(", ")}${h.length > 6 ? ", …" : ""}.`;
                     })()
                     : "Agent instructions for this project (AGENTS.md — not present).",
-                url: "./AGENTS.md",
-            },
-            {
-                identifier: `urn:air:${host}:memory`,
-                displayName: `${host} — persistent memory (.fafm)`,
-                type: "application/vnd.fafm+yaml",
-                mediaType: "application/vnd.fafm+yaml",
-                description: `Cross-session memory — ${fafm.facts.length} fact(s), profile "${fafm.profile ?? "?"}". Recall survives a process restart. No de-facto standard for this concern yet.`,
-                url: "./project.fafm",
-                _meta: { [`${META_NS}/iana`]: iana("application/vnd.fafm+yaml") },
+                url: at("AGENTS.md"),
             },
+            ...(opts.publishMemory ? [{
+                    identifier: id("memory"),
+                    displayName: `${host} — persistent memory (.fafm)`,
+                    type: "application/vnd.fafm+yaml",
+                    description: `Cross-session memory — ${fafm.facts.length} fact(s), profile "${fafm.profile ?? "?"}". Recall survives a process restart. No de-facto standard for this concern yet.`,
+                    url: at("project.fafm"),
+                    ...ext("application/vnd.fafm+yaml"),
+                }] : []),
             {
-                identifier: `urn:air:${host}:identity`,
+                identifier: id("identity"),
                 displayName: `${host} — agent identity (.fafa)`,
                 type: "application/vnd.fafa+yaml",
-                mediaType: "application/vnd.fafa+yaml",
                 description: fafa?.description ??
                     `Agent identity card (status: ${fafa?.status ?? "unknown"}).`,
-                url: "./.well-known/fafa",
-                _meta: { [`${META_NS}/iana`]: iana("application/vnd.fafa+yaml") },
+                url: at(".well-known/fafa"),
+                ...ext("application/vnd.fafa+yaml"),
             },
         ],
     };
 }
-// Direct run → write the file.
+// Direct run → write the static file (no origin: relative URLs, card inline).
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
     const root = join(dirname(fileURLToPath(import.meta.url)), "..");
     writeFileSync(join(root, ".well-known/ai-catalog.json"), JSON.stringify(buildCatalog(root), null, 2) + "\n");
-    console.log("wrote .well-known/ai-catalog.json — 3 sibling entries, derived from AGENTS.md / project.fafm / .well-known/fafa");
+    console.log("wrote .well-known/ai-catalog.json — Server Card + AGENTS.md + .fafa entries (memory is opt-in, never in the static file)");
 }