feat(mcp): expose every documentation page as a resource

package.json

@@ -45,6 +45,7 @@
     "@iconify-json/simple-icons": "^1.2.93",
     "@iconify-json/vscode-icons": "^1.2.74",
     "@iconify/vue": "^5.0.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@nuxt/kit": "^4.5.2",
     "@nuxt/ui": "^4.11.1",
     "@nuxtjs/mcp-toolkit": "^0.18.1",

server/mcp/resources/page.ts

@@ -0,0 +1,33 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { useEvent } from 'nitropack/runtime'
+import { getAgentDocument, listAgentPages } from '#agent-discovery'
+
+export default defineMcpResource({
+  name: 'page',
+  title: 'Documentation page',
+  description:
+    'A documentation page as markdown, the same document `/raw/<path>.md` serves. Listing the resources lists every page; read one by its `docs://page/<path>` URI.',
+  uri: new ResourceTemplate(`${PAGE_RESOURCE_PREFIX}{+route}`, {
+    list: async () => {
+      const pages = await listAgentPages(useEvent())
+      return {
+        resources: pages.map((page) => ({
+          uri: pageResourceUri(page.route),
+          name: page.title ?? page.route,
+          description: page.description,
+          mimeType: 'text/markdown',
+        })),
+      }
+    },
+  }),
+  handler: async (uri: URL) => {
+    const route = pageRouteFromUri(uri)
+    const document = route ? await getAgentDocument(useEvent(), route) : null
+    if (!document || 'redirect' in document) {
+      throw new Error(`Page not found: ${uri.href}. List the resources to see every page.`)
+    }
+    return {
+      contents: [{ uri: uri.href, mimeType: 'text/markdown', text: document.markdown }],
+    }
+  },
+})

server/utils/agent-resources.ts

@@ -0,0 +1,17 @@
+import { withLeadingSlash } from 'ufo'
+
+/** URI prefix of the MCP resource that serves a documentation page. */
+export const PAGE_RESOURCE_PREFIX = 'docs://page'
+
+/** `/getting-started/installation` -> `docs://page/getting-started/installation` */
+export function pageResourceUri(route: string): string {
+  return `${PAGE_RESOURCE_PREFIX}${withLeadingSlash(route)}`
+}
+
+/** The page route a resource URI names, or `null` when the URI is not a page resource. */
+export function pageRouteFromUri(uri: string | URL): string | null {
+  const href = typeof uri === 'string' ? uri : uri.href
+  if (!href.startsWith(`${PAGE_RESOURCE_PREFIX}/`)) return null
+  const route = href.slice(PAGE_RESOURCE_PREFIX.length).replace(/[?#].*$/, '')
+  return route === '/' ? null : route
+}

test/agent-resources.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { pageResourceUri, pageRouteFromUri } from '../server/utils/agent-resources'
+
+describe('pageResourceUri', () => {
+  it('prefixes a page route', () => {
+    expect(pageResourceUri('/getting-started/installation')).toBe('docs://page/getting-started/installation')
+    expect(pageResourceUri('getting-started/installation')).toBe('docs://page/getting-started/installation')
+  })
+})
+
+describe('pageRouteFromUri', () => {
+  it('returns the route of a page resource, from a string or a URL', () => {
+    expect(pageRouteFromUri('docs://page/getting-started/installation')).toBe('/getting-started/installation')
+    expect(pageRouteFromUri(new URL('docs://page/getting-started/installation'))).toBe('/getting-started/installation')
+  })
+
+  it('drops a query or hash', () => {
+    expect(pageRouteFromUri('docs://page/syntax/markdown#lists')).toBe('/syntax/markdown')
+    expect(pageRouteFromUri('docs://page/syntax/markdown?x=1')).toBe('/syntax/markdown')
+  })
+
+  it('rejects anything that is not a page resource', () => {
+    expect(pageRouteFromUri('docs://page')).toBeNull()
+    expect(pageRouteFromUri('docs://page/')).toBeNull()
+    expect(pageRouteFromUri('docs://pages/syntax')).toBeNull()
+    expect(pageRouteFromUri('https://comark.dev/raw/syntax/markdown.md')).toBeNull()
+  })
+})