mcp-context-card 1.7.0 → 1.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.well-known/ai-catalog.json +1 -1
- package/.well-known/fafa +1 -1
- package/AGENTS.md +5 -3
- package/CHANGELOG.md +72 -0
- package/README.md +26 -4
- package/dist/bin.d.ts +1 -1
- package/dist/bin.js +12 -3
- package/dist/card-app.bundle.js +103 -0
- package/dist/card-gen.js +15 -6
- package/dist/constants.d.ts +17 -1
- package/dist/constants.js +35 -1
- package/dist/render-card.d.ts +14 -43
- package/dist/render-card.js +96 -327
- package/dist/server-card.js +3 -2
- package/dist/server.d.ts +19 -3
- package/dist/server.js +88 -33
- package/dist/transport/http.js +23 -9
- package/docs/MECHANISMS.md +2 -2
- package/docs/TRANSPORT.md +76 -11
- package/docs/WIRING.md +6 -0
- package/docs/card-dark.html +5 -5
- package/docs/card-light.html +5 -5
- package/docs/card.html +5 -5
- package/docs/img/card-dark.png +0 -0
- package/docs/img/card-identity.png +0 -0
- package/docs/img/card-light.png +0 -0
- package/docs/index.html +5 -5
- package/package.json +10 -6
- package/project.faf +1 -1
- package/server.json +2 -2
package/dist/server.js
CHANGED
|
@@ -13,10 +13,12 @@
|
|
|
13
13
|
* and `GET /.well-known/mcp/server-card` (out of band, http transport).
|
|
14
14
|
* 2. ai-catalog — `GET /.well-known/ai-catalog.json`, three sibling entries
|
|
15
15
|
* keyed by media type (see catalog-gen.ts).
|
|
16
|
+
*
|
|
17
|
+
* Both protocol eras are served: 2026-07-28 (`server/discover`, a `_meta`
|
|
18
|
+
* envelope on every request) and 2025 (`initialize`). See docs/TRANSPORT.md.
|
|
16
19
|
*/
|
|
17
|
-
import {
|
|
18
|
-
import {
|
|
19
|
-
import { CallToolRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, RootsListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
|
|
20
|
+
import { serveStdio } from "@modelcontextprotocol/server/stdio";
|
|
21
|
+
import { CLIENT_CAPABILITIES_META_KEY, inputRequired, inputResponse, isInputRequiredResult, Server } from "@modelcontextprotocol/server";
|
|
20
22
|
import { existsSync, statSync, writeFileSync } from "node:fs";
|
|
21
23
|
import { basename, dirname, join } from "node:path";
|
|
22
24
|
import { fileURLToPath, pathToFileURL } from "node:url";
|
|
@@ -24,9 +26,9 @@ import { findSection, parseAgentsMd } from "./agents-md.js";
|
|
|
24
26
|
import { authorAgentsMd } from "./author.js";
|
|
25
27
|
import { forget, parseFafm, recall, remember } from "./memory.js";
|
|
26
28
|
import { identity, resolveIdentity, whoami } from "./identity.js";
|
|
27
|
-
import { renderCard, renderCardText, safeAccent } from "./render-card.js";
|
|
29
|
+
import { renderAppsCard, renderCard, renderCardText, safeAccent } from "./render-card.js";
|
|
28
30
|
export { NAME, VERSION, SERVER_CARD_URI } from "./constants.js";
|
|
29
|
-
import { VERSION, SERVER_CARD_URI, CARD_UI_URI, MCP_APP_MIME, UI_EXTENSION, REGISTRY_NAME, TITLE, SERVER_CARD_MEDIA_TYPE } from "./constants.js";
|
|
31
|
+
import { VERSION, SERVER_CARD_URI, CARD_UI_URI, MCP_APP_MIME, UI_EXTENSION, REGISTRY_NAME, TITLE, SERVER_CARD_MEDIA_TYPE, cardAppFromEnv, toCardApp } from "./constants.js";
|
|
30
32
|
import { serverCard } from "./server-card.js";
|
|
31
33
|
const here = dirname(fileURLToPath(import.meta.url));
|
|
32
34
|
/** Default package root — `dist/` at runtime, `src/` under tsx. Both are one up. */
|
|
@@ -71,20 +73,33 @@ const CARD_ARGS = {
|
|
|
71
73
|
* Defaults to the package root; a deploy points `MCP_CONTEXT_CARD_ROOT`
|
|
72
74
|
* at a real project, a test points it at a fixture.
|
|
73
75
|
*/
|
|
74
|
-
/**
|
|
76
|
+
/** The client's declared capabilities. 2026-07-28 requests carry them in their
|
|
77
|
+
* own `_meta` envelope (there is no `initialize`); 2025-era connections
|
|
78
|
+
* declared them once, at `initialize`, and envelope keys a 2025 request
|
|
79
|
+
* happens to carry are ignored. */
|
|
80
|
+
function clientCaps(server, ctx, era) {
|
|
81
|
+
if (era !== "modern")
|
|
82
|
+
return server.getClientCapabilities();
|
|
83
|
+
// The SDK publishes the envelope as `{}`; it is keyed by the meta-key constants.
|
|
84
|
+
const envelope = ctx?.mcpReq?.envelope;
|
|
85
|
+
return envelope?.[CLIENT_CAPABILITIES_META_KEY] ?? server.getClientCapabilities();
|
|
86
|
+
}
|
|
87
|
+
/** True when the client declared MCP Apps support
|
|
75
88
|
* (capabilities.extensions["io.modelcontextprotocol/ui"].mimeTypes). */
|
|
76
|
-
function hostRendersApps(server) {
|
|
77
|
-
const ext = server
|
|
89
|
+
function hostRendersApps(server, ctx, era) {
|
|
90
|
+
const ext = clientCaps(server, ctx, era)?.extensions?.[UI_EXTENSION];
|
|
78
91
|
return Array.isArray(ext?.mimeTypes) && ext.mimeTypes.includes(MCP_APP_MIME);
|
|
79
92
|
}
|
|
80
93
|
export function createServer(root = ROOT, opts = {}) {
|
|
94
|
+
// A JS caller can pass any string: normalise it; an unknown value falls back to the environment.
|
|
95
|
+
const cardApp = toCardApp(opts.cardApp) ?? cardAppFromEnv();
|
|
81
96
|
const server = new Server({ name: REGISTRY_NAME, title: TITLE, version: VERSION }, { capabilities: { tools: {}, resources: {} }, instructions: INSTRUCTIONS });
|
|
82
97
|
// ── Which project? ────────────────────────────────────────────────────
|
|
83
98
|
// Resolved per call, not at startup: a client's roots are only known once
|
|
84
99
|
// it has connected, and they can change (goose sends its session's working
|
|
85
100
|
// directory, and notifies when it moves).
|
|
86
101
|
let found;
|
|
87
|
-
server.setNotificationHandler(
|
|
102
|
+
server.setNotificationHandler('notifications/roots/list_changed', async () => {
|
|
88
103
|
found = undefined;
|
|
89
104
|
});
|
|
90
105
|
const isDir = (p) => {
|
|
@@ -95,30 +110,51 @@ export function createServer(root = ROOT, opts = {}) {
|
|
|
95
110
|
return false;
|
|
96
111
|
}
|
|
97
112
|
};
|
|
98
|
-
|
|
99
|
-
|
|
113
|
+
const firstDir = (roots) => {
|
|
114
|
+
for (const r of roots) {
|
|
115
|
+
if (!r.uri.startsWith("file:"))
|
|
116
|
+
continue;
|
|
117
|
+
const dir = fileURLToPath(r.uri);
|
|
118
|
+
if (isDir(dir))
|
|
119
|
+
return dir;
|
|
120
|
+
}
|
|
121
|
+
return undefined;
|
|
122
|
+
};
|
|
123
|
+
async function fromClientRoots(ctx) {
|
|
124
|
+
if (!clientCaps(server, ctx, opts.era)?.roots)
|
|
100
125
|
return undefined;
|
|
126
|
+
if (opts.era === "modern") {
|
|
127
|
+
// 2026-07-28 has no server→client requests: ask for the roots in-band.
|
|
128
|
+
// The client answers by retrying this same call with the roots attached.
|
|
129
|
+
const answer = inputResponse(ctx?.mcpReq?.inputResponses, "roots");
|
|
130
|
+
if (answer.kind === "roots")
|
|
131
|
+
return firstDir(answer.roots);
|
|
132
|
+
if (answer.kind === "missing")
|
|
133
|
+
return inputRequired({ inputRequests: { roots: inputRequired.listRoots() } });
|
|
134
|
+
return undefined;
|
|
135
|
+
}
|
|
101
136
|
try {
|
|
102
137
|
const { roots } = await server.listRoots(undefined, { timeout: 5000 });
|
|
103
|
-
|
|
104
|
-
if (!r.uri.startsWith("file:"))
|
|
105
|
-
continue;
|
|
106
|
-
const dir = fileURLToPath(r.uri);
|
|
107
|
-
if (isDir(dir))
|
|
108
|
-
return dir;
|
|
109
|
-
}
|
|
138
|
+
return firstDir(roots);
|
|
110
139
|
}
|
|
111
140
|
catch {
|
|
112
141
|
// a client that declares roots but doesn't answer: fall through
|
|
113
142
|
}
|
|
114
143
|
return undefined;
|
|
115
144
|
}
|
|
116
|
-
async function project() {
|
|
145
|
+
async function project(ctx) {
|
|
117
146
|
if (!opts.detectRoot)
|
|
118
147
|
return { root, from: root === ROOT ? "package" : "configured" };
|
|
148
|
+
// 2026-07-28 has no roots/list_changed (the SDK drops it on that era), so a
|
|
149
|
+
// roots answer carried by this call (roots, or a decline) replaces the cached
|
|
150
|
+
// root. No answer keeps the cache: the server asks once per connection.
|
|
151
|
+
if (opts.era === "modern" && inputResponse(ctx?.mcpReq?.inputResponses, "roots").kind !== "missing")
|
|
152
|
+
found = undefined;
|
|
119
153
|
if (found)
|
|
120
154
|
return found;
|
|
121
|
-
const fromRoots = await fromClientRoots();
|
|
155
|
+
const fromRoots = await fromClientRoots(ctx);
|
|
156
|
+
if (fromRoots !== undefined && typeof fromRoots !== "string")
|
|
157
|
+
return fromRoots;
|
|
122
158
|
const cwd = opts.cwd ?? process.cwd();
|
|
123
159
|
found = fromRoots
|
|
124
160
|
? { root: fromRoots, from: "client roots" }
|
|
@@ -132,7 +168,7 @@ export function createServer(root = ROOT, opts = {}) {
|
|
|
132
168
|
FAFM: join(dir, "project.fafm"),
|
|
133
169
|
});
|
|
134
170
|
// ── Mechanism 1: the Server Card resource + its _meta context block ───
|
|
135
|
-
server.setRequestHandler(
|
|
171
|
+
server.setRequestHandler('resources/list', async () => ({
|
|
136
172
|
resources: [
|
|
137
173
|
{
|
|
138
174
|
uri: SERVER_CARD_URI,
|
|
@@ -148,13 +184,21 @@ export function createServer(root = ROOT, opts = {}) {
|
|
|
148
184
|
},
|
|
149
185
|
],
|
|
150
186
|
}));
|
|
151
|
-
server.setRequestHandler(
|
|
187
|
+
server.setRequestHandler('resources/read', async (req, ctx) => {
|
|
152
188
|
if (req.params.uri === CARD_UI_URI) {
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
189
|
+
const p = await project(ctx);
|
|
190
|
+
if (isInputRequiredResult(p))
|
|
191
|
+
return p;
|
|
192
|
+
// Rendered at read time from the project's own files. This is the only
|
|
193
|
+
// card that includes the MCP Apps helper and the inline view. Tool text,
|
|
194
|
+
// save_context_card, GET /card and the CLI stay on renderCard. Inline
|
|
195
|
+
// CSS, no external requests. The helper reports the card's size and,
|
|
196
|
+
// in a host panel, shows the inline view.
|
|
197
|
+
// MCP_CONTEXT_CARD_APP=plain: the plain card here too (no helper, so
|
|
198
|
+
// no inline view: the full card in the host's default frame).
|
|
199
|
+
const render = cardApp === "plain" ? renderCard : renderAppsCard;
|
|
156
200
|
return {
|
|
157
|
-
contents: [{ uri: CARD_UI_URI, mimeType: MCP_APP_MIME, text:
|
|
201
|
+
contents: [{ uri: CARD_UI_URI, mimeType: MCP_APP_MIME, text: render(p.root, { theme: "auto" }) }],
|
|
158
202
|
};
|
|
159
203
|
}
|
|
160
204
|
if (req.params.uri !== SERVER_CARD_URI) {
|
|
@@ -170,11 +214,11 @@ export function createServer(root = ROOT, opts = {}) {
|
|
|
170
214
|
// templated resources here (the Server Card URI is fixed), but answer with an
|
|
171
215
|
// empty list rather than -32601 — a client shouldn't get method-not-found for
|
|
172
216
|
// something the declared capability covers.
|
|
173
|
-
server.setRequestHandler(
|
|
217
|
+
server.setRequestHandler('resources/templates/list', async () => ({
|
|
174
218
|
resourceTemplates: [],
|
|
175
219
|
}));
|
|
176
220
|
// ── Tools ───────────────────────────────────────────────────────────
|
|
177
|
-
server.setRequestHandler(
|
|
221
|
+
server.setRequestHandler('tools/list', async () => ({
|
|
178
222
|
tools: [
|
|
179
223
|
{
|
|
180
224
|
name: "read_agents_md",
|
|
@@ -304,9 +348,12 @@ export function createServer(root = ROOT, opts = {}) {
|
|
|
304
348
|
},
|
|
305
349
|
],
|
|
306
350
|
}));
|
|
307
|
-
server.setRequestHandler(
|
|
351
|
+
server.setRequestHandler('tools/call', async (req, ctx) => {
|
|
308
352
|
const args = (req.params.arguments ?? {});
|
|
309
|
-
const
|
|
353
|
+
const p = await project(ctx);
|
|
354
|
+
if (isInputRequiredResult(p))
|
|
355
|
+
return p;
|
|
356
|
+
const { root, from } = p;
|
|
310
357
|
const { AGENTS, FAFM } = files(root);
|
|
311
358
|
switch (req.params.name) {
|
|
312
359
|
case "read_agents_md": {
|
|
@@ -350,7 +397,7 @@ export function createServer(root = ROOT, opts = {}) {
|
|
|
350
397
|
case "whoami":
|
|
351
398
|
return text(whoami(root));
|
|
352
399
|
case "render_context_card": {
|
|
353
|
-
if (hostRendersApps(server)) {
|
|
400
|
+
if (hostRendersApps(server, ctx, opts.era)) {
|
|
354
401
|
// The host renders the card itself from CARD_UI_URI, so the model
|
|
355
402
|
// gets a short summary instead of a whole HTML page.
|
|
356
403
|
const doc = parseAgentsMd(AGENTS);
|
|
@@ -410,6 +457,7 @@ export function createServer(root = ROOT, opts = {}) {
|
|
|
410
457
|
mcp: {
|
|
411
458
|
serverCard: `resource ${SERVER_CARD_URI}`,
|
|
412
459
|
card: `resource ${CARD_UI_URI} (MCP App, ${MCP_APP_MIME})`,
|
|
460
|
+
cardApp,
|
|
413
461
|
},
|
|
414
462
|
http: {
|
|
415
463
|
serverCard: "GET /mcp/server-card",
|
|
@@ -425,7 +473,14 @@ export function createServer(root = ROOT, opts = {}) {
|
|
|
425
473
|
});
|
|
426
474
|
return server;
|
|
427
475
|
}
|
|
428
|
-
/**
|
|
476
|
+
/** Serve over stdio, both protocol eras: a 2026-07-28 client connects with
|
|
477
|
+
* `server/discover`, a 2025 client with `initialize`. The factory builds one
|
|
478
|
+
* instance per connection, for that connection's era. */
|
|
479
|
+
export function serveStdioServer(root = ROOT, opts = {}) {
|
|
480
|
+
return serveStdio(({ era }) => createServer(root, { ...opts, era }));
|
|
481
|
+
}
|
|
482
|
+
/** Connect a server instance to a transport you supply. 2025 era only (the
|
|
483
|
+
* transport decides the wire); for both eras use `serveStdioServer` or `httpApp`. */
|
|
429
484
|
export async function serve(transport, root = ROOT, opts = {}) {
|
|
430
485
|
const server = createServer(root, opts);
|
|
431
486
|
await server.connect(transport);
|
|
@@ -436,5 +491,5 @@ export async function serve(transport, root = ROOT, opts = {}) {
|
|
|
436
491
|
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
|
|
437
492
|
const { openInBrowser } = await import("./open.js");
|
|
438
493
|
const pinned = process.env.MCP_CONTEXT_CARD_ROOT;
|
|
439
|
-
|
|
494
|
+
serveStdioServer(pinned ?? ROOT, { openFile: openInBrowser, detectRoot: !pinned });
|
|
440
495
|
}
|
package/dist/transport/http.js
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* http — the stateless Streamable HTTP transport
|
|
2
|
+
* http — the stateless Streamable HTTP transport, both MCP protocol eras.
|
|
3
3
|
*
|
|
4
4
|
* A Hono app. `POST /mcp` is the MCP endpoint, run **stateless**: a fresh
|
|
5
|
-
* server
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* server per request and a complete JSON body per response (no SSE stream,
|
|
6
|
+
* nothing to keep open). 2026-07-28 requests go to the SDK's
|
|
7
|
+
* `createMcpHandler`; 2025 requests to a per-request transport with
|
|
8
|
+
* `sessionIdGenerator: undefined` and `enableJsonResponse`, as in 1.x. That's the right default here — it scales
|
|
8
9
|
* horizontally, needs no sticky sessions, and there's no per-connection
|
|
9
10
|
* state to leak. A server that needs server-streamed
|
|
10
11
|
* notifications or resumability would set a `sessionIdGenerator` and hold
|
|
@@ -36,7 +37,7 @@ import { existsSync, readFileSync } from "node:fs";
|
|
|
36
37
|
import { join } from "node:path";
|
|
37
38
|
import { Hono } from "hono";
|
|
38
39
|
import { cors } from "hono/cors";
|
|
39
|
-
import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
|
|
40
|
+
import { createMcpHandler, isLegacyRequest, WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/server";
|
|
40
41
|
import { buildCatalog } from "../catalog-gen.js";
|
|
41
42
|
import { fafaFile } from "../identity.js";
|
|
42
43
|
import { createServer, NAME, ROOT, VERSION, serverCard } from "../server.js";
|
|
@@ -90,20 +91,33 @@ export function httpApp(root = ROOT, opts = {}) {
|
|
|
90
91
|
app.use(MCP_PATH, cors());
|
|
91
92
|
app.use("/card", cors());
|
|
92
93
|
app.use("/", cors());
|
|
93
|
-
// ── MCP endpoint — stateless
|
|
94
|
-
|
|
95
|
-
|
|
94
|
+
// ── MCP endpoint — stateless, both protocol eras ────────────────────
|
|
95
|
+
// 2026-07-28 requests (per-request `_meta` envelope) go to the SDK's
|
|
96
|
+
// createMcpHandler. 2025 requests keep the 1.x wiring byte for byte: a fresh
|
|
97
|
+
// server + transport per request, complete JSON bodies (the handler's own
|
|
98
|
+
// legacy leg would answer them as SSE). Neither checks Host/Origin; the
|
|
99
|
+
// guards above do.
|
|
100
|
+
// responseMode stays "auto": one JSON body unless a tool emits a notification
|
|
101
|
+
// before its result, and ours never do ("json" would warn on every start).
|
|
102
|
+
const modern = createMcpHandler(({ era }) => createServer(root, { era }), { legacy: "reject" });
|
|
103
|
+
const legacy = async (request) => {
|
|
104
|
+
const server = createServer(root, { era: "legacy" });
|
|
96
105
|
const transport = new WebStandardStreamableHTTPServerTransport({
|
|
97
106
|
sessionIdGenerator: undefined, // stateless
|
|
98
107
|
enableJsonResponse: true, // complete JSON body, no SSE stream
|
|
99
108
|
});
|
|
100
109
|
await server.connect(transport);
|
|
101
|
-
const res = await transport.handleRequest(
|
|
110
|
+
const res = await transport.handleRequest(request);
|
|
102
111
|
// JSON/stateless mode: the response body is fully built before we get
|
|
103
112
|
// here, so closing the per-request instances now can't truncate it.
|
|
104
113
|
void transport.close();
|
|
105
114
|
void server.close();
|
|
106
115
|
return res;
|
|
116
|
+
};
|
|
117
|
+
app.all(MCP_PATH, async (c) => {
|
|
118
|
+
const request = c.req.raw;
|
|
119
|
+
// isLegacyRequest clones a POST body itself, so the chosen leg still reads the original.
|
|
120
|
+
return (await isLegacyRequest(request)) ? legacy(request) : modern.fetch(request);
|
|
107
121
|
});
|
|
108
122
|
// ── Discovery documents ─────────────────────────────────────────────
|
|
109
123
|
const card = (c) => discovery(c, JSON.stringify(serverCard({ origin: originOf(c) }), null, 2), SERVER_CARD_MEDIA_TYPE);
|
package/docs/MECHANISMS.md
CHANGED
|
@@ -32,7 +32,7 @@ Streamable HTTP endpoint at `<origin>/mcp` and its protocol versions):
|
|
|
32
32
|
{
|
|
33
33
|
"$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
|
|
34
34
|
"name": "io.github.Wolfe-Jam/mcp-context-card",
|
|
35
|
-
"version": "1.
|
|
35
|
+
"version": "1.8.0",
|
|
36
36
|
"title": "MCP Context Card",
|
|
37
37
|
"description": "MCP server for a project's context (AGENTS.md), memory, and identity — base or drop-in extension.",
|
|
38
38
|
"websiteUrl": "https://github.com/Wolfe-Jam/mcp-context-card",
|
|
@@ -85,7 +85,7 @@ publisher lists artifacts, each entry keyed by its **media type** (`type`).
|
|
|
85
85
|
GET /.well-known/ai-catalog.json
|
|
86
86
|
```
|
|
87
87
|
|
|
88
|
-
Served from `https://ctx.example.com` (1.
|
|
88
|
+
Served from `https://ctx.example.com` (1.8.0, this repo's own files):
|
|
89
89
|
|
|
90
90
|
```jsonc
|
|
91
91
|
{
|
package/docs/TRANSPORT.md
CHANGED
|
@@ -12,11 +12,71 @@ HOST=0.0.0.0 PORT=8080 … → exposed beyond this machine (a hosted deploy
|
|
|
12
12
|
mcp-context-card --stdio → force stdio even when PORT is set
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
+
## Protocol eras
|
|
16
|
+
|
|
17
|
+
The server speaks both MCP protocol eras, on both transports:
|
|
18
|
+
|
|
19
|
+
- **2026-07-28** — the client opens with `server/discover` and sends its
|
|
20
|
+
capabilities in a `_meta` envelope on every request. No `initialize`.
|
|
21
|
+
- **2025** (2024-10-07 to 2025-11-25) — the client opens with `initialize`.
|
|
22
|
+
|
|
23
|
+
A client that negotiates (Claude Code and goose already do) gets 2026-07-28;
|
|
24
|
+
an older client gets 2025, unchanged from 1.x. The Server Card lists both.
|
|
25
|
+
|
|
26
|
+
**Roots differ by era.** On 2025 the server asks the client with a
|
|
27
|
+
`roots/list` request; if the client fails to answer, the server falls back to
|
|
28
|
+
the start directory. On 2026-07-28 there are no server-to-client requests: the
|
|
29
|
+
server returns `input_required` with a roots request, and the client retries
|
|
30
|
+
the call with its roots. It asks once per connection: 2026-07-28 has no
|
|
31
|
+
`roots/list_changed`, so a host whose roots change sends them with a later
|
|
32
|
+
call (`inputResponses`) or reconnects. The client answers the roots request
|
|
33
|
+
itself, so a client that declares `roots` but can't answer (no handler, or an
|
|
34
|
+
error) fails the tool call on 2026-07-28 instead of falling back. Host
|
|
35
|
+
authors: either answer roots or don't declare the capability.
|
|
36
|
+
|
|
37
|
+
## The card in an MCP Apps host
|
|
38
|
+
|
|
39
|
+
Hosts that support MCP Apps read `ui://mcp-context-card/card.html`
|
|
40
|
+
(`text/html;profile=mcp-app`). That resource is the card plus one script.
|
|
41
|
+
Inside a host, the script uses `@modelcontextprotocol/ext-apps`
|
|
42
|
+
`App.connect()` (the default transport is `PostMessageTransport` to
|
|
43
|
+
`window.parent`). `autoResize: true` (the helper's default, set explicitly
|
|
44
|
+
here) sends `ui/notifications/size-changed` with `{ width, height }` when
|
|
45
|
+
the document's size changes. The helper is bundled into that resource at
|
|
46
|
+
build time; it makes no network request. A page with no host
|
|
47
|
+
(`window.parent === window`) does not start the exchange.
|
|
48
|
+
|
|
49
|
+
`render_context_card` for a client without MCP Apps, `save_context_card`,
|
|
50
|
+
`GET /card`, and `mcp-context-card card` return the plain card. That page
|
|
51
|
+
does not include the helper or the inline view. `card:check` fails if it
|
|
52
|
+
exceeds 64 KB.
|
|
53
|
+
|
|
54
|
+
After `ui/initialize`, `App.getHostContext()` is the host context
|
|
55
|
+
(`McpUiHostContext` in `@modelcontextprotocol/ext-apps`). The fields this
|
|
56
|
+
card reads are `displayMode` (`inline` | `fullscreen` | `pip`),
|
|
57
|
+
`availableDisplayModes`, and `theme` (`light` | `dark`). A later
|
|
58
|
+
`ui/notifications/host-context-changed` is merged into that same object;
|
|
59
|
+
the card listens with `addEventListener("hostcontextchanged")` and reads
|
|
60
|
+
`getHostContext()` again, because the notification params are only the
|
|
61
|
+
fields that changed.
|
|
62
|
+
|
|
63
|
+
`inline` and `pip` show the inline view (a mini card). `fullscreen` shows
|
|
64
|
+
the full card. No `displayMode`, and no host at all, show the full card.
|
|
65
|
+
"Open full card" calls `requestDisplayMode({ mode: "fullscreen" })` — method
|
|
66
|
+
`ui/request-display-mode` — only when `availableDisplayModes` includes
|
|
67
|
+
`fullscreen`, matching the helper's own example. The result's `mode` is
|
|
68
|
+
what the host actually set. Anything other than `fullscreen` leaves the
|
|
69
|
+
inline view up and points to `save_context_card`, which writes the full
|
|
70
|
+
card to `context-card.html`. On `ui/initialize` the card declares the modes
|
|
71
|
+
it supports (`appCapabilities.availableDisplayModes`: `inline`, `pip`,
|
|
72
|
+
`fullscreen`), as the spec requires of a View.
|
|
73
|
+
|
|
15
74
|
## stdio
|
|
16
75
|
|
|
17
|
-
`
|
|
18
|
-
|
|
19
|
-
|
|
76
|
+
`serveStdio` from the MCP SDK — one process, one client, JSON-RPC over
|
|
77
|
+
stdin/stdout. The first message picks the era for the connection. This is
|
|
78
|
+
what Claude Desktop, Cursor, and `npx`-style hosts use. `stdout` is the wire,
|
|
79
|
+
so all logging goes to `stderr`.
|
|
20
80
|
|
|
21
81
|
```jsonc
|
|
22
82
|
// claude_desktop_config.json
|
|
@@ -29,15 +89,19 @@ the wire, so all logging goes to `stderr`.
|
|
|
29
89
|
|
|
30
90
|
## Streamable HTTP — stateless
|
|
31
91
|
|
|
32
|
-
`POST /mcp` is the MCP endpoint. It runs **stateless**:
|
|
92
|
+
`POST /mcp` is the MCP endpoint, for both eras. It runs **stateless**:
|
|
33
93
|
|
|
34
|
-
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
94
|
+
- **2026-07-28 requests** (the `_meta` envelope) go to the SDK's
|
|
95
|
+
`createMcpHandler`, which builds a fresh server per request. Answers are
|
|
96
|
+
one JSON body: the handler streams only when a tool sends a notification
|
|
97
|
+
before its result, and these tools never do.
|
|
98
|
+
- **2025 requests** keep the 1.x wiring: `sessionIdGenerator: undefined` (no
|
|
99
|
+
session IDs, no `Mcp-Session-Id` header) and `enableJsonResponse: true`
|
|
100
|
+
(every response is a complete JSON body, no SSE stream).
|
|
101
|
+
- The SDK's own `isLegacyRequest` decides which; the `Host` and `Origin`
|
|
102
|
+
guards run before either.
|
|
103
|
+
- A **fresh `Server` per request** on both. Two concurrent requests never
|
|
104
|
+
share state or collide on JSON-RPC ids.
|
|
41
105
|
|
|
42
106
|
```
|
|
43
107
|
GET / → index (endpoints)
|
|
@@ -108,6 +172,7 @@ they carry no private data.
|
|
|
108
172
|
| `MCP_CONTEXT_CARD_ALLOWED_HOSTS=ctx.example.com` | extra Host names to accept, e.g. a reverse proxy's public name in front of a local bind |
|
|
109
173
|
| `MCP_CONTEXT_CARD_ALLOWED_ORIGINS=https://app.example.com` | browser origins allowed to call the server |
|
|
110
174
|
| `MCP_CONTEXT_CARD_PUBLISH_MEMORY=1` | serve `project.fafm`, list it in the AI Catalog, and show memory facts on an exposed `/card` |
|
|
175
|
+
| `MCP_CONTEXT_CARD_APP=plain` | the `ui://mcp-context-card/card.html` card an MCP Apps host reads is the plain card (~30 KB, no MCP Apps messages, the host's default frame) instead of the card with the MCP Apps helper (`helper`, the default, ~700 KB). Tool text, `save_context_card`, `GET /card` and the CLI are the plain card either way. Any case is read (`PLAIN` is `plain`); any other value prints one line to stderr and uses `helper`. `list_context_sources` reports the active value (`surfaces.mcp.cardApp`). |
|
|
111
176
|
|
|
112
177
|
### Where memory shows
|
|
113
178
|
|
package/docs/WIRING.md
CHANGED
|
@@ -118,5 +118,11 @@ To serve *your* artifacts:
|
|
|
118
118
|
a registered type.
|
|
119
119
|
4. `npm run catalog` to regenerate, `npm run demo` to confirm all three still
|
|
120
120
|
round‑trip, `npm test` for the suite.
|
|
121
|
+
5. **The business card has two parts.** `src/render-card.ts` is the reader:
|
|
122
|
+
it gathers the fields from identity, `AGENTS.md`, memory and discovery. The
|
|
123
|
+
printer is a dependency, [`agent-business-card`](https://github.com/Wolfe-Jam/agent-business-card)
|
|
124
|
+
(browser-safe, no dependencies of its own). To change what the business
|
|
125
|
+
card says, change the reader here. To change how it looks, that's the
|
|
126
|
+
printer, and every reader that uses it changes with it.
|
|
121
127
|
|
|
122
128
|
---
|
package/docs/card-dark.html
CHANGED
|
@@ -205,7 +205,7 @@ details.ctx-section>.md{padding:0 0 16px}
|
|
|
205
205
|
</details>
|
|
206
206
|
<div class="id">
|
|
207
207
|
<h1>mcp-context-card</h1>
|
|
208
|
-
<p class="title">MCP server · v1.
|
|
208
|
+
<p class="title">MCP server · v1.8.0</p>
|
|
209
209
|
<p class="oneliner">The essential MCP components for a project's context (AGENTS.md), cross-session memory, and identity</p>
|
|
210
210
|
</div>
|
|
211
211
|
<div class="foot-front"><span class="domain">faf.one</span><div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill accent">published</span><span class="pill">MIT</span></div></div>
|
|
@@ -223,17 +223,17 @@ details.ctx-section>.md{padding:0 0 16px}
|
|
|
223
223
|
</div>
|
|
224
224
|
</details>
|
|
225
225
|
<div class="tabbar"><label for="t-about">About</label><label for="t-context">Context</label><label for="t-memory">Memory</label><label for="t-discovery">Discovery</label></div>
|
|
226
|
-
<div class="panes"><div class="pane p-about"><p class="label">About</p><p class="lead">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 a self-published ai-catalog.json.</p><table class="kv"><tbody><tr><th>Agent ID</th><td><code>urn:air:faf.one:agent:mcp-context-card</code></td></tr><tr><th>Publisher</th><td>io.github.Wolfe-Jam</td></tr><tr><th>Version</th><td>v1.
|
|
226
|
+
<div class="panes"><div class="pane p-about"><p class="label">About</p><p class="lead">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 a self-published ai-catalog.json.</p><table class="kv"><tbody><tr><th>Agent ID</th><td><code>urn:air:faf.one:agent:mcp-context-card</code></td></tr><tr><th>Publisher</th><td>io.github.Wolfe-Jam</td></tr><tr><th>Version</th><td>v1.8.0</td></tr><tr><th>Status</th><td>published</td></tr><tr><th>License</th><td>MIT</td></tr><tr><th>Package (npm)</th><td><code>mcp-context-card</code></td></tr></tbody></table></div><div class="pane p-context"><p class="label">Context — AGENTS.md</p><div class="ctx-nav"><ul class="toc"><li><a href="#setup">Setup</a></li><li><a href="#build">Build</a></li><li><a href="#test">Test</a></li><li><a href="#layout">Layout</a></li><li><a href="#conventions">Conventions</a></li><li><a href="#the-invariant">The invariant</a></li><li><a href="#safety">Safety</a></li><li><a href="#definition-of-done">Definition of done</a></li><li><a href="#authoring-this-file">Authoring this file</a></li></ul><button type="button" class="xall" hidden>Expand all</button></div>
|
|
227
227
|
<div class="ctx-preamble md"><p><code>mcp-context-card</code> is the essential MCP server for a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> — usable as your base MCP, or dropped into any existing MCP server as an extension. Discoverable to any MCP client through the two surfaces already in the ecosystem: the Server Card <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
|
|
228
228
|
<p><code>read_agents_md</code> serves this file, section by section, over the same MCP connection.</p></div>
|
|
229
229
|
<div class="ctx-body"><details class="ctx-section" id="setup"><summary>Setup</summary><div class="md"><pre><code class="language-bash">npm ci</code></pre>
|
|
230
|
-
<p>Node 22 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build # tsc -p tsconfig.build.json
|
|
231
|
-
npm run typecheck # tsc --noEmit over src/ + test
|
|
230
|
+
<p>Node 22 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build # tsc -p tsconfig.build.json, then copy the bundled card script → dist/
|
|
231
|
+
npm run typecheck # tsc --noEmit over src/ + test/, then the browser script</code></pre></div></details><details class="ctx-section" id="test"><summary>Test</summary><div class="md"><pre><code class="language-bash">npm test # node:test — every test/*.test.ts
|
|
232
232
|
npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
|
|
233
233
|
npm run demo # end to end: all tools over stdio, then over stateless HTTP
|
|
234
234
|
npm run version:check # every version-bearing spot agrees with package.json
|
|
235
235
|
npm run faf:check # project.faf / project.fafm / .well-known/fafa still describe the project</code></pre>
|
|
236
|
-
<p>CI runs <code>version:check → faf:check → typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the ten tools + the Server Card and card resources</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — BETTER via <code>agents-md-facts</code>, BEST when <code>project.faf</code> exists</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code> · <code>--help</code> · <code>--version</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><ul><li>TypeScript strict, ESM only (<code>"type": "module"</code>, <code>.js</code> import specifiers).</li><li>Tests use <code>node:test</code> + <code>node:assert/strict</code> — no test framework.</li><li>Every source file opens with a comment stating what it is and why.</li><li>Conventional Commit messages (<code>feat:</code>, <code>fix:</code>, <code>chore:</code>, <code>test:</code>, <code>docs:</code>).</li></ul></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><p><code>src/identity.ts</code>, <code>src/catalog-gen.ts</code>, and <code>src/render-card.ts</code> all describe the <strong>same three sources</strong>: this file, <code>project.fafm</code>, <code>.well-known/fafa</code>. Change what one exposes and you must change the others. <code>npm run catalog:check</code> and <code>npm run card:check</code> enforce it in CI — each regenerates its surface and fails on any diff.</p></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><p><code>npm run typecheck && npm run build && npm test && npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><p><code>AGENTS.md</code> here is maintained by hand. The <code>author_agents_md</code> tool (or <code>faf export --agents</code>) would draft a BEST version straight from this repo's own <code>project.faf</code> plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div></details></div></div><div class="pane p-memory"><p class="label">Memory — 4 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 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><div class="fact"><p>author_agents_md authors the best AGENTS.md the project has the material for, not a fixed floor. BETTER is the facts-only draft (via agents-md-facts: build/test commands, entry points, conventions — nothing invented). BEST is that plus a '## Project' section ahead of it, read straight from project.faf when one exists — goal, who it's for, why, and a start-here file list. The rule is concrete: project.faf present means BEST, absent means BETTER.</p><div class="meta"><span class="tag">agents-md</span><span class="tag">author_agents_md</span><span class="tag">faf</span><span class="dot" title="verified"></span></div></div></div><div class="pane p-discovery"><p class="label">Discovery</p><table class="disc"><thead><tr><th>concern</th><th>source</th><th>media type</th></tr></thead><tbody><tr><td>context</td><td><code>AGENTS.md</code></td><td><code>text/markdown</code></td></tr><tr><td>memory</td><td><code>project.fafm</code></td><td><code>application/vnd.fafm+yaml</code></td></tr><tr><td>identity</td><td><code>.well-known/fafa</code></td><td><code>application/vnd.fafa+yaml</code></td></tr></tbody></table>
|
|
236
|
+
<p>CI runs <code>version:check → faf:check → typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the ten tools + the Server Card and card resources</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — BETTER via <code>agents-md-facts</code>, BEST when <code>project.faf</code> exists</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/browser/card-app.ts</code></td><td>the card's MCP Apps script (size, inline view), inlined only into the <code>ui://</code> resource</td></tr><tr><td><code>scripts/bundle-card-app.mjs</code></td><td>bundles the script so the sandbox loads nothing from the network</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code> · <code>--help</code> · <code>--version</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><ul><li>TypeScript strict, ESM only (<code>"type": "module"</code>, <code>.js</code> import specifiers).</li><li>Tests use <code>node:test</code> + <code>node:assert/strict</code> — no test framework.</li><li>Every source file opens with a comment stating what it is and why.</li><li>Conventional Commit messages (<code>feat:</code>, <code>fix:</code>, <code>chore:</code>, <code>test:</code>, <code>docs:</code>).</li></ul></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><p><code>src/identity.ts</code>, <code>src/catalog-gen.ts</code>, and <code>src/render-card.ts</code> all describe the <strong>same three sources</strong>: this file, <code>project.fafm</code>, <code>.well-known/fafa</code>. Change what one exposes and you must change the others. <code>npm run catalog:check</code> and <code>npm run card:check</code> enforce it in CI — each regenerates its surface and fails on any diff. <code>card:check</code> also fails if a plain card exceeds 64 KB.</p></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><p><code>npm run typecheck && npm run build && npm test && npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><p><code>AGENTS.md</code> here is maintained by hand. The <code>author_agents_md</code> tool (or <code>faf export --agents</code>) would draft a BEST version straight from this repo's own <code>project.faf</code> plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div></details></div></div><div class="pane p-memory"><p class="label">Memory — 4 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 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><div class="fact"><p>author_agents_md authors the best AGENTS.md the project has the material for, not a fixed floor. BETTER is the facts-only draft (via agents-md-facts: build/test commands, entry points, conventions — nothing invented). BEST is that plus a '## Project' section ahead of it, read straight from project.faf when one exists — goal, who it's for, why, and a start-here file list. The rule is concrete: project.faf present means BEST, absent means BETTER.</p><div class="meta"><span class="tag">agents-md</span><span class="tag">author_agents_md</span><span class="tag">faf</span><span class="dot" title="verified"></span></div></div></div><div class="pane p-discovery"><p class="label">Discovery</p><table class="disc"><thead><tr><th>concern</th><th>source</th><th>media type</th></tr></thead><tbody><tr><td>context</td><td><code>AGENTS.md</code></td><td><code>text/markdown</code></td></tr><tr><td>memory</td><td><code>project.fafm</code></td><td><code>application/vnd.fafm+yaml</code></td></tr><tr><td>identity</td><td><code>.well-known/fafa</code></td><td><code>application/vnd.fafa+yaml</code></td></tr></tbody></table>
|
|
237
237
|
<p class="fetch">A machine reads this over <b>MCP</b> from the
|
|
238
238
|
<code>mcp-context-card://server-card</code> resource; over <b>HTTP</b> also
|
|
239
239
|
from <code>GET /mcp/server-card</code> and
|