mcp-context-card 1.5.0 → 1.6.0

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

@@ -11,7 +11,7 @@
       "data": {
         "$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
         "name": "io.github.Wolfe-Jam/mcp-context-card",
-        "version": "1.5.0",
+        "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",

package/.well-known/fafa

@@ -13,7 +13,7 @@ agent:
   # a deployment for your own project uses your domain.
   id: "urn:air:faf.one:agent:mcp-context-card"
   vendor: "io.github.Wolfe-Jam"
-  version: "1.5.0"
+  version: "1.6.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
@@ -21,3 +21,8 @@ agent:
     Server Card _meta block and a self-published ai-catalog.json.
   status: "published"
   license: "MIT"
+metadata:
+  cards:
+    packages:
+      - registryType: "npm"
+        identifier: "mcp-context-card"

package/CHANGELOG.md

@@ -2,9 +2,50 @@
 
 All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
 
+## 1.6.0
+
+The card is a business card.
+
+`npx mcp-context-card card` used to open a technical page. It now opens a
+**business card**: what you'd hand someone on the front, and the full detail
+one flip away.
+
+- **Front:** a monogram logo (the first letters of the name: **MC**), the
+  name, a title, and a one-liner.
+  - The **title** says what it is and its version ("MCP server · v1.6.0",
+    "A2A agent · v0.3.0"), from where the project's `.fafa` says it runs
+    (`endpoints`, or `metadata.cards.packages`). With nothing declared, it
+    claims nothing.
+  - The **one-liner** is the start of the description, stopping at its first
+    natural pause rather than mid-phrase.
+  - Domain, publisher, status and licence sit along the bottom.
+- **Back:** tabs for About (the identity in full), Skills (when the `.fafa`
+  lists capabilities), Context (AGENTS.md), Memory and Discovery. Long content
+  scrolls inside the card, including by mouse wheel or trackpad on macOS.
+- **Controls:** the same two on both faces. **(i)** top-right explains
+  Business Cards for Agents; the outline flip button bottom-right (↻ on the
+  front, ↺ on the back) has an instant tooltip.
+- **Views:** ▭ ▯ switches landscape or portrait (`--portrait`,
+  `?layout=portrait`, `layout` on the tools). ◐ switches the **card** between
+  light and dark. `--theme` / `?theme=` set the card's starting colour, and
+  the page around it follows your OS on its own.
+- **Works with scripts off:** flip, tabs and both toggles are CSS. The one
+  small script adds Expand all, `#section` links on the back, and printing.
+  `--expanded` and print lay both faces out flat.
+- **The `.fafa` reader** now reads `endpoints`, `capabilities` and
+  `metadata.cards.packages`, as `faf card init` writes them. This repo's own
+  `.fafa` declares its npm package.
+- **Read and render are separate:** `readCard` turns a project's files into a
+  neutral business card; `renderBusinessCard` draws any card, so a person's
+  card or an A2A Agent Card needs no renderer change.
+- The saved file is still `context-card.html`: underneath, it's the project's
+  context.
+
+No tool or protocol change. 209 tests, all green.
+
 ## 1.5.0
 
-MCP Server Cards (SEP-2127, Final) and AI Catalog 1.0, and HTTP that is local by default.
+MCP Server Cards (SEP-2127, Final) and the AI Catalog (specVersion 1.0), and HTTP that is local by default.
 
 **Breaking for exposed deploys:** HTTP mode now binds `127.0.0.1`. A container or
 hosted deploy must set `HOST=0.0.0.0` (`examples/Dockerfile` does). Local use is
@@ -21,7 +62,7 @@ unchanged.
   spec's CORS (`Access-Control-Allow-Origin: *`, GET, `Content-Type` and
   `If-None-Match` allowed, `ETag` exposed), `Cache-Control: public,
   max-age=3600`, and an `ETag` answered with `304 Not Modified`.
-- **AI Catalog 1.0.** The Server Card is the first entry. Entries use `type`,
+- **AI Catalog (specVersion 1.0).** The Server Card is the first entry. Entries use `type`,
   custom data sits in `extensions`, and identifiers are
   `urn:air:{domain}:{namespace}:{name}` with the domain taken from the project's
   own `.fafa` (none is ever invented). `/AGENTS.md` is served, so every catalog

package/README.md

@@ -11,10 +11,11 @@ rendered as one card you can read.
 
 | Light | Dark |
 |---|---|
-| ![the context card, light theme](./docs/img/card-light.png) | ![the context card, dark theme](./docs/img/card-dark.png) |
+| ![the business card front, light theme: name, title, one-liner](./docs/img/card-light.png) | ![the business card front, dark theme](./docs/img/card-dark.png) |
 
-**See your own project's card** — run this in its folder. It writes
-`context-card.html` and opens it in your browser:
+**See your own project's business card** — run this in its folder. It writes
+`context-card.html` and opens it in your browser. The front is the card: name,
+title, one-liner. Flip it for the back: About, Context, Memory, Discovery.
 
 ```
 npx mcp-context-card card
@@ -22,15 +23,15 @@ npx mcp-context-card card
 
 **context** — the project's `AGENTS.md`, served whole or one section at a time.
 
-![the card's context section — AGENTS.md, section nav, read_agents_md](./docs/img/card-context.png)
+![the back's Context tab — AGENTS.md, section nav, read_agents_md](./docs/img/card-context.png)
 
 **memory** — facts that persist across sessions, in a file.
 
-![the card's memory section — a real, tagged, verified fact](./docs/img/card-memory.png)
+![the back's Memory tab — real, tagged, verified facts](./docs/img/card-memory.png)
 
 **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)
+![the back's About tab — the identity in full](./docs/img/card-identity.png)
 
 Discovery goes through two surfaces already in the ecosystem: the Server Card
 `_meta` block and `ai-catalog.json` sibling entries.
@@ -76,23 +77,34 @@ no search.
 
 ## The card
 
-The screenshot at the top of this page is exactly this — the same three
-sources rendered as one self‑contained HTML page: identity, `AGENTS.md`,
-memory, and how a machine fetches it. The view for people: read it, screenshot
-it, drop it in a PR, put it on a status page.
-
-`AGENTS.md` sections are collapsed by default, so the card scans in one screen;
-a sticky index jumps to any section, **Expand all** opens everything. Sections
-toggle natively — the one small inline script only adds the bulk button and the
-print handler. `--expanded` / `?expand=all` renders it fully open, script-free,
-for a screenshot.
+The screenshot at the top of this page is exactly this: the same sources
+rendered as a **business card** in one self‑contained HTML page. The view for
+people: read it, screenshot it, drop it in a PR, put it on a status page.
+
+- **Front:** the name, a title (what it is and its version: "MCP server", "A2A
+  agent", from where the project's `.fafa` says it runs) and a one-liner (the
+  start of its description).
+- **Back (Flip):** tabs for **About** (the identity in full),
+  **Skills** (when the `.fafa` lists capabilities), **Context** (`AGENTS.md`),
+  **Memory** and **Discovery**. Long content scrolls inside the card.
+- **Landscape or portrait:** the ▭ ▯ button switches the view; `--portrait` /
+  `?layout=portrait` sets it.
+- **Light or dark card:** the card's colour is its own, like a printed card.
+  `--theme` / `?theme=` sets it (default: follow your OS), and ◐ switches it.
+  The page around it always follows your OS.
+
+Flip, tabs and the view switch are plain CSS, so they work with scripts off.
+The one small inline script adds Expand all, opens a `#section` link on the
+back, and opens every section for printing. `--expanded` / `?expand=all`
+renders both faces flat, every section open, for a screenshot or print.
 
 ```
 npx mcp-context-card card            # at a terminal: writes context-card.html and opens it
-npx mcp-context-card card --expanded # every section open
+npx mcp-context-card card --portrait # the tall view
+npx mcp-context-card card --expanded # both faces flat, every section open
 npx mcp-context-card card > x.html   # piped/redirected: raw HTML to stdout
 GET /card                            # live, on the HTTP transport
-GET /card?expand=all&theme=light&accent=%230066cc
+GET /card?layout=portrait&theme=light&accent=%230066cc
 ```
 
 In a chat, hosts that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps)
@@ -188,6 +200,19 @@ Extending an MCP you already run: most hosts accept more than one
 `server-git`, or your own, and every agent in that host gains context,
 memory, and identity discovery without anything else changing.
 
+### Your identifiers
+
+The AI Catalog names each entry `urn:air:{domain}:{namespace}:{name}`, and
+the domain is yours. It comes from your project's `.fafa`: run
+`npx faf-cli card init` (or `--domain example.com`), and it writes
+`agent.id: urn:air:example.com:agent:<short-name>`. Your catalog then publishes
+`urn:air:example.com:context:<short-name>` and so on, with no code to change.
+This repo's own `.fafa` says `faf.one`; that's our example, and yours says yours.
+
+With no `.fafa`, no domain is invented: the served catalog uses the host it's
+served from (`localhost` when you run it locally), and the static
+`.well-known/ai-catalog.json` uses plain `<short-name>:<namespace>` IDs.
+
 ## Why
 
 `AGENTS.md` is the de-facto standard for telling a coding agent how to work in a
@@ -246,7 +271,7 @@ over both transports:
 4. **Discovery** — `list_context_sources()`, then the same server over stateless
    HTTP with its `.well-known` routes and `GET /card`.
 
-200 tests on Linux, macOS, and Windows, coverage‑gated in CI.
+209 tests on Linux, macOS, and Windows, coverage‑gated in CI.
 `npm run wjttc` runs the WJTTC certification suite (seven tiers, from protocol
 and Server Card conformance to stdio/HTTP parity and the shipped package). Two spawn a real
 child process and check a remembered fact survives the restart — one against

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.5.0\nServe a project's context (AGENTS.md), memory, and identity over MCP.\n\nUSAGE\n  mcp-context-card                  stdio MCP server \u2014 what an MCP host spawns (default)\n  mcp-context-card --http           stateless Streamable HTTP on PORT (default 3000)\n  mcp-context-card --stdio          force stdio even when PORT is set\n  mcp-context-card card             this dir's context card \u2014 opens it in your browser\n                                    at a terminal; HTML to stdout when piped ( > f.html )\n                                      --theme light|dark   --accent #hex\n                                      --expanded (all sections open)   --stdout\n  mcp-context-card --help           this text\n  mcp-context-card --version        print version\n\nENV\n  MCP_CONTEXT_CARD_ROOT   read AGENTS.md / project.fafm / .well-known/ from here\n  PORT                    if set, run HTTP instead of stdio\n  HOST                    HTTP bind address (default 127.0.0.1, this machine\n                          only); 0.0.0.0 exposes it, e.g. in a container\n  MCP_CONTEXT_CARD_ALLOWED_HOSTS / _ALLOWED_ORIGINS\n                          comma-separated Host names / browser origins to\n                          accept besides this machine's own (reverse proxy, web app)\n  MCP_CONTEXT_CARD_PUBLISH_MEMORY=1\n                          HTTP: serve project.fafm, list it in the AI Catalog,\n                          and show its facts on an exposed /card (off: memory\n                          is session data). HTTP has no auth\n\nA bare run is an stdio server: it waits for a host to speak JSON-RPC on stdin,\nso it looks idle at a terminal. Try `card` (opens your context in a browser) or `--http`.\nhttps://github.com/Wolfe-Jam/mcp-context-card\n";
+export declare const HELP = "mcp-context-card 1.6.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)   --portrait   --stdout\n  mcp-context-card --help           this text\n  mcp-context-card --version        print version\n\nENV\n  MCP_CONTEXT_CARD_ROOT   read AGENTS.md / project.fafm / .well-known/ from here\n  PORT                    if set, run HTTP instead of stdio\n  HOST                    HTTP bind address (default 127.0.0.1, this machine\n                          only); 0.0.0.0 exposes it, e.g. in a container\n  MCP_CONTEXT_CARD_ALLOWED_HOSTS / _ALLOWED_ORIGINS\n                          comma-separated Host names / browser origins to\n                          accept besides this machine's own (reverse proxy, web app)\n  MCP_CONTEXT_CARD_PUBLISH_MEMORY=1\n                          HTTP: serve project.fafm, list it in the AI Catalog,\n                          and show its facts on an exposed /card (off: memory\n                          is session data). HTTP has no auth\n\nA bare run is an stdio server: it waits for a host to speak JSON-RPC on stdin,\nso it looks idle at a terminal. Try `card` (opens your context in a browser) or `--http`.\nhttps://github.com/Wolfe-Jam/mcp-context-card\n";
 /**
  * The address the HTTP server binds: `HOST`, else 127.0.0.1. Local by default,
  * as the MCP transports spec recommends; a hosted deploy sets HOST=0.0.0.0.

package/dist/bin.js

@@ -10,7 +10,7 @@
  *                                   writes context-card.html and opens it. Piped
  *                                   or redirected: HTML to stdout ( > card.html ).
  *                                   --theme light|dark · --accent #hex
- *                                   --expanded (all sections open) · --stdout
+ *                                   --expanded (all sections open) · --portrait · --stdout
  *   mcp-context-card --help       → usage
  *   mcp-context-card --version    → version
  *
@@ -34,7 +34,7 @@ USAGE
   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
-                                      --expanded (all sections open)   --stdout
+                                      --expanded (all sections open)   --portrait   --stdout
   mcp-context-card --help           this text
   mcp-context-card --version        print version
 
@@ -128,6 +128,7 @@ if (entryPath && import.meta.url === pathToFileURL(entryPath).href) {
             theme: theme === "light" || theme === "dark" ? theme : "auto",
             accent: safeAccent(flagValue(argv, "--accent")),
             expanded: argv.includes("--expanded"),
+            layout: argv.includes("--portrait") ? "portrait" : "landscape",
         });
         // 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.

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.5.0";
+export declare const VERSION = "1.6.0";
 export declare const SERVER_CARD_URI = "mcp-context-card://server-card";
 /** The server's registry identity: reverse-DNS, the same as server.json `name`.
  *  It is also `serverInfo.name`, so a Server Card never contradicts the live

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.5.0";
+export const VERSION = "1.6.0";
 export const SERVER_CARD_URI = "mcp-context-card://server-card";
 /** The server's registry identity: reverse-DNS, the same as server.json `name`.
  *  It is also `serverInfo.name`, so a Server Card never contradicts the live

package/dist/faf/parse-fafa.js

@@ -23,6 +23,7 @@ export function parseFafa(path) {
         description: str(agent.description),
         status: str(agent.status),
         license: str(agent.license),
+        ...extras(doc),
     };
 }
 function str(v) {
@@ -31,3 +32,23 @@ function str(v) {
     const s = String(v).trim().replace(/\s+/g, " ");
     return s.length ? s : undefined;
 }
+/** Where it runs, what it can do, and what installs it: `.fafa` fields outside `agent`. */
+function extras(doc) {
+    const list = (v) => Array.isArray(v) ? v.filter((x) => !!x && typeof x === "object") : [];
+    const endpoints = list(doc.endpoints)
+        .filter((e) => typeof e.protocol === "string" && e.protocol.trim())
+        .map((e) => ({ protocol: String(e.protocol).trim().toLowerCase(), ...(typeof e.location === "string" ? { location: e.location } : {}) }));
+    const skills = list(doc.capabilities)
+        .filter((c) => typeof c.name === "string" && c.name.trim())
+        .map((c) => ({ name: String(c.name), ...(typeof c.description === "string" ? { description: c.description } : {}) }));
+    const meta = doc.metadata && typeof doc.metadata === "object" ? doc.metadata : {};
+    const cards = meta.cards && typeof meta.cards === "object" ? meta.cards : {};
+    const packages = list(cards.packages)
+        .filter((p) => typeof p.registryType === "string" && typeof p.identifier === "string")
+        .map((p) => ({ registryType: String(p.registryType), identifier: String(p.identifier) }));
+    return {
+        ...(endpoints.length ? { endpoints } : {}),
+        ...(skills.length ? { skills } : {}),
+        ...(packages.length ? { packages } : {}),
+    };
+}

package/dist/faf/types.d.ts

@@ -33,4 +33,19 @@ export interface AgentIdentity {
     description?: string;
     status?: string;
     license?: string;
+    /** Where it runs (`.fafa` `endpoints`), as `faf card init` writes them: protocol `a2a` or `mcp`. */
+    endpoints?: {
+        protocol: string;
+        location?: string;
+    }[];
+    /** What it can do (`.fafa` `capabilities`). */
+    skills?: {
+        name: string;
+        description?: string;
+    }[];
+    /** Installable packages (`.fafa` `metadata.cards.packages`), e.g. an npm MCP server. */
+    packages?: {
+        registryType: string;
+        identifier: string;
+    }[];
 }

package/dist/render-card.d.ts

@@ -1,3 +1,4 @@
+import type { AgentIdentity } from "./faf/types.js";
 export type Theme = "light" | "dark" | "auto";
 export interface CardOptions {
     theme?: Theme;
@@ -14,11 +15,56 @@ export interface CardOptions {
      * served beyond this machine without the publish opt-in. Default: `full`.
      */
     memory?: "full" | "private";
+    /** Business-card view. Default `landscape`; the reader can switch it too. */
+    layout?: "landscape" | "portrait";
 }
 /** AAIF brand orange (aaif.io). The default accent. */
 export declare const AAIF_ACCENT = "#FF702D";
 export declare function safeAccent(a?: string): string;
+/** What the front calls this thing, from where it runs: "MCP server", "A2A agent", or both. */
+export declare function cardKind(id: AgentIdentity | null): string[];
+/** The front's title line: what it is, then its version. Empty when nothing is known. */
+export declare function cardTitle(id: AgentIdentity | null): string;
+/** The front's logo: the first letters of the name's first two words ("mcp-context-card" → "MC"). */
+export declare function cardInitials(name: string): string;
+/** The front's one-liner: the first sentence of the description. */
+export declare function cardOneLiner(id: AgentIdentity | null, max?: number): string;
+/**
+ * A business card, independent of where its facts came from: everything the
+ * renderer draws. `readCard` builds one from a project's files; another reader
+ * (an A2A Agent Card, an MCP Server Card, a person's card) can build one too,
+ * and `renderBusinessCard` draws any of them the same way.
+ */
+export interface BusinessCard {
+    name: string;
+    /** What it is (and its version): "MCP server · v1.5.0", or a person's role. */
+    title?: string;
+    oneLiner?: string;
+    /** Shown bottom-left on the front, e.g. the publisher domain. */
+    domain?: string;
+    /** Footer chips; `accent` highlights one (e.g. the status). Plain text. */
+    chips: {
+        text: string;
+        accent?: boolean;
+    }[];
+    /** The back's tabs, in order. `key` is [a-z0-9-]; `html` is already-safe markup. */
+    tabs: {
+        key: string;
+        label: string;
+        heading: string;
+        html: string;
+    }[];
+    /** The (i) panel, as already-safe markup. */
+    about: string;
+}
+/** How to draw a card: the owner's colour and accent, the view, and the flat (print) layout. */
+export type RenderOptions = Pick<CardOptions, "theme" | "accent" | "layout" | "expanded">;
+/** The project's card: read its files, then draw. */
 export declare function renderCard(root: string, opts?: CardOptions): string;
+/** Read a project's AGENTS.md, memory and identity into a business card. */
+export declare function readCard(root: string, opts?: Pick<CardOptions, "expanded" | "memory">): BusinessCard;
+/** Draw any business card as one self-contained HTML page. */
+export declare function renderBusinessCard(card: BusinessCard, opts?: RenderOptions): string;
 /** tl;dr: the first few facts, each cut to about a line. `full`: every fact, whole. */
 export type Detail = "tldr" | "full";
 /**