mcp-context-card 0.6.2 → 1.0.1

package/.well-known/fafa

@@ -9,7 +9,7 @@ agent:
   name: "mcp-context-card"
   displayName: "mcp-context-card"
   vendor: "io.github.Wolfe-Jam"
-  version: "0.6.2"
+  version: "1.0.1"
   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,66 @@
 
 All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
 
+## 1.0.1
+
+`npx mcp-context-card` now runs — it silently no-op'd when launched through
+`npx` or a global install. Plus: `card` opens your context in a browser at a
+terminal, and Node 20 is supported.
+
+Once `npx` works, `npx mcp-context-card card` from a project directory is the
+fastest way to see what an agent actually gets: at a terminal it writes
+`context-card.html` and opens it in your browser — no MCP host, no redirect.
+Piped or redirected output is unchanged (`> card.html`, scripts, CI);
+`--stdout` forces raw HTML from a terminal too.
+
+- **Node 20 supported.** `engines` was `>=22` with nothing in the code that
+  needed it — it runs identically on Node 20 (verified against the published
+  package). No more `npm warn EBADENGINE` on the current LTS. CI now runs the
+  full suite on Node 20, 22, and 24 across all three OSes.
+- **`card` at a terminal.** A bare `npx mcp-context-card card` used to dump
+  raw HTML at the prompt — noise for anyone who just wanted to look. Now it
+  writes a file and opens it; the pipe/redirect path is untouched.
+- **`npx` / global-install entry fixed.** The bin's "am I the entry point?"
+  guard compared `import.meta.url` (always resolved) against an unresolved
+  `process.argv[1]` — so when `npx`, a global install, or `./node_modules/.bin`
+  routed through the bin **symlink**, the check failed and the CLI **silently
+  did nothing** (exit 0, no output). `process.argv[1]` is now realpath'd first.
+  Direct `node dist/bin.js` was never affected, which is why CI and the client
+  conformance passes (which spawn `node <path>`) stayed green. CI now also
+  exercises the packaged `npx` entry.
+
+No API change. Nine tools, three concerns, two transports, two discovery
+mechanisms — all as 1.0.0.
+
+## 1.0.0
+
+Stable surface. No functional change from 0.6.2 — this release declares
+the API settled and is the reference point everything downstream pins to.
+
+The shape that's now stable: **nine tools** (`read_agents_md`,
+`list_agents_md_sections`, `author_agents_md`, `remember`, `recall`,
+`forget`, `whoami`, `list_context_sources`, `render_context_card`),
+**three concerns** (context / memory / identity), **two discovery
+mechanisms** (the Server Card `_meta` block, a self-published
+`ai-catalog.json`), **two transports** (stdio, stateless Streamable HTTP).
+
+Verified against three independent clients before the cut:
+
+- **Cursor** (3.18.25 / Grok 4.6) — the full behavioural matrix, **10/10**.
+- **Claude Code protocol pass** — the 10-item matrix run through the
+  MCP SDK `Client` + `StdioClientTransport` (the client stack Claude
+  Code uses), over stdio. **`CLAUDE CODE PROTOCOL PASS: 10/10`** —
+  every check, and `resources/templates/list` issued directly on the
+  wire (`[]`, not `-32601`).
+- **`@modelcontextprotocol/inspector`** (2.5.0, the canonical
+  conformance tool) — every method answers correctly; `tools/list
+  --strict` reports zero schema-portability problems across all nine.
+
+- `docs/WIRING.md` gains one host-gotcha note: `@modelcontextprotocol/inspector`
+  2.x reports `prompts/list` as `{ "prompts": [] }` — the server declares
+  only `tools` + `resources` and returns `-32601` for `prompts/list` on
+  the wire; the current Inspector CLI masks that as an empty list.
+
 ## 0.6.2
 
 Tool-description quality and anti-drift. Nothing here changes what the

package/README.md

@@ -1,7 +1,9 @@
 # mcp-context-card
 
+[![npm](https://img.shields.io/npm/v/mcp-context-card.svg)](https://www.npmjs.com/package/mcp-context-card)
 [![CI](https://github.com/Wolfe-Jam/mcp-context-card/actions/workflows/ci.yml/badge.svg)](https://github.com/Wolfe-Jam/mcp-context-card/actions/workflows/ci.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![mcp-context-card MCP server](https://glama.ai/mcp/servers/Wolfe-Jam/mcp-context-card/badges/score.svg)](https://glama.ai/mcp/servers/Wolfe-Jam/mcp-context-card)
 
 **Get one. Or add it to yours.** The essential MCP server for a project's
 context, memory, and identity — discoverable to any MCP client, and
@@ -72,9 +74,10 @@ memory, and how a machine fetches it. The view for people: screenshot it,
 drop it in a PR, put it on a status page.
 
 ```
-GET /card                      # live, on the HTTP transport
+npx mcp-context-card card       # at a terminal: writes context-card.html and opens it
+npx mcp-context-card card > x.html   # piped/redirected: raw HTML to stdout
+GET /card                       # live, on the HTTP transport
 GET /card?theme=light&accent=%230066cc
-npx mcp-context-card card       # or:  npm run card  →  docs/card.html
 ```
 
 Light, dark, or auto; the accent defaults to the AAIF palette and takes any hex.
@@ -104,12 +107,16 @@ npx agents-md-facts --check  # fail if missing or stale (CI, pre-commit)
 
 ### See the card
 
-One command, no host, no config:
+One command, no host, no config — from your project directory:
 
 ```bash
-npx mcp-context-card card > card.html
+npx mcp-context-card card
 ```
 
+At a terminal it writes `context-card.html` and opens it in your browser. Piped
+or redirected (`> card.html`, a script, CI) it writes raw HTML to stdout instead;
+`--stdout` forces that from a terminal too.
+
 ### Wire it into a host
 
 Claude Desktop, Cursor, or any stdio host:
@@ -128,7 +135,7 @@ Claude Desktop, Cursor, or any stdio host:
 
 `MCP_CONTEXT_CARD_ROOT` points at the directory with your `AGENTS.md`. The
 memory tools work with or without it; identity is optional. Over HTTP instead:
-`PORT=8080 npx mcp-context-card`. Requires Node ≥22.
+`PORT=8080 npx mcp-context-card`. Requires Node ≥20.
 
 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

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 0.6.2\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";
+export declare const HELP = "mcp-context-card 1.0.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   --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/bin.js

@@ -6,14 +6,17 @@
  *   mcp-context-card --http       → stateless Streamable HTTP on PORT (default 3000)
  *   PORT=8080 mcp-context-card    → HTTP too (a hosted deploy sets PORT)
  *   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 card         → this directory's context card. At a terminal:
+ *                                   writes context-card.html and opens it. Piped
+ *                                   or redirected: HTML to stdout ( > card.html ).
+ *                                   --theme light|dark · --accent #hex · --stdout
  *   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.
  */
+import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -27,8 +30,9 @@ 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 card             this dir's context card — opens it in your browser
+                                    at a terminal; HTML to stdout when piped ( > f.html )
+                                      --theme light|dark   --accent #hex   --stdout
   mcp-context-card --help           this text
   mcp-context-card --version        print version
 
@@ -37,7 +41,7 @@ ENV
   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.
+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
 `;
 /**
@@ -76,8 +80,21 @@ export function flagValue(argv, flag) {
     const i = argv.indexOf(flag);
     return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined;
 }
-/** Direct run only — importing this module (e.g. from a test) must not launch. */
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+/**
+ * Direct run only — importing this module (e.g. from a test) must not launch.
+ * `process.argv[1]` can be a bin symlink (`npx`, a global install, `.bin/…`)
+ * while `import.meta.url` is always the resolved file, so realpath argv[1]
+ * before comparing — otherwise the CLI silently no-ops when run via npx.
+ */
+const entryPath = (() => {
+    try {
+        return process.argv[1] ? realpathSync(process.argv[1]) : undefined;
+    }
+    catch {
+        return process.argv[1];
+    }
+})();
+if (entryPath && import.meta.url === pathToFileURL(entryPath).href) {
     const argv = process.argv.slice(2);
     const { mode, port, root } = resolveLaunch(argv);
     if (mode === "help") {
@@ -89,10 +106,31 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
     else if (mode === "card") {
         const { renderCard, safeAccent } = await import("./render-card.js");
         const theme = flagValue(argv, "--theme");
-        process.stdout.write(renderCard(root, {
+        const html = renderCard(root, {
             theme: theme === "light" || theme === "dark" ? theme : "auto",
             accent: safeAccent(flagValue(argv, "--accent")),
-        }));
+        });
+        // Piped / redirected (or --stdout) → raw HTML on stdout, unchanged.
+        // A bare run at a terminal → the HTML is noise; write a file and open it.
+        if (!process.stdout.isTTY || argv.includes("--stdout")) {
+            process.stdout.write(html);
+        }
+        else {
+            const { writeFileSync } = await import("node:fs");
+            const { join } = await import("node:path");
+            const { spawn } = await import("node:child_process");
+            const out = join(process.cwd(), "context-card.html");
+            writeFileSync(out, html);
+            const opener = process.platform === "darwin"
+                ? ["open", [out]]
+                : process.platform === "win32"
+                    ? ["cmd", ["/c", "start", "", out]]
+                    : ["xdg-open", [out]];
+            spawn(opener[0], opener[1], { stdio: "ignore", detached: true })
+                .on("error", () => { })
+                .unref();
+            process.stderr.write(`${NAME} · wrote ${out} — opening in your browser  (--stdout for raw HTML)\n`);
+        }
     }
     else if (mode === "http") {
         const { httpApp } = await import("./transport/http.js");

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.6.2";
+export declare const VERSION = "1.0.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.6.2";
+export const VERSION = "1.0.1";
 export const SERVER_CARD_URI = "mcp-context-card://server-card";

package/docs/MECHANISMS.md

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

package/docs/WIRING.md

@@ -33,6 +33,10 @@
   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).
+- **`@modelcontextprotocol/inspector` 2.x reports `prompts/list` as `{ "prompts": [] }`** —
+  this server declares only `tools` + `resources`, so `prompts/list` returns
+  `-32601` on the wire; the current Inspector CLI masks that as an empty list
+  (raw JSON-RPC, or Inspector 0.21.x, shows the real `-32601`).
 
 ### Streamable HTTP (remote)
 

package/docs/card-dark.html

@@ -78,7 +78,7 @@ section:last-child{border-bottom:0}
 <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">v0.6.2</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.0.1</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

@@ -78,7 +78,7 @@ section:last-child{border-bottom:0}
 <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">v0.6.2</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.0.1</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

@@ -78,7 +78,7 @@ section:last-child{border-bottom:0}
 <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">v0.6.2</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.0.1</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

@@ -78,7 +78,7 @@ section:last-child{border-bottom:0}
 <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">v0.6.2</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.0.1</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": "0.6.2",
+  "version": "1.0.1",
   "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": [
@@ -28,7 +28,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=20"
   },
   "files": [
     "dist",
@@ -46,9 +46,10 @@
     "build": "tsc -p tsconfig.build.json",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "version:check": "node scripts/check-versions.mjs",
+    "engines:check": "node scripts/check-engines.mjs",
     "faf:check": "node scripts/check-faf-consistency.mjs",
     "faf:nudge": "node scripts/faf-drift-nudge.mjs",
-    "prepublishOnly": "npm run clean && npm run version:check && npm run faf:check && npm run build && npm run typecheck && npm test",
+    "prepublishOnly": "npm run clean && npm run version:check && npm run engines:check && npm run faf:check && npm run build && npm run typecheck && npm test",
     "start": "node dist/bin.js",
     "start:http": "node dist/bin.js --http",
     "dev": "tsx src/bin.ts",

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": "0.6.2",
+  "version": "1.0.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.6.2",
+      "version": "1.0.1",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"