mcp-context-card 0.5.0 → 0.5.1

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

@@ -29,7 +29,7 @@
       "displayName": "mcp-context-card — agent identity (.fafa)",
       "type": "application/vnd.fafa+yaml",
       "mediaType": "application/vnd.fafa+yaml",
-      "description": "Reference MCP server that makes a project's context (AGENTS.md), memory, and identity discoverable to any MCP client, through the Server Card _meta block and a self-published ai-catalog.json.",
+      "description": "An MCP server that makes a project's context (AGENTS.md), cross-session memory, and identity discoverable to any MCP client, 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"

package/.well-known/fafa

@@ -8,11 +8,11 @@ version: "1.0"
 agent:
   name: "mcp-context-card"
   displayName: "mcp-context-card"
-  vendor: "reference"
-  version: "0.5.0"
+  vendor: "io.github.wolfe-jam"
+  version: "0.5.1"
   description: >-
-    Reference MCP server that makes a project's context (AGENTS.md), memory,
-    and identity discoverable to any MCP client, through the Server Card _meta
-    block and a self-published ai-catalog.json.
-  status: "reference"
+    An MCP server that makes a project's context (AGENTS.md), cross-session
+    memory, and identity discoverable to any MCP client, through the Server
+    Card _meta block and a self-published ai-catalog.json.
+  status: "published"
   license: "MIT"

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
 
+## 0.5.1
+
+First-hour ergonomics and wording, from the 0.5.0 soak.
+
+- `--help` / `-h` and `--version` / `-V` (and the `help` / `version` subcommands)
+  — a bare `mcp-context-card` is a stdio server that waits on stdin, so at a
+  terminal it looked idle with no way to ask what it was.
+- stdio mode now prints one line to **stderr** on start
+  (`… · stdio · waiting for an MCP host on stdin`) — mirrors what `--http`
+  already did. stdout stays clean for the JSON-RPC wire.
+- The npm and `server.json` descriptions no longer open with "Reference MCP
+  server" — they now match the README ("An MCP server that makes a project's
+  context, memory, and identity discoverable…"). Same in `.well-known/fafa`;
+  the three `project.fafm` facts are `type: fact`. `package.json` `author` set
+  to the LICENSE holder.
+- `.well-known/fafa` — `vendor: io.github.wolfe-jam`, `status: published`
+  (were both `reference`). Shows in `whoami` and as the card's pills.
+- **Fix:** `remember` on a project that has never had a `project.fafm` threw
+  `ENOENT` instead of starting one — the single most common first-use case.
+  Found by a real host check (Cursor, 2026-09-04). `remember` now creates a
+  fresh `.fafm` on first write; `forget` and `parseFafm` were already safe on
+  a missing file and are unchanged in behaviour.
+- `docs/WIRING.md`: a note on hosts whose spawn `PATH` lacks `npx`
+  (`spawn npx ENOENT`, observed in Cursor) — point `command` at `node` +
+  the installed `dist/bin.js` instead.
+
 ## 0.5.0
 
 The first public release — installable, and settling in the open before a
@@ -70,6 +96,6 @@ tested server.
 
 ## v0.1.0 (2026-08-12)
 
-- Initial private reference implementation (as `faf-trinity`): project context,
+- Initial private implementation (as `faf-trinity`): project context,
   persistent memory, and agent identity in one MCP server, through two
   mechanisms already live in production. `demo.ts` proved all three.

package/dist/bin.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-export type Mode = "stdio" | "http" | "card";
+export type Mode = "stdio" | "http" | "card" | "help" | "version";
 export interface Launch {
     mode: Mode;
     /** port for http mode (ignored otherwise). */
@@ -7,14 +7,18 @@ export interface Launch {
     /** directory to read from — cwd for `card`, else MCP_CONTEXT_CARD_ROOT ?? package root. */
     root: string;
 }
+/** what a bare `--help` / `help` prints. */
+export declare const HELP = "mcp-context-card 0.5.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 [> f.html]  render this directory's context card to stdout\n                                      --theme light|dark    --accent #hex\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` or `--http` to see output directly.\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.
  *
- *   card               → render the cwd's card to stdout
- *   (nothing)          → stdio
- *   --http | PORT=<n>  → http
- *   --stdio            → stdio, even when PORT is set
+ *   --help  | -h  | help     → print usage
+ *   --version | -V | version → print version
+ *   card                     → render the cwd's card to stdout
+ *   (nothing)                → stdio
+ *   --http | PORT=<n>        → http
+ *   --stdio                  → stdio, even when PORT is set
  */
 export declare function resolveLaunch(argv: readonly string[], env?: NodeJS.ProcessEnv): Launch;
 /** value of `--flag <value>` in argv, or undefined. */

package/dist/bin.js

@@ -8,6 +8,8 @@
  *   mcp-context-card --stdio      → force stdio even when PORT is set
  *   mcp-context-card card         → render THIS directory's context card to stdout
  *                                   ( > card.html · --theme light|dark · --accent #hex )
+ *   mcp-context-card --help       → usage
+ *   mcp-context-card --version    → version
  *
  * MCP_CONTEXT_CARD_ROOT=/path/to/project → read AGENTS.md / project.fafm /
  *   .well-known/ from there instead of the package's own bundled copies.
@@ -15,17 +17,46 @@
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { NAME, VERSION } from "./constants.js";
 import { ROOT, serve } from "./server.js";
+/** what a bare `--help` / `help` prints. */
+export const HELP = `${NAME} ${VERSION}
+Serve a project's context (AGENTS.md), memory, and identity over MCP.
+
+USAGE
+  mcp-context-card                  stdio MCP server — what an MCP host spawns (default)
+  mcp-context-card --http           stateless Streamable HTTP on PORT (default 3000)
+  mcp-context-card --stdio          force stdio even when PORT is set
+  mcp-context-card card [> f.html]  render this directory's context card to stdout
+                                      --theme light|dark    --accent #hex
+  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
+
+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\` or \`--http\` to see output directly.
+https://github.com/Wolfe-Jam/mcp-context-card
+`;
 /**
  * Decide how to launch, from argv + env. Pure — so the mode matrix is unit
  * tested without spawning a process.
  *
- *   card               → render the cwd's card to stdout
- *   (nothing)          → stdio
- *   --http | PORT=<n>  → http
- *   --stdio            → stdio, even when PORT is set
+ *   --help  | -h  | help     → print usage
+ *   --version | -V | version → print version
+ *   card                     → render the cwd's card to stdout
+ *   (nothing)                → stdio
+ *   --http | PORT=<n>        → http
+ *   --stdio                  → stdio, even when PORT is set
  */
 export function resolveLaunch(argv, env = process.env) {
+    const has = (...flags) => flags.some((f) => argv.includes(f));
+    if (argv[0] === "help" || has("--help", "-h"))
+        return { mode: "help", port: 0, root: ROOT };
+    if (argv[0] === "version" || has("--version", "-V"))
+        return { mode: "version", port: 0, root: ROOT };
     if (argv[0] === "card") {
         return {
             mode: "card",
@@ -49,7 +80,13 @@ export function flagValue(argv, flag) {
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
     const argv = process.argv.slice(2);
     const { mode, port, root } = resolveLaunch(argv);
-    if (mode === "card") {
+    if (mode === "help") {
+        process.stdout.write(HELP);
+    }
+    else if (mode === "version") {
+        process.stdout.write(`${VERSION}\n`);
+    }
+    else if (mode === "card") {
         const { renderCard, safeAccent } = await import("./render-card.js");
         const theme = flagValue(argv, "--theme");
         process.stdout.write(renderCard(root, {
@@ -62,9 +99,12 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
         const { serve: serveHttp } = await import("@hono/node-server");
         serveHttp({ fetch: httpApp(root).fetch, port });
         // stderr, not stdout — stdout is the MCP wire in stdio mode.
-        console.error(`mcp-context-card · http · :${port}  (POST /mcp · GET /card · GET /.well-known/*)`);
+        console.error(`${NAME} · http · :${port}  (POST /mcp · GET /card · GET /.well-known/*)`);
     }
     else {
+        // stderr so it never touches the JSON-RPC wire on stdout; a bare run at a
+        // terminal otherwise looks hung.
+        console.error(`${NAME} · stdio · waiting for an MCP host on stdin  (--help for usage · Ctrl-C to exit)`);
         await serve(new StdioServerTransport(), root);
     }
 }

package/dist/constants.d.ts

@@ -1,5 +1,5 @@
 /** 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 = "0.5.0";
+export declare const VERSION = "0.5.1";
 export declare const SERVER_CARD_URI = "mcp-context-card://server-card";

package/dist/constants.js

@@ -1,5 +1,5 @@
 /** 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 = "0.5.0";
+export const VERSION = "0.5.1";
 export const SERVER_CARD_URI = "mcp-context-card://server-card";

package/dist/faf/parse-fafm.js

@@ -27,8 +27,29 @@ function factMap(entries) {
         m.set(k, q(v));
     return m;
 }
+/** A brand-new .fafm — what `remember()` writes the first time a project has none. */
+const FRESH_FAFM = `version: "1.1"
+memory:
+  facts: []
+  sessions: []
+  preferences: {}
+  custom: {}
+`;
+/**
+ * Load the .fafm at `path`. A missing file is not an error here — it means
+ * "no memory yet", and remember()/forget() need a document to edit even
+ * before anything has ever been written. Any other read error (permissions,
+ * a directory in the way, …) still throws.
+ */
 function load(path) {
-    return parseDocument(readFileSync(path, "utf8"));
+    try {
+        return parseDocument(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return parseDocument(FRESH_FAFM);
+        throw err;
+    }
 }
 export function parseFafm(path) {
     let doc;

package/dist/transport/http.js

@@ -4,9 +4,9 @@
  * A Hono app. `POST /mcp` is the MCP endpoint, run **stateless**: a fresh
  * server + transport per request, `sessionIdGenerator: undefined`, and
  * `enableJsonResponse` so every response is a complete JSON body (no SSE
- * stream, nothing to keep open). That's the right default for a reference
- * server — it scales horizontally, needs no sticky sessions, and there's
- * no per-connection state to leak. A server that needs server-streamed
+ * stream, nothing to keep open). That's the right default here — it scales
+ * horizontally, needs no sticky sessions, and there's no per-connection
+ * state to leak. A server that needs server-streamed
  * notifications or resumability would set a `sessionIdGenerator` and hold
  * transports in a map; this one deliberately does not.
  *

package/docs/MECHANISMS.md

@@ -5,7 +5,7 @@ mechanisms that already exist in the MCP ecosystem. This is the wire‑level
 detail.
 
 The **context** concern points at `AGENTS.md` (`text/markdown`). Memory and
-identity have no de‑facto standard, so the reference points them at `.fafm` and
+identity have no de‑facto standard, so this server points them at `.fafm` and
 `.fafa`. Everything below is about the *shape* — swap the artifacts and the
 mechanism is unchanged.
 

package/docs/TRANSPORT.md

@@ -81,6 +81,6 @@ streaming tools would flip this. See `src/transport/http.ts`.
 
 ### DNS-rebinding protection
 
-Off by default (a reference server should run anywhere with no config). For
-a real deployment, pass `allowedHosts` / `allowedOrigins` to the transport
-and set `enableDnsRebindingProtection: true`.
+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`.

package/docs/WIRING.md

@@ -26,6 +26,13 @@
 - **`MCP_CONTEXT_CARD_ROOT`** — directory holding `AGENTS.md`, `project.fafm`, and
   `.well-known/fafa`. Omit it and the server uses its own bundled copies.
 - `stdout` is the JSON‑RPC wire; logging is on `stderr`.
+- **`command: "npx"` fails to spawn on some hosts** (`spawn npx ENOENT`) — the
+  host's process spawn doesn't inherit a shell `PATH` that has `npx` on it,
+  even though a login shell does. Observed with Cursor. Fix: point `command`
+  at an absolute path to `node`, with the installed package's `dist/bin.js` as
+  the arg — e.g. `command: "node"`, `args: ["/path/to/node_modules/mcp-context-card/dist/bin.js"]`
+  (or wherever `npm install -g` / your package manager put it; find it with
+  `npm root -g` or `which mcp-context-card` after a global install).
 
 ### Streamable HTTP (remote)
 
@@ -72,7 +79,10 @@ And to discover what a server offers before committing to it:
 await client.callTool({ name: "list_context_sources", arguments: {} });
 // → { context: { source: "AGENTS.md", mediaType: "text/markdown", present: true, sections: 9 },
 //     memory:  { … }, identity: { … },
-//     surfaces: { serverCard: [...], aiCatalog: [...] } }
+//     surfaces: { mcp: { serverCard: "resource mcp-context-card://server-card" },
+//                 http: { serverCard: "GET /.well-known/mcp/server-card",
+//                         aiCatalog: "GET /.well-known/ai-catalog.json",
+//                         card: "GET /card" } } }
 ```
 
 ---

package/docs/card.html

@@ -73,7 +73,7 @@ section:last-child{border-bottom:0}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">v0.5.0</span><span class="pill accent">reference</span><span class="pill">MIT</span></div>
+    <div class="pills"><span class="pill">io.github.wolfe-jam</span><span class="pill">v0.5.1</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -105,7 +105,7 @@ npm run demo          # end to end: all tools over stdio, then over stateless HT
   </section>
   <section>
     <p class="label">Memory — 3 facts</p>
-    <div class="fact"><p>The context concern points at AGENTS.md — the de-facto standard for agent instructions. read_agents_md serves it whole or one section at a time, so a client pulls '## Test' without spending its context window on the whole file. Memory and identity have no de-facto standard, so the reference uses .fafm and .fafa as one instantiation each.</p><div class="meta"><span class="tag">scope</span><span class="tag">agents-md</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Both exposure mechanisms — the Server Card _meta block and a self-published ai-catalog.json — already exist in the MCP ecosystem. This server wires all three concerns through them, from one set of source files, with a CI check (catalog:check) that fails if the two surfaces drift apart.</p><div class="meta"><span class="tag">mcp</span><span class="tag">server-card</span><span class="tag">ai-catalog</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Distribution: a published npm package (bin <code>mcp-context-card</code>, dual transport). The three source files (AGENTS.md, project.fafm, .well-known/fafa) ship with the package so it is a working discovery target on install. MCP_CONTEXT_CARD_ROOT points it at a real project.</p><div class="meta"><span class="tag">distribution</span><span class="tag">mit</span><span class="tag">npm</span><span class="dot" title="verified"></span></div></div>
+    <div class="fact"><p>The context concern points at AGENTS.md — the de-facto standard for agent instructions. read_agents_md serves it whole or one section at a time, so a client pulls '## Test' without spending its context window on the whole file. Memory and identity have no de-facto standard, so this server uses .fafm and .fafa as one instantiation each.</p><div class="meta"><span class="tag">scope</span><span class="tag">agents-md</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Both exposure mechanisms — the Server Card _meta block and a self-published ai-catalog.json — already exist in the MCP ecosystem. This server wires all three concerns through them, from one set of source files, with a CI check (catalog:check) that fails if the two surfaces drift apart.</p><div class="meta"><span class="tag">mcp</span><span class="tag">server-card</span><span class="tag">ai-catalog</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Distribution: a published npm package (bin <code>mcp-context-card</code>, dual transport). The three source files (AGENTS.md, project.fafm, .well-known/fafa) ship with the package so it is a working discovery target on install. MCP_CONTEXT_CARD_ROOT points it at a real project.</p><div class="meta"><span class="tag">distribution</span><span class="tag">mit</span><span class="tag">npm</span><span class="dot" title="verified"></span></div></div>
   </section>
   <section>
     <p class="label">Discovery</p>

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "mcp-context-card",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "mcpName": "io.github.wolfe-jam/mcp-context-card",
-  "description": "Reference MCP server: project context, persistent memory, and agent identity — through the two exposure surfaces already in the ecosystem (Server Card _meta, ai-catalog sibling entries).",
+  "description": "An MCP server that makes a project's context (AGENTS.md), cross-session memory, and identity discoverable to any MCP client — through the Server Card _meta block and ai-catalog.json sibling entries.",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -12,7 +12,7 @@
     "agent-memory",
     "agent-identity"
   ],
-  "author": "wolfejam",
+  "author": "James Wolfe",
   "license": "MIT",
   "type": "module",
   "private": false,

package/project.fafm

@@ -17,9 +17,9 @@ index:
 
 memory:
   facts:
-    - text: "The context concern points at AGENTS.md — the de-facto standard for agent instructions. read_agents_md serves it whole or one section at a time, so a client pulls '## Test' without spending its context window on the whole file. Memory and identity have no de-facto standard, so the reference uses .fafm and .fafa as one instantiation each."
+    - text: "The context concern points at AGENTS.md — the de-facto standard for agent instructions. read_agents_md serves it whole or one section at a time, so a client pulls '## Test' without spending its context window on the whole file. Memory and identity have no de-facto standard, so this server uses .fafm and .fafa as one instantiation each."
       id: "mcp-context-card-scope"
-      type: "reference"
+      type: "fact"
       priority: "high"
       tags: ["scope", "agents-md"]
       source: "README.md"
@@ -27,7 +27,7 @@ memory:
 
     - text: "Both exposure mechanisms — the Server Card _meta block and a self-published ai-catalog.json — already exist in the MCP ecosystem. This server wires all three concerns through them, from one set of source files, with a CI check (catalog:check) that fails if the two surfaces drift apart."
       id: "mechanisms-already-proven"
-      type: "reference"
+      type: "fact"
       priority: "high"
       tags: ["mcp", "server-card", "ai-catalog"]
       links: ["mcp-context-card-scope"]
@@ -36,7 +36,7 @@ memory:
 
     - text: "Distribution: a published npm package (bin `mcp-context-card`, dual transport). The three source files (AGENTS.md, project.fafm, .well-known/fafa) ship with the package so it is a working discovery target on install. MCP_CONTEXT_CARD_ROOT points it at a real project."
       id: "distribution-model"
-      type: "reference"
+      type: "fact"
       priority: "standard"
       tags: ["distribution", "mit", "npm"]
       source: "README.md"

package/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.wolfe-jam/mcp-context-card",
   "title": "mcp-context-card",
-  "description": "Reference MCP server that makes a project's context (AGENTS.md), memory, and identity discoverable to any MCP client — through the Server Card _meta block and ai-catalog.json sibling entries.",
-  "version": "0.5.0",
+  "description": "An MCP server that makes a project's context (AGENTS.md), cross-session memory, and identity discoverable to any MCP client — through the Server Card _meta block and ai-catalog.json sibling entries.",
+  "version": "0.5.1",
   "repository": {
     "url": "https://github.com/Wolfe-Jam/mcp-context-card",
     "source": "github"
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "mcp-context-card",
-      "version": "0.5.0",
+      "version": "0.5.1",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"
@@ -21,7 +21,7 @@
       "environmentVariables": [
         {
           "name": "MCP_CONTEXT_CARD_ROOT",
-          "description": "Directory holding project.faf / project.fafm / .well-known/fafa. Omitted → the server's own bundled reference copies.",
+          "description": "Directory holding project.faf / project.fafm / .well-known/fafa. Omitted → the server's own bundled copies.",
           "isRequired": false
         }
       ]