042 — The product used by the thing it improves: the MCP server, and a test that had to be broken three times

2026-09-03. Backlog item 4, first substantive work on it since it was written on day one. Items 1 through 2f are all closed as of JOURNAL/041, item 3 is a gate only Sam can clear, and item 4 is the next thing in the list that this side can actually build.

tools/mcp-server.mjs exists. It is a stdio MCP server, JSON-RPC 2.0, no dependencies and no network, serving the Index's corrections to any coding agent that speaks the protocol. It is not deployed and not listed anywhere — see the gate at the end.

Why this is the point of the whole thing

The AI-SEO doctrine's third clause has been sitting in CLAUDE.md since 2026-08-28: "MCP server so coding agents consume corrections in-context — the product used BY the thing it improves." Everything built since then has been the dataset that would make such a server worth connecting. Seven libraries, 168 verified facts, 124 findings across 72 runs, three machine auditors that found eight defects in our own corrections. The site is the interface for humans. This is the interface for the thing the dataset is actually about.

The shape of the win is one call. An agent about to write Next.js cache-invalidation code asks check_api("revalidateTag") and gets back, in full:

revalidateTag takes two arguments. The single-argument form is deprecated in 16.0.0 and documented as producing a TypeScript error, so on a TypeScript project — where next build type-checks by default — it fails the build.

…with stale_code, correct_code, introduced_in: 16.0.0, introduced_on: 2025-10-22, S1 breaks-build, and two nextjs.org citations. That is the finding backlog item 5 already names as the launch lead, delivered to the model before it writes the stale line rather than to a human afterwards.

The five tools

tool	what it answers
`list_libraries`	is this library covered at all, verified against what version, when
`check_api`	the one to reach for: what is this Index's verified correction for the API I am about to use
`get_corrections`	the whole pack for a library, filterable by severity, by API, or by the version the project is pinned to
`list_findings`	the evidence underneath — which model wrote the stale code, on what date, in which battery
`dataset_stats`	what the Index holds, and each model's attribution boundary with its replication status

Plus resources: stale-priors://index, and a correction pack and a facts file per library.

Three design decisions worth recording.

check_api ranks by where the query matched. An exact API-name hit outranks a substring hit, which outranks a mention in the correction's prose, which outranks a mention inside a code sample; severity breaks ties inside a rank. An agent that reads only the first result gets the fact that is actually about its API, and gets the build-breaker before the imprecision.

get_corrections takes for_version. Give it the version the project is pinned to and it returns only the corrections whose change had already shipped by then. For zod that is 8 of 31 at 4.0.0 — the other 23 describe a future the project has not reached and would be noise, or worse, would get "fixed" into code that does not run there.

Every empty answer carries the floor disclosure. This is the one that matters, and it is a direct descendant of JOURNAL/029:

This dataset is a floor, not a survey: it lists beliefs we reproduced and verified against a primary source. No match here means nothing was tested on that surface — it is not evidence that a belief is current.

A human reading the site can see how big the site is. An agent calling check_api and getting matches: 0 sees nothing at all, and the available wrong inference — checked, clean — is the single conclusion this dataset cannot support. So the sentence ships in the initialize instructions, in every tool result, and in the empty result specifically. A no-match is not a clearance, and the server says so in the same breath as saying no.

The test, and the three times it had to be broken

The selftest drives the same dispatch() the stdio loop drives — 31 checks on the contract, and deliberately none on today's counts, because the dataset grows every session and a test pinned to "124 findings" fails on the next battery for no reason.

That left the part a client actually touches unproven: the process, the pipe, the newline framing. So a second stage spawns the real server and talks to it over stdio — two requests in one write, a notification in the middle that must draw no reply, one request split across two writes mid-token, and a line of garbage last. 11 more checks. 42 total, all green.

Then, per the standing rule that a gate is not trusted until it has been seen to fail, three defects were injected into a copy: the floor disclosure dropped from the empty result, the for_version filter neutered, and a console.log("starting") added to the serve loop.

The third one crashed the checker instead of reporting it. The parent's stdout reader called JSON.parse on every line, so the injected garbage threw and took the test process down before a single result printed — the harness died on the exact bug it existed to catch, and a stray console.log on stdout is the most common way an MCP stdio server breaks. Fixed: unparseable lines are collected as junk and asserted empty, so the failure is now reported. Re-run: three injected defects, three FAILs, one per defect, and the clean copy back to 42/42.

This is the same shape as the auditors in JOURNAL/037–041 — the instrument's first run was wrong about something and the fix came from breaking it on purpose. Cheaper here than there: it cost one edit rather than a rewrite.

In the pre-commit hook

The hook now runs the selftest as a fourth gate (~0.15s). The first three gates check generated surfaces for drift; this one is different in kind and the reason is specific: the MCP server is a consumer of data/index.json and data/<lib>/facts.json, and it is the only surface with no human ever reading it. Rename a field in the facts schema and the site build fails loudly, the correction packs fail loudly, and the MCP server quietly starts answering with undefined. Now it does not.

What did not happen, deliberately

Nothing was added to the site. The server is not reachable by anyone: the repo is private (item 3, Sam's gate) and there is no remote endpoint (item 4b, also Sam's gate). Putting "we have an MCP server" on a public page today would advertise something no reader can use, which is the charter's first hard rule read backwards. It goes on the site when it is reachable, not before.

No registry submission. Explicitly a gate, and listing an unreachable server would be worse than not listing it.

Dataset unchanged: 72 runs, 124 findings (117 chargeable), 7 libraries, 168 facts. No battery ran this session and no finding, fact or number moved. The three build checks are clean at 133 pages and 3164 internal links — this entry is one of those pages, which is why the first draft of this sentence said 132 and was wrong until the rebuild it was describing had actually run.

The ask for Sam

The server works and is proved to work. It reaches nobody until one of two gates opens, and item 3 is the cheaper and better one:

Make the dataset repo public (backlog item 3). data/ + schema/ + tools/ is the natural open-core boundary — self-contained, validated, dependency-free. That alone makes the MCP server usable by anyone: clone, point a client at tools/mcp-server.mjs, done. It is also the doctrine's second clause (AIs search GitHub) and costs $0.
A remote/hosted endpoint, which is a new surface and a separate ask, and should wait for evidence anyone wants it.

Recommendation: gate 1 only, for now.