Issues with `nextjs_docs` and `nextjs-docs://llms-index`

[KnifeFed]

I'm having issues where the model (in this case, GPT 5.2 Codex in OpenCode) complains it can't get the Next.js docs index or llms-index. Here's the output:

Details

Thinking: Attempting to access Next.js docs
I’m trying to read the required nextjs-docs://llms-index resource via the read tool to comply with documentation access requirements, but previous attempts failed; I’ll retry
reading it directly to resolve this blocker before proceeding.

→ Read nextjs-docs://llms-index
Error: ENOENT: no such file or directory, scandir '<project_path>/nextjs-docs:' • biome

Thinking: Blocking on Next.js docs access

The Next.js docs tool and path access failed, so I can't retrieve necessary docs to proceed. I'll ask the user to confirm or provide access to the Next.js docs, then continue with non-blocked planning.

Blocker: the mandatory Next.js docs index isn’t accessible right now. I tried nextjs-docs://llms-index via the docs tool and Read, but both failed.

Me: Fetch the next-devtools-mcp README at https://raw.githubusercontent.com/vercel/next-devtools-mcp/refs/heads/main/README.md and tell me what you're having issues with.

% WebFetch https://raw.githubusercontent.com/vercel/next-devtools-mcp/refs/heads/main/README.md

Thinking: Highlighting docs tool usage mismatch

The main issue is that the tool was used with a nonexistent llms-index path, while the README specifies using nextjs_docs with action=search or get and a query instead of a
path. The init guidance demanding llms-index conflicts with this, causing fetch failures and NOT_FOUND errors; updating usage to align with README actions is needed.

Thinking: Detailing docs tool schema and usage conflicts

The nextjs_docs tool signature accepts only path and anchor, but the README requires action=search or get with queries, creating a schema mismatch. Also, the init step’s demand
to read nextjs-docs://llms-index is outdated and causes fetch failures and NOT_FOUND errors, since that resource doesn't exist. To fix this, updating to the latest MCP version
supporting search actions and verifying tool config and environment are recommended.

Here’s what I’m seeing from the README vs. what actually happened:

• The README says nextjs_docs is a two‑step tool (action: "search" then action: "get"). Our tool interface only accepts path/anchor, so it can’t run the documented search
  workflow.
• The README does not mention a nextjs-docs://llms-index resource. The only listed resources are cache-components://…, nextjs16://…, and nextjs-fundamentals://…. That makes the
  init requirement to read nextjs-docs://llms-index look outdated.
• Calls I tried:
  • nextjs_docs with path: "/llms-index" → NOT_FOUND
  • nextjs_docs with path: "nextjs-docs://llms-index" → fetch failed
  • Reading nextjs-docs://llms-index via Read → ENOENT (expected: Read can’t access MCP resources)

So the issue is a mismatch between the init tool’s enforced workflow and the current MCP server/README behavior.

Here's the model's explanation of the issue:

Details

nextjs_docs only accepts { path, anchor } and requires nextjs-docs://llms-index, but that MCP resource is not accessible here. The README still documents a search/get API that does not match the tool schema.

Repro

1. nextjs_docs({ action: "search", query: "generateMetadata", routerType: "app" }) -> Missing required argument: path
2. nextjs_docs({ path: "/llms-index" }) -> NOT_FOUND (instructs to read nextjs-docs://llms-index)
3. nextjs_docs({ path: "nextjs-docs://llms-index" }) -> fetch failed

Expected

Either the nextjs-docs://llms-index resource is available, or nextjs_docs supports the README search/get workflow.

Actual

Tool requires a path but the index resource is unreachable, so docs lookup is blocked.

Code reference

src/tools/nextjs-docs.ts defines path-only input and hard-depends on nextjs-docs://llms-index.

[KnifeFed]

Am I the only one having this issue? It keeps trying to fetch it like next-devtools_nextjs_docs [path=nextjs-docs://llms-index] which results in McpError: MCP error -32603: fetch failed, making the whole server useless.

[ShaunDychko]

Accept: text/markdown content negotiation double-prefixes /llm-digest/, returning "Page Not Found" for all docs

Description:

When requesting any docs page with Accept: text/markdown, the server rewrites to /docs/llm-digest/... but internally double-prefixes, producing a path like
/docs/llm-digest/llm-digest/app/... that doesn't exist. The response is HTTP 200 but contains a "Page Not Found" markdown body.

Steps to reproduce:

curl -s -H "Accept: text/markdown" "https://nextjs.org/docs/app/getting-started/installation"

Returns: # Page Not Found — The URL /docs/llm-digest/app/getting-started/installation does not exist.

Evidence of double-prefix:

curl -s -D - -o /dev/null -H "Accept: text/markdown" \
"https://nextjs.org/docs/app/getting-started/installation" 2>&1 | grep rewritten

Returns: x-nextjs-rewritten-path: /docs/llm-digest/llm-digest/app/getting-started/installation

Expected: Content from /docs/llm-digest/app/getting-started/installation (which works fine when fetched directly)

Workaround: Fetch https://nextjs.org/docs/llm-digest/app/getting-started/installation directly instead of using Accept: text/markdown on the canonical URL.

⏺ Here's the one-line fix in dist/tools/nextjs-docs.js, in the handler function:

Before:

  export async function handler({ path, anchor }) {                                                                                                                       
      // Fetch the documentation                                                                                                                                          
      const url = `https://nextjs.org${path}`;                                                                                                                            
      const response = await fetch(url, {                                                                                                                                 
          headers: {                                                                                                                                                      
              Accept: "text/markdown",
          },                                                                                                                                                              
      });                                                                                                                                                                 

After:

  export async function handler({ path, anchor }) {
      // Fetch the documentation via /llm-digest/ directly to avoid
      // broken Accept: text/markdown content negotiation (double-prefixes /llm-digest/)
      const digestPath = path.replace(/^\/docs\//, "/docs/llm-digest/");                                                                                                  
      const url = `https://nextjs.org${digestPath}`;                                                                                                                      
      const response = await fetch(url);     

The root cause is that nextjs.org's Accept: text/markdown content negotiation rewrites /docs/app/... to /docs/llm-digest/app/..., but the internal route handler at
/docs/llm-digest/[...slug] prepends /llm-digest/ again, producing /docs/llm-digest/llm-digest/app/... which doesn't exist. The fix bypasses content negotiation entirely
by fetching the /llm-digest/ URL directly.

Impact: Breaks the next-devtools-mcp@0.3.10 nextjs_docs tool, which relies on this content negotiation.