Add MCP server to valibot.dev#1550
Conversation
Provide a Model Context Protocol server at https://valibot.dev/mcp so that coding agents can search and read the documentation with tools instead of crawling the website: - Implement a stateless Streamable HTTP MCP server in the Worker with the tools search_docs, get_doc, and list_docs, validated with Valibot and with input schemas generated via @valibot/to-json-schema - Generate a search index from the documentation at build time and cache it in isolate memory with precomputed lowercase fields - Publish an MCP server card at /.well-known/mcp/server-card.json with constants shared between the Worker and the build script, and list the server in the API catalog, llms.txt, and the hidden HTML hint - Rename the LLMs.txt guide to the more general "Coding agents" guide, document the MCP server there, move it after the installation guide, and redirect the old URLs - Split the Worker into focused modules (routing, Markdown negotiation, header utilities, shared docs knowledge) and fix review findings (304 handling, JSON-RPC edge cases, trailing slash support, capped suggestion scans)
dosubot
Bot
added
size:XXL
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (4)
🚧 Files skipped from review as they are similar to previous changes (3)
WalkthroughThe website now generates a documentation search index and MCP server card, serves Markdown documentation through content negotiation, and exposes a stateless MCP endpoint with search, retrieval, and listing tools. Worker routing and static-asset configuration handle MCP requests. New coding-agent documentation, catalog metadata, redirects, navigation entries, and accessibility text describe the available MCP, Markdown, and LLMs.txt resources. Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
commit: |
There was a problem hiding this comment.
Pull request overview
Adds a first-class MCP (Model Context Protocol) server endpoint to valibot.dev and expands the existing “docs-for-agents” surface (Markdown negotiation, discovery artifacts, and indexing) so coding agents can search/list/read docs via tools instead of crawling HTML.
Changes:
- Adds a stateless JSON-RPC MCP server at
/mcpwithsearch_docs,get_doc, andlist_docstools backed by a build-generatedsearch-index.json. - Refactors the Cloudflare Worker into focused modules (
docs,headers,markdown,mcp,mcp-info) and wires/mcprouting + doc markdown negotiation. - Renames the “LLMs.txt” guide to “Coding agents”, updates navigation/links, and adds redirects + discovery entries (API catalog + server card).
Reviewed changes
Copilot reviewed 20 out of 21 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| website/wrangler.jsonc | Routes /mcp and /mcp/ through the Worker. |
| website/worker/index.ts | Adds /mcp handling and keeps Markdown negotiation + discovery headers for docs pages. |
| website/worker/mcp.ts | Implements the MCP Streamable HTTP JSON-RPC server and the three tools. |
| website/worker/mcp-info.ts | Centralizes MCP constants shared by Worker runtime and build scripts. |
| website/worker/markdown.ts | Extracts Markdown negotiation + .md serving with caching/ETag preservation. |
| website/worker/headers.ts | Adds merge-aware header utilities used by Worker responses. |
| website/worker/docs.ts | Defines doc areas, path regex, search index entry type, and URL helpers. |
| website/src/routes/guides/menu.md | Updates guides menu to include “Coding agents” and remove “LLMs.txt”. |
| website/src/routes/guides/(get-started)/llms-txt/index.mdx | Removes the old LLMs.txt guide page. |
| website/src/routes/guides/(get-started)/coding-agents/index.mdx | Adds the new “Coding agents” guide covering MCP + LLMs.txt + negotiation + skill. |
| website/src/routes/blog/(posts)/why-migrate-to-valibot/index.mdx | Updates internal link from /guides/llms-txt/ to /guides/coding-agents/. |
| website/src/root.tsx | Updates the hidden agent hint to mention the MCP server at /mcp. |
| website/scripts/utils/transformTextSegments.ts | Adds helper to transform Markdown text while preserving fenced code blocks. |
| website/scripts/utils/index.ts | Re-exports the new transformTextSegments utility. |
| website/scripts/llms.ts | Generates public/search-index.json and refactors MDX→MD transforms to reuse transformTextSegments. |
| website/scripts/agents.ts | Generates /.well-known/mcp/server-card.json from shared constants at build time. |
| website/public/.well-known/api-catalog.json | Adds MCP server entry to the API catalog linkset. |
| website/public/_redirects | Adds 301 redirects from /guides/llms-txt* to /guides/coding-agents* (including .md). |
| website/package.json | Adds @valibot/to-json-schema dependency for tool JSON Schema generation. |
| website/.gitignore | Ignores generated MCP/server-card and search index outputs under public/. |
| pnpm-lock.yaml | Locks the added workspace dependency and updates package metadata. |
Files not reviewed (1)
- pnpm-lock.yaml: Generated file
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9649f47665
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed across 21 files
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
- Reject requests with an unsupported MCP-Protocol-Version header with status 400 as required by the specification - Validate the type of JSON-RPC message IDs and never echo IDs of an invalid type back to the client - Extend the MCP server card with the fields of the evolving SEP-1649 draft (name, version, repository, remotes) while keeping the fields of the original proposal for older consumers - Add redirects of the renamed coding agents guide to vercel.json to keep Vercel deployments in sync with Cloudflare - Hyphenate "type-safe" in the MCP instructions and card description
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: eedf6ce12f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| input: v.InferOutput<typeof SearchDocsSchema> | ||
| ): { entry: IndexedEntry; score: number }[] { | ||
| // Split query into lowercase search terms | ||
| const terms = input.query.toLowerCase().split(/\s+/).filter(Boolean); |
There was a problem hiding this comment.
When a client searches for the documented Valibot spelling like v.string, v.pipe, or v.minLength (the server instructions use this namespace form), the query remains a single term such as v.string, so it does not match index names/titles like string and pipe and search_docs can return no results for common API lookups. Strip a leading v. or tokenize punctuation before scoring so the MCP search works with the API names users and agents actually see.
Useful? React with 👍 / 👎.
Summary
Adds a Model Context Protocol server at
https://valibot.dev/mcpso coding agents can search and read the documentation through first-class tools instead of crawling pages. This addresses the last substantive gap in the Mintlify agent score and isitagentready audits.MCP server (
website/worker/mcp.ts)initialize,ping,tools/list,tools/call, notifications, batches, CORS for browser-based clients, and protocol version negotiation (2025-06-18 / 2025-03-26).search_docs(ranked search over all 794 pages with API-name-first scoring),get_doc(full page Markdown; acceptsapi/string, full URLs, or bare names likeminLength, with typo suggestions on misses), andlist_docs(grouped overview).@valibot/to-json-schema(ignoreActions: ['trim']) — validation and declaration cannot drift.search-index.json, generated inscripts/llms.tsfrom the same source as the.mdmirrors) cached in isolate memory with precomputed lowercase fields. Deliberately not Algolia: results are always consistent with the deployed.mdfiles, and the endpoint has no third-party runtime dependency.Discovery
/.well-known/mcp/server-card.json(SEP-1649), generated at build time from constants shared with the Worker (worker/mcp-info.ts) so the card and the live handshake cannot diverge.llms.txt, and the visually hidden agent hint on every HTML page.Guide rename
guides/llms-txt→guides/coding-agents: a general page covering the MCP server (with Claude Code and Cursor setup snippets), the LLMs.txt routes, Markdown content negotiation, and the agent skill. Moved after the installation guide in the menu. Old URLs (HTML and.md) redirect with 301.Structure and robustness
index.ts(routing),markdown.ts(content negotiation),headers.ts(merge-aware header utilities),docs.ts(shared area/slug knowledge and theSearchEntrytype used by both the Worker and the generator),mcp-info.ts(shared MCP constants).id: nullrequests, empty batches, id preservation in batch errors),/mcp/trailing-slash support,#anchor/?querytolerance inget_docpaths, whitespace-only queries rejected viav.trim(),$schemastripped from tool schemas, and the typo-suggestion scan capped (maxLengthon inputs plus a prefix ceiling).Test plan
pnpm lint,pnpm format.check, andpnpm buildpasswrangler dev: handshake, all three tools, invalid arguments, unknown tool/method, parse errors, empty batch,id: null, trailing slash, CORS preflight, 405 on GET@modelcontextprotocol/sdkclient: connect, list tools, call all three tools.mdcaching headers (ETag/304), API catalog, and redirect regressions all re-verifiedSummary by CodeRabbit
/mcp)..mdURLs).