feat(docs): add x-mcp-tools header to specify available tools - #6788
feat(docs): add x-mcp-tools header to specify available tools#6788Barbapapazes wants to merge 1 commit into
Conversation
📝 WalkthroughWalkthroughAdds an MCP server handler that reads the Estimated code review effort: 3 (Moderate) | ~20 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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: 3
🧹 Nitpick comments (1)
docs/server/mcp/index.ts (1)
3-24: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd coverage for the header contract.
Add tests for absent, empty, whitespace-only, duplicate, selected, and unknown tool names. Assert the exact returned tools and the HTTP 400 response.
🤖 Prompt for 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. In `@docs/server/mcp/index.ts` around lines 3 - 24, Add tests covering the MCP handler’s x-mcp-tools contract around tools: verify absent, empty, whitespace-only, duplicate, and selected tool names return the exact expected tool lists, and verify unknown names produce an HTTP 400 response with the expected error. Reuse the existing handler and tool-name helpers or test fixtures rather than changing production behavior.
🤖 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 `@docs/content/docs/1.getting-started/7.ai/1.mcp.md`:
- Line 61: Update the X-MCP-Tools documentation sentence to state that selecting
specific tool names reduces the tool context sent to the assistant, replacing
the inaccurate reference to context defined in the assistant.
- Line 65: Update the code fence in the MCP documentation section to use the
json language tag on its opening fence, preserving the existing fenced content.
In `@docs/server/mcp/index.ts`:
- Around line 27-38: Update getToolName() to convert _meta.filename using the
MCP toolkit’s filename-to-name conversion, preserving kebab-case names such as
search-icons instead of only stripping .ts and lowercasing. Keep the existing
tool.name preference and ensure the fallback matches the toolkit’s generated
names for X-MCP-Tools.
---
Nitpick comments:
In `@docs/server/mcp/index.ts`:
- Around line 3-24: Add tests covering the MCP handler’s x-mcp-tools contract
around tools: verify absent, empty, whitespace-only, duplicate, and selected
tool names return the exact expected tool lists, and verify unknown names
produce an HTTP 400 response with the expected error. Reuse the existing handler
and tool-name helpers or test fixtures rather than changing production behavior.
🪄 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 Plus
Run ID: 7fac1ab8-105e-4a7e-9418-b1c06c5113ac
📒 Files selected for processing (2)
docs/content/docs/1.getting-started/7.ai/1.mcp.mddocs/server/mcp/index.ts
|
|
||
| ## Limit available tools | ||
|
|
||
| Set the optional `X-MCP-Tools` HTTP header to a comma-separated list of tool names to expose only the tools your assistant needs. This helps to reduce the context defined in your assistant. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Clarify the context reduction.
context defined in your assistant does not describe the behavior. The handler reduces the tool context sent to the assistant.
Proposed wording
-This helps to reduce the context defined in your assistant.
+This helps to reduce the tool context sent to your assistant.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Set the optional `X-MCP-Tools` HTTP header to a comma-separated list of tool names to expose only the tools your assistant needs. This helps to reduce the context defined in your assistant. | |
| Set the optional `X-MCP-Tools` HTTP header to a comma-separated list of tool names to expose only the tools your assistant needs. This helps to reduce the tool context sent to your assistant. |
🤖 Prompt for 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.
In `@docs/content/docs/1.getting-started/7.ai/1.mcp.md` at line 61, Update the
X-MCP-Tools documentation sentence to state that selecting specific tool names
reduces the tool context sent to the assistant, replacing the inaccurate
reference to context defined in the assistant.
|
|
||
| Use the exact kebab-case MCP tool names, for example: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add a language tag to the code fence.
Use json on the opening fence. This fixes the MD040 warning and enables syntax highlighting.
Proposed fix
-```
+```json📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.23.1)
[warning] 65-65: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for 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.
In `@docs/content/docs/1.getting-started/7.ai/1.mcp.md` at line 65, Update the
code fence in the MCP documentation section to use the json language tag on its
opening fence, preserving the existing fenced content.
Source: Linters/SAST tools
| function getAvailableToolNames(tools: Awaited<ReturnType<typeof getMcpTools>>) { | ||
| const names = new Set<string>() | ||
|
|
||
| for (const tool of tools) { | ||
| const name = getToolName(tool) | ||
| if (name) { | ||
| names.add(name) | ||
| } | ||
| } | ||
|
|
||
| return names | ||
| } |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
rg -n -C 8 'defineMcpTool|name\s*:' --glob '*.ts' --glob '*.vue' .
rg -n -C 3 'search-components|search-composables|search-icons|get-component|get-component-metadata|search-documentation|get-documentation-page|list-templates|get-template|list-examples|get-example|get-migration-guide|getToolName|_meta.*filename' .Repository: nuxt/ui
Length of output: 50364
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Focus only on the MCP docs file and the surrounding implementation.
printf '--- docs/server/mcp/index.ts ---\n'
wc -l docs/server/mcp/index.ts
cat -n docs/server/mcp/index.ts
printf '\n--- exact getToolName definitions/usages ---\n'
rg -n -C 4 'function getToolName|const getToolName|getToolName|defineMcpTool|_meta.*filename|filename' docs/server/mcp src docs --glob '!**/node_modules/**' --glob '!**/.nuxt/**' | m
printf '\n--- target tool names ---\n'
rg -n -C 3 'search-icons|search-components|search-composables|get-component|get-component-metadata|search-documentation|get-documentation-page|list-templates|get-template|list-examples|get-example|get-migration-guide' docs/src src docs --glob '!**/node_modules/**' --glob '!**/.nuxt/**' | head -n 300
printf '\n--- package/toolkit references ---\n'
rg -n -C 3 '`@nuxt`[\S]*mcp|mcp-tool|defineMcpTool|mcp' package.json pnpm-lock.yaml yarn.lock package-lock.json --glob '!**/node_modules/**' | head -n 200Repository: nuxt/ui
Length of output: 236
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- docs/server/mcp/index.ts ---'
wc -l docs/server/mcp/index.ts
cat -n docs/server/mcp/index.ts
printf '%s\n' ''
printf '%s\n' '--- exact getToolName definitions/usages ---'
rg -n -C 4 'function getToolName|const getToolName|getToolName|defineMcpTool|_meta.*filename|filename' docs/server/mcp src docs --glob '!**/node_modules/**' --glob '!**/.nuxt/**' | m || true
printf '%s\n' ''
printf '%s\n' '--- target tool names ---'
rg -n -C 3 'search-icons|search-components|search-composables|get-component|get-component-metadata|search-documentation|get-documentation-page|list-templates|get-template|list-examples|get-example|get-migration-guide' docs/src src docs --glob '!**/node_modules/**' --glob '!**/.nuxt/**' | head -n 300 || true
printf '%s\n' ''
printf '%s\n' '--- package/toolkit references ---'
rg -n -C 3 '`@nuxt`[\S]*mcp|mcp-tool|defineMcpTool|mcp' package.json pnpm-lock.yaml yarn.lock package-lock.json --glob '!**/node_modules/**' | head -n 200 || trueRepository: nuxt/ui
Length of output: 13606
🌐 Web query:
@nuxtjs/mcp-toolkit 0.18.0 filename fallback underscore canonical tool name
💡 Result:
In @nuxtjs/mcp-toolkit, tool names are automatically derived from their filenames [1][2]. Specifically, the filename is converted to a kebab-case name (e.g., list-documentation.ts becomes list-documentation) [1]. While older or alternative naming conventions might use underscores (such as the legacy behavior mentioned in some Nuxt blog content where list-documentation-pages.ts becomes list_documentation_pages) [2], the official, current documentation specifies that the filename automatically becomes the name in kebab-case [1]. There is no "filename fallback" mechanism that defaults to using underscores as a primary canonical tool name; rather, kebab-case is the standard behavior for automatic name generation [1]. Users can always override the auto-generated name by explicitly providing a name property in the defineMcpTool configuration [1]. [1][2]
Citations:
🌐 Web query:
site:mcp-toolkit.nuxt.dev tools/overview filename kebab-case @nuxtjs/mcpp-toolkit``
💡 Result:
In the @nuxtjs/mcp-toolkit, filenames in the server/mcp/tools/ directory are automatically used to derive the tool's name and title [1][2]. Specifically, the toolkit applies the following conventions: - The tool name is generated as the kebab-case version of the filename (e.g., a file named list-documentation.ts results in a tool name of 'list-documentation') [1][2]. - The tool title is generated in Title Case based on the filename (e.g., 'List Documentation') [1][2]. While these values are auto-generated by default, you can explicitly define the name or title within the defineMcpTool function to override these automatic values [1][2]. Additionally, if you organize files in subdirectories within server/mcp/tools/, the toolkit will use the directory structure to automatically infer a group for the tools [1][3][4].
Citations:
- 1: https://mcp-toolkit.nuxt.dev/tools/overview
- 2: https://mcp-toolkit.nuxt.dev/llms-full.txt
- 3: https://mcp-toolkit.nuxt.dev/advanced/listing-definitions
- 4: https://mcp-toolkit.nuxt.dev/tools/groups-organization
🌐 Web query:
@nuxtjs/mcp-toolkit 0.18.0 github _meta filename kebab-case
💡 Result:
In the @nuxtjs/mcp-toolkit (version 0.18.0), the library automatically generates MCP tool names and titles based on the filename of the tool definition file [1][2]. When you define a tool in a file such as server/mcp/tools/list-documentation.ts, the following rules apply: - The filename is automatically converted to kebab-case to determine the tool name (e.g., list-documentation.ts becomes name: 'list-documentation') [1][2]. - The filename is converted to title case to determine the tool title (e.g., list-documentation.ts becomes title: 'List Documentation') [1][2]. This automatic generation happens by default, but you can override these values by explicitly providing name or title properties within your defineMcpTool definition [1][2]. Additionally, the toolkit uses an internal _meta object to store organizational data such as group and tags [2][3]. While you can manually attach metadata to _meta for specific purposes—such as in MCP Apps [4]—the group and tags properties are automatically inferred from the directory structure or set explicitly on the definition object to support filtering and discovery within the protocol [5][3].
Citations:
- 1: https://mcp-toolkit.nuxt.dev/tools/overview
- 2: https://mcp-toolkit.nuxt.dev/llms-full.txt
- 3: https://mcp-toolkit.nuxt.dev/tools/groups-organization
- 4: https://mcp-toolkit.nuxt.dev/advanced/mcp-apps-internals
- 5: https://mcp-toolkit.nuxt.dev/advanced/listing-definitions
Use the MCP toolkit’s filename-to-name conversion in the fallback.
@nuxtjs/mcp-toolkit 0.18.0 derives filenames such as search-icons.ts under docs/server/mcp/tools/ as kebab-case (search-icons) for tool.name. getToolName() should apply the same conversion to _meta.filename instead of only removing .ts and lowercasing, so documented tools remain usable from X-MCP-Tools.
🤖 Prompt for 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.
In `@docs/server/mcp/index.ts` around lines 27 - 38, Update getToolName() to
convert _meta.filename using the MCP toolkit’s filename-to-name conversion,
preserving kebab-case names such as search-icons instead of only stripping .ts
and lowercasing. Keep the existing tool.name preference and ensure the fallback
matches the toolkit’s generated names for X-MCP-Tools.
commit: |
1 participant
🔗 Linked issue
fix #6761
❓ Type of change
📚 Description
Hello 👋,
This PR introduces a new header for the MCP API that allows users to limit the available tools exposed to their assistant. By setting the
X-MCP-ToolsHTTP header to a comma-separated list of tool names, users can reduce the tool context sent to their assistant.📝 Checklist