Answer questions about Data Hub through the MCP server

[wasimxyz]

What this does

An AI assistant connected to the Data Hub MCP server can now answer how-to questions about Data Hub itself, using the docs that ship with that deployment.

• search_docs(query) returns up to five matching sections from the docs pages and the changelog. Each result has a short excerpt, a page ID, and a link to cite. When nothing matches, it returns the list of all docs pages and tells the agent to offer send_feedback for the gap.
• read_doc(page, section?) returns one page or one section as Markdown. No tool returns all the docs at once, and the longest page is about 18,000 characters.
• datahub://docs/{page} is a resource template that lists the 26 docs pages (not the changelog) and autocompletes page IDs, for clients where people attach context by hand.
• Server instructions are rewritten from 2.2 KB to 1.6 KB. Claude Code keeps only the first 2 KB, so the old feedback guidance was cut off there. The text now says what Data Hub is and points how-to questions at search_docs. A unit test fails if it grows past 2,048 bytes. datahub://glossary stays, but the instructions no longer point to it, because most clients cannot read resources on their own.

Why tools and not only resources: in claude.ai, Claude Desktop, VS Code, and ChatGPT, the model cannot read a resource by itself, and the MCP specification says model-controlled access should use tools. The resource template is there for people who attach pages by hand.

How the docs get into the web app

Each deployment answers from its own docs, so the pages are bundled with the web app:

• docs/site/scripts/generate-docs-corpus.ts writes web/lib/mcp/docs/docs-corpus.snapshot.json using the same Markdown the site serves at /docs/<page>.md.
• make docs-catalogs runs it last. docs-lint.yml regenerates it and fails when the committed copy differs, like the other generated files.
• It includes the hand-written pages, including cli-reference, mcp, and api (the overview). It leaves out the generated API endpoint pages, the MCP catalog pages, and docs/developer/.
• The docs package becomes an ES module package ("type": "module") and gains tsx, because Fumadocs can only load the site's MDX outside Next.js that way. The docs site's typecheck, lint, link check, and production build all still pass.
• Search uses minisearch (new dependency in web/), with no embeddings, extra service, or API key.

Analytics

mcp_docs_search records only a result-count bucket, and mcp_docs_read records only a page ID that resolved against the bundle. Query text is never recorded, per the rule in web/lib/analytics/track.ts. A rising share of empty searches shows where the docs have gaps.

Testing

• 21 golden questions in web/tests/unit/mcp-docs-search.test.ts, each with the page that should answer it, which must be in the top three results. I checked they can fail: turning off stop-word removal broke four of them.
• Unit tests for section splitting, plain-text conversion, excerpts, and page references. Protocol tests for both tools and the resource template. Analytics tests. A test that every page fits in one tool result under Claude Code's 25,000-token cap.
• The MCP integration suite now calls both tools against a real next build and next start, which proves the bundle and the changelog files ship with the app. mcp.test.ts and mcp-oauth.test.ts pass (37 tests), the unit suite passes (550 tests), and make check passes.
• A clean npm ci followed by make docs-catalogs leaves no changes, so CI's drift check will pass.

Excerpt from a recorded session over HTTP against the production build

== search_docs("how do I revoke a token") ==
- manage-tokens#revoke-a-token
    url: …/docs/manage-tokens#revoke-a-token
    Go to Settings → Access Tokens. Click the delete icon on the token’s row and confirm. The token stops working immediately. …
- manage-tokens
- security#token-hygiene
- security#how-tokens-act
- concepts#personal-access-token

== search_docs("zxqv plorgnak"): nothing matches ==
results: 0, pages listed: 26
hint: Nothing matched. Pick a page from `pages` and call read_doc, or try different words. If the docs do not cover the question, say so and offer to report the gap with send_feedback.

== read_doc(page="manage-token"): a wrong page ID ==
isError: true
Page 'manage-token' not found. Closest: manage-tokens. Docs pages: overview, self-hosting, …

Notes for reviewers

• The plan said 29 docs pages. The site has 29, but three are the generated MCP catalogs, which are left out, so the bundle and the resource list have 26.
• Changelog entries have no page of their own in the app (the changelog is a dialog), so their link is the entry's own docs link, or none.
• Docs-only changes now also change a file under web/, so the web app's Vercel project rebuilds for them. That is intended: the deployed MCP server has to carry the new text.
• Postgres and uv were missing on the VM I used, so I installed them to run the integration tests and make check.

  

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
data-hub	Ready	Preview	Oct 9, 2026 6:22pm UTC
data-hub-docs	Ready	Preview	Oct 9, 2026 6:22pm UTC