feat(mcp): add mcp server

docs/nuxt.config.ts

@@ -25,6 +25,9 @@ export default defineNuxtConfig({
       description: 'Write beautiful docs with Markdown.',
     },
   },
+  mcp: {
+    name: 'Docus documentation',
+  },
   studio: {
     route: '/admin',
     repository: {

docs/package.json

@@ -16,7 +16,8 @@
     "docus": "workspace:*",
     "nuxt-studio": "https://pkg.pr.new/nuxt-content/studio/nuxt-studio@dc78b20",
     "tailwindcss": "^4.1.14",
-    "unist-util-visit": "^5.0.0"
+    "unist-util-visit": "^5.0.0",
+    "zod": "^3.24.1"
   },
   "devDependencies": {
     "nuxt": "4.1.3"

docs/server/mcp/tools/example.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod'
+
+// delete this file before merging
+export default defineMcpTool({
+  name: 'example_tool',
+  description: 'An example custom tool to test auto-detection',
+  paramsSchema: {
+    message: z.string().describe('A message to echo back'),
+  },
+  handler: async (params) => {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Echo: ${params.message}`,
+        },
+      ],
+    }
+  },
+})

docs/tsconfig.json

@@ -1,3 +1,17 @@
 {
-  "extends": "./.nuxt/tsconfig.json"
-}
+  "files": [],
+  "references": [
+    {
+      "path": "./.nuxt/tsconfig.app.json"
+    },
+    {
+      "path": "./.nuxt/tsconfig.server.json"
+    },
+    {
+      "path": "./.nuxt/tsconfig.shared.json"
+    },
+    {
+      "path": "./.nuxt/tsconfig.node.json"
+    }
+  ]
+}

layer/nuxt.config.ts

@@ -11,6 +11,7 @@ export default defineNuxtConfig({
     '@nuxt/content',
     '@nuxt/image',
     '@nuxtjs/robots',
+    '@hrcd/mcp',
     'nuxt-og-image',
     'nuxt-llms',
     () => {

layer/package.json

@@ -22,6 +22,7 @@
     "README.md"
   ],
   "dependencies": {
+    "@hrcd/mcp": "^0.0.4",
     "@iconify-json/lucide": "^1.2.69",
     "@iconify-json/simple-icons": "^1.2.54",
     "@iconify-json/vscode-icons": "^1.2.32",
@@ -43,7 +44,8 @@
     "pkg-types": "^2.3.0",
     "scule": "^1.3.0",
     "tailwindcss": "^4.1.14",
-    "ufo": "^1.6.1"
+    "ufo": "^1.6.1",
+    "zod": "^3.24.1"
   },
   "peerDependencies": {
     "better-sqlite3": "12.x",

layer/server/api/.docus-mcp/get-page.get.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+import { queryCollection } from '@nuxt/content/server'
+import type { Collections } from '@nuxt/content'
+import { getAvailableLocales, getCollectionFromPath } from '../../utils/content'
+
+const querySchema = z.object({
+  path: z.string().describe('The page path (e.g., /en/getting-started/installation)'),
+})
+
+export default defineCachedEventHandler(async (event) => {
+  const { path } = await getValidatedQuery(event, querySchema.parse)
+  const config = useRuntimeConfig(event).public
+
+  const siteUrl = import.meta.dev ? 'http://localhost:3000' : getRequestURL(event).origin
+  const availableLocales = getAvailableLocales(config)
+  const collectionName = config.i18n?.locales
+    ? getCollectionFromPath(path, availableLocales)
+    : 'docs'
+
+  const page = await queryCollection(event, collectionName as keyof Collections)
+    .where('path', '=', path)
+    .select('title', 'path', 'description')
+    .first()
+
+  if (!page) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Page not found',
+    })
+  }
+
+  const content = await $fetch<string>(`/raw${path}.md`, {
+    baseURL: siteUrl,
+  }).catch(() => {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Raw content not found',
+    })
+  })
+
+  return {
+    title: page.title,
+    path: page.path,
+    description: page.description,
+    content,
+    url: `${siteUrl}${page.path}`,
+  }
+}, {
+  maxAge: 60 * 60,
+  getKey: (event) => {
+    const query = getQuery(event)
+    return `mcp-get-page-${query.path}`
+  },
+})

layer/server/api/.docus-mcp/list-pages.get.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod'
+import { queryCollection } from '@nuxt/content/server'
+import type { Collections } from '@nuxt/content'
+import { getCollectionsToQuery, getAvailableLocales } from '../../utils/content'
+
+const querySchema = z.object({
+  locale: z.string().optional().describe('Language code (e.g., "en", "fr")'),
+})
+
+export default defineCachedEventHandler(async (event) => {
+  const { locale } = await getValidatedQuery(event, querySchema.parse)
+  const config = useRuntimeConfig(event).public
+
+  const siteUrl = import.meta.dev ? 'http://localhost:3000' : getRequestURL(event).origin
+  const availableLocales = getAvailableLocales(config)
+  const collections = getCollectionsToQuery(locale, availableLocales)
+
+  const allPages = await Promise.all(
+    collections.map(async (collectionName) => {
+      try {
+        const pages = await queryCollection(event, collectionName as keyof Collections)
+          .select('title', 'path', 'description')
+          .all()
+
+        return pages.map(page => ({
+          title: page.title,
+          path: page.path,
+          description: page.description,
+          locale: collectionName.replace('docs_', ''),
+          url: `${siteUrl}${page.path}`,
+        }))
+      }
+      catch {
+        return []
+      }
+    }),
+  )
+
+  return allPages.flat()
+}, {
+  maxAge: 60 * 60,
+  getKey: (event) => {
+    const query = getQuery(event)
+    return `mcp-list-pages-${query.locale || 'all'}`
+  },
+})

layer/server/mcp/tools/get-page.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod'
+
+export default defineMcpTool({
+  name: 'get_page',
+  description: 'Retrieves the full markdown content of a specific documentation page by path',
+  inputSchema: {
+    path: z.string().describe('The page path (e.g., /en/getting-started/installation)'),
+  },
+  handler: async (params) => {
+    const result = await $fetch('/api/.docus-mcp/get-page', { query: params })
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    }
+  },
+})

layer/server/mcp/tools/list-pages.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod'
+
+export default defineMcpTool({
+  name: 'list_pages',
+  description: 'Lists all available documentation pages with their titles, paths, and descriptions',
+  inputSchema: {
+    locale: z.string().optional().describe('The locale to filter pages by'),
+  },
+  handler: async (params) => {
+    const result = await $fetch('/api/.docus-mcp/list-pages', { query: params })
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    }
+  },
+})

layer/server/routes/raw/[...slug].md.get.ts

@@ -1,6 +1,6 @@
 import { withLeadingSlash } from 'ufo'
 import { stringify } from 'minimark/stringify'
-import { queryCollection } from '@nuxt/content/nitro'
+import { queryCollection } from '@nuxt/content/server'
 import type { Collections } from '@nuxt/content'
 
 export default eventHandler(async (event) => {

layer/server/utils/content.ts

@@ -0,0 +1,37 @@
+import type { LocaleObject } from '@nuxtjs/i18n'
+
+type ConfigWithLocales = {
+  i18n?: { locales?: Array<string | LocaleObject> }
+  docus?: { filteredLocales?: LocaleObject<string>[] }
+}
+
+export function getAvailableLocales(config: ConfigWithLocales): string[] {
+  if (config.docus?.filteredLocales) {
+    return config.docus.filteredLocales.map(locale => locale.code)
+  }
+
+  return config.i18n?.locales
+    ? config.i18n.locales.map(locale => typeof locale === 'string' ? locale : locale.code)
+    : []
+}
+
+export function getCollectionsToQuery(locale: string | undefined, availableLocales: string[]): string[] {
+  if (locale && availableLocales.includes(locale)) {
+    return [`docs_${locale}`]
+  }
+
+  return availableLocales.length > 0
+    ? availableLocales.map(l => `docs_${l}`)
+    : ['docs']
+}
+
+export function getCollectionFromPath(path: string, availableLocales: string[]): string {
+  const pathSegments = path.split('/').filter(Boolean)
+  const firstSegment = pathSegments[0]
+
+  if (firstSegment && availableLocales.includes(firstSegment)) {
+    return `docs_${firstSegment}`
+  }
+
+  return 'docs'
+}