Fix docs MCP content fetch on Vercel (#711)

* Fix docs MCP content fetch on Vercel

* Use static docs index for MCP

* Use native SQLite for Nuxt Content

* Remove better-sqlite3 build approval

* Fix MCP static fetch origin

* Handle MCP doc fetch failures

Author: bryantgillespie

modules/content-markdown.ts

@@ -3,6 +3,13 @@ import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, sep } from 'node:path';
 import { defineNuxtModule, useLogger } from '@nuxt/kit';
 import { contentToMarkdown } from '../server/utils/contentToMarkdown';
+import { parseMcpMarkdown } from '../server/utils/mcpMarkdown';
+
+interface McpDocIndexEntry {
+	title: string;
+	path: string;
+	description: string;
+}
 
 export default defineNuxtModule({
 	meta: { name: 'content-markdown' },
@@ -27,6 +34,7 @@ export default defineNuxtModule({
 			}
 
 			let written = 0;
+			const index: McpDocIndexEntry[] = [];
 			for (const file of markdownFiles) {
 				const rel = relative(contentDir, file);
 				const segments = rel.split(sep);
@@ -35,14 +43,24 @@ export default defineNuxtModule({
 				const route = toRoute(segments);
 				const raw = await readFile(file, 'utf8');
 				const md = contentToMarkdown(raw, partials);
+				const path = route === '/index' ? '/' : route;
+				const page = parseMcpMarkdown(md, path);
 
 				const outPath = join(outDir, route + '.md');
 				await mkdir(dirname(outPath), { recursive: true });
 				await writeFile(outPath, md, 'utf8');
+				index.push({
+					title: page.title,
+					path,
+					description: page.description,
+				});
 				written++;
 			}
 
-			logger.info(`Wrote ${written} content markdown files`);
+			index.sort((a, b) => a.path.localeCompare(b.path));
+			await writeFile(join(outDir, 'mcp-docs-index.json'), JSON.stringify(index, null, 2), 'utf8');
+
+			logger.info(`Wrote ${written} content markdown files and ${index.length} MCP index entries`);
 		});
 	},
 });

nuxt.config.ts

@@ -86,6 +86,9 @@ export default defineNuxtConfig({
 	},
 
 	content: {
+		experimental: {
+			sqliteConnector: 'native',
+		},
 		build: {
 			markdown: {
 				toc: {

package.json

@@ -71,10 +71,7 @@
 		"overrides": {
 			"vite": "npm:rolldown-vite@latest",
 			"h3": "1.15.11"
-		},
-		"onlyBuiltDependencies": [
-			"better-sqlite3"
-		]
+		}
 	},
 	"packageManager": "pnpm@10.29.2+sha512.bef43fa759d91fd2da4b319a5a0d13ef7a45bb985a3d7342058470f9d2051a3ba8674e629672654686ef9443ad13a82da2beb9eeb3e0221c87b8154fff9d74b8",
 	"engines": {

server/mcp/tools/get-doc.ts

@@ -1,7 +1,9 @@
 import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server';
-import { queryCollection } from '@nuxt/content/server';
+import { ofetch } from 'ofetch';
 import { useEvent } from 'nitropack/runtime';
 import { z } from 'zod';
+import { normalizeDocPath, parseMcpMarkdown } from '../../utils/mcpMarkdown';
+import { getMcpMarkdownPath, getMcpStaticBaseUrl } from '../../utils/mcpStatic';
 
 const BASE_PATH = '/docs';
 
@@ -20,22 +22,51 @@ export default defineMcpTool({
 		const event = useEvent();
 		const config = useRuntimeConfig();
 		const siteOrigin = config.public.siteUrl.replace(/\/$/, '');
-		const normalized = path.startsWith('/') ? path : `/${path}`;
+		const normalized = normalizeDocPath(path);
 
-		const page = await queryCollection(event, 'content')
-			.where('path', '=', normalized)
-			.first();
+		let markdown: string;
+		try {
+			markdown = await ofetch(`${getMcpStaticBaseUrl()}${getMcpMarkdownPath(normalized)}.md`, { responseType: 'text' });
+		}
+		catch (error) {
+			if (!import.meta.dev) {
+				if (fetchStatusCode(error) !== 404) {
+					throw createError({ statusCode: 503, message: `Doc markdown unavailable for ${normalized}` });
+				}
+				throw createError({ statusCode: 404, message: `No doc found at ${normalized}` });
+			}
+
+			const { queryCollection } = await import('@nuxt/content/server');
+			const page = await queryCollection(event, 'content')
+				.where('path', '=', normalized)
+				.first();
+
+			if (!page) {
+				throw createError({ statusCode: 404, message: `No doc found at ${normalized}` });
+			}
 
-		if (!page) {
-			throw createError({ statusCode: 404, message: `No doc found at ${normalized}` });
+			return {
+				title: page.title,
+				path: page.path,
+				description: page.description ?? '',
+				content: page.rawbody ?? '',
+				url: `${siteOrigin}${BASE_PATH}${page.path}`,
+			};
 		}
 
+		const page = parseMcpMarkdown(markdown, normalized);
+
 		return {
 			title: page.title,
-			path: page.path,
+			path: normalized,
 			description: page.description ?? '',
-			content: page.rawbody ?? '',
-			url: `${siteOrigin}${BASE_PATH}${page.path}`,
+			content: page.content,
+			url: `${siteOrigin}${BASE_PATH}${normalized}`,
 		};
 	},
 });
+
+function fetchStatusCode(error: unknown): number | undefined {
+	if (!error || typeof error !== 'object' || !('response' in error)) return;
+	return (error as { response?: { status?: number } }).response?.status;
+}

server/mcp/tools/list-docs.ts

@@ -1,14 +1,21 @@
 import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server';
-import { queryCollection } from '@nuxt/content/server';
+import { ofetch } from 'ofetch';
 import { useEvent } from 'nitropack/runtime';
 import { z } from 'zod';
 import { docsSections } from '#shared/utils/docsSections';
+import { getMcpStaticBaseUrl } from '../../utils/mcpStatic';
 
 const BASE_PATH = '/docs';
 
 const allPrefixes = Array.from(new Set(docsSections.flatMap(s => s.prefixes))).sort();
 const prefixDescription = `Path prefix to filter by. Must start with "/". Valid prefixes: ${allPrefixes.join(', ')}.`;
 
+interface McpDocIndexEntry {
+	title: string;
+	path: string;
+	description: string;
+}
+
 export default defineMcpTool({
 	name: 'list-docs',
 	title: 'List Directus docs',
@@ -27,22 +34,40 @@ export default defineMcpTool({
 		const event = useEvent();
 		const config = useRuntimeConfig();
 		const siteOrigin = config.public.siteUrl.replace(/\/$/, '');
-		let query = queryCollection(event, 'content')
-			.where('path', 'NOT LIKE', '%/.%')
-			.where('path', 'NOT LIKE', '%/_partials/%')
-			.order('path', 'ASC');
+		const rows = await loadDocIndex(event);
+		const filtered = pathPrefix
+			? rows.filter(row => row.path.startsWith(pathPrefix))
+			: rows;
+
+		return filtered.slice(0, limit ?? 200).map(row => ({
+			title: row.title,
+			path: row.path,
+			description: row.description ?? '',
+			url: `${siteOrigin}${BASE_PATH}${row.path}`,
+		}));
+	},
+});
 
-		if (pathPrefix) {
-			query = query.where('path', 'LIKE', `${pathPrefix}%`);
+async function loadDocIndex(event: ReturnType<typeof useEvent>): Promise<McpDocIndexEntry[]> {
+	try {
+		return await ofetch<McpDocIndexEntry[]>(`${getMcpStaticBaseUrl()}/mcp-docs-index.json`);
+	}
+	catch {
+		if (!import.meta.dev) {
+			throw createError({ statusCode: 503, message: 'Docs index unavailable' });
 		}
 
-		const rows = await query.limit(limit ?? 200).all();
+		const { queryCollection } = await import('@nuxt/content/server');
+		const rows = await queryCollection(event, 'content')
+			.where('path', 'NOT LIKE', '%/.%')
+			.where('path', 'NOT LIKE', '%/_partials/%')
+			.order('path', 'ASC')
+			.all();
 
 		return rows.map(row => ({
 			title: row.title,
 			path: row.path,
 			description: row.description ?? '',
-			url: `${siteOrigin}${BASE_PATH}${row.path}`,
 		}));
-	},
-});
+	}
+}

server/utils/mcpMarkdown.ts

@@ -0,0 +1,46 @@
+export interface ParsedMcpMarkdown {
+	title: string;
+	description: string;
+	content: string;
+}
+
+export function normalizeDocPath(path: string): string {
+	return path.startsWith('/') ? path : `/${path}`;
+}
+
+export function parseMcpMarkdown(markdown: string, path: string): ParsedMcpMarkdown {
+	const { frontmatter, body } = splitFrontmatter(markdown);
+
+	return {
+		title: frontmatterValue(frontmatter, 'title') || titleFromMarkdown(body) || path,
+		description: frontmatterValue(frontmatter, 'description') || '',
+		content: body,
+	};
+}
+
+function splitFrontmatter(markdown: string): { frontmatter: string; body: string } {
+	const content = markdown.replace(/^\uFEFF/, '');
+	if (!content.startsWith('---\n')) return { frontmatter: '', body: content };
+
+	const end = content.indexOf('\n---', 4);
+	if (end === -1) return { frontmatter: '', body: content };
+
+	return {
+		frontmatter: content.slice(4, end).trim(),
+		body: content.slice(end + 4).replace(/^\n+/, ''),
+	};
+}
+
+function frontmatterValue(frontmatter: string, key: string): string {
+	const match = new RegExp(`^${key}:\\s*(.*)$`, 'm').exec(frontmatter);
+	if (!match?.[1]) return '';
+
+	return match[1]
+		.trim()
+		.replace(/^['"]|['"]$/g, '');
+}
+
+function titleFromMarkdown(markdown: string): string {
+	const match = /^#\s+(.+)$/m.exec(markdown);
+	return match?.[1]?.trim() ?? '';
+}

server/utils/mcpStatic.ts

@@ -0,0 +1,13 @@
+import { normalizeDocPath } from './mcpMarkdown';
+
+export function getMcpStaticBaseUrl(): string {
+	const config = useRuntimeConfig();
+	const baseUrl = config.app.baseURL.replace(/\/$/, '');
+	const siteOrigin = config.public.siteUrl.replace(/\/$/, '');
+	return `${siteOrigin}${baseUrl}`;
+}
+
+export function getMcpMarkdownPath(path: string): string {
+	const normalized = normalizeDocPath(path);
+	return normalized === '/' ? '/index' : normalized;
+}

tests/server/mcpMarkdown.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeDocPath, parseMcpMarkdown } from '../../server/utils/mcpMarkdown';
+import { getMcpMarkdownPath } from '../../server/utils/mcpStatic';
+
+describe('mcpMarkdown', () => {
+	it('normalizes doc paths', () => {
+		expect(normalizeDocPath('self-hosting/requirements')).toBe('/self-hosting/requirements');
+		expect(normalizeDocPath('/self-hosting/requirements')).toBe('/self-hosting/requirements');
+	});
+
+	it('maps root docs path to index markdown', () => {
+		expect(getMcpMarkdownPath('/')).toBe('/index');
+		expect(getMcpMarkdownPath('/self-hosting/requirements')).toBe('/self-hosting/requirements');
+	});
+
+	it('parses frontmatter and markdown body', () => {
+		const page = parseMcpMarkdown(`---
+title: Self-Hosting Requirements
+description: This page outlines the requirements.
+---
+
+# Ignored title
+
+Body
+`, '/self-hosting/requirements');
+
+		expect(page).toEqual({
+			title: 'Self-Hosting Requirements',
+			description: 'This page outlines the requirements.',
+			content: '# Ignored title\n\nBody\n',
+		});
+	});
+
+	it('falls back to markdown title', () => {
+		const page = parseMcpMarkdown('# Page title\n\nBody\n', '/fallback');
+
+		expect(page.title).toBe('Page title');
+		expect(page.description).toBe('');
+		expect(page.content).toBe('# Page title\n\nBody\n');
+	});
+});