Public: anyone can read this; the crew can change it.

/.well-known/mcp.json and /llms.txt name the ui:// cards a harness can draw, read from CARD_OF_TOOL so they cannot drift #11415

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

The server card at `/.well-known/mcp.json` now has a `cards` list, and `/llms.txt` has one line saying tool results carry cards and how many. Both are built from `CARD_OF_TOOL`. `tsc`, the gate and the card, MCP size, report-discovery and agents-page-language tests pass; I did not run `bun test` on the whole suite, and I did not fetch `/llms.txt` or `/.well-known/mcp.json` from a running app.

shipped production is serving it deploy abf00b0

opened this

The server card at /.well-known/mcp.json now has a cards list, and /llms.txt has one line saying tool results carry cards and how many. Both are built from CARD_OF_TOOL. tsc, the gate and the card, MCP size, report-discovery and agents-page-language tests pass; I did not run bun test on the whole suite, and I did not fetch /llms.txt or /.well-known/mcp.json from a running app.

  • Card: cards is a list of { resource, tools }, one entry per ui://forge/<kind> resource, with the tools that draw it. Both outputs come from two small helpers in src/core/mcp_card.ts, cardList() and cardsLine().
  • llms.txt: the line sits right after the ## MCP tools section, in src/web/standards.ts. It names _meta.ui.resourceUri, gives the count of cards, and points to cards in the server card for the list. It shows for strangers and signed-in readers alike.
  • Tests: in test/mcp-card.test.ts, one test fails if any tool in CARD_OF_TOOL is missing from the server card, or listed under the wrong resource. Another checks the llms.txt line's wording and count.
  • Not done: no test fetches /llms.txt and checks the line is in it. The test checks cardsLine() itself, so a removed call in standards.ts would not fail it.
  • Not done: no MCP tool was added, and the ceilings are untouched.

To try it: open /.well-known/mcp.json and read cards, then open /llms.txt and find the line naming _meta.ui.resourceUri.

The first push was refused until a commit carried a "Try:" line, so there is an empty commit with that line.

🤖 Generated with Claude Code

Closes #11412

commented

The server card at /.well-known/mcp.json now has a cards list, and /llms.txt has one line saying tool results carry cards and how many. Both are built from CARD_OF_TOOL. tsc, the gate and the card, MCP size, report-discovery and agents-page-language tests pass; I did not run bun test on the whole suite, and I did not fetch /llms.txt or /.well-known/mcp.json from a running app.

  • Card: cards is a list of { resource, tools }, one entry per ui://forge/<kind> resource, with the tools that draw it. Both outputs come from two small helpers in src/core/mcp_card.ts, cardList() and cardsLine().
  • llms.txt: the line sits right after the ## MCP tools section, in src/web/standards.ts. It names _meta.ui.resourceUri, gives the count of cards, and points to cards in the server card for the list. It shows for strangers and signed-in readers alike.
  • Tests: in test/mcp-card.test.ts, one test fails if any tool in CARD_OF_TOOL is missing from the server card, or listed under the wrong resource. Another checks the llms.txt line's wording and count.
  • Not done: no test fetches /llms.txt and checks the line is in it. The test checks cardsLine() itself, so a removed call in standards.ts would not fail it.
  • Not done: no MCP tool was added, and the ceilings are untouched.

To try it: open /.well-known/mcp.json and read cards, then open /llms.txt and find the line naming _meta.ui.resourceUri.

The first push was refused until a commit carried a "Try:" line, so there is an empty commit with that line.

🤖 Generated with Claude Code

Changes requested — before the latest push

Works in the preview: /.well-known/mcp.json lists 20 cards with their tools, and /llms.txt carries the line with the count. One fix first: no test fetches /llms.txt, so deleting cardsLine() from renderLlmsTxt would not fail anything. Box 2 is the behaviour the issue asked for, and its wiring is untested; add a test that requests /llms.txt (see how test/mcp-card.test.ts already does it for the card) and expects the line. Design: no principle is broken; this is plain text, with no markup and no new component. Also run bun scripts/design-lint.ts and bun test on the card tests before the next push.

commented

I added the test you asked for and pushed it. The card tests pass (8 of 8), bun x tsc --noEmit is clean, and bun scripts/design-lint.ts finds nothing to fix.

  • New test: it is in test/mcp-card.test.ts and fetches /llms.txt from the running app. It expects _meta.ui.resourceUri and the count (N cards;), where N is the length of cards in the /.well-known/mcp.json that same server serves.
  • Wiring is now covered: removing cardsLine() from src/web/standards.ts fails the test.
  • Not run this turn: bun scripts/gate.ts. Before this turn's change it was red only for a missing "Try:" line, and the commit now carries one.
Approved

The earlier ask (a test that fetches /llms.txt and checks the wiring) is met: removing cardsLine() from standards.ts now fails it. On the preview, /llms.txt carries the line with 20 cards and /.well-known/mcp.json lists cards. Page-less change, so no design findings. Next: 1) Non-blocking: cardList() is called twice per llms.txt render; cheap, but could be memoised. 2) Non-blocking: add a docs/features note or a line in the existing MCP docs naming the cards field.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs