Your framework's docs should be an MCP server

2026-08-04

A growing share of the code written against any framework today is written by an AI agent. That reader does not browse your docs site. It either knows your API from training data (stale the day it shipped) or it guesses. Nifra's answer: the documentation, the runnable examples, and the exact public API types are a live MCP server, listed in the official MCP registry, that any assistant can query mid-task.

The reader changed. Docs did not.

Documentation has always been written for a human on a second monitor: narrative pages, screenshots, a search box. The agent writing code in your editor has none of that context. What it has is whatever your framework looked like in its training data, which for a young or fast-moving project means an API surface that is months out of date or entirely hallucinated. Every framework maintainer has seen the result: issues opened against methods that never existed, generated code importing from paths that were renamed two releases ago.

The stopgap is llms.txt - a crawlable corpus for training and retrieval. Nifra ships that too. But a static file answers the question "what did this framework look like when the corpus was fetched", and the question that matters mid-task is "what is the exact signature of this function, right now, in the version I have installed".

What a live docs endpoint looks like

mcp.nifra.dev is a hosted MCP server (streamable HTTP, no auth, stateless and read-only). Connected to Claude Code, Cursor, or any MCP client, an assistant can search the documentation, pull complete runnable examples, and read the exact TypeScript types of the public API - the same corpus for every tool, generated from the same source the npm packages are built from.

BASH
# Claude Code
claude mcp add --transport http nifra https://mcp.nifra.dev

# Any MCP client: streamable HTTP endpoint
https://mcp.nifra.dev

It is registered as io.github.nifrajs/nifra-docs in the official MCP registry, which means clients that browse the registry can discover it without any of this setup.

There is a second, more interesting endpoint: every Nifra project is itself an MCP surface. nifra mcp exposes the app's real routes, schemas, and verification commands to the assistant working on it - not what the docs say a Nifra app looks like, but what this app's contract actually is. The generic docs server answers "how does the framework work"; the project server answers "what did we build".

Machine docs that cannot lie

The failure mode of every machine-readable corpus is staleness. If the corpus is maintained by hand, it drifts from the code within weeks, and now the agent is confidently wrong with citations. So the rule in Nifra's repo is that no machine-facing doc is hand-written:

  • The API reference, the per-package contract cards, and the llms.txt / llms-full.txt corpora are generated from source, and CI rejects a commit where the generated output is stale. The docs cannot trail the code because the build fails if they do.
  • The types corpus is extracted from the built packages - the same declaration files TypeScript users consume - so "what does this function accept" has exactly one answer.
  • Every self-contained example in the corpus is typechecked against the live API on every commit. At the time of writing that is 71 examples that provably compile. An example that stops compiling stops the merge.

None of this is exotic engineering. It is the same discipline as testing, applied to the artifact your newest and fastest-growing user population actually reads.

The other half: structured failure

Docs get the agent to write plausible code. The framework's second job is catching the implausible parts, in a form the agent can act on. Nifra's verification commands (nifra check, nifra assure, nifra doctor) exist for humans, but their output is designed for the other reader:

BASH
$ nifra assure

✖ POST /jobs (authenticated-write) is missing nifra.authenticated
  route declared: db.write
  policy: authenticated-write requires an authentication guard
  fix: add nifra.authenticated (docs: /docs/capabilities)

That is a complete loop: the agent scaffolds a route, the policy engine refuses it with the rule that failed and the fix that satisfies it, the agent applies the fix and re-runs. No human in the middle, no prose error to misparse. In practice this loop is where the agent-native design pays for itself - not in writing the first draft, but in converging on a correct one.

Do this for your project

The recipe generalizes to any framework or library:

TEXT
1. Generate, never hand-write. Docs that humans maintain drift; docs built
   from source at release time cannot.
2. Gate staleness in CI. A generated corpus that can be forgotten is a
   hand-written corpus with extra steps.
3. Typecheck your examples. An example that does not compile against the
   current API is worse than no example.
4. Serve it over MCP. llms.txt is for crawlers; a live endpoint is for the
   agent in the editor, mid-task.
5. Make failures structured. The agent will get it wrong; the framework's
   job is to say exactly what and where, in a shape a program can act on.

The pieces are independently useful, but the compounding effect comes from all five: the agent reads true docs, writes against true types, verifies against real rules, and fixes what it got wrong - against your current release, not your training-data ghost.

Try it

Add https://mcp.nifra.dev to your MCP client and ask it something specific about Nifra - then scaffold an app with bunx create-nifra and watch the verification loop run. Setup for each client is on the agents page. If you maintain a framework and want to compare notes on any of this, the repo is open.