feat: add mcp server

Author: HugoRCD

content/3.ai/1.mcp.md

@@ -0,0 +1,284 @@
+---
+title: MCP Server
+description: Connect your documentation to AI tools with a native MCP server.
+navigation:
+  icon: i-lucide-cpu
+---
+
+## About MCP Servers
+
+The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open protocol that creates standardized connections between AI applications and external services, like documentation.
+
+This documentation template includes a built-in MCP server, preparing your content for the broader AI ecosystem where any MCP client (like Claude, Cursor, VS Code, and others) can connect to your documentation.
+
+### How MCP Servers Work
+
+When an MCP server is connected to an AI tool, the LLM can decide to use your documentation tools during response generation:
+
+- The LLM can **proactively search your documentation** while generating a response, not just when explicitly asked.
+- The LLM determines **when to use tools** based on the context of the conversation and the relevance of your documentation.
+- Each tool call happens **during the generation process**, allowing the LLM to incorporate real-time information from your documentation into its response.
+
+For example, if a user asks a coding question and the LLM determines that your documentation is relevant, it can search your docs and include that information in the response without the user explicitly asking about your documentation.
+
+## Accessing Your MCP Server
+
+Your MCP server is automatically available at the `/mcp` path of your documentation URL.
+
+::prose-note
+For example, if your documentation is hosted at `https://docs.example.com`, your MCP server URL is `https://docs.example.com/mcp`.
+::
+
+## Disable the MCP Server
+
+If you want to disable the MCP server, you can do so in your `nuxt.config.ts`:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  mcp: {
+    enabled: false,
+  },
+})
+```
+
+## Built-in Tools
+
+This template provides two tools out of the box that allow any LLM to discover and read your documentation:
+
+### `list-pages`
+
+Lists all documentation pages with their titles, paths, and descriptions. AI assistants should call this first to discover available content.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `locale` | string (optional) | Filter pages by locale |
+
+### `get-page`
+
+Retrieves the full markdown content of a specific documentation page.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | string (required) | The page path (e.g., `/en/getting-started/installation`) |
+
+## Setup
+
+The MCP server uses HTTP transport and can be installed in different AI assistants.
+
+### Claude Code
+
+Add the server using the CLI command:
+
+```bash
+claude mcp add --transport http my-docs https://docs.example.com/mcp
+```
+
+### Cursor
+
+::install-button
+---
+url: "https://docs.example.com/mcp"
+ide: "cursor"
+label: "Install in Cursor"
+---
+::
+
+Or manually create/update `.cursor/mcp.json` in your project root:
+
+```json [.cursor/mcp.json]
+{
+  "mcpServers": {
+    "my-docs": {
+      "type": "http",
+      "url": "https://docs.example.com/mcp"
+    }
+  }
+}
+```
+
+### Visual Studio Code
+
+Ensure you have GitHub Copilot and GitHub Copilot Chat extensions installed.
+
+::install-button
+---
+url: "https://docs.example.com/mcp"
+ide: "vscode"
+label: "Install in VS Code"
+---
+::
+
+Or manually create/update the `.vscode/mcp.json` file:
+
+```json [.vscode/mcp.json]
+{
+  "servers": {
+    "my-docs": {
+      "type": "http",
+      "url": "https://docs.example.com/mcp"
+    }
+  }
+}
+```
+
+### Windsurf
+
+1. Open Windsurf and navigate to **Settings** > **Windsurf Settings** > **Cascade**
+2. Click the **Manage MCPs** button, then select the **View raw config** option
+3. Add the following configuration:
+
+```json [.codeium/windsurf/mcp_config.json]
+{
+  "mcpServers": {
+    "my-docs": {
+      "type": "http",
+      "url": "https://docs.example.com/mcp"
+    }
+  }
+}
+```
+
+### Zed
+
+1. Open Zed and go to **Settings** > **Open Settings**
+2. Navigate to the JSON settings file
+3. Add the following context server configuration:
+
+```json [.config/zed/settings.json]
+{
+  "context_servers": {
+    "my-docs": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["mcp-remote", "https://docs.example.com/mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+## Customization
+
+Since this template uses the [`@nuxtjs/mcp-toolkit`](https://mcp-toolkit.nuxt.dev/) module, you can extend the MCP server with custom tools, resources, prompts, and handlers.
+
+### Adding Custom Tools
+
+Create new tools in the `server/mcp/tools/` directory:
+
+```ts [server/mcp/tools/search.ts]
+import { z } from 'zod'
+
+export default defineMcpTool({
+  description: 'Search documentation by keyword',
+  inputSchema: {
+    query: z.string().describe('The search query'),
+  },
+  handler: async ({ query }) => {
+    const results = await searchDocs(query)
+    return {
+      content: [{ type: 'text', text: JSON.stringify(results) }],
+    }
+  },
+})
+```
+
+### Adding Resources
+
+Expose files or data sources as MCP resources in the `server/mcp/resources/` directory. The simplest way is using the `file` property:
+
+```ts [server/mcp/resources/changelog.ts]
+export default defineMcpResource({
+  file: 'CHANGELOG.md',
+  metadata: {
+    description: 'Project changelog',
+  },
+})
+```
+
+This automatically handles URI generation, MIME type detection, and file reading.
+
+### Adding Prompts
+
+Create reusable prompts for AI assistants in the `server/mcp/prompts/` directory:
+
+```ts [server/mcp/prompts/migration-help.ts]
+import { z } from 'zod'
+
+export default defineMcpPrompt({
+  description: 'Get help with migrating between versions',
+  inputSchema: {
+    fromVersion: z.string().describe('Current version'),
+    toVersion: z.string().describe('Target version'),
+  },
+  handler: async ({ fromVersion, toVersion }) => {
+    return {
+      messages: [{
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `Help me migrate from version ${fromVersion} to ${toVersion}. What are the breaking changes and steps I need to follow?`,
+        },
+      }],
+    }
+  },
+})
+```
+
+### Adding Custom Handlers
+
+Handlers allow you to create separate MCP endpoints with their own tools, resources, and prompts. This is useful for exposing different capabilities at different routes.
+
+For example, you could have:
+- `/mcp` - Main documentation MCP server
+- `/mcp/migration` - Dedicated MCP server for migration assistance
+
+```ts [server/mcp/migration.ts]
+import { z } from 'zod'
+
+const migrationTool = defineMcpTool({
+  name: 'migrate-v3-to-v4',
+  description: 'Migrate code from version 3 to version 4',
+  inputSchema: {
+    code: z.string().describe('The code to migrate'),
+  },
+  handler: async ({ code }) => {
+    // Migration logic
+    return {
+      content: [{ type: 'text', text: migratedCode }],
+    }
+  },
+})
+
+export default defineMcpHandler({
+  route: '/mcp/migration',
+  name: 'Migration Assistant',
+  version: '1.0.0',
+  tools: [migrationTool],
+})
+```
+
+### Overwriting Built-in Tools
+
+You can override the default `list-pages` or `get-page` tools by creating a tool with the same name in your project:
+
+```ts [server/mcp/tools/list-pages.ts]
+import { z } from 'zod'
+
+export default defineMcpTool({
+  description: 'Custom list pages implementation',
+  inputSchema: {
+    locale: z.string().optional(),
+    category: z.string().optional(),
+  },
+  handler: async ({ locale, category }) => {
+    const pages = await getCustomPageList(locale, category)
+    return {
+      content: [{ type: 'text', text: JSON.stringify(pages) }],
+    }
+  },
+})
+```
+
+::tip{to="https://mcp-toolkit.nuxt.dev/"}
+Check the MCP Toolkit documentation for more information about tools, resources, prompts, handlers and advanced configuration.
+::

content/3.ai/2.llms.md

@@ -0,0 +1,44 @@
+---
+title: LLMs Integration
+description: Generate AI-ready content files using Nuxt LLMs module
+navigation:
+  icon: i-lucide-message-circle-code
+---
+
+This documentation template integrates `nuxt-llms` by default to prepare your content for Large Language Models (LLMs). All your documentation pages are injected and `/llms.txt` and `/llms-full.txt` files are automatically generated and pre-rendered.
+
+::prose-note{to="/llms.txt"}
+Have a check at the `/llms.txt` file generated for this documentation.
+::
+
+## Defaults
+
+Here are the default values use to generate the `/llms.txt` file:
+
+- `domain` → computed based on your deployment platform (or by using `NUXT_SITE_URL` env variable)
+- `title` → extracted from your `package.json`
+- `description` → extracted from your `package.json`
+- `full.title` → extracted from your `package.json`
+- `full.description` → extracted from your `package.json`
+
+## Customize
+
+You can override your LLMs data from the `nuxt.config.ts` :
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  llms: {
+    domain: 'https://your-site.com',
+    title: 'Your Site Name',
+    description: 'A brief description of your site',
+    full: {
+      title: 'Your Site Name',
+      description: 'A brief description of your site',
+    },
+  },
+})
+```
+
+::tip{to="https://github.com/nuxt-content/nuxt-llms"}
+Checkout the nuxt-llms documentation for more information about the module.
+::

nuxt.config.ts

@@ -6,7 +6,8 @@ export default defineNuxtConfig({
     '@nuxt/ui',
     '@nuxt/content',
     'nuxt-og-image',
-    'nuxt-llms'
+    'nuxt-llms',
+    '@nuxtjs/mcp-toolkit'
   ],
 
   devtools: {
@@ -25,6 +26,10 @@ export default defineNuxtConfig({
     }
   },
 
+  experimental: {
+    asyncContext: true
+  },
+
   compatibilityDate: '2024-07-11',
 
   nitro: {
@@ -74,5 +79,9 @@ export default defineNuxtConfig({
         ]
       }
     ]
+  },
+
+  mcp: {
+    name: 'Docs template'
   }
 })

package.json

@@ -17,10 +17,12 @@
     "@nuxt/content": "^3.8.2",
     "@nuxt/image": "^2.0.0",
     "@nuxt/ui": "^4.2.1",
+    "@nuxtjs/mcp-toolkit": "0.5.1",
     "better-sqlite3": "^12.4.6",
     "nuxt": "^4.2.1",
     "nuxt-llms": "0.1.3",
-    "nuxt-og-image": "^5.1.12"
+    "nuxt-og-image": "^5.1.12",
+    "zod": "^4.1.13"
   },
   "devDependencies": {
     "@nuxt/eslint": "^1.10.0",