Reduce to a thin Next.js dev server connector#145
Open
gaojude wants to merge 3 commits into
Open
Conversation
Remove the docs-search tool, the init tool, the upgrade/Cache Components tools and their prompts, and all knowledge-base resources. Documentation now ships with Next.js itself (node_modules/next/dist/docs/) and workflows are distributed as agent skills, so the server is now tools-only: nextjs_index, nextjs_call, and browser_eval.
Instead of fetching docs over the network, nextjs_docs now detects the project's installed Next.js version and points the agent at the docs bundled in node_modules/next/dist/docs/ (Next.js 16+), or recommends the upgrade codemod for older projects. It enables agents to read version-accurate docs themselves rather than doing the search.
gaojude
force-pushed
the
jude/thin-wrapper-deprecate-docs-prompts
branch
from
4a326b9 to
17a8d81
Compare
Instead of spawning and proxying @playwright/mcp, browser_eval now detects whether the agent-browser CLI is installed and returns install/usage guidance (npm install -g agent-browser / agent-browser skills get core --full), so the agent drives the native CLI directly. Removes the now-unused browser-eval manager and external MCP client.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reduces the server to a thin connector to the Next.js dev server, since Next.js now ships its own docs.
nextjs_docsis kept but no longer fetches anything. It is now a version-aware gateway: it detects the project's installed Next.js version and, on 16+, points the agent at the docs bundled innode_modules/next/dist/docs/(which match the installed version and are surfaced throughAGENTS.md); on older projects it recommendsnpx @next/codemod@latest upgrade latest. This keeps the docs entry point agents already know while letting them read version-accurate docs themselves. Thenextjs-docs://llms-indexresource is removed.browser_evalis also now a gateway. Instead of spawning and proxying@playwright/mcp, it detects whether theagent-browserCLI is installed and returns install/usage guidance (npm install -g agent-browser/agent-browser skills get core --full), so the agent drives the native CLI directly. The orphaned browser-eval manager and external MCP client are removed.Removed: the
inittool (it only enforced the old docs-fetch workflow), theupgrade_nextjs_16andenable_cache_componentstools and their prompts (thin wrappers over prompts; the workflows move to distributable agent skills), and allcache-components:///nextjs16:///nextjs-fundamentals://resources. The server now declares only thetoolscapability — no prompt or resource handlers — and the build no longer copies markdown (scripts/copy-resources.jsremoved).What remains:
nextjs_docs(gateway),nextjs_index(discover dev servers),nextjs_call(proxy/_next/mcp),browser_eval(gateway). README and CLAUDE.md are rewritten with a Migrating from 0.3.x section; version bumped to 0.4.0.This is a breaking change: callers of the removed tools (including agent configs wired to call
initfirst) will getTool not found.Validation
Typecheck, build, 25 unit tests, and 8 e2e tests pass. The e2e registration test asserts the surface is exactly the four tools with no prompts or resources.
The gateway design was also validated end-to-end with a real headless Claude Code session (
claude -pwith--mcp-config) against a throwaway project containing a realnext@16.2.9install (422 bundled doc files):nextjs_docs: the agent called the tool, received{status: use_bundled_docs, nextVersion: 16.2.9, docsAvailable: true}, then followed the guidance — ran the suggestedgrepovernode_modules/next/dist/docs, read the real bundled caching guide, and answered version-accurately (Cache Components,use cache,cacheLife/cacheTag) rather than from training data.browser_eval: both branches confirmed in the agent loop — withagent-browseron PATH it returneduse_agent_browserplus the CLI steps; withagent-browsermasked from PATH it returnedinstall_requiredplus thenpm install -g agent-browser/agent-browser installsteps.This confirms the gateway indirection (tool points → agent self-serves) produces correct behavior in a real agent loop. Spawned MCP servers inherit the session's project directory as cwd, so the gateway's version/CLI detection resolves against the right project.
The matching Next.js docs update (#94859) lands with the 0.4.0 release.