fix(mcp): resolve legacy documentation paths and update tool examples#2268
fix(mcp): resolve legacy documentation paths and update tool examples#2268santiagodeheza wants to merge 2 commits into
Conversation
The get_documentation_page MCP tool advertised Nuxt 3-era directory structure URLs that 404 in queryCollection lookups. nuxt.com already redirects those paths in the browser, but MCP fetches content by path directly. - Add resolveDocumentationPath() mirroring directory-structure redirects - Apply resolution in fetchPageMarkdown for all MCP doc fetches - Update COMMON PAGES and inputExamples to Nuxt 4 paths Co-authored-by: Cursor <cursoragent@cursor.com>
|
@santiagodeheza is attempting to deploy a commit to the Nuxt Team on Vercel. A member of the Team first needs to authorize it. |
|
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 (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughThis PR adds a documentation path resolver to the MCP tools service. A new Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@server/utils/mcp.ts`:
- Around line 34-37: The variable `resolved` in the `server/utils/mcp.ts`
snippet is never reassigned, so change its declaration from `let resolved =
path.replace(...)` to use `const resolved = path.replace(...)` to satisfy lint
rules and reflect intent; locate the `resolved` assignment that applies the
regex /^(... )\/guide\/directory-structure$/ and update the `let` to `const`
there.
- Around line 56-59: The current branch that checks topLevel from rest and
APP_SCOPED_DIRECTORIES builds `${prefix}/directory-structure/app/${rest}` which
produces `.../app/app` when rest === 'app'; change the logic in that branch (the
block using topLevel, APP_SCOPED_DIRECTORIES, rest and prefix) to special-case
rest === 'app' and return `${prefix}/directory-structure/app` for that case,
otherwise return `${prefix}/directory-structure/app/${rest}` so you don't
duplicate "app".
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: c4f483ab-2aa4-4d59-b837-e77564ff6081
📒 Files selected for processing (2)
server/mcp/tools/docs/get-documentation-page.tsserver/utils/mcp.ts
2 participants
Summary
The official Nuxt MCP server at
https://nuxt.com/mcpreturns 404 for several paths listed in theget_documentation_pagetool description — most notably Nuxt 4 directory-structure pages.Root cause: The tool's
COMMON PAGESexamples still use Nuxt 3-era URLs (/docs/4.x/guide/directory-structure/composables, etc.). The nuxt.com site already redirects those URLs in the browser (nuxt.config.tsrouteRules), but MCP resolves documentation viaqueryCollection(event, collection).path(path)and does not follow HTTP redirects.This causes AI assistants to fail when they trust the MCP tool metadata or Nuxt 3 muscle memory, even though
list_documentation_pagesreturns the correct paths.Changes
resolveDocumentationPath()inserver/utils/mcp.ts— maps legacyguide/directory-structure/*paths to current content paths (mirroring existing route redirects; includesapp/segment for Nuxt 4+ app dirs).fetchPageMarkdown()— applies path resolution before every content lookup, so all MCP doc tools benefit.get-documentation-page.ts— updatesCOMMON PAGES,inputExamples, and guidance to Nuxt 4 canonical paths (/docs/4.x/directory-structure/app/*).Reproduction (before fix)
get_documentation_page({ path: "/docs/4.x/guide/directory-structure/composables" }) → 404 Documentation page not found get_documentation_page({ path: "/docs/4.x/directory-structure/app/composables" }) → ✅ returns content list_documentation_pages({ version: "4.x", search: "composables" }) → ✅ returns correct path (catalog was already fine)Also broken in tool metadata:
/docs/4.x/guide/going-further/error-handling→ should be/docs/4.x/getting-started/error-handlingTest plan
get_documentation_pagewith legacy path/docs/4.x/guide/directory-structure/composablesreturns composables docget_documentation_pagewith canonical path/docs/4.x/directory-structure/app/composablesstill worksget_documentation_pagewith/docs/4.x/guide/going-further/error-handlingresolves to getting-started error-handling pagedirectory-structure/app/*pathsMade with Cursor