@farming-labs/docs 0.1.1-beta.4 → 0.1.2

package/dist/mcp-8rCBy2-U.mjs

@@ -0,0 +1,93 @@
+import "./api-reference-wh4_pwG8.mjs";
+import { createFilesystemDocsMcpSource, resolveDocsMcpConfig, runDocsMcpStdio } from "./mcp.mjs";
+import "./server.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+//#region src/cli/mcp.ts
+const FILE_EXTS = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js"
+];
+async function runMcp(options = {}) {
+	const rootDir = process.cwd();
+	const content = readFileSync(resolveDocsConfigPath(rootDir, options.configPath), "utf-8");
+	const entry = readStringProperty(content, "entry") ?? "docs";
+	const contentDir = readStringProperty(content, "contentDir") ?? entry;
+	const navTitle = readNavTitle(content);
+	const mcp = readMcpConfig(content);
+	await runDocsMcpStdio({
+		source: createFilesystemDocsMcpSource({
+			rootDir,
+			entry,
+			contentDir,
+			siteTitle: navTitle ?? "Documentation"
+		}),
+		mcp: resolveDocsMcpConfig(mcp ?? true, { defaultName: navTitle ?? "@farming-labs/docs" }),
+		defaultName: navTitle ?? "@farming-labs/docs"
+	});
+}
+function resolveDocsConfigPath(rootDir, explicitPath) {
+	if (explicitPath) {
+		const resolvedPath = resolve(rootDir, explicitPath);
+		if (!existsSync(resolvedPath)) throw new Error(`Could not find docs config at ${explicitPath}.`);
+		return resolvedPath;
+	}
+	for (const ext of FILE_EXTS) {
+		const configPath = join(rootDir, `docs.config.${ext}`);
+		if (existsSync(configPath)) return configPath;
+	}
+	throw new Error("Could not find docs.config.ts or docs.config.tsx in the current project. Use --config to point at a custom path.");
+}
+function readStringProperty(content, key) {
+	return content.match(new RegExp(`${key}\\s*:\\s*["']([^"']+)["']`))?.[1];
+}
+function readNavTitle(content) {
+	const block = extractObjectLiteral(content, "nav");
+	if (!block) return void 0;
+	return readStringProperty(block, "title");
+}
+function readMcpConfig(content) {
+	if (content.match(/mcp\s*:\s*false/)) return false;
+	if (content.match(/mcp\s*:\s*true/)) return true;
+	const block = extractObjectLiteral(content, "mcp");
+	if (!block) return void 0;
+	return {
+		enabled: readBooleanProperty(block, "enabled"),
+		route: readStringProperty(block, "route"),
+		name: readStringProperty(block, "name"),
+		version: readStringProperty(block, "version"),
+		tools: {
+			listPages: readBooleanProperty(block, "listPages"),
+			readPage: readBooleanProperty(block, "readPage"),
+			searchDocs: readBooleanProperty(block, "searchDocs"),
+			getNavigation: readBooleanProperty(block, "getNavigation")
+		}
+	};
+}
+function readBooleanProperty(content, key) {
+	const match = content.match(new RegExp(`${key}\\s*:\\s*(true|false)`));
+	return match ? match[1] === "true" : void 0;
+}
+function extractObjectLiteral(content, key) {
+	const keyIndex = content.search(new RegExp(`${key}\\s*:\\s*\\{`));
+	if (keyIndex === -1) return void 0;
+	const braceStart = content.indexOf("{", keyIndex);
+	if (braceStart === -1) return void 0;
+	let depth = 0;
+	for (let index = braceStart; index < content.length; index += 1) {
+		const char = content[index];
+		if (char === "{") {
+			depth += 1;
+			continue;
+		}
+		if (char !== "}") continue;
+		depth -= 1;
+		if (depth === 0) return content.slice(braceStart + 1, index);
+	}
+}
+
+//#endregion
+export { runMcp };

package/dist/mcp.d.mts

@@ -0,0 +1,86 @@
+import { u as DocsMcpConfig, w as OrderingItem } from "./types-dqnMXLdw.mjs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/mcp.d.ts
+interface DocsMcpPage {
+  slug: string;
+  url: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  content: string;
+  rawContent?: string;
+}
+interface DocsMcpPageNode {
+  type: "page";
+  name: string;
+  url: string;
+  icon?: string;
+  description?: string;
+}
+interface DocsMcpFolderNode {
+  type: "folder";
+  name: string;
+  icon?: string;
+  index?: DocsMcpPageNode;
+  children: DocsMcpNavigationNode[];
+}
+type DocsMcpNavigationNode = DocsMcpPageNode | DocsMcpFolderNode;
+interface DocsMcpNavigationTree {
+  name: string;
+  children: DocsMcpNavigationNode[];
+}
+interface DocsMcpSource {
+  entry?: string;
+  siteTitle?: string;
+  getPages(locale?: string): DocsMcpPage[] | Promise<DocsMcpPage[]>;
+  getNavigation(locale?: string): DocsMcpNavigationTree | Promise<DocsMcpNavigationTree>;
+}
+interface DocsMcpResolvedConfig {
+  enabled: boolean;
+  route: string;
+  name: string;
+  version: string;
+  tools: {
+    listPages: boolean;
+    readPage: boolean;
+    searchDocs: boolean;
+    getNavigation: boolean;
+  };
+}
+interface DocsMcpHttpHandlers {
+  GET: (context: {
+    request: Request;
+  }) => Promise<Response>;
+  POST: (context: {
+    request: Request;
+  }) => Promise<Response>;
+  DELETE: (context: {
+    request: Request;
+  }) => Promise<Response>;
+}
+interface CreateDocsMcpServerOptions {
+  source: DocsMcpSource;
+  mcp?: boolean | DocsMcpConfig;
+  defaultName?: string;
+  defaultVersion?: string;
+}
+interface CreateFilesystemDocsMcpSourceOptions {
+  rootDir?: string;
+  entry?: string;
+  contentDir?: string;
+  siteTitle?: string;
+  ordering?: "alphabetical" | "numeric" | OrderingItem[];
+}
+declare function normalizeDocsMcpRoute(route?: string): string;
+declare function resolveDocsMcpConfig(mcp?: boolean | DocsMcpConfig, defaults?: {
+  defaultName?: string;
+  defaultVersion?: string;
+  defaultRoute?: string;
+}): DocsMcpResolvedConfig;
+declare function createFilesystemDocsMcpSource(options?: CreateFilesystemDocsMcpSourceOptions): DocsMcpSource;
+declare function createDocsMcpServer(options: CreateDocsMcpServerOptions): Promise<McpServer>;
+declare function createDocsMcpHttpHandler(options: CreateDocsMcpServerOptions): DocsMcpHttpHandlers;
+declare function runDocsMcpStdio(options: CreateDocsMcpServerOptions): Promise<void>;
+//#endregion
+export { DocsMcpFolderNode, DocsMcpHttpHandlers, DocsMcpNavigationNode, DocsMcpNavigationTree, DocsMcpPage, DocsMcpPageNode, DocsMcpResolvedConfig, DocsMcpSource, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio };

package/dist/mcp.mjs

@@ -0,0 +1,485 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import matter from "gray-matter";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import * as z from "zod/v4";
+
+//#region src/mcp.ts
+const DEFAULT_MCP_ROUTE = "/api/docs/mcp";
+const DEFAULT_MCP_VERSION = "0.0.0";
+const DEFAULT_MCP_NAME = "@farming-labs/docs";
+const searchDocsInputSchema = z.object({
+	query: z.string().trim().min(1),
+	limit: z.number().int().min(1).max(25).optional(),
+	locale: z.string().min(1).optional()
+});
+const readPageInputSchema = z.object({
+	path: z.string().min(1),
+	locale: z.string().min(1).optional()
+});
+const listPagesInputSchema = z.object({ locale: z.string().min(1).optional() });
+const getNavigationInputSchema = z.object({ locale: z.string().min(1).optional() });
+function normalizeDocsMcpRoute(route) {
+	if (!route || route.trim().length === 0) return DEFAULT_MCP_ROUTE;
+	const normalized = `/${route}`.replace(/\/+/g, "/");
+	return normalized !== "/" ? normalized.replace(/\/+$/, "") : DEFAULT_MCP_ROUTE;
+}
+function resolveDocsMcpConfig(mcp, defaults = {}) {
+	if (!mcp) return {
+		enabled: false,
+		route: normalizeDocsMcpRoute(defaults.defaultRoute),
+		name: defaults.defaultName ?? DEFAULT_MCP_NAME,
+		version: defaults.defaultVersion ?? DEFAULT_MCP_VERSION,
+		tools: {
+			listPages: true,
+			readPage: true,
+			searchDocs: true,
+			getNavigation: true
+		}
+	};
+	const config = typeof mcp === "object" ? mcp : {};
+	return {
+		enabled: typeof mcp === "boolean" ? mcp : config.enabled ?? true,
+		route: normalizeDocsMcpRoute(config.route ?? defaults.defaultRoute),
+		name: config.name ?? defaults.defaultName ?? DEFAULT_MCP_NAME,
+		version: config.version ?? defaults.defaultVersion ?? DEFAULT_MCP_VERSION,
+		tools: {
+			listPages: config.tools?.listPages ?? true,
+			readPage: config.tools?.readPage ?? true,
+			searchDocs: config.tools?.searchDocs ?? true,
+			getNavigation: config.tools?.getNavigation ?? true
+		}
+	};
+}
+function createFilesystemDocsMcpSource(options = {}) {
+	const rootDir = options.rootDir ?? process.cwd();
+	const entry = normalizePathSegment(options.entry ?? "docs") || "docs";
+	const contentDir = options.contentDir ?? entry;
+	const contentDirAbs = path.resolve(rootDir, contentDir);
+	const cache = /* @__PURE__ */ new Map();
+	const navigationCache = /* @__PURE__ */ new Map();
+	function getPages() {
+		const cached = cache.get("__default__");
+		if (cached) return cached;
+		const pages = scanFilesystemDocsPages(contentDirAbs, entry);
+		cache.set("__default__", pages);
+		return pages;
+	}
+	function getNavigation() {
+		const cached = navigationCache.get("__default__");
+		if (cached) return cached;
+		const tree = buildNavigationTreeFromPages(getPages(), options.siteTitle ?? "Documentation", options.ordering);
+		navigationCache.set("__default__", tree);
+		return tree;
+	}
+	return {
+		entry,
+		siteTitle: options.siteTitle ?? "Documentation",
+		getPages,
+		getNavigation
+	};
+}
+async function createDocsMcpServer(options) {
+	const resolved = resolveDocsMcpConfig(options.mcp, {
+		defaultName: options.defaultName ?? options.source.siteTitle ?? DEFAULT_MCP_NAME,
+		defaultVersion: options.defaultVersion
+	});
+	const server = new McpServer({
+		name: resolved.name,
+		version: resolved.version
+	});
+	const defaultPages = dedupePages(await options.source.getPages());
+	const defaultTree = await options.source.getNavigation();
+	server.registerResource("docs-navigation", "docs://navigation", {
+		title: "Docs Navigation",
+		description: "Structured navigation tree for the documentation site.",
+		mimeType: "text/plain"
+	}, async () => ({ contents: [{
+		uri: "docs://navigation",
+		mimeType: "text/plain",
+		text: renderNavigationTree(defaultTree)
+	}] }));
+	for (const page of defaultPages) {
+		const resourceUri = toPageResourceUri(page.url);
+		server.registerResource(`page-${slugToKey(page.slug)}`, resourceUri, {
+			title: page.title,
+			description: page.description,
+			mimeType: "text/markdown"
+		}, async () => ({ contents: [{
+			uri: resourceUri,
+			mimeType: "text/markdown",
+			text: renderPageDocument(page)
+		}] }));
+	}
+	if (resolved.tools.listPages) server.registerTool("list_pages", {
+		title: "List docs pages",
+		description: "List the known documentation pages with titles, slugs, and URLs.",
+		inputSchema: listPagesInputSchema,
+		annotations: { readOnlyHint: true }
+	}, async ({ locale }) => {
+		const pages = toPageSummaries(dedupePages(await options.source.getPages(locale)));
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({ pages }, null, 2)
+		}] };
+	});
+	if (resolved.tools.getNavigation) server.registerTool("get_navigation", {
+		title: "Get docs navigation",
+		description: "Return the documentation navigation tree for the current docs site.",
+		inputSchema: getNavigationInputSchema,
+		annotations: { readOnlyHint: true }
+	}, async ({ locale }) => {
+		return { content: [{
+			type: "text",
+			text: renderNavigationTree(await options.source.getNavigation(locale))
+		}] };
+	});
+	if (resolved.tools.searchDocs) server.registerTool("search_docs", {
+		title: "Search documentation",
+		description: "Search the docs by keyword across titles, descriptions, and page content.",
+		inputSchema: searchDocsInputSchema,
+		annotations: { readOnlyHint: true }
+	}, async ({ query, limit, locale }) => {
+		const results = searchDocsPages(dedupePages(await options.source.getPages(locale)), query, limit ?? 10);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({ results }, null, 2)
+		}] };
+	});
+	if (resolved.tools.readPage) server.registerTool("read_page", {
+		title: "Read a docs page",
+		description: "Read a documentation page by slug or URL path.",
+		inputSchema: readPageInputSchema,
+		annotations: { readOnlyHint: true }
+	}, async ({ path: requestedPath, locale }) => {
+		const page = findDocsPage(dedupePages(await options.source.getPages(locale)), requestedPath, options.source.entry);
+		if (!page) return {
+			content: [{
+				type: "text",
+				text: JSON.stringify({ error: `No docs page matched "${requestedPath}".` }, null, 2)
+			}],
+			isError: true
+		};
+		return { content: [{
+			type: "text",
+			text: renderPageDocument(page)
+		}] };
+	});
+	return server;
+}
+function createDocsMcpHttpHandler(options) {
+	if (!resolveDocsMcpConfig(options.mcp, {
+		defaultName: options.defaultName ?? options.source.siteTitle ?? DEFAULT_MCP_NAME,
+		defaultVersion: options.defaultVersion
+	}).enabled) return {
+		GET: async () => createJsonErrorResponse(404, "MCP is not enabled. Set `mcp: { enabled: true }` in docs.config to enable it."),
+		POST: async () => createJsonErrorResponse(404, "MCP is not enabled. Set `mcp: { enabled: true }` in docs.config to enable it."),
+		DELETE: async () => createJsonErrorResponse(404, "MCP is not enabled. Set `mcp: { enabled: true }` in docs.config to enable it.")
+	};
+	const sessions = /* @__PURE__ */ new Map();
+	async function createSession() {
+		const server = await createDocsMcpServer(options);
+		const transport = new WebStandardStreamableHTTPServerTransport({
+			sessionIdGenerator: () => randomUUID(),
+			onsessioninitialized(sessionId) {
+				sessions.set(sessionId, {
+					server,
+					transport
+				});
+			},
+			async onsessionclosed(sessionId) {
+				const session = sessions.get(sessionId);
+				sessions.delete(sessionId);
+				await session?.server.close().catch(() => void 0);
+			}
+		});
+		await server.connect(transport);
+		return {
+			server,
+			transport
+		};
+	}
+	async function handle(request) {
+		const method = request.method.toUpperCase();
+		const sessionId = request.headers.get("mcp-session-id") ?? request.headers.get("Mcp-Session-Id");
+		const existing = sessionId ? sessions.get(sessionId) : void 0;
+		let parsedBody;
+		if (method === "POST") try {
+			parsedBody = await request.clone().json();
+		} catch {
+			parsedBody = void 0;
+		}
+		const initializeRequest = method === "POST" && parsedBody && isInitializeRequest(parsedBody);
+		if (!existing) {
+			if (!initializeRequest) return createJsonErrorResponse(method === "DELETE" ? 404 : 400, "MCP session not initialized. Start with an initialize request against this endpoint.");
+			return (await createSession()).transport.handleRequest(request, parsedBody === void 0 ? void 0 : { parsedBody });
+		}
+		return existing.transport.handleRequest(request, parsedBody === void 0 ? void 0 : { parsedBody });
+	}
+	return {
+		GET: async ({ request }) => handle(request),
+		POST: async ({ request }) => handle(request),
+		DELETE: async ({ request }) => handle(request)
+	};
+}
+async function runDocsMcpStdio(options) {
+	const server = await createDocsMcpServer(options);
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+function createJsonErrorResponse(status, error) {
+	return new Response(JSON.stringify({ error }), {
+		status,
+		headers: { "Content-Type": "application/json" }
+	});
+}
+function normalizePathSegment(value) {
+	return value.replace(/^\/+|\/+$/g, "");
+}
+function titleize(value) {
+	return value.replace(/-/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
+}
+function stripMarkdownForMcp(content) {
+	return content.replace(/^(import|export)\s.*$/gm, "").replace(/<[^>]+\/>/g, "").replace(/<\/?[A-Z][^>]*>/g, "").replace(/<\/?[a-z][^>]*>/g, "").replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/^#{1,6}\s+/gm, "").replace(/(\*{1,3}|_{1,3})(.*?)\1/g, "$2").replace(/```[\s\S]*?```/g, "").replace(/`([^`]+)`/g, "$1").replace(/^>\s+/gm, "").replace(/^[-*_]{3,}\s*$/gm, "").replace(/\n{3,}/g, "\n\n").trim();
+}
+function scanFilesystemDocsPages(contentDirAbs, entry) {
+	const pages = [];
+	function scan(dir, slugParts) {
+		if (!fs.existsSync(dir)) return;
+		const entries = fs.readdirSync(dir).sort();
+		for (const name of entries) {
+			const full = path.join(dir, name);
+			if (fs.statSync(full).isDirectory()) {
+				scan(full, [...slugParts, name]);
+				continue;
+			}
+			if (!name.endsWith(".md") && !name.endsWith(".mdx") && !name.endsWith(".svx")) continue;
+			const { data, content } = matter(fs.readFileSync(full, "utf-8"));
+			const baseName = name.replace(/\.(md|mdx|svx)$/, "");
+			const isIndex = baseName === "index" || baseName === "page" || baseName === "+page";
+			const slug = isIndex ? slugParts.join("/") : [...slugParts, baseName].join("/");
+			const url = slug ? `/${entry}/${slug}` : `/${entry}`;
+			const title = data.title ?? (isIndex ? slugParts.length > 0 ? titleize(slugParts[slugParts.length - 1]) : "Documentation" : titleize(baseName));
+			pages.push({
+				slug,
+				url,
+				title,
+				description: data.description,
+				icon: data.icon,
+				content: stripMarkdownForMcp(content),
+				rawContent: content,
+				order: typeof data.order === "number" ? data.order : Number.POSITIVE_INFINITY
+			});
+		}
+	}
+	scan(contentDirAbs, []);
+	return pages;
+}
+function buildNavigationTreeFromPages(pages, siteTitle, ordering) {
+	const bySlug = new Map(pages.map((page) => [page.slug, page]));
+	const rootPage = bySlug.get("");
+	function childOrderFor(parentSlug) {
+		if (!Array.isArray(ordering)) return void 0;
+		if (!parentSlug) return ordering;
+		let items = ordering;
+		for (const segment of parentSlug.split("/")) {
+			items = (items?.find((item) => item.slug === segment))?.children;
+			if (!items) return void 0;
+		}
+		return items;
+	}
+	function sortChildSlugs(childSlugs, parentSlug) {
+		const explicitOrder = childOrderFor(parentSlug);
+		if (explicitOrder) {
+			const explicit = new Set(explicitOrder.map((item) => item.slug));
+			const ordered = [];
+			for (const item of explicitOrder) {
+				const childSlug = parentSlug ? `${parentSlug}/${item.slug}` : item.slug;
+				if (childSlugs.includes(childSlug)) ordered.push(childSlug);
+			}
+			for (const childSlug of childSlugs) {
+				const segment = childSlug.split("/").pop() ?? childSlug;
+				if (!explicit.has(segment)) ordered.push(childSlug);
+			}
+			return ordered;
+		}
+		if (ordering === "numeric") return [...childSlugs].sort((left, right) => {
+			const leftPage = bySlug.get(left);
+			const rightPage = bySlug.get(right);
+			const leftOrder = leftPage?.order ?? Number.POSITIVE_INFINITY;
+			const rightOrder = rightPage?.order ?? Number.POSITIVE_INFINITY;
+			if (leftOrder !== rightOrder) return leftOrder - rightOrder;
+			return left.localeCompare(right);
+		});
+		return [...childSlugs].sort((left, right) => left.localeCompare(right));
+	}
+	function buildLevel(parentSlug) {
+		const prefix = parentSlug ? `${parentSlug}/` : "";
+		const childSet = /* @__PURE__ */ new Set();
+		for (const page of pages) {
+			if (!page.slug.startsWith(prefix) || page.slug === parentSlug) continue;
+			const remainder = page.slug.slice(prefix.length);
+			if (!remainder) continue;
+			const [firstSegment] = remainder.split("/");
+			childSet.add(parentSlug ? `${parentSlug}/${firstSegment}` : firstSegment);
+		}
+		const childSlugs = sortChildSlugs([...childSet], parentSlug);
+		const nodes = [];
+		for (const childSlug of childSlugs) {
+			const page = bySlug.get(childSlug);
+			const hasChildren = pages.some((candidate) => candidate.slug.startsWith(`${childSlug}/`));
+			const segment = childSlug.split("/").pop() ?? childSlug;
+			const name = page?.title ?? titleize(segment);
+			const icon = page?.icon;
+			const description = page?.description;
+			if (hasChildren) {
+				nodes.push({
+					type: "folder",
+					name,
+					icon,
+					index: page ? {
+						type: "page",
+						name: page.title,
+						url: page.url,
+						icon: page.icon,
+						description: page.description
+					} : void 0,
+					children: buildLevel(childSlug)
+				});
+				continue;
+			}
+			if (!page) continue;
+			nodes.push({
+				type: "page",
+				name,
+				url: page.url,
+				icon,
+				description
+			});
+		}
+		return nodes;
+	}
+	const children = [];
+	if (rootPage) children.push({
+		type: "page",
+		name: rootPage.title,
+		url: rootPage.url,
+		icon: rootPage.icon,
+		description: rootPage.description
+	});
+	children.push(...buildLevel(""));
+	return {
+		name: siteTitle,
+		children
+	};
+}
+function dedupePages(pages) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const page of pages) seen.set(page.url, page);
+	return [...seen.values()];
+}
+function toPageSummaries(pages) {
+	return pages.map((page) => ({
+		slug: page.slug,
+		url: page.url,
+		title: page.title,
+		description: page.description,
+		icon: page.icon
+	}));
+}
+function findDocsPage(pages, requestedPath, entry) {
+	const normalizedRequest = normalizeRequestedPath(requestedPath, entry);
+	for (const page of pages) if (normalizeUrlPath(page.url) === normalizedRequest) return page;
+	const normalizedSlug = normalizePathSegment(requestedPath.replace(/^\//, ""));
+	for (const page of pages) if (normalizePathSegment(page.slug) === normalizedSlug) return page;
+	return null;
+}
+function normalizeRequestedPath(requestedPath, entry) {
+	const trimmed = requestedPath.trim();
+	if (!trimmed) return "/";
+	if (/^https?:\/\//i.test(trimmed)) try {
+		return normalizeUrlPath(new URL(trimmed).pathname);
+	} catch {
+		return "/";
+	}
+	const normalized = normalizeUrlPath(trimmed.startsWith("/") ? trimmed : `/${trimmed}`);
+	if (!entry) return normalized;
+	const normalizedEntry = `/${normalizePathSegment(entry)}`;
+	if (normalized === normalizedEntry || normalized.startsWith(`${normalizedEntry}/`)) return normalized;
+	const slug = normalizePathSegment(trimmed);
+	return slug ? normalizeUrlPath(`${normalizedEntry}/${slug}`) : normalizedEntry;
+}
+function normalizeUrlPath(value) {
+	const normalized = value.replace(/\/+/g, "/");
+	if (normalized === "/") return normalized;
+	return normalized.replace(/\/+$/, "");
+}
+function searchDocsPages(pages, query, limit) {
+	const normalizedQuery = query.toLowerCase().trim();
+	if (!normalizedQuery) return [];
+	const words = normalizedQuery.split(/\s+/).filter(Boolean);
+	return pages.map((page) => {
+		const titleScore = page.title.toLowerCase().includes(normalizedQuery) ? 10 : 0;
+		const descriptionScore = page.description?.toLowerCase().includes(normalizedQuery) ? 4 : 0;
+		const contentScore = words.reduce((score, word) => {
+			return score + (page.content.toLowerCase().includes(word) ? 1 : 0);
+		}, 0);
+		return {
+			slug: page.slug,
+			url: page.url,
+			title: page.title,
+			description: page.description,
+			icon: page.icon,
+			excerpt: buildExcerpt(page, words),
+			score: titleScore + descriptionScore + contentScore
+		};
+	}).filter((page) => page.score > 0).sort((left, right) => right.score - left.score).slice(0, limit).map(({ score: _score, ...page }) => page);
+}
+function buildExcerpt(page, words) {
+	const haystack = page.rawContent ?? page.content;
+	const lower = haystack.toLowerCase();
+	const firstHit = words.find((word) => lower.includes(word.toLowerCase()));
+	if (!firstHit) return page.description;
+	const index = lower.indexOf(firstHit.toLowerCase());
+	const start = Math.max(0, index - 80);
+	const end = Math.min(haystack.length, index + 140);
+	const excerpt = haystack.slice(start, end).replace(/\s+/g, " ").trim();
+	return excerpt.length > 0 ? excerpt : page.description;
+}
+function renderPageDocument(page) {
+	const lines = [`# ${page.title}`, `URL: ${page.url}`];
+	if (page.description) lines.push(`Description: ${page.description}`);
+	lines.push("", page.rawContent ?? page.content);
+	return lines.join("\n");
+}
+function renderNavigationTree(tree) {
+	const lines = [`# ${tree.name}`, ""];
+	function visit(nodes, depth) {
+		const prefix = "  ".repeat(depth);
+		for (const node of nodes) {
+			if (node.type === "page") {
+				lines.push(`${prefix}- ${node.name} (${node.url})`);
+				continue;
+			}
+			lines.push(`${prefix}- ${node.name}`);
+			if (node.index) lines.push(`${prefix}  - Overview (${node.index.url})`);
+			visit(node.children, depth + 1);
+		}
+	}
+	visit(tree.children, 0);
+	return lines.join("\n");
+}
+function slugToKey(slug) {
+	const normalized = normalizePathSegment(slug);
+	return normalized.length > 0 ? normalized.replace(/\//g, "-") : "index";
+}
+function toPageResourceUri(url) {
+	return `docs://${normalizePathSegment(url.replace(/^\//, "")) || "docs"}`;
+}
+
+//#endregion
+export { createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio };