@farming-labs/docs 0.1.1-beta.2 → 0.1.1

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";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types";
+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 };

package/dist/server.d.mts

@@ -1,4 +1,5 @@
-import { o as DocsConfig } from "./types-DpijZMth.mjs";
+import { o as DocsConfig } from "./types-Bd3kyFF1.mjs";
+import { DocsMcpHttpHandlers, DocsMcpNavigationNode, DocsMcpNavigationTree, DocsMcpPage, DocsMcpResolvedConfig, DocsMcpSource, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio } from "./mcp.mjs";
 
 //#region src/api-reference.d.ts
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
@@ -35,4 +36,4 @@ declare function buildApiReferenceOpenApiDocumentAsync(config: DocsConfig, optio
 declare function buildApiReferenceHtmlDocument(config: DocsConfig, options: BuildApiReferenceHtmlOptions): string;
 declare function buildApiReferenceHtmlDocumentAsync(config: DocsConfig, options: BuildApiReferenceHtmlOptions): Promise<string>;
 //#endregion
-export { type ApiReferenceFramework, type ApiReferenceRoute, type ResolvedApiReferenceConfig, buildApiReferenceHtmlDocument, buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocument, buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, resolveApiReferenceConfig };
+export { type ApiReferenceFramework, type ApiReferenceRoute, type DocsMcpHttpHandlers, type DocsMcpNavigationNode, type DocsMcpNavigationTree, type DocsMcpPage, type DocsMcpResolvedConfig, type DocsMcpSource, type ResolvedApiReferenceConfig, buildApiReferenceHtmlDocument, buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocument, buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, normalizeDocsMcpRoute, resolveApiReferenceConfig, resolveDocsMcpConfig, runDocsMcpStdio };