docs(mcp): consolidate tools and add icons search

Author: benjamincanac

docs/content/docs/1.getting-started/7.ai/1.mcp.md

@@ -26,24 +26,26 @@ You're able to access these resources with tools like Claude Code by using `@`.
 
 The Nuxt UI MCP server provides the following tools organized by category:
 
+### Search Tools
+
+- **`search_components`**: Search components by name, description, or category. With no params, lists all components
+- **`search_composables`**: Search composables by name or description. With no params, lists all composables
+- **`search_icons`**: Search for icons across Iconify collections (defaults to `lucide`). Returns icon names in the `i-{prefix}-{name}` format used by Nuxt UI
+
 ### Component Tools
 
-- **`list_components`**: Lists all available Nuxt UI components with their categories and basic information
-- **`list_composables`**: Lists all available Nuxt UI composables with their categories and basic information
 - **`get_component`**: Retrieves component documentation and details. Supports a `sections` parameter (`usage`, `examples`, `api`, `theme`, `changelog`) to fetch only specific parts and reduce response size
 - **`get_component_metadata`**: Retrieves detailed metadata for a component including props, slots, and events (lightweight, no documentation content)
-- **`search_components_by_category`**: Searches components by category or text filter
 
-### Template Tools
+### Documentation Tools
 
-- **`list_templates`**: Lists all available Nuxt UI templates with optional category filtering
-- **`get_template`**: Retrieves template details and setup instructions
+- **`search_documentation`**: Search documentation pages by title, description, or section. With no params, lists all pages. Use `section` to filter (e.g., `"getting-started"`, `"components"`)
+- **`get_documentation_page`**: Retrieves documentation page content by URL path. Supports a `headings` parameter to fetch only specific h2 sections (e.g., `["Usage", "API"]`) and reduce response size
 
-### Documentation Tools
+### Template Tools
 
-- **`list_documentation_pages`**: Lists all documentation pages
-- **`get_documentation_page`**: Retrieves documentation page content by URL path. Supports a `sections` parameter to fetch only specific h2 sections (e.g., `["Usage", "API"]`) and reduce response size
-- **`list_getting_started_guides`**: Lists all getting started guides and installation instructions
+- **`list_templates`**: Lists all available Nuxt UI templates with optional framework filtering
+- **`get_template`**: Retrieves template details and setup instructions
 
 ### Example Tools
 
@@ -340,6 +342,7 @@ Once configured, you can ask your AI assistant questions like:
 - "Show me just the Button usage examples"
 - "What props does Input accept?"
 - "Find form-related components"
+- "Search for arrow icons in lucide"
 - "List dashboard templates"
 - "Get template setup instructions"
 - "Show installation guide"
@@ -350,5 +353,5 @@ Once configured, you can ask your AI assistant questions like:
 The AI assistant will use the MCP server to fetch structured JSON data and provide guided assistance for Nuxt UI during development.
 
 ::tip
-For large documentation pages, the AI can use the `sections` parameter to fetch only relevant parts (like "Usage" or "API"), reducing response size and improving performance.
+For component docs, the AI can use the `sections` parameter (`usage`, `examples`, `api`, `theme`, `changelog`) to fetch only relevant parts. For other pages, use the `headings` parameter with h2 titles (e.g., `["Usage", "API"]`).
 ::

docs/server/mcp/tools/get-documentation-page.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
 
 export default defineMcpTool({
-  description: 'Retrieves documentation page content by URL path. Use the `sections` parameter to fetch only specific h2 sections to reduce response size.',
+  description: 'Retrieves documentation page content by URL path. Use the `headings` parameter to fetch only specific h2 sections to reduce response size.',
   annotations: {
     readOnlyHint: true,
     destructiveHint: false,
@@ -10,24 +10,23 @@ export default defineMcpTool({
   },
   inputSchema: {
     path: z.string().describe('The path to the content page (e.g., /docs/components/button)'),
-    sections: z.array(z.string()).optional().describe('Specific h2 section titles to return (e.g., ["Usage", "API"]). If omitted, returns full documentation.')
+    headings: z.array(z.string()).optional().describe('Specific h2 heading titles to extract (e.g., ["Usage", "API"]). If omitted, returns full page.')
   },
   inputExamples: [
-    { path: '/docs/components/button', sections: ['Usage', 'API'] },
+    { path: '/docs/components/button', headings: ['Usage', 'API'] },
     { path: '/docs/getting-started/installation' }
   ],
   cache: '30m',
-  async handler({ path, sections }) {
+  async handler({ path, headings }) {
     let content
     try {
       content = await $fetch<string>(`/raw${path}.md`)
     } catch {
       throw createError({ statusCode: 404, message: `Documentation page not found at path: ${path}` })
     }
 
-    // If sections are specified, extract only those sections
-    if (sections && sections.length > 0) {
-      content = extractSections(content, sections)
+    if (headings && headings.length > 0) {
+      content = extractSections(content, headings)
     }
 
     return content

docs/server/mcp/tools/list-components.ts

@@ -2,7 +2,7 @@ import { z } from 'zod'
 import { queryCollection } from '@nuxt/content/server'
 
 export default defineMcpTool({
-  description: 'Searches components by category or text filter',
+  description: 'Search components by name, description, or category',
   annotations: {
     readOnlyHint: true,
     destructiveHint: false,
@@ -44,7 +44,6 @@ export default defineMcpTool({
       links: component.links
     }))
 
-    // Apply search filter if provided
     if (search) {
       const searchLower = search.toLowerCase()
       results = results.filter(component =>

docs/server/mcp/tools/list-composables.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod'
+import { queryCollection } from '@nuxt/content/server'
+
+export default defineMcpTool({
+  description: 'Search composables by name or description',
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  inputSchema: {
+    search: z.string().optional().describe('Search term to filter composables by name or description')
+  },
+  inputExamples: [
+    {},
+    { search: 'toast' },
+    { search: 'overlay' }
+  ],
+  cache: '1h',
+  async handler({ search }) {
+    const event = useEvent()
+
+    const composables = await queryCollection(event, 'docs')
+      .where('path', 'LIKE', '/docs/composables/%')
+      .where('extension', '=', 'md')
+      .select('path', 'title', 'description')
+      .all()
+
+    let results = composables.map(composable => ({
+      name: composable.path.split('/').pop(),
+      title: composable.title,
+      description: composable.description,
+      path: composable.path,
+      url: `https://ui.nuxt.com${composable.path}`
+    }))
+
+    if (search) {
+      const searchLower = search.toLowerCase()
+      results = results.filter(composable =>
+        composable.name?.toLowerCase().includes(searchLower)
+        || composable.title?.toLowerCase().includes(searchLower)
+        || composable.description?.toLowerCase().includes(searchLower)
+      )
+    }
+
+    return {
+      composables: results.sort((a, b) => (a.name || '').localeCompare(b.name || '')),
+      total: results.length
+    }
+  }
+})

docs/server/mcp/tools/list-documentation-pages.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod'
+import { queryCollection } from '@nuxt/content/server'
+
+export default defineMcpTool({
+  description: 'Search documentation pages by title, description, or section. With no params, lists all pages.',
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  inputSchema: {
+    search: z.string().optional().describe('Search term to filter pages by title or description'),
+    section: z.string().optional().describe('Filter by documentation section (e.g., "getting-started", "components", "composables")')
+  },
+  inputExamples: [
+    {},
+    { section: 'getting-started' },
+    { search: 'installation' },
+    { search: 'color', section: 'getting-started' }
+  ],
+  cache: '30m',
+  async handler({ search, section }) {
+    const event = useEvent()
+
+    let query = queryCollection(event, 'docs')
+      .select('title', 'description', 'path')
+
+    if (section) {
+      query = query.where('path', 'LIKE', `/docs/${section}/%`)
+    }
+
+    const pages = await query.all()
+
+    let results = pages.map(page => ({
+      title: page.title,
+      description: page.description,
+      path: page.path,
+      url: `https://ui.nuxt.com${page.path}`
+    }))
+
+    if (search) {
+      const searchLower = search.toLowerCase()
+      results = results.filter(page =>
+        page.title?.toLowerCase().includes(searchLower)
+        || page.description?.toLowerCase().includes(searchLower)
+      )
+    }
+
+    return {
+      pages: results.sort((a, b) => a.path.localeCompare(b.path)),
+      total: results.length
+    }
+  }
+})

docs/server/mcp/tools/list-getting-started-guides.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod'
+
+export default defineMcpTool({
+  description: 'Search for icons across Iconify collections. Returns matching icon names in the `i-{prefix}-{name}` format used by Nuxt UI. Default collection is `lucide`.',
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: {
+    query: z.string().describe('Search query (e.g., "arrow", "home", "settings")'),
+    collection: z.string().default('lucide').describe('Icon collection to search within (e.g., "lucide", "heroicons", "mdi"). Defaults to "lucide".'),
+    limit: z.number().min(1).max(999).optional().describe('Maximum number of results (default: 64)')
+  },
+  inputExamples: [
+    { query: 'home' },
+    { query: 'arrow', collection: 'heroicons' },
+    { query: 'chart', collection: 'lucide', limit: 10 }
+  ],
+  cache: '1h',
+  async handler({ query, collection, limit }) {
+    const params = new URLSearchParams({ query, prefix: collection })
+    if (limit) params.set('limit', String(limit))
+
+    const data = await $fetch<{ icons: string[], total: number }>(`https://api.iconify.design/search?${params}`)
+
+    return {
+      icons: data.icons.map((icon) => {
+        const [iconPrefix, ...nameParts] = icon.split(':')
+        const name = nameParts.join(':')
+        return {
+          name: `i-${iconPrefix}-${name}`,
+          preview: `https://api.iconify.design/${iconPrefix}/${name}.svg`
+        }
+      }),
+      total: data.total,
+      query,
+      collection
+    }
+  }
+})