mcp-context-card 0.5.0

package/dist/memory.d.ts

@@ -0,0 +1,13 @@
+/**
+ * memory — real, file-backed remember/recall against a `.fafm` file.
+ *
+ * No in-memory cache, no side-file: every call reads/writes the `.fafm`
+ * from disk via a structural YAML edit (comments + layout preserved).
+ * That's the actual claim `.fafm` makes ("memory that survives across
+ * sessions") — proven by demo.ts / the test suite restarting the server
+ * process between remember() and recall() and getting the same fact back.
+ *
+ * Thin re-export: the parse/read/write logic lives in ./faf/parse-fafm.
+ */
+export { recall, remember, forget, parseFafm } from "./faf/parse-fafm.js";
+export type { Memory, MemoryFact } from "./faf/types.js";

package/dist/memory.js

@@ -0,0 +1,12 @@
+/**
+ * memory — real, file-backed remember/recall against a `.fafm` file.
+ *
+ * No in-memory cache, no side-file: every call reads/writes the `.fafm`
+ * from disk via a structural YAML edit (comments + layout preserved).
+ * That's the actual claim `.fafm` makes ("memory that survives across
+ * sessions") — proven by demo.ts / the test suite restarting the server
+ * process between remember() and recall() and getting the same fact back.
+ *
+ * Thin re-export: the parse/read/write logic lives in ./faf/parse-fafm.
+ */
+export { recall, remember, forget, parseFafm } from "./faf/parse-fafm.js";

package/dist/render-card.d.ts

@@ -0,0 +1,10 @@
+export type Theme = "light" | "dark" | "auto";
+export interface CardOptions {
+    theme?: Theme;
+    /** CSS hex colour for the accent. Validated; invalid falls back to AAIF. */
+    accent?: string;
+}
+/** AAIF brand orange (aaif.io). The default accent. */
+export declare const AAIF_ACCENT = "#FF702D";
+export declare function safeAccent(a?: string): string;
+export declare function renderCard(root: string, opts?: CardOptions): string;

package/dist/render-card.js

@@ -0,0 +1,175 @@
+/**
+ * render-card - the project's context card as one self-contained HTML page.
+ *
+ * Everything an MCP client discovers about a project - its AGENTS.md, its
+ * memory, its identity - rendered as a card a person can read, screenshot,
+ * or drop into a PR. Same three sources as the Server Card _meta block and
+ * ai-catalog; this is the view for people.
+ *
+ * Self-contained: inline CSS, no JS, no external fonts. Renders anywhere,
+ * including as a data: URI.
+ */
+import { join } from "node:path";
+import { parseAgentsMd } from "./agents-md.js";
+import { parseFafm } from "./memory.js";
+import { resolveIdentity, trinityMeta, META_NS } from "./identity.js";
+import { NAME, SERVER_CARD_URI } from "./constants.js";
+import { escapeHtml, renderInline, renderMarkdown, slug } from "./md.js";
+/** AAIF brand orange (aaif.io). The default accent. */
+export const AAIF_ACCENT = "#FF702D";
+const ACCENT_OK = /^#[0-9a-fA-F]{3}(?:[0-9a-fA-F]{3}(?:[0-9a-fA-F]{2})?)?$/;
+export function safeAccent(a) {
+    return a && ACCENT_OK.test(a) ? a : AAIF_ACCENT;
+}
+const CSS = (accent) => `
+:root{
+  --accent:${accent};
+  --bg:#f4f4f5; --card:#fff; --fg:#0a0a0a; --muted:#6b6b70;
+  --line:rgba(0,0,0,.09); --chip:rgba(0,0,0,.05);
+}
+:root[data-theme="dark"]{
+  --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
+  --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
+}
+@media (prefers-color-scheme:dark){
+  :root:not([data-theme="light"]){
+    --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
+    --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
+  }
+}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--fg);
+  font:15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+  padding:40px 18px}
+.card{max-width:760px;margin:0 auto;background:var(--card);border:1px solid var(--line);
+  border-radius:14px;overflow:hidden}
+.card>*{padding:26px 30px}
+.top{border-top:4px solid var(--accent);border-bottom:1px solid var(--line)}
+h1{margin:0 0 10px;font-size:1.7rem;letter-spacing:-.02em}
+.pills{display:flex;flex-wrap:wrap;gap:6px}
+.pill{font-size:.74rem;font-weight:600;padding:3px 9px;border-radius:20px;background:var(--chip);color:var(--muted)}
+.pill.accent{background:color-mix(in srgb,var(--accent) 16%,transparent);color:var(--accent)}
+section{border-bottom:1px solid var(--line)}
+section:last-child{border-bottom:0}
+.label{font-size:.7rem;font-weight:700;letter-spacing:.16em;text-transform:uppercase;
+  color:var(--accent);margin:0 0 14px}
+.toc{display:flex;flex-wrap:wrap;gap:6px 14px;margin:0 0 20px;padding:0;list-style:none}
+.toc a{font-size:.82rem;color:var(--muted);text-decoration:none}
+.toc a:hover{color:var(--accent)}
+.md h1,.md h2,.md h3,.md h4{margin:22px 0 8px;font-size:1rem;letter-spacing:-.01em}
+.md h1{font-size:1.15rem}
+.md p{margin:8px 0}
+.md ul,.md ol{margin:8px 0;padding-left:22px}
+.md li{margin:3px 0}
+.md code{background:var(--chip);padding:1px 5px;border-radius:5px;
+  font:.86em ui-monospace,SFMono-Regular,Menlo,monospace}
+.md pre{background:var(--chip);padding:14px 16px;border-radius:9px;overflow:auto}
+.md pre code{background:none;padding:0}
+.md table{border-collapse:collapse;width:100%;margin:12px 0;font-size:.88rem;display:block;overflow:auto}
+.md th,.md td{border:1px solid var(--line);padding:6px 10px;text-align:left}
+.md blockquote{margin:10px 0;padding-left:14px;border-left:3px solid var(--line);color:var(--muted)}
+.md a{color:var(--accent)}
+.fact{padding:12px 0;border-bottom:1px solid var(--line)}
+.fact:last-child{border-bottom:0}
+.fact p{margin:0 0 7px}
+.meta{display:flex;flex-wrap:wrap;gap:6px;align-items:center}
+.tag{font-size:.72rem;padding:2px 8px;border-radius:5px;background:var(--chip);color:var(--muted)}
+.dot{width:7px;height:7px;border-radius:50%;background:var(--accent);display:inline-block}
+.dot.pending{background:var(--muted)}
+.disc{width:100%;border-collapse:collapse;font-size:.84rem}
+.disc th,.disc td{text-align:left;padding:6px 10px;border-bottom:1px solid var(--line)}
+.disc th{color:var(--muted);font-weight:600}
+.disc code{font:.86em ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--muted)}
+.fetch{margin:14px 0 0;font-size:.82rem;color:var(--muted)}
+.fetch code{background:var(--chip);padding:1px 5px;border-radius:5px}
+.foot{color:var(--muted);font-size:.78rem;text-align:center;border-top:1px solid var(--line)}
+.none{color:var(--muted);font-style:italic}
+`;
+const htmlAttr = (theme) => theme === "auto" ? "" : ` data-theme="${theme}"`;
+export function renderCard(root, opts = {}) {
+    const theme = opts.theme ?? "auto";
+    const accent = safeAccent(opts.accent);
+    const agents = parseAgentsMd(join(root, "AGENTS.md"));
+    const mem = parseFafm(join(root, "project.fafm"));
+    const id = resolveIdentity(root);
+    const meta = trinityMeta();
+    const name = id?.displayName ?? id?.name ?? NAME;
+    const pills = [
+        id?.vendor && id.vendor !== id.status && `<span class="pill">${escapeHtml(id.vendor)}</span>`,
+        id?.agentVersion && `<span class="pill">v${escapeHtml(id.agentVersion)}</span>`,
+        id?.status && `<span class="pill accent">${escapeHtml(id.status)}</span>`,
+        id?.license && `<span class="pill">${escapeHtml(id.license)}</span>`,
+    ]
+        .filter(Boolean)
+        .join("");
+    // CONTEXT — drop the redundant top-level "# AGENTS.md" heading, keep its intro
+    const bodySections = agents?.sections.filter((s) => s.level > 1) ?? [];
+    const toc = bodySections.length
+        ? `<ul class="toc">${bodySections
+            .map((s) => `<li><a href="#${slug(s.heading)}">${escapeHtml(s.heading)}</a></li>`)
+            .join("")}</ul>`
+        : "";
+    const contextBody = agents
+        ? `${toc}<div class="md">${renderMarkdown([
+            agents.preamble,
+            agents.sections.find((s) => s.level === 1)?.body ?? "",
+            ...bodySections.map((s) => `${"#".repeat(s.level)} ${s.heading}\n\n${s.body}`),
+        ]
+            .filter(Boolean)
+            .join("\n\n"))}</div>`
+        : `<p class="none">No AGENTS.md in this project.</p>`;
+    // MEMORY
+    const memoryBody = mem.facts.length
+        ? mem.facts
+            .map((f) => {
+            const verified = f.verification_status === "verified";
+            const tags = (f.tags ?? [])
+                .map((t) => `<span class="tag">${escapeHtml(t)}</span>`)
+                .join("");
+            return `<div class="fact"><p>${renderInline(f.text)}</p><div class="meta">${tags}<span class="dot${verified ? "" : " pending"}" title="${verified ? "verified" : f.verification_status ?? "unverified"}"></span></div></div>`;
+        })
+            .join("")
+        : `<p class="none">No facts yet.</p>`;
+    // DISCOVERY
+    const rows = Object.entries(meta)
+        .map(([k, v]) => {
+        const concern = k.slice(META_NS.length + 1);
+        return `<tr><td>${concern}</td><td><code>${escapeHtml(v.source)}</code></td><td><code>${escapeHtml(v.mediaType)}</code></td></tr>`;
+    })
+        .join("");
+    return `<!doctype html>
+<html lang="en"${htmlAttr(theme)}>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(name)} — context card</title>
+<style>${CSS(accent)}</style>
+</head>
+<body>
+<main class="card">
+  <div class="top">
+    <h1>${escapeHtml(name)}</h1>
+    <div class="pills">${pills || '<span class="pill">MCP context card</span>'}</div>
+  </div>
+  <section>
+    <p class="label">Context — AGENTS.md</p>
+    ${contextBody}
+  </section>
+  <section>
+    <p class="label">Memory — ${mem.facts.length} fact${mem.facts.length === 1 ? "" : "s"}</p>
+    ${memoryBody}
+  </section>
+  <section>
+    <p class="label">Discovery</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
+      from <code>GET /.well-known/mcp/server-card</code> and
+      <code>GET /.well-known/ai-catalog.json</code>.</p>
+  </section>
+  <div class="foot">${escapeHtml(name)} · context card</div>
+</main>
+</body>
+</html>
+`;
+}

package/dist/server.d.ts

@@ -0,0 +1,56 @@
+/**
+ * mcp-context-card server — makes a project's context, memory, and identity
+ * discoverable to any MCP client.
+ *
+ *   context   — read_agents_md · list_agents_md_sections   (this project's AGENTS.md)
+ *   memory    — remember · recall · forget                 (a .fafm file)
+ *   identity  — whoami                                     (this server's .fafa)
+ *   discovery — list_context_sources                       (what's published, and how)
+ *
+ * ...exposed through the two mechanisms already in the ecosystem:
+ *
+ *   1. Server Card `_meta` — the `mcp-context-card://server-card` resource (in band)
+ *      and `GET /.well-known/mcp/server-card` (out of band, http transport).
+ *   2. ai-catalog — `GET /.well-known/ai-catalog.json`, three sibling entries
+ *      keyed by media type (see catalog-gen.ts).
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+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`.
+ */
+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;
+        };
+    };
+};
+/**
+ * @param root  directory holding `AGENTS.md`, `project.fafm`, `.well-known/`.
+ *              Defaults to the package root; a deploy points `MCP_CONTEXT_CARD_ROOT`
+ *              at a real project, a test points it at a fixture.
+ */
+export declare function createServer(root?: string): Server;
+/** Connect a server instance to a transport (stdio or http). */
+export declare function serve(transport: Transport, root?: string): Promise<Server>;

package/dist/server.js

@@ -0,0 +1,250 @@
+/**
+ * mcp-context-card server — makes a project's context, memory, and identity
+ * discoverable to any MCP client.
+ *
+ *   context   — read_agents_md · list_agents_md_sections   (this project's AGENTS.md)
+ *   memory    — remember · recall · forget                 (a .fafm file)
+ *   identity  — whoami                                     (this server's .fafa)
+ *   discovery — list_context_sources                       (what's published, and how)
+ *
+ * ...exposed through the two mechanisms already in the ecosystem:
+ *
+ *   1. Server Card `_meta` — the `mcp-context-card://server-card` resource (in band)
+ *      and `GET /.well-known/mcp/server-card` (out of band, http transport).
+ *   2. ai-catalog — `GET /.well-known/ai-catalog.json`, three sibling entries
+ *      keyed by media type (see catalog-gen.ts).
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { dirname, join } from "node:path";
+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, trinityMeta, whoami } from "./identity.js";
+import { renderCard, safeAccent } from "./render-card.js";
+export { NAME, VERSION, SERVER_CARD_URI } from "./constants.js";
+import { NAME, VERSION, SERVER_CARD_URI } from "./constants.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`.
+ */
+export function serverCard() {
+    return { name: NAME, version: VERSION, _meta: trinityMeta() };
+}
+const text = (s) => ({ content: [{ type: "text", text: s }] });
+/**
+ * @param root  directory holding `AGENTS.md`, `project.fafm`, `.well-known/`.
+ *              Defaults to the package root; a deploy points `MCP_CONTEXT_CARD_ROOT`
+ *              at a real project, a test points it at a fixture.
+ */
+export function createServer(root = ROOT) {
+    const AGENTS = join(root, "AGENTS.md");
+    const FAFM = join(root, "project.fafm");
+    const FAFA = join(root, ".well-known/fafa");
+    const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: {}, resources: {} } });
+    // ── Mechanism 1: the Server Card resource + its _meta context block ───
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: [
+            {
+                uri: SERVER_CARD_URI,
+                name: "Server Card",
+                description: "This server's identity + the _meta context block.",
+                mimeType: "application/json",
+            },
+        ],
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+        if (req.params.uri !== SERVER_CARD_URI) {
+            throw new Error(`unknown resource: ${req.params.uri}`);
+        }
+        return {
+            contents: [
+                { uri: SERVER_CARD_URI, mimeType: "application/json", text: JSON.stringify(serverCard(), null, 2) },
+            ],
+        };
+    });
+    // ── Tools ───────────────────────────────────────────────────────────
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "read_agents_md",
+                description: "Return this project's AGENTS.md — the whole file, or one section by heading. The instructions a client would otherwise have to know to look for and read wholesale.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        section: {
+                            type: "string",
+                            description: "A heading to return just that section (case-insensitive, prefix match). Omit for the whole file.",
+                        },
+                    },
+                },
+            },
+            {
+                name: "author_agents_md",
+                description: "Author an AGENTS.md for this project from its repo facts (via agents-md-facts) and return the draft — a managed block, ready to drop in. Detects real build/test commands, entry points, and toolchain conventions; nothing invented. Does not write a file.",
+                inputSchema: { type: "object", properties: {} },
+            },
+            {
+                name: "list_agents_md_sections",
+                description: "List the headings in this project's AGENTS.md, so a client can pull one section instead of spending context on the whole file.",
+                inputSchema: { type: "object", properties: {} },
+            },
+            {
+                name: "remember",
+                description: "Persist a fact past the session boundary — written to a .fafm file, not held in memory.",
+                inputSchema: {
+                    type: "object",
+                    properties: { id: { type: "string" }, text: { type: "string" } },
+                    required: ["id", "text"],
+                },
+            },
+            {
+                name: "recall",
+                description: "Retrieve a fact stored in a previous session by id.",
+                inputSchema: {
+                    type: "object",
+                    properties: { id: { type: "string" } },
+                    required: ["id"],
+                },
+            },
+            {
+                name: "forget",
+                description: "Remove a fact by id — to correct or drop something stale.",
+                inputSchema: {
+                    type: "object",
+                    properties: { id: { type: "string" } },
+                    required: ["id"],
+                },
+            },
+            {
+                name: "whoami",
+                description: "This server's own identity — name, vendor, version, status, license — from its .fafa card.",
+                inputSchema: { type: "object", properties: {} },
+            },
+            {
+                name: "list_context_sources",
+                description: "What context does this project publish (AGENTS.md, memory, identity), in what media types, and through which discovery surface. For a client connecting cold.",
+                inputSchema: { type: "object", properties: {} },
+            },
+            {
+                name: "render_context_card",
+                description: "Render the whole card — identity, AGENTS.md, memory, discovery — as one self-contained HTML page a person can read or screenshot. Also served at GET /card over the HTTP transport.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        theme: { type: "string", enum: ["light", "dark", "auto"], description: "default: auto" },
+                        accent: { type: "string", description: "CSS hex colour, e.g. #FF702D (default: the AAIF palette)" },
+                    },
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const args = (req.params.arguments ?? {});
+        switch (req.params.name) {
+            case "read_agents_md": {
+                const doc = parseAgentsMd(AGENTS);
+                if (!doc)
+                    return text("(no AGENTS.md in this project)");
+                if (!args.section)
+                    return text(doc.raw);
+                const s = findSection(doc, args.section);
+                return s
+                    ? text(`${"#".repeat(s.level)} ${s.heading}\n\n${s.body}`)
+                    : text(`(no section matching "${args.section}" — headings: ${doc.sections
+                        .map((x) => x.heading)
+                        .join(", ")})`);
+            }
+            case "list_agents_md_sections": {
+                const doc = parseAgentsMd(AGENTS);
+                if (!doc)
+                    return text("(no AGENTS.md in this project)");
+                return text(JSON.stringify(doc.sections.map((s) => ({ heading: s.heading, level: s.level })), null, 2));
+            }
+            case "author_agents_md": {
+                const a = authorAgentsMd(root);
+                const note = a.exists
+                    ? "AGENTS.md already exists — diff this managed block in, don't overwrite"
+                    : "no AGENTS.md yet — write this, then `npx agents-md-facts --check` keeps it true";
+                return text(`<!-- ${note} -->\n\n${a.markdown}`);
+            }
+            case "remember": {
+                remember(FAFM, args.id, args.text);
+                return text(`remembered: ${args.id}`);
+            }
+            case "recall": {
+                const fact = recall(FAFM, args.id);
+                return text(fact ? fact.text : `(no memory for "${args.id}")`);
+            }
+            case "forget": {
+                return text(forget(FAFM, args.id) ? `forgot: ${args.id}` : `(no memory for "${args.id}")`);
+            }
+            case "whoami":
+                return text(whoami(root));
+            case "render_context_card":
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: renderCard(root, {
+                                theme: (["light", "dark", "auto"].includes(args.theme) ? args.theme : "auto"),
+                                accent: safeAccent(args.accent),
+                            }),
+                        },
+                    ],
+                };
+            case "list_context_sources": {
+                const doc = parseAgentsMd(AGENTS);
+                const mem = parseFafm(FAFM);
+                return text(JSON.stringify({
+                    context: {
+                        source: "AGENTS.md",
+                        mediaType: "text/markdown",
+                        present: !!doc,
+                        sections: doc?.sections.length ?? 0,
+                    },
+                    memory: {
+                        source: "project.fafm",
+                        mediaType: "application/vnd.fafm+yaml",
+                        present: mem.facts.length > 0 || mem.profile !== undefined,
+                        facts: mem.facts.length,
+                    },
+                    identity: {
+                        source: ".well-known/fafa",
+                        mediaType: "application/vnd.fafa+yaml",
+                        present: identity(root) !== null,
+                    },
+                    surfaces: {
+                        mcp: { serverCard: `resource ${SERVER_CARD_URI}` },
+                        http: {
+                            serverCard: "GET /.well-known/mcp/server-card",
+                            aiCatalog: "GET /.well-known/ai-catalog.json",
+                            card: "GET /card",
+                        },
+                    },
+                }, null, 2));
+            }
+            default:
+                throw new Error(`unknown tool: ${req.params.name}`);
+        }
+    });
+    return server;
+}
+/** Connect a server instance to a transport (stdio or http). */
+export async function serve(transport, root = ROOT) {
+    const server = createServer(root);
+    await server.connect(transport);
+    return server;
+}
+// Direct run (incl. the demo's spawned child) → stdio. pathToFileURL keeps
+// this correct on Windows, where argv[1] is a `C:\...` path.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    await serve(new StdioServerTransport());
+}

package/dist/transport/http.d.ts

@@ -0,0 +1,2 @@
+import { Hono } from "hono";
+export declare function httpApp(root?: string): Hono;

package/dist/transport/http.js

@@ -0,0 +1,74 @@
+/**
+ * http — the stateless Streamable HTTP transport (MCP 2026-03-26+).
+ *
+ * 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
+ * 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 trinity
+ *   GET /.well-known/ai-catalog.json   — the three sibling entries
+ *   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 { createServer, NAME, ROOT, VERSION, serverCard } from "../server.js";
+import { renderCard, safeAccent } from "../render-card.js";
+export function httpApp(root = ROOT) {
+    const app = new Hono();
+    app.use("*", cors());
+    // ── MCP endpoint — stateless ────────────────────────────────────────
+    app.all("/mcp", async (c) => {
+        const server = createServer(root);
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            sessionIdGenerator: undefined, // stateless
+            enableJsonResponse: true, // complete JSON body, no SSE stream
+        });
+        await server.connect(transport);
+        const res = await transport.handleRequest(c.req.raw);
+        // JSON/stateless mode: the response body is fully built before we get
+        // here, so closing the per-request instances now can't truncate it.
+        void transport.close();
+        void server.close();
+        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));
+    });
+    app.get("/.well-known/fafa", (c) => {
+        c.header("content-type", "application/vnd.fafa+yaml");
+        return c.body(readFileSync(join(root, ".well-known/fafa"), "utf8"));
+    });
+    // ── 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) }));
+    });
+    // ── Index ───────────────────────────────────────────────────────────
+    app.get("/", (c) => c.json({
+        name: NAME,
+        version: VERSION,
+        mcp: "/mcp",
+        card: "/card",
+        wellKnown: [
+            "/.well-known/mcp/server-card",
+            "/.well-known/ai-catalog.json",
+            "/.well-known/fafa",
+        ],
+    }));
+    return app;
+}