Only serve libraries over MCP that actually publish a llms-full.txt

[abernier]

Found while wiring https://docs.pmnd.rs/api/mcp into a Claude Code plugin: the server advertises 11 libraries and can only serve 4.

The bug

Libraries were selected by testing whether docs_url is on pmndrs.github.io, as a proxy for "built with this generator, therefore ships a /llms-full.txt". The proxy is wrong for 7 of the 11 it lets through — probed just now against production:

library	${docs_url}/llms-full.txt	<page> elements
react-three-fiber	200	20
drei	200	134
zustand	200	42
docs	200	16
a11y	404	0
react-postprocessing	404	0
uikit	404	0
xr	404	0
prai	404	0
viverse	404	0
leva	404	0

Those 7 are non-functional today on both entry points — but only one of them says so:

get_page_content(lib="leva", …)  →  MCP server error: Failed to fetch llms-full.txt: Not Found
read docs://leva/index           →  ""     ← silent

get_page_content checks response.ok. The index resource did not, so the 404 body parsed to zero <page> elements and shipped an empty index. A client reads that as "this library has no documentation pages" — which is an invitation to guess paths. Every guess then fails with Page not found: /x, which points at the path rather than at the missing dump. That is a long way to walk from a 404.

The fix

• page.tsx — an explicit llms_full?: boolean on the four libraries whose sites publish a dump. Flip it on as each of the others ships one; that is a fact maintainers know and the URL cannot tell you. No second list: it is one field on the existing libs, which stays the single source of truth.
• route.ts — select on that flag, and check response.ok in the index resource too, so a missing dump fails loudly on both paths.

Nothing is lost: the 7 dropped libraries return errors or empty strings today.

libs was also declared as const with no annotation, so Library was decorative — llms_ful: true would have compiled and silently dropped a library from MCP. It is now as const satisfies Record<string, Library>, which keeps the literal types and makes that a type error.

On the home page

The page lists fourteen libraries and the server can serve four; nothing said which, so the only way to find out was to ask and get an empty index back. Each servable card now carries an MCP badge, read from the same llms_full flag the enum filters on — so the page and the server cannot disagree, and a library gets its badge on the commit that makes it servable.

Uses shadcn's Badge, which the repo was already set up for (components.json, the token block in globals.css, cn() in lib/utils), so it pulls in no new dependency. Checked in both colour schemes.

⚠️ This changes the home page snapshot — the Chromatic baselines will need accepting.

Manifest

docs://pmndrs/manifest was sending clients down the same road, so it is corrected in the same pass:

• advertised docs://jotai/index and docs://valtio/index — neither is served (both are filtered out; their docs live off-pmndrs)
• every example used zustand paths under /docs/... that 404. The real ones are /learn/... and /reference/.... Path shapes differ per library — r3f uses /api and /tutorials, drei /abstractions and /staging — so the manifest now says to read the index rather than extrapolate from another library
• claimed local docs_urls resolve to https://docs.pmnd.rs/<lib>; the code discards the path and uses the host
• pointed "Getting Started" at /api/sse while the homepage advertises /api/mcp

Tests

vitest.config.ts was missing the @/package.json alias that tsconfig.json has, so import('./route') threw Cannot find package — the one test that actually imports the route has been failing on main, and passing anyway, because it only asserts toBeDefined(). Alias added; that test now genuinely runs.

Which exposed the next layer: once it ran, it went to the real pmndrs.github.io. The MSW handlers mock r3f.docs.pmnd.rs and zustand.docs.pmnd.rs — hosts the route never requests — and onUnhandledRequest was 'warn'. The suite is now hermetic:

• handlers derived from libs, the same source of truth the route reads, so mocks cannot drift from the real docs_urls
• onUnhandledRequest: 'error' — any future unmocked call fails instead of opening a socket
• that test asserts on the returned page content, not toBeDefined(), which an error response satisfies just as well. Comment out the handlers and it goes red, which is the point

On top of that, Library Filtering re-implemented the old filter inline and asserted on the copy, so it would have kept passing after this change. It now asserts against the real libs export, including the 7 pmndrs.github.io libraries that must stay excluded.

New regression test: a 404 on llms-full.txt must produce an error, not an empty index.

Before (main):  Tests  1 failed | 76 passed (77)
After:          Tests  78 passed (78)

tsc --noEmit and eslint are clean.

No changeset

Per the README policy this is a site-only change — it touches the deployed API route, not the reusable workflow, build behavior or templates that consumers pin @v3 for.

---

🤖 Generated with Claude Code