mcp-context-card 1.3.1 → 1.4.0

package/.well-known/fafa

@@ -9,7 +9,7 @@ agent:
   name: "mcp-context-card"
   displayName: "mcp-context-card"
   vendor: "io.github.Wolfe-Jam"
-  version: "1.3.1"
+  version: "1.4.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,22 @@
 
 All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
 
+## 1.4.0
+
+The card reads the `.fafa` that `faf card init` writes, and shows the agent's ID.
+
+- **Identity reads `agent.fafa`.** `faf card init` writes the agent's `.fafa`
+  to `./agent.fafa`; the card, `whoami`, the AI Catalog and the served
+  `/.well-known/fafa` now read it, and fall back to `.well-known/fafa` as
+  before. With both, `agent.fafa` wins.
+- The README's identity line names the `.fafa`, not "its own Server Card"
+  (the MCP Server Card is the `_meta` block).
+- **The agent ID shows.** `agent.id` (the `urn:air:…` that `faf card init`
+  writes) is read and shown in the card's Discovery section, the Markdown
+  card and `whoami`. No `id`, no line.
+
+No API change. 140 tests, all green.
+
 ## 1.3.1
 
 The registry listing catches up with 1.3.0.

package/README.md

@@ -28,7 +28,7 @@ npx mcp-context-card card
 
 ![the card's memory section — a real, tagged, verified fact](./docs/img/card-memory.png)
 
-**identity** — what this server is, from its own Server Card.
+**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)
 
@@ -70,7 +70,7 @@ It composes:
 
 Vendor-free — context is plain Markdown (`AGENTS.md`); the memory and
 identity formats are swappable examples. It reads and writes only its own
-three files (`AGENTS.md`, `project.fafm`, `.well-known/fafa`), plus the
+three files (`AGENTS.md`, `project.fafm`, and `agent.fafa` or `.well-known/fafa`), plus the
 `context-card.html` it saves on request — no general file access, no shell,
 no search.
 
@@ -235,7 +235,7 @@ over both transports:
 4. **Discovery** — `list_context_sources()`, then the same server over stateless
    HTTP with its `.well-known` routes and `GET /card`.
 
-134 tests on Linux, macOS, and Windows, coverage‑gated in CI. Two spawn a real
+140 tests on Linux, macOS, and Windows, coverage‑gated in CI. 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

package/dist/bin.d.ts

@@ -8,7 +8,7 @@ export interface Launch {
     root: string;
 }
 /** what a bare `--help` / `help` prints. */
-export declare const HELP = "mcp-context-card 1.3.1\nServe a project's context (AGENTS.md), memory, and identity over MCP.\n\nUSAGE\n  mcp-context-card                  stdio MCP server \u2014 what an MCP host spawns (default)\n  mcp-context-card --http           stateless Streamable HTTP on PORT (default 3000)\n  mcp-context-card --stdio          force stdio even when PORT is set\n  mcp-context-card card             this dir's context card \u2014 opens it in your browser\n                                    at a terminal; HTML to stdout when piped ( > f.html )\n                                      --theme light|dark   --accent #hex\n                                      --expanded (all sections open)   --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.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";
 /**
  * Decide how to launch, from argv + env. Pure — so the mode matrix is unit
  * tested without spawning a process.

package/dist/catalog-gen.js

@@ -13,12 +13,13 @@ 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 } from "./identity.js";
+import { META_NS, fafaFile } from "./identity.js";
 const iana = (t) => `https://www.iana.org/assignments/media-types/${t}`;
 export function buildCatalog(root) {
     const agents = parseAgentsMd(join(root, "AGENTS.md"));
     const fafm = parseFafm(join(root, "project.fafm"));
-    const fafa = parseFafa(join(root, ".well-known/fafa"));
+    const file = fafaFile(root);
+    const fafa = file ? parseFafa(file) : null;
     const host = fafa?.name ?? "mcp-context-card";
     return {
         specVersion: "1.0",

package/dist/constants.d.ts

@@ -1,7 +1,7 @@
 /** Server identity constants, in their own module so any file can import
  *  them without pulling in the whole server. */
 export declare const NAME = "mcp-context-card";
-export declare const VERSION = "1.3.1";
+export declare const VERSION = "1.4.0";
 export declare const SERVER_CARD_URI = "mcp-context-card://server-card";
 /** MCP Apps (io.modelcontextprotocol/ui): the card as an inline UI resource.
  *  A host that supports MCP Apps fetches this resource and renders it in a

package/dist/constants.js

@@ -1,7 +1,7 @@
 /** Server identity constants, in their own module so any file can import
  *  them without pulling in the whole server. */
 export const NAME = "mcp-context-card";
-export const VERSION = "1.3.1";
+export const VERSION = "1.4.0";
 export const SERVER_CARD_URI = "mcp-context-card://server-card";
 /** MCP Apps (io.modelcontextprotocol/ui): the card as an inline UI resource.
  *  A host that supports MCP Apps fetches this resource and renders it in a

package/dist/faf/parse-fafa.js

@@ -17,6 +17,7 @@ export function parseFafa(path) {
         version: str(doc.version),
         name: str(agent.name),
         displayName: str(agent.displayName),
+        id: str(agent.id),
         vendor: str(agent.vendor),
         agentVersion: str(agent.version),
         description: str(agent.description),

package/dist/faf/types.d.ts

@@ -26,6 +26,8 @@ export interface AgentIdentity {
     version?: string;
     name?: string;
     displayName?: string;
+    /** `agent.id` — globally unique, e.g. `urn:air:example.com:agent:weather` (what `faf card init` writes). */
+    id?: string;
     vendor?: string;
     agentVersion?: string;
     description?: string;

package/dist/identity.d.ts

@@ -1,9 +1,14 @@
 import type { AgentIdentity } from "./faf/types.js";
 /** The `_meta` key namespace — the publisher's, reverse-DNS. */
 export declare const META_NS = "io.github.Wolfe-Jam.mcp-context-card";
+/** Where a project keeps its `.fafa`, in the order they are read. */
+export declare const FAFA_FILES: readonly ["agent.fafa", ".well-known/fafa"];
+/** The project's `.fafa`: `agent.fafa` (what `faf card init` writes), else
+ *  `.well-known/fafa`. null when there is neither. */
+export declare function fafaFile(root: string): string | null;
 export declare function identity(root: string): AgentIdentity | null;
 /**
- * The identity to show: the `.well-known/fafa` card if present — richer and
+ * The identity to show: the `.fafa` ({@link fafaFile}) if present — richer and
  * portable — else a thin one from `package.json` (the common project has no
  * `.fafa`). null only when neither exists.
  */

package/dist/identity.js

@@ -1,20 +1,34 @@
 /**
- * identity — reads this server's own `.well-known/fafa` and reports it, and
- * builds the `_meta` context block for the Server Card.
+ * identity — reads this server's own `.fafa` (`agent.fafa`, where `faf card
+ * init` writes it, else `.well-known/fafa`) and reports it, and builds the
+ * `_meta` context block for the Server Card.
  *
  * The `_meta` block is three reverse-DNS-namespaced keys — one per concern
  * (context, memory, identity) — each naming a source file, its media type,
  * and (where one exists) its IANA anchor. Same shape a real client reading
  * the Server Card would consume; see server.ts for where it's emitted.
  */
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parseFafa } from "./faf/parse-fafa.js";
 /** The `_meta` key namespace — the publisher's, reverse-DNS. */
 export const META_NS = "io.github.Wolfe-Jam.mcp-context-card";
 const iana = (t) => `https://www.iana.org/assignments/media-types/${t}`;
+/** Where a project keeps its `.fafa`, in the order they are read. */
+export const FAFA_FILES = ["agent.fafa", ".well-known/fafa"];
+/** The project's `.fafa`: `agent.fafa` (what `faf card init` writes), else
+ *  `.well-known/fafa`. null when there is neither. */
+export function fafaFile(root) {
+    for (const f of FAFA_FILES) {
+        const p = join(root, f);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
 export function identity(root) {
-    return parseFafa(join(root, ".well-known/fafa"));
+    const file = fafaFile(root);
+    return file ? parseFafa(file) : null;
 }
 /** Fall back to package.json — most projects have no .fafa, but they have this. */
 function fromPackageJson(root) {
@@ -34,7 +48,7 @@ function fromPackageJson(root) {
     }
 }
 /**
- * The identity to show: the `.well-known/fafa` card if present — richer and
+ * The identity to show: the `.fafa` ({@link fafaFile}) if present — richer and
  * portable — else a thin one from `package.json` (the common project has no
  * `.fafa`). null only when neither exists.
  */
@@ -45,7 +59,7 @@ export function resolveIdentity(root) {
 export function whoami(root) {
     const id = resolveIdentity(root);
     if (!id)
-        return "(no .well-known/fafa or package.json found)";
+        return "(no agent.fafa, .well-known/fafa or package.json found)";
     const parts = [
         id.displayName ?? id.name ?? "(unnamed)",
         id.agentVersion ? `v${id.agentVersion}` : null,
@@ -53,7 +67,7 @@ export function whoami(root) {
         id.status ? `status: ${id.status}` : null,
         id.license ? id.license : null,
     ].filter(Boolean);
-    return parts.join(" · ") + (id.description ? `\n${id.description}` : "");
+    return parts.join(" · ") + (id.description ? `\n${id.description}` : "") + (id.id ? `\n${id.id}` : "");
 }
 /**
  * The `_meta` context block — one namespaced key per concern. The `context`

package/dist/render-card.js

@@ -195,7 +195,7 @@ export function renderCard(root, opts = {}) {
     ${memoryBody}
   </section>
   <section>
-    <p class="label">Discovery</p>
+    <p class="label">Discovery</p>${id?.id ? `\n    <p class="fetch">Agent ID <code>${escapeHtml(id.id)}</code></p>` : ""}
     <table class="disc"><thead><tr><th>concern</th><th>source</th><th>media type</th></tr></thead><tbody>${rows}</tbody></table>
     <p class="fetch">A machine reads this over <b>MCP</b> from the
       <code>${escapeHtml(SERVER_CARD_URI)}</code> resource; over <b>HTTP</b> also
@@ -294,6 +294,6 @@ export function renderCardText(root, opts = {}) {
             .join("\n")}${rest ? `\n\n…and ${plural(rest, "more fact")}, in the full card` : ""}`
         : "**Memory** · no facts yet. Ask your agent to remember something, and it lands here.");
     const rows = Object.entries(meta).map(([k, v]) => `| ${k.slice(META_NS.length + 1)} | \`${v.source}\` | \`${v.mediaType}\` |`);
-    out.push(["**Discovery**", "| concern | source | media type |", "|---|---|---|", ...rows].join("\n"));
+    out.push(["**Discovery**", ...(id?.id ? [`Agent ID \`${id.id}\``, ""] : []), "| concern | source | media type |", "|---|---|---|", ...rows].join("\n"));
     return out.join("\n\n");
 }

package/dist/transport/http.js

@@ -16,11 +16,11 @@
  *   GET /.well-known/fafa              — the agent identity card
  */
 import { 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";
 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) {
@@ -47,9 +47,13 @@ export function httpApp(root = ROOT) {
         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(join(root, ".well-known/fafa"), "utf8"));
+        return c.body(readFileSync(file, "utf8"));
     });
     // ── The card — the view for people ──────────────────────────────────
     app.get("/card", (c) => {

package/docs/MECHANISMS.md

@@ -29,7 +29,7 @@ Both return:
 ```jsonc
 {
   "name": "mcp-context-card",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "_meta": {
     "io.github.Wolfe-Jam.mcp-context-card/context": {
       "source": "AGENTS.md",

package/docs/card-dark.html

@@ -100,7 +100,7 @@ details.ctx-section>.md{padding:0 0 16px}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.3.1</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
+    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.4.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>

package/docs/card-light.html

@@ -100,7 +100,7 @@ details.ctx-section>.md{padding:0 0 16px}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.3.1</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
+    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.4.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>

package/docs/card.html

@@ -100,7 +100,7 @@ details.ctx-section>.md{padding:0 0 16px}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.3.1</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
+    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.4.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>

package/docs/index.html

@@ -100,7 +100,7 @@ details.ctx-section>.md{padding:0 0 16px}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.3.1</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
+    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.4.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-context-card",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "mcpName": "io.github.Wolfe-Jam/mcp-context-card",
   "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 ai-catalog.json sibling entries.",
   "keywords": [

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.Wolfe-Jam/mcp-context-card",
   "title": "MCP Context Card",
   "description": "MCP server for a project's context (AGENTS.md), memory, and identity — base or drop-in extension.",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "repository": {
     "url": "https://github.com/Wolfe-Jam/mcp-context-card",
     "source": "github"
@@ -14,7 +14,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "mcp-context-card",
-      "version": "1.3.1",
+      "version": "1.4.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"