mcp-context-card 1.4.0 → 1.5.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.5.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.5.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/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
 
+## 1.5.0
+
+MCP Server Cards (SEP-2127, Final) and AI Catalog 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 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

@@ -167,6 +167,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
@@ -190,9 +200,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 +246,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
+200 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 +267,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.5.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  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

@@ -41,11 +41,27 @@ USAGE
 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.
@@ -131,9 +147,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)");
 }

package/dist/conformance/discovery.d.ts

@@ -0,0 +1,60 @@
+/**
+ * conformance/discovery — a portable checker for MCP Server Card discovery
+ * (SEP-2127, Final), the AI Catalog (spec 1.0), and the Streamable HTTP
+ * transport's security rules, run against any server URL.
+ *
+ * Self-contained on purpose: no imports from this package, only the global
+ * `fetch` (and `node:http` for the one check that must forge a Host header,
+ * which `fetch` drops), so the file can be lifted into another tool as-is.
+ * The transport checks send one JSON-RPC `ping`, which changes nothing. Point it at a
+ * server's Streamable HTTP endpoint and it returns one result per requirement,
+ * each tagged MUST or SHOULD exactly as the spec words it. Requirements the
+ * spec leaves at MAY (where the card lives, whether a catalog exists) are
+ * never failures: a missing optional document turns its checks into skips.
+ *
+ * JSON Schema validation is optional: pass `validateCard` (for example Ajv
+ * against the official v1 schema) and it runs as one more card check.
+ */
+export declare const SERVER_CARD_SCHEMA_URL = "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json";
+export declare const SERVER_CARD_TYPE = "application/mcp-server-card+json";
+export declare const AI_CATALOG_TYPE = "application/ai-catalog+json";
+export type Tier = "card" | "hosting" | "catalog" | "transport";
+export type Level = "must" | "should";
+export type Status = "pass" | "fail" | "skip";
+export interface CheckResult {
+    id: string;
+    tier: Tier;
+    level: Level;
+    title: string;
+    status: Status;
+    detail?: string;
+}
+export interface DiscoveryTarget {
+    /** The server's Streamable HTTP endpoint, e.g. `https://ctx.example.com/mcp`. */
+    mcpUrl: string;
+    /** Where to read the card. Default: `<mcpUrl>/server-card`, then the catalog's card entry. */
+    cardUrl?: string;
+    /** Where to read the catalog. Default: `<origin>/.well-known/ai-catalog.json`. */
+    catalogUrl?: string;
+}
+export interface DiscoveryOptions {
+    fetch?: typeof fetch;
+    /** Returns null when the card is valid, else a short error. */
+    validateCard?: (card: unknown) => string | null;
+    /** Per-request timeout in milliseconds (default 10000). */
+    timeoutMs?: number;
+    /** POST with exact headers (Host included); returns the status, or null. Default: node:http. */
+    rawStatus?: (url: string, headers: Record<string, string>, body: string, timeoutMs: number) => Promise<number | null>;
+}
+export interface DiscoveryReport {
+    mcpUrl: string;
+    cardUrl: string | null;
+    catalogUrl: string;
+    results: CheckResult[];
+    passed: number;
+    failed: number;
+    skipped: number;
+    /** Failed MUST checks: zero means nothing the spec requires is broken. */
+    mustFailures: number;
+}
+export declare function checkDiscovery(target: DiscoveryTarget, opts?: DiscoveryOptions): Promise<DiscoveryReport>;