mcp-context-card 1.4.0 → 1.6.0

package/dist/server.d.ts

@@ -20,32 +20,13 @@ export { NAME, VERSION, SERVER_CARD_URI } from "./constants.js";
 /** Default package root — `dist/` at runtime, `src/` under tsx. Both are one up. */
 export declare const ROOT: string;
 /**
- * The Server Card — this server's identity plus the `_meta` context block,
- * one namespaced key per concern. Served in-band as the
- * `mcp-context-card://server-card` resource and out-of-band at
- * `/.well-known/mcp/server-card`.
+ * The Server Card (SEP-2127, schema v1): this server's identity plus the `_meta`
+ * context block, one namespaced key per concern. Served in-band as the
+ * `mcp-context-card://server-card` resource and out-of-band at `/mcp/server-card`
+ * (the spec's reserved `<streamable-http-url>/server-card`; the 1.x path
+ * `/.well-known/mcp/server-card` is kept as an alias). Built in server-card.ts.
  */
-export declare function serverCard(): {
-    name: string;
-    version: string;
-    _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;
-        };
-    };
-};
+export { serverCard } from "./server-card.js";
 /** Sent to every client at initialize. Hosts that support MCP Apps show the
  *  card inline; for the rest, this steers the model to save the card as a
  *  file instead of pasting a whole HTML page into the chat. */

package/dist/server.js

@@ -23,22 +23,22 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { findSection, parseAgentsMd } from "./agents-md.js";
 import { authorAgentsMd } from "./author.js";
 import { forget, parseFafm, recall, remember } from "./memory.js";
-import { identity, resolveIdentity, serverCardMeta, whoami } from "./identity.js";
+import { identity, resolveIdentity, whoami } from "./identity.js";
 import { renderCard, renderCardText, safeAccent } from "./render-card.js";
 export { NAME, VERSION, SERVER_CARD_URI } from "./constants.js";
-import { NAME, VERSION, SERVER_CARD_URI, CARD_UI_URI, MCP_APP_MIME, UI_EXTENSION } from "./constants.js";
+import { VERSION, SERVER_CARD_URI, CARD_UI_URI, MCP_APP_MIME, UI_EXTENSION, REGISTRY_NAME, TITLE, SERVER_CARD_MEDIA_TYPE } from "./constants.js";
+import { serverCard } from "./server-card.js";
 const here = dirname(fileURLToPath(import.meta.url));
 /** Default package root — `dist/` at runtime, `src/` under tsx. Both are one up. */
 export const ROOT = join(here, "..");
 /**
- * The Server Card — this server's identity plus the `_meta` context block,
- * one namespaced key per concern. Served in-band as the
- * `mcp-context-card://server-card` resource and out-of-band at
- * `/.well-known/mcp/server-card`.
+ * The Server Card (SEP-2127, schema v1): this server's identity plus the `_meta`
+ * context block, one namespaced key per concern. Served in-band as the
+ * `mcp-context-card://server-card` resource and out-of-band at `/mcp/server-card`
+ * (the spec's reserved `<streamable-http-url>/server-card`; the 1.x path
+ * `/.well-known/mcp/server-card` is kept as an alias). Built in server-card.ts.
  */
-export function serverCard() {
-    return { name: NAME, version: VERSION, _meta: serverCardMeta() };
-}
+export { serverCard } from "./server-card.js";
 const text = (s) => ({ content: [{ type: "text", text: s }] });
 /** Sent to every client at initialize. Hosts that support MCP Apps show the
  *  card inline; for the rest, this steers the model to save the card as a
@@ -57,12 +57,14 @@ function cardOptions(args) {
         theme: (["light", "dark", "auto"].includes(theme) ? theme : "auto"),
         accent: safeAccent(args.accent),
         expanded: args.expanded === true || args.expanded === "true",
+        layout: (args.layout === "portrait" ? "portrait" : "landscape"),
     };
 }
 const CARD_ARGS = {
     theme: { type: "string", enum: ["light", "dark", "auto"], description: "default: auto" },
     accent: { type: "string", description: "CSS hex colour, e.g. #FF702D (default: the AAIF palette)" },
     expanded: { type: "boolean", description: "render every AGENTS.md section open (default: collapsed)" },
+    layout: { type: "string", enum: ["landscape", "portrait"], description: "business-card view (default: landscape)" },
 };
 /**
  * @param root  directory holding `AGENTS.md`, `project.fafm`, `.well-known/`.
@@ -76,7 +78,7 @@ function hostRendersApps(server) {
     return Array.isArray(ext?.mimeTypes) && ext.mimeTypes.includes(MCP_APP_MIME);
 }
 export function createServer(root = ROOT, opts = {}) {
-    const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: {}, resources: {} }, instructions: INSTRUCTIONS });
+    const server = new Server({ name: REGISTRY_NAME, title: TITLE, version: VERSION }, { capabilities: { tools: {}, resources: {} }, instructions: INSTRUCTIONS });
     // ── Which project? ────────────────────────────────────────────────────
     // Resolved per call, not at startup: a client's roots are only known once
     // it has connected, and they can change (goose sends its session's working
@@ -136,7 +138,7 @@ export function createServer(root = ROOT, opts = {}) {
                 uri: SERVER_CARD_URI,
                 name: "Server Card",
                 description: "This server's identity + the _meta context block.",
-                mimeType: "application/json",
+                mimeType: SERVER_CARD_MEDIA_TYPE,
             },
             {
                 uri: CARD_UI_URI,
@@ -160,7 +162,7 @@ export function createServer(root = ROOT, opts = {}) {
         }
         return {
             contents: [
-                { uri: SERVER_CARD_URI, mimeType: "application/json", text: JSON.stringify(serverCard(), null, 2) },
+                { uri: SERVER_CARD_URI, mimeType: SERVER_CARD_MEDIA_TYPE, text: JSON.stringify(serverCard(), null, 2) },
             ],
         };
     });
@@ -276,7 +278,7 @@ export function createServer(root = ROOT, opts = {}) {
                 // resource. Both key forms, as the official ext-apps helper writes them.
                 _meta: { ui: { resourceUri: CARD_UI_URI }, "ui/resourceUri": CARD_UI_URI },
                 annotations: { title: "Render Context Card", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
-                description: "Render the whole card — identity, AGENTS.md, memory, discovery — as one self-contained HTML page a person can read or screenshot. AGENTS.md sections collapse by default; pass expanded:true for the full render. Also served at GET /card (?expand=all) over the HTTP transport.",
+                description: "Render the project's business card as one self-contained HTML page a person can read or screenshot. Front: name, title, one-liner. Flip it for the back: About, Skills (when the .fafa lists any), Context (AGENTS.md), Memory, Discovery. layout:\"portrait\" for the tall view; expanded:true renders both faces flat with every section open. Also served at GET /card (?expand=all) over the HTTP transport.",
                 inputSchema: { type: "object", properties: CARD_ARGS },
             },
             {
@@ -410,7 +412,7 @@ export function createServer(root = ROOT, opts = {}) {
                             card: `resource ${CARD_UI_URI} (MCP App, ${MCP_APP_MIME})`,
                         },
                         http: {
-                            serverCard: "GET /.well-known/mcp/server-card",
+                            serverCard: "GET /mcp/server-card",
                             aiCatalog: "GET /.well-known/ai-catalog.json",
                             card: "GET /card",
                         },

package/dist/transport/guard.d.ts

@@ -0,0 +1,35 @@
+/**
+ * guard — DNS-rebinding and cross-origin protection for the HTTP transport.
+ *
+ * The MCP transports spec (Streamable HTTP, Security Warning):
+ *   1. Servers MUST validate the `Origin` header on all incoming connections;
+ *      a present, invalid `Origin` gets 403 Forbidden.
+ *   2. When running locally, servers SHOULD bind only to localhost.
+ *   3. Servers SHOULD authenticate all connections (left to the deployer; see
+ *      the README).
+ *
+ * `hostGuard` mirrors the SDK's Express `hostHeaderValidation` (hostname only,
+ * any port; 403 with a JSON-RPC error and `id: null`) for Hono. A local server
+ * accepts loopback Host names only, which is what stops a rebound DNS name
+ * from reaching it: plain GETs often carry no `Origin`, but always a `Host`.
+ *
+ * `originGuard` passes requests without an `Origin` (non-browser clients) and
+ * browser requests from loopback pages, an allowlisted origin, or the server's
+ * own origin. Everything else is refused before any route runs.
+ */
+import type { MiddlewareHandler } from "hono";
+/** Loopback host names, as a URL parser reports them (IPv6 in brackets). */
+export declare const LOOPBACK_HOSTNAMES: readonly ["localhost", "127.0.0.1", "[::1]"];
+export declare const isLoopbackHostname: (hostname: string) => boolean;
+/** A bind address that keeps the server on this machine. */
+export declare const isLoopbackBind: (address: string) => boolean;
+/** Comma-separated env value → trimmed, non-empty entries. */
+export declare const listFromEnv: (value: string | undefined) => string[];
+/** Refuse any request whose Host name is not loopback or in `allowed`. */
+export declare function hostGuard(allowed?: readonly string[]): MiddlewareHandler;
+/**
+ * Refuse a request whose `Origin` is present and not loopback, allowlisted or
+ * this server's own. `exempt(path)` skips paths that the Server Card spec
+ * requires to be readable from any origin (`Access-Control-Allow-Origin: *`).
+ */
+export declare function originGuard(allowedOrigins?: readonly string[], exempt?: (path: string) => boolean): MiddlewareHandler;

package/dist/transport/guard.js

@@ -0,0 +1,63 @@
+/** Loopback host names, as a URL parser reports them (IPv6 in brackets). */
+export const LOOPBACK_HOSTNAMES = ["localhost", "127.0.0.1", "[::1]"];
+export const isLoopbackHostname = (hostname) => {
+    const h = hostname.toLowerCase();
+    return LOOPBACK_HOSTNAMES.includes(h) || /^127(\.\d{1,3}){3}$/.test(h);
+};
+/** A bind address that keeps the server on this machine. */
+export const isLoopbackBind = (address) => isLoopbackHostname(address.startsWith("[") || !address.includes(":") ? address : `[${address}]`);
+/** Comma-separated env value → trimmed, non-empty entries. */
+export const listFromEnv = (value) => (value ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+function forbidden(c, message) {
+    return c.json({ jsonrpc: "2.0", error: { code: -32000, message }, id: null }, 403);
+}
+function hostnameOf(hostHeader) {
+    try {
+        return new URL(`http://${hostHeader}`).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+/** Refuse any request whose Host name is not loopback or in `allowed`. */
+export function hostGuard(allowed = []) {
+    const extra = allowed.map((h) => h.toLowerCase());
+    return async (c, next) => {
+        // Real HTTP always carries Host; an in-process request falls back to its URL.
+        const host = c.req.header("host") ?? new URL(c.req.url).host;
+        if (!host)
+            return forbidden(c, "Missing Host header");
+        const hostname = hostnameOf(host);
+        if (!hostname)
+            return forbidden(c, `Invalid Host header: ${host}`);
+        if (!isLoopbackHostname(hostname) && !extra.includes(hostname))
+            return forbidden(c, `Invalid Host: ${hostname}`);
+        await next();
+    };
+}
+/**
+ * Refuse a request whose `Origin` is present and not loopback, allowlisted or
+ * this server's own. `exempt(path)` skips paths that the Server Card spec
+ * requires to be readable from any origin (`Access-Control-Allow-Origin: *`).
+ */
+export function originGuard(allowedOrigins = [], exempt = () => false) {
+    const allowed = new Set(allowedOrigins.map((o) => o.replace(/\/+$/, "").toLowerCase()));
+    return async (c, next) => {
+        const origin = c.req.header("origin");
+        if (origin === undefined || exempt(c.req.path))
+            return next();
+        let url;
+        try {
+            url = new URL(origin);
+        }
+        catch {
+            return forbidden(c, `Invalid Origin: ${origin}`);
+        }
+        const ok = isLoopbackHostname(url.hostname) ||
+            allowed.has(url.origin.toLowerCase()) ||
+            url.host.toLowerCase() === (c.req.header("host") ?? new URL(c.req.url).host).toLowerCase();
+        if (!ok)
+            return forbidden(c, `Invalid Origin: ${origin}`);
+        await next();
+    };
+}

package/dist/transport/http.d.ts

@@ -1,2 +1,19 @@
-import { Hono } from "hono";
-export declare function httpApp(root?: string): Hono;
+import { Hono, type Context } from "hono";
+export interface HttpAppOptions {
+    /** Serve `project.fafm` and list it in the catalog. Default: the env switch. */
+    publishMemory?: boolean;
+    /**
+     * `local` (default): only loopback Host names are served, and the card shows
+     * memory in full (the reader is on this machine). `exposed`: bound beyond
+     * this machine; no Host check unless `allowedHosts` is given, and the card
+     * keeps memory private unless `publishMemory` is on.
+     */
+    exposure?: "local" | "exposed";
+    /** Extra Host names to accept (a reverse proxy's public name). */
+    allowedHosts?: string[];
+    /** Browser origins allowed to call this server, e.g. `https://app.example.com`. */
+    allowedOrigins?: string[];
+}
+/** The public origin of this request, honouring a reverse proxy's forwarded headers. */
+export declare function originOf(c: Context): string;
+export declare function httpApp(root?: string, opts?: HttpAppOptions): Hono;

package/dist/transport/http.js

@@ -10,12 +10,30 @@
  * notifications or resumability would set a `sessionIdGenerator` and hold
  * transports in a map; this one deliberately does not.
  *
- * Alongside the MCP endpoint it serves the discovery documents:
- *   GET /.well-known/mcp/server-card   — the Server Card + _meta block
- *   GET /.well-known/ai-catalog.json   — the three sibling entries
- *   GET /.well-known/fafa              — the agent identity card
+ * Alongside the MCP endpoint it serves the discovery documents (MCP Server
+ * Cards, SEP-2127 Final; AI Catalog specVersion 1.0):
+ *   GET /mcp/server-card               — the Server Card (the spec's reserved
+ *                                         `<streamable-http-url>/server-card`)
+ *   GET /.well-known/mcp/server-card   — the same card, the 1.x location (alias)
+ *   GET /.well-known/ai-catalog.json   — the card + its sibling entries
+ *   GET /AGENTS.md · /.well-known/fafa — the files the catalog links
+ *   GET /project.fafm                  — only with MCP_CONTEXT_CARD_PUBLISH_MEMORY=1:
+ *                                         memory is session data, private by default
+ *
+ * Local by default (MCP transports spec, Security Warning): the bin binds
+ * 127.0.0.1, `hostGuard` serves loopback Host names only (DNS rebinding), and
+ * `originGuard` refuses foreign browser origins with 403 on every route except
+ * the public discovery documents. Exposing the server (HOST=0.0.0.0) is a
+ * deliberate act; there is no authentication, so put it behind your own.
+ *
+ * Discovery documents carry the spec's CORS (GET only, `Content-Type` and
+ * `If-None-Match` allowed, `ETag` exposed), `Cache-Control: public,
+ * max-age=3600`, and an `ETag` honoured with `304 Not Modified`. Serve them over
+ * HTTPS in production (TLS is the host's job; HTTP is for local development).
  */
-import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
@@ -23,11 +41,57 @@ import { buildCatalog } from "../catalog-gen.js";
 import { fafaFile } from "../identity.js";
 import { createServer, NAME, ROOT, VERSION, serverCard } from "../server.js";
 import { renderCard, safeAccent } from "../render-card.js";
-export function httpApp(root = ROOT) {
+import { AI_CATALOG_MEDIA_TYPE, LEGACY_SERVER_CARD_PATH, MCP_PATH, SERVER_CARD_MEDIA_TYPE, publishMemoryFromEnv, ALLOWED_HOSTS_ENV, ALLOWED_ORIGINS_ENV, SERVER_CARD_PATH, } from "../constants.js";
+import { hostGuard, listFromEnv, originGuard } from "./guard.js";
+/**
+ * Public-by-design discovery documents: the Server Card spec requires them to
+ * be readable from any origin, so they get its CORS and skip the Origin check.
+ * They carry no private data (SEP-2127 rules that out).
+ */
+const PUBLIC_PATHS = [SERVER_CARD_PATH, LEGACY_SERVER_CARD_PATH, "/.well-known/ai-catalog.json", "/.well-known/fafa"];
+/** CORS exactly as the Server Card spec lists it. */
+const discoveryCors = cors({
+    origin: "*",
+    allowMethods: ["GET"],
+    allowHeaders: ["Content-Type", "If-None-Match"],
+    exposeHeaders: ["ETag"],
+});
+/** The public origin of this request, honouring a reverse proxy's forwarded headers. */
+export function originOf(c) {
+    const url = new URL(c.req.url);
+    const proto = (c.req.header("x-forwarded-proto") ?? url.protocol.replace(":", "")).split(",")[0].trim();
+    const host = (c.req.header("x-forwarded-host") ?? c.req.header("host") ?? url.host).split(",")[0].trim();
+    return `${proto}://${host}`;
+}
+/** A cacheable discovery response: Content-Type, Cache-Control, ETag, and 304 on a match. */
+function discovery(c, body, contentType) {
+    const etag = `"${createHash("sha256").update(body).digest("base64url").slice(0, 27)}"`;
+    c.header("Cache-Control", "public, max-age=3600");
+    c.header("ETag", etag);
+    const match = c.req.header("if-none-match");
+    if (match && match.split(",").some((t) => t.trim().replace(/^W\//, "") === etag)) {
+        return c.body(null, 304);
+    }
+    c.header("Content-Type", contentType);
+    return c.body(body);
+}
+export function httpApp(root = ROOT, opts = {}) {
+    const publishMemory = opts.publishMemory ?? publishMemoryFromEnv();
+    const exposure = opts.exposure ?? "local";
+    const allowedHosts = opts.allowedHosts ?? listFromEnv(process.env[ALLOWED_HOSTS_ENV]);
+    const allowedOrigins = opts.allowedOrigins ?? listFromEnv(process.env[ALLOWED_ORIGINS_ENV]);
     const app = new Hono();
-    app.use("*", cors());
+    // DNS-rebinding and cross-origin protection first, before any route runs.
+    if (exposure === "local" || allowedHosts.length)
+        app.use("*", hostGuard(allowedHosts));
+    app.use("*", originGuard(allowedOrigins, (path) => PUBLIC_PATHS.includes(path)));
+    for (const p of PUBLIC_PATHS)
+        app.use(p, discoveryCors);
+    app.use(MCP_PATH, cors());
+    app.use("/card", cors());
+    app.use("/", cors());
     // ── MCP endpoint — stateless ────────────────────────────────────────
-    app.all("/mcp", async (c) => {
+    app.all(MCP_PATH, async (c) => {
         const server = createServer(root);
         const transport = new WebStandardStreamableHTTPServerTransport({
             sessionIdGenerator: undefined, // stateless
@@ -42,34 +106,41 @@ export function httpApp(root = ROOT) {
         return res;
     });
     // ── Discovery documents ─────────────────────────────────────────────
-    app.get("/.well-known/mcp/server-card", (c) => c.json(serverCard()));
-    app.get("/.well-known/ai-catalog.json", (c) => {
-        c.header("content-type", "application/ai-catalog+json");
-        return c.body(JSON.stringify(buildCatalog(root), null, 2));
-    });
-    // Served at the well-known path, read from agent.fafa or .well-known/fafa.
-    app.get("/.well-known/fafa", (c) => {
-        const file = fafaFile(root);
-        if (!file)
-            return c.notFound();
-        c.header("content-type", "application/vnd.fafa+yaml");
-        return c.body(readFileSync(file, "utf8"));
-    });
+    const card = (c) => discovery(c, JSON.stringify(serverCard({ origin: originOf(c) }), null, 2), SERVER_CARD_MEDIA_TYPE);
+    app.get(SERVER_CARD_PATH, card);
+    app.get(LEGACY_SERVER_CARD_PATH, card);
+    app.get("/.well-known/ai-catalog.json", (c) => discovery(c, JSON.stringify(buildCatalog(root, { origin: originOf(c), publishMemory }), null, 2), AI_CATALOG_MEDIA_TYPE));
+    // The files the catalog links to, each with the type its entry declares.
+    // Fixed names only: nothing from the request picks a path.
+    const file = (path, type) => (c) => path && existsSync(path) ? discovery(c, readFileSync(path, "utf8"), type) : c.notFound();
+    app.get("/.well-known/fafa", (c) => file(fafaFile(root), "application/vnd.fafa+yaml")(c));
+    app.get("/AGENTS.md", file(join(root, "AGENTS.md"), "text/markdown; charset=utf-8"));
+    if (publishMemory)
+        app.get("/project.fafm", file(join(root, "project.fafm"), "application/vnd.fafm+yaml"));
     // ── The card — the view for people ──────────────────────────────────
     app.get("/card", (c) => {
         const q = c.req.query();
         const theme = (["light", "dark", "auto"].includes(q.theme ?? "") ? q.theme : "auto");
         c.header("content-type", "text/html; charset=utf-8");
-        return c.body(renderCard(root, { theme, accent: safeAccent(q.accent), expanded: q.expand === "all" }));
+        return c.body(renderCard(root, {
+            theme,
+            accent: safeAccent(q.accent),
+            layout: q.layout === "portrait" ? "portrait" : "landscape",
+            expanded: q.expand === "all",
+            // A card that may be read beyond this machine keeps memory private
+            // unless the project publishes it.
+            memory: exposure === "exposed" && !publishMemory ? "private" : "full",
+        }));
     });
     // ── Index ───────────────────────────────────────────────────────────
     app.get("/", (c) => c.json({
         name: NAME,
         version: VERSION,
-        mcp: "/mcp",
+        mcp: MCP_PATH,
+        serverCard: SERVER_CARD_PATH,
         card: "/card",
         wellKnown: [
-            "/.well-known/mcp/server-card",
+            LEGACY_SERVER_CARD_PATH,
             "/.well-known/ai-catalog.json",
             "/.well-known/fafa",
         ],

package/docs/MECHANISMS.md

@@ -21,15 +21,22 @@ top‑level `_meta`. So the card is served the two ways a client can consume it:
 
 ```
 resources/read  mcp-context-card://server-card       # in band
-GET /.well-known/mcp/server-card                 # out of band (http transport)
+GET /mcp/server-card                             # out of band (http transport; the 1.x
+                                                 # /.well-known/mcp/server-card still answers)
 ```
 
-Both return:
+Both return the card below (over HTTP it also carries `remotes`, the
+Streamable HTTP endpoint at `<origin>/mcp` and its protocol versions):
 
 ```jsonc
 {
-  "name": "mcp-context-card",
-  "version": "1.4.0",
+  "$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",
@@ -78,39 +85,52 @@ publisher lists artifacts, each entry keyed by its **media type** (`type`).
 GET /.well-known/ai-catalog.json
 ```
 
+Served from `https://ctx.example.com` (1.6.0, this repo's own files):
+
 ```jsonc
 {
   "specVersion": "1.0",
   "host": { "displayName": "mcp-context-card", "identifier": "https://github.com/Wolfe-Jam/mcp-context-card" },
   "entries": [
-    {
-      "identifier": "urn:air:mcp-context-card:context",
-      "type": "text/markdown",
-      "mediaType": "text/markdown",
-      "description": "…derived from the real AGENTS.md — section count + headings…",
-      "url": "./AGENTS.md"
-    },
-    { "identifier": "urn:air:mcp-context-card:memory",   "type": "application/vnd.fafm+yaml", "…": "…" },
-    { "identifier": "urn:air:mcp-context-card:identity", "type": "application/vnd.fafa+yaml", "…": "…" }
+    { "identifier": "urn:air:faf.one:mcp:mcp-context-card", "type": "application/mcp-server-card+json",
+      "url": "https://ctx.example.com/mcp/server-card" },
+    { "identifier": "urn:air:faf.one:context:mcp-context-card", "type": "text/markdown",
+      "displayName": "mcp-context-card — project context (AGENTS.md)",
+      "description": "Agent instructions for this project — 9 section(s): Setup, Build, Test, …",
+      "url": "https://ctx.example.com/AGENTS.md" },
+    { "identifier": "urn:air:faf.one:identity:mcp-context-card", "type": "application/vnd.fafa+yaml",
+      "url": "https://ctx.example.com/.well-known/fafa",
+      "extensions": { "io.github.Wolfe-Jam.mcp-context-card": { "iana": "https://www.iana.org/assignments/media-types/application/vnd.fafa+yaml" } },
+      "…": "…" }
   ]
 }
 ```
 
+The static `.well-known/ai-catalog.json` is the same, with relative URLs and the
+Server Card inline as `data`. Memory (`application/vnd.fafm+yaml`) is listed only
+with `MCP_CONTEXT_CARD_PUBLISH_MEMORY=1`.
+
 **Why it looks like this:**
 
+- **The Server Card comes first** (`application/mcp-server-card+json`). It
+  carries its own name, description and version, so the entry repeats none.
 - **`type` is the routing key.** A consumer scanning catalogs for
   `text/markdown` context, or `application/vnd.fafm+yaml` memory, finds the
   entry without knowing this publisher.
 - **`identifier` is a `urn:air:` URN** scoped to the publisher
-  (`urn:air:<host>:<concern>`). In ai-catalog's
+  (`urn:air:{domain}:{namespace}:{name}`). The domain is the one your `.fafa`
+  declares (`faf card init` writes it into `agent.id`); `faf.one` above is this
+  repo's. With no `.fafa` domain, the served catalog uses the serving host and
+  the static file uses plain IDs. No domain is ever invented. In ai-catalog's
   [trust‑manifest ADRs](https://github.com/Agent-Card/ai-catalog/tree/main/adr),
-  `urn:air` identifiers carry a publisher‑domain‑aligned trust manifest — the
-  entries here align to `github.com/Wolfe-Jam/mcp-context-card`.
+  `urn:air` identifiers carry a publisher‑domain‑aligned trust manifest, so the
+  domain in the identifier is the one a publisher would sign with.
 - **`description` is derived from real content** — the live AGENTS.md heading
   list, the current fact count, the agent's own description — not a blurb that
   drifts. See `buildCatalog()` in [`src/catalog-gen.ts`](../src/catalog-gen.ts).
-- **`url` is relative.** Served over HTTP it resolves against the origin; in a
-  repo browser, against the tree.
+- **`url` is absolute when served** (against the request's origin, honouring a
+  reverse proxy's forwarded headers) and relative in the static file, so it also
+  resolves in a repo browser.
 
 ---
 

package/docs/TRANSPORT.md

@@ -6,8 +6,9 @@ the Server Card `_meta` block, and the memory file are identical either way
 
 ```
 mcp-context-card              → stdio                 (default; an MCP host spawns this)
-mcp-context-card --http       → Streamable HTTP :3000
-PORT=8080 mcp-context-card    → Streamable HTTP :8080 (a hosted deploy sets PORT)
+mcp-context-card --http       → Streamable HTTP 127.0.0.1:3000 (this machine only)
+PORT=8080 mcp-context-card    → Streamable HTTP 127.0.0.1:8080
+HOST=0.0.0.0 PORT=8080 …      → exposed beyond this machine (a hosted deploy or container)
 mcp-context-card --stdio      → force stdio even when PORT is set
 ```
 
@@ -79,8 +80,40 @@ when the server needs to:
 "memory" is a file on disk, not a live subscription. A fork that adds
 streaming tools would flip this. See `src/transport/http.ts`.
 
-### DNS-rebinding protection
-
-Off by default (the server should run anywhere with no config). For a real
-deployment, pass `allowedHosts` / `allowedOrigins` to the transport and set
-`enableDnsRebindingProtection: true`.
+### Security: local by default
+
+The MCP transports spec (Streamable HTTP, Security Warning) asks three things
+of a server, and this one does them as follows:
+
+| Spec | Here |
+|---|---|
+| MUST validate `Origin`; refuse an invalid one with 403 | `originGuard` on every route except the public discovery documents: a request with no `Origin` (a non-browser client), from a page on this machine, from an allowlisted origin, or from the server's own origin passes; any other gets 403 with a JSON-RPC error (`id: null`) |
+| SHOULD bind only to localhost when running locally | binds `127.0.0.1` unless `HOST` says otherwise; the startup line says which |
+| SHOULD authenticate every connection | not built in: keep it local, or put it behind your own auth |
+| SHOULD rate-limit the Server Card endpoint (Server Card spec) | not built in: your proxy or host's limiter |
+
+A local server also checks the `Host` header (`hostGuard`, the SDK's Express
+`hostHeaderValidation` semantics for Hono): only loopback names are served, so a
+DNS name rebound to 127.0.0.1 is refused, including on plain GETs, which often
+carry no `Origin`.
+
+The discovery documents (`/mcp/server-card`, `/.well-known/ai-catalog.json`,
+`/.well-known/fafa`) stay readable from any origin with
+`Access-Control-Allow-Origin: *`, because the Server Card spec requires it and
+they carry no private data.
+
+| Setting | Effect |
+|---|---|
+| `HOST=0.0.0.0` | expose the server (containers, hosted deploys); the Host check is then off unless names are listed below |
+| `MCP_CONTEXT_CARD_ALLOWED_HOSTS=ctx.example.com` | extra Host names to accept, e.g. a reverse proxy's public name in front of a local bind |
+| `MCP_CONTEXT_CARD_ALLOWED_ORIGINS=https://app.example.com` | browser origins allowed to call the server |
+| `MCP_CONTEXT_CARD_PUBLISH_MEMORY=1` | serve `project.fafm`, list it in the AI Catalog, and show memory facts on an exposed `/card` |
+
+### Where memory shows
+
+| Surface | Reader | Memory facts |
+|---|---|---|
+| `mcp-context-card card`, the MCP App panel, `render_context_card`, `save_context_card` | you and your agent | shown |
+| `GET /card`, local server | a browser on this machine | shown |
+| `GET /card`, exposed server | anyone who can reach it | the count only, unless `MCP_CONTEXT_CARD_PUBLISH_MEMORY=1` |
+| `GET /project.fafm`, the AI Catalog | anyone, and crawlers | not served or listed, unless `MCP_CONTEXT_CARD_PUBLISH_MEMORY=1` |

package/docs/WIRING.md

@@ -46,7 +46,7 @@
 ### Streamable HTTP (remote)
 
 ```bash
-PORT=8080 npx mcp-context-card        # or:  npx mcp-context-card --http
+HOST=0.0.0.0 PORT=8080 npx mcp-context-card   # exposed; without HOST it binds 127.0.0.1 only
 ```
 
 ```jsonc
@@ -104,10 +104,15 @@ To serve *your* artifacts:
 1. **Replace the three files** — `AGENTS.md`, `project.fafm`, `.well-known/fafa`
    — with your own, or point `MCP_CONTEXT_CARD_ROOT` at a directory that has them.
    `AGENTS.md` is the one with a real standard; the other two are swappable.
-2. **Rename the namespace.** `serverCardMeta()` in `src/identity.ts` uses
-   `io.github.Wolfe-Jam.mcp-context-card/*` keys, and `buildCatalog()` in
-   `src/catalog-gen.ts` uses `urn:air:mcp-context-card:*` identifiers. Change both to
-   a domain or GitHub identity you control ([MECHANISMS.md](./MECHANISMS.md)).
+2. **Set your domain in your `.fafa`, not in code.** The AI Catalog identifiers
+   (`urn:air:{domain}:{namespace}:{name}`) take the domain and short name from
+   your project's `.fafa`: `npx faf-cli card init` (or `--domain example.com`)
+   writes `agent.id: urn:air:example.com:agent:<short-name>`, and the catalog
+   follows it. No `.fafa`, no invented domain: the served catalog uses the host
+   it's served from, and the static file uses plain IDs. Only the Server Card
+   `_meta` key namespace (`io.github.Wolfe-Jam.mcp-context-card/*`,
+   `META_NS` in `src/identity.ts`) is a code constant. Change it if you fork
+   ([MECHANISMS.md](./MECHANISMS.md)).
 3. **Swap the media types** in `serverCardMeta()` if your memory / identity
    artifacts aren't `.fafm` / `.fafa`. Drop the `iana` field for any that isn't
    a registered type.