@farming-labs/docs 0.2.73 → 0.2.75

package/dist/mcp.mjs

@@ -1,8 +1,8 @@
 import { a as emitDocsAnalyticsEvent, i as emitDocsAgentTraceEvent, n as createDocsAgentTraceContext, r as createDocsAgentTraceId } from "./analytics-Bx44lg6d.mjs";
-import { Kt as normalizeDocsRelated, an as isDocsMcpResourcePath, cn as resolveDocsMcpProtectedResourceMetadataLocation, jt as resolveDocsAudienceMdxContent, ln as resolveDocsMcpResourceLocation, nn as isDocsMcpOAuthScopeToken, on as normalizeDocsMcpAuthorizationServerUrls, qt as renderDocsRelatedMarkdownLines, rn as isDocsMcpProtectedResourceMetadataPath, sn as normalizeDocsMcpEndpointPath } from "./agent-o9OTadrf.mjs";
+import { E as DOCS_MARKDOWN_SECTION_INDEX_FORMAT, Kt as normalizeDocsRelated, P as buildDocsMarkdownSectionIndex, an as isDocsMcpResourcePath, cn as resolveDocsMcpProtectedResourceMetadataLocation, jt as resolveDocsAudienceMdxContent, ln as resolveDocsMcpResourceLocation, nn as isDocsMcpOAuthScopeToken, on as normalizeDocsMcpAuthorizationServerUrls, qt as renderDocsRelatedMarkdownLines, rn as isDocsMcpProtectedResourceMetadataPath, sn as normalizeDocsMcpEndpointPath, wt as toDocsMarkdownUrl } from "./agent-BHqaZx-X.mjs";
 import { S as upsertPageAgentContractMarkdown, _ as hasStructuredPageAgentContract, o as findDocsMarkdownSection, s as parseDocsMarkdownSections, v as normalizePageAgentFrontmatter } from "./markdown-sections-7OoA7ylx.mjs";
 import "./standards-discovery-BwL5ffGx.mjs";
-import { A as stripGeneratedAgentProvenance, F as emitDocsTelemetryAgentSurfaceEvent, L as emitDocsTelemetryMcpToolEvent, M as resolvePageSidebarFolderIndexBehavior, R as emitDocsTelemetryProjectEvent, S as normalizeAgentScopeValues, b as normalizeAgentFramework, d as performDocsSearch, f as performDocsSearchWithMetadata, u as normalizeDocsSearchFilters, v as agentVersionConstraintMatches, x as normalizeAgentLocale, y as agentVersionConstraintsOverlap } from "./search-RfPcG1if.mjs";
+import { C as agentVersionConstraintsOverlap, E as normalizeAgentScopeValues, I as stripGeneratedAgentProvenance, R as resolvePageSidebarFolderIndexBehavior, S as agentVersionConstraintMatches, T as normalizeAgentLocale, U as emitDocsTelemetryMcpToolEvent, V as emitDocsTelemetryAgentSurfaceEvent, W as emitDocsTelemetryProjectEvent, f as normalizeDocsSearchFilters, k as isDocsRetrievalCanonicalUrl, m as performDocsSearchWithMetadata, p as performDocsSearch, w as normalizeAgentFramework } from "./search-BmC8wVr0.mjs";
 import matter from "gray-matter";
 import fs from "node:fs";
 import path from "node:path";
@@ -1254,18 +1254,27 @@ const DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE = [
 		default: true,
 		description: "Built-in simple search, Typesense, Algolia, MCP, or a custom adapter.",
 		docs: "/docs/customization/search",
-		children: [{
-			path: "search.provider",
-			name: "provider",
-			type: "\"simple\" | \"typesense\" | \"algolia\" | \"mcp\" | \"custom\"",
-			default: "simple",
-			description: "Search backend used by the docs UI and MCP search tool."
-		}, {
-			path: "search.maxResults",
-			name: "maxResults",
-			type: "number",
-			description: "Maximum result count returned by search requests."
-		}]
+		children: [
+			{
+				path: "search.provider",
+				name: "provider",
+				type: "\"simple\" | \"typesense\" | \"algolia\" | \"mcp\" | \"custom\"",
+				default: "simple",
+				description: "Search backend used by the docs UI and MCP search tool."
+			},
+			{
+				path: "search.maxResults",
+				name: "maxResults",
+				type: "number",
+				description: "Maximum result count returned by search requests."
+			},
+			{
+				path: "search.syncNamespace",
+				name: "syncNamespace",
+				type: "string",
+				description: "Stable ownership namespace used to isolate and safely prune this corpus in a shared hosted index."
+			}
+		]
 	},
 	{
 		path: "cloud",
@@ -1479,6 +1488,13 @@ const DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE = [
 						default: true,
 						description: "Expose the list_pages tool."
 					},
+					{
+						path: "mcp.tools.listPageSections",
+						name: "listPageSections",
+						type: "boolean",
+						default: true,
+						description: "Expose the body-free list_page_sections discovery tool for page headings, anchors, hierarchy, sizes, and follow-up fetch URLs."
+					},
 					{
 						path: "mcp.tools.listTasks",
 						name: "listTasks",
@@ -1691,7 +1707,7 @@ const searchFilterValueSchema = z.union([z.string().trim().min(1).max(128), z.ar
 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(),
+	locale: z.string().trim().min(1).max(128).optional(),
 	audience: z.enum(["human", "agent"]).optional(),
 	framework: searchFilterValueSchema.optional(),
 	version: searchFilterValueSchema.optional(),
@@ -1700,16 +1716,22 @@ const searchDocsInputSchema = z.object({
 });
 const readPageInputSchema = z.object({
 	path: z.string().min(1),
-	locale: z.string().min(1).optional(),
+	locale: z.string().trim().min(1).max(128).optional(),
 	section: z.string().trim().min(1).optional(),
 	maxChars: z.number().int().min(256).max(1e6).optional()
 });
+const listPageSectionsInputSchema = z.object({
+	path: z.string().min(1),
+	locale: z.string().trim().min(1).max(128).optional(),
+	tokenBudget: z.number().int().min(1).max(1e6).optional(),
+	byteBudget: z.number().int().min(1).max(1e6).optional()
+});
 const listTasksInputSchema = z.object({
 	query: z.string().trim().min(1).optional(),
 	framework: z.string().trim().min(1).optional(),
 	version: z.string().trim().min(1).optional(),
 	package: z.string().trim().min(1).optional(),
-	locale: z.string().min(1).optional()
+	locale: z.string().trim().min(1).max(128).optional()
 });
 const readTaskInputSchema = readPageInputSchema;
 const pageAgentAppliesToOutputSchema = z.object({
@@ -1768,12 +1790,12 @@ const readTaskOutputSchema = z.object({
 	}),
 	contract: pageAgentContractOutputSchema
 });
-const listPagesInputSchema = z.object({ locale: z.string().min(1).optional() });
+const listPagesInputSchema = z.object({ locale: z.string().trim().min(1).max(128).optional() });
 const listDocsInputSchema = z.object({
 	section: z.string().trim().min(1).optional(),
-	locale: z.string().min(1).optional()
+	locale: z.string().trim().min(1).max(128).optional()
 });
-const getNavigationInputSchema = z.object({ locale: z.string().min(1).optional() });
+const getNavigationInputSchema = z.object({ locale: z.string().trim().min(1).max(128).optional() });
 const getConfigSchemaInputSchema = z.object({
 	option: z.string().trim().min(1).optional(),
 	query: z.string().trim().min(1).optional()
@@ -1786,7 +1808,7 @@ const getCodeExamplesInputSchema = z.object({
 	language: z.string().trim().min(1).optional(),
 	runnable: z.boolean().optional(),
 	limit: z.number().int().min(1).max(50).optional(),
-	locale: z.string().min(1).optional()
+	locale: z.string().trim().min(1).max(128).optional()
 });
 const getContextInputSchema = z.object({
 	query: z.string().trim().min(1),
@@ -1794,7 +1816,7 @@ const getContextInputSchema = z.object({
 	version: z.string().trim().min(1).optional(),
 	package: searchFilterValueSchema.optional(),
 	tags: searchFilterValueSchema.optional(),
-	locale: z.string().trim().min(1).optional(),
+	locale: z.string().trim().min(1).max(128).optional(),
 	tokenBudget: z.number().int().min(MIN_MCP_CONTEXT_TOKEN_BUDGET).max(MAX_MCP_CONTEXT_TOKEN_BUDGET).default(DEFAULT_MCP_CONTEXT_TOKEN_BUDGET)
 });
 const relatedLinkOutputSchema = z.object({ href: z.string() });
@@ -1854,6 +1876,37 @@ const navigationOutputSchema = z.object({
 	}),
 	markdown: z.string()
 });
+const retrievalSourceValueOutputSchema = z.string().max(128);
+const retrievalSourceValuesOutputSchema = z.array(retrievalSourceValueOutputSchema).max(16);
+const retrievalSourceScopeOutputSchema = z.object({
+	audience: z.enum(["human", "agent"]),
+	locale: retrievalSourceValuesOutputSchema.optional(),
+	framework: retrievalSourceValuesOutputSchema.optional(),
+	version: retrievalSourceValuesOutputSchema.optional(),
+	versionGroups: z.array(retrievalSourceValuesOutputSchema).max(16).optional(),
+	package: retrievalSourceValuesOutputSchema.optional(),
+	tags: retrievalSourceValuesOutputSchema.optional(),
+	truncated: z.array(z.enum([
+		"framework",
+		"version",
+		"package",
+		"tags"
+	])).max(4).optional(),
+	conflicts: z.array(z.enum([
+		"framework",
+		"version",
+		"package",
+		"tags"
+	])).max(4).optional()
+});
+const retrievalSourceDigestOutputSchema = z.string().regex(/^sha256:[a-f\d]{64}$/iu);
+const retrievalSourceOutputSchema = z.object({
+	canonicalUrl: z.string().max(4096).refine(isDocsRetrievalCanonicalUrl, "Expected a safe HTTP(S) URL or root-relative path"),
+	scope: retrievalSourceScopeOutputSchema,
+	lastModified: z.string().max(256).refine((value) => Number.isFinite(Date.parse(value)), "Expected a parseable modified time").optional(),
+	digest: retrievalSourceDigestOutputSchema,
+	indexGeneration: retrievalSourceDigestOutputSchema
+});
 const searchResultOutputSchema = z.object({
 	id: z.string(),
 	url: z.string(),
@@ -1865,7 +1918,8 @@ const searchResultOutputSchema = z.object({
 		"text"
 	]),
 	score: z.number().optional(),
-	section: z.string().optional()
+	section: z.string().optional(),
+	source: retrievalSourceOutputSchema.optional()
 });
 const searchFiltersOutputSchema = z.object({
 	framework: z.array(z.string()).optional(),
@@ -1896,6 +1950,7 @@ const searchDocsOutputSchema = z.object({
 	query: z.string(),
 	audience: z.enum(["human", "agent"]),
 	filters: searchFiltersOutputSchema,
+	indexGeneration: retrievalSourceDigestOutputSchema,
 	resultCount: z.number().int().nonnegative(),
 	results: z.array(searchResultOutputSchema),
 	warnings: z.array(searchWarningOutputSchema)
@@ -1971,6 +2026,34 @@ const readPageOutputSchema = z.object({
 	totalChars: z.number().int().nonnegative(),
 	truncated: z.boolean()
 });
+const pageSectionMetadataOutputSchema = z.object({
+	id: z.string(),
+	heading: z.string(),
+	level: z.number().int().positive(),
+	parentId: z.string().optional(),
+	startLine: z.number().int().positive(),
+	endLine: z.number().int().positive(),
+	estimatedTokens: z.number().int().nonnegative(),
+	utf8Bytes: z.number().int().nonnegative(),
+	canonicalUrl: z.string(),
+	markdownUrl: z.string()
+});
+const pageSectionIndexOutputSchema = z.object({
+	schemaVersion: z.literal(2),
+	format: z.literal(DOCS_MARKDOWN_SECTION_INDEX_FORMAT),
+	canonicalUrl: z.string(),
+	markdownUrl: z.string(),
+	sectionIndexUrl: z.string(),
+	lineNumbering: z.literal("body"),
+	sectionCount: z.number().int().nonnegative(),
+	estimatedTokens: z.number().int().nonnegative(),
+	utf8Bytes: z.number().int().nonnegative(),
+	fetchBudget: z.object({
+		tokenBudget: z.number().int().positive().optional(),
+		byteBudget: z.number().int().positive().optional()
+	}).optional(),
+	sections: z.array(pageSectionMetadataOutputSchema)
+});
 const contextSourceOutputSchema = z.object({
 	id: z.string(),
 	title: z.string(),
@@ -1985,6 +2068,7 @@ const contextSourceOutputSchema = z.object({
 	version: z.string().optional(),
 	package: z.array(z.string()).optional(),
 	tags: z.array(z.string()).optional(),
+	source: retrievalSourceOutputSchema.optional(),
 	score: z.number().optional(),
 	content: z.string(),
 	chars: z.number().int().nonnegative(),
@@ -2026,6 +2110,7 @@ function resolveDocsMcpConfig(mcp, defaults = {}) {
 		tools: {
 			listDocs: true,
 			listPages: true,
+			listPageSections: true,
 			readPage: true,
 			listTasks: true,
 			readTask: true,
@@ -2046,6 +2131,7 @@ function resolveDocsMcpConfig(mcp, defaults = {}) {
 		tools: {
 			listDocs: config.tools?.listDocs ?? true,
 			listPages: config.tools?.listPages ?? true,
+			listPageSections: config.tools?.listPageSections ?? true,
 			readPage: config.tools?.readPage ?? true,
 			listTasks: config.tools?.listTasks ?? true,
 			readTask: config.tools?.readTask ?? true,
@@ -2156,6 +2242,8 @@ function createFilesystemDocsMcpSource(options = {}) {
 	return {
 		entry,
 		siteTitle: options.siteTitle ?? "Documentation",
+		baseUrl: options.baseUrl,
+		resolveLocale: () => void 0,
 		getPages,
 		getNavigation
 	};
@@ -2192,10 +2280,13 @@ async function createDocsMcpServer(options) {
 	};
 	const telemetryFramework = options.telemetryFramework ?? "mcp";
 	function getSourcePages(locale) {
-		return options.source.getPages(locale, options.requestContext);
+		return options.source.getPages(resolveSourceLocale(locale), options.requestContext);
 	}
 	function getSourceNavigation(locale) {
-		return options.source.getNavigation(locale, options.requestContext);
+		return options.source.getNavigation(resolveSourceLocale(locale), options.requestContext);
+	}
+	function resolveSourceLocale(locale) {
+		return options.source.resolveLocale ? options.source.resolveLocale(locale, options.requestContext) : locale;
 	}
 	function getSourceSkills() {
 		return options.source.getSkills?.(options.requestContext) ?? [];
@@ -2811,6 +2902,7 @@ async function createDocsMcpServer(options) {
 		const startedAt = nowMs();
 		const resolvedLimit = limit ?? 10;
 		const resolvedAudience = audience ?? "agent";
+		const resolvedLocale = resolveSourceLocale(locale);
 		const filters = {
 			framework,
 			version,
@@ -2839,13 +2931,15 @@ async function createDocsMcpServer(options) {
 		});
 		try {
 			const searchResponse = await performDocsSearchWithMetadata({
-				pages: toSearchSourcePages(dedupePages(await getSourcePages(locale))),
+				pages: toSearchSourcePages(dedupePages(await options.source.getPages(resolvedLocale, options.requestContext))),
 				query,
 				search: toolSearchConfig ?? true,
 				audience: resolvedAudience,
 				filters,
-				locale,
+				locale: resolvedLocale,
 				siteTitle: options.source.siteTitle,
+				baseUrl: options.source.baseUrl ?? (options.requestContext?.request ? new URL(options.requestContext.request.url).origin : void 0),
+				syncBaseUrl: options.source.baseUrl ?? null,
 				limit: resolvedLimit
 			});
 			const elapsed = durationMs(startedAt);
@@ -3012,6 +3106,7 @@ async function createDocsMcpServer(options) {
 		annotations: { readOnlyHint: true }
 	}, async ({ query, framework, version, package: packageName, tags, locale, tokenBudget }) => {
 		const startedAt = nowMs();
+		const resolvedLocale = resolveSourceLocale(locale);
 		const trace = createDocsAgentTraceContext("mcp.tool.get_context");
 		const callSpanId = createDocsAgentTraceId("span");
 		await emitDocsAgentTraceEvent(options.observability, {
@@ -3036,16 +3131,17 @@ async function createDocsMcpServer(options) {
 		});
 		try {
 			const result = await buildDocsMcpContext({
-				pages: dedupePages(await getSourcePages(locale)),
+				pages: dedupePages(await options.source.getPages(resolvedLocale, options.requestContext)),
 				query,
 				framework,
 				version,
 				package: packageName,
 				tags,
-				locale,
+				locale: resolvedLocale,
 				tokenBudget,
 				entry: options.source.entry,
-				siteTitle: options.source.siteTitle
+				siteTitle: options.source.siteTitle,
+				baseUrl: options.source.baseUrl ?? (options.requestContext?.request ? new URL(options.requestContext.request.url).origin : void 0)
 			});
 			const elapsed = durationMs(startedAt);
 			await emitDocsAnalyticsEvent(options.analytics, {
@@ -3112,6 +3208,154 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
+	if (resolved.tools.listPageSections !== false) server.registerTool("list_page_sections", {
+		title: "List sections in a docs page",
+		description: "Discover a page's canonical headings, anchors, hierarchy, line ranges, size estimates, and budget-aware fetch URLs without returning the page body.",
+		inputSchema: listPageSectionsInputSchema,
+		outputSchema: pageSectionIndexOutputSchema,
+		annotations: { readOnlyHint: true }
+	}, async ({ path: requestedPath, locale, tokenBudget, byteBudget }) => {
+		const startedAt = nowMs();
+		const resolvedLocale = resolveSourceLocale(locale);
+		const trace = createDocsAgentTraceContext("mcp.tool.list_page_sections");
+		const callSpanId = createDocsAgentTraceId("span");
+		await emitDocsAgentTraceEvent(options.observability, {
+			type: "tool.call",
+			source: "mcp",
+			traceId: trace.traceId,
+			spanId: callSpanId,
+			name: "list_page_sections",
+			startedAt: trace.startedAt,
+			status: "started",
+			locale: resolvedLocale,
+			inputPreview: {
+				path: requestedPath,
+				locale,
+				resolvedLocale,
+				tokenBudget,
+				byteBudget
+			},
+			metadata: { tool: "list_page_sections" }
+		});
+		try {
+			const page = findDocsPage(dedupePages(await options.source.getPages(resolvedLocale, options.requestContext)), requestedPath, options.source.entry);
+			if (!page) {
+				const elapsed = durationMs(startedAt);
+				await emitDocsAnalyticsEvent(options.analytics, {
+					type: "mcp_tool",
+					source: "mcp",
+					locale: resolvedLocale,
+					properties: {
+						tool: "list_page_sections",
+						requestedPath,
+						found: false,
+						durationMs: elapsed
+					}
+				});
+				trackMcpTool("list_page_sections", {
+					locale: resolvedLocale,
+					resultCount: 0
+				});
+				await emitDocsAgentTraceEvent(options.observability, {
+					type: "tool.error",
+					source: "mcp",
+					traceId: trace.traceId,
+					parentSpanId: callSpanId,
+					name: "list_page_sections",
+					startedAt: trace.startedAt,
+					endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+					durationMs: elapsed,
+					status: "error",
+					locale: resolvedLocale,
+					outputPreview: {
+						found: false,
+						path: requestedPath
+					},
+					metadata: {
+						tool: "list_page_sections",
+						reason: "not_found"
+					}
+				});
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify({ error: `No docs page matched "${requestedPath}".` }, null, 2)
+					}],
+					isError: true
+				};
+			}
+			const document = upsertPageAgentContractMarkdown(getDocsMcpSourceMarkdown(page), page.agent);
+			const publicBaseUrl = options.source.baseUrl ?? (options.requestContext?.request ? new URL(options.requestContext.request.url).origin : void 0);
+			const sectionIndex = buildDocsMarkdownSectionIndex(document, {
+				canonicalUrl: resolveDocsMcpPublicUrl(withDocsMcpUrlLocale(page.url, resolvedLocale), publicBaseUrl),
+				markdownUrl: resolveDocsMcpPublicUrl(toDocsMcpPageMarkdownUrl(page.url, resolvedLocale), publicBaseUrl),
+				tokenBudget,
+				byteBudget
+			});
+			const elapsed = durationMs(startedAt);
+			await emitDocsAnalyticsEvent(options.analytics, {
+				type: "mcp_tool",
+				source: "mcp",
+				locale: resolvedLocale,
+				path: page.url,
+				properties: {
+					tool: "list_page_sections",
+					requestedPath,
+					slug: page.slug,
+					found: true,
+					sectionCount: sectionIndex.sectionCount,
+					estimatedTokens: sectionIndex.estimatedTokens,
+					utf8Bytes: sectionIndex.utf8Bytes,
+					tokenBudget,
+					byteBudget,
+					durationMs: elapsed
+				}
+			});
+			trackMcpTool("list_page_sections", {
+				locale: resolvedLocale,
+				resultCount: sectionIndex.sectionCount
+			});
+			await emitDocsAgentTraceEvent(options.observability, {
+				type: "tool.result",
+				source: "mcp",
+				traceId: trace.traceId,
+				parentSpanId: callSpanId,
+				name: "list_page_sections",
+				startedAt: trace.startedAt,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				durationMs: elapsed,
+				status: "success",
+				locale: resolvedLocale,
+				path: page.url,
+				outputPreview: {
+					found: true,
+					slug: page.slug,
+					sectionCount: sectionIndex.sectionCount,
+					estimatedTokens: sectionIndex.estimatedTokens,
+					utf8Bytes: sectionIndex.utf8Bytes
+				},
+				metadata: { tool: "list_page_sections" }
+			});
+			return createStructuredTextResult(sectionIndex);
+		} catch (error) {
+			const elapsed = durationMs(startedAt);
+			await emitDocsAgentTraceEvent(options.observability, {
+				type: "tool.error",
+				source: "mcp",
+				traceId: trace.traceId,
+				parentSpanId: callSpanId,
+				name: "list_page_sections",
+				startedAt: trace.startedAt,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				durationMs: elapsed,
+				status: "error",
+				locale: resolvedLocale,
+				outputPreview: { message: error instanceof Error ? error.message : "Unknown error" },
+				metadata: { tool: "list_page_sections" }
+			});
+			throw error;
+		}
+	});
 	if (resolved.tools.readPage) server.registerTool("read_page", {
 		title: "Read a docs page",
 		description: "Read a documentation page by slug or URL path, optionally selecting one heading and limiting returned characters.",
@@ -3831,6 +4075,10 @@ function hasVisibleDescendantFilesystemDocsPage(dir) {
 	}
 	return false;
 }
+function normalizeFrontmatterLastmod(value) {
+	if (typeof value === "string") return value;
+	return value instanceof Date && Number.isFinite(value.getTime()) ? value.toISOString() : void 0;
+}
 function scanFilesystemDocsPages(contentDirAbs, entry, rootDir) {
 	const pages = [];
 	function scan(dir, slugParts) {
@@ -3865,6 +4113,7 @@ function scanFilesystemDocsPages(contentDirAbs, entry, rootDir) {
 				agent: normalizePageAgentFrontmatter(data.agent),
 				icon: data.icon,
 				sourcePath: path.relative(rootDir, full).replace(/\\/g, "/"),
+				lastmod: normalizeFrontmatterLastmod(data.lastmod),
 				lastModified: stat.mtime.toISOString(),
 				locale: typeof data.locale === "string" ? data.locale : void 0,
 				framework: typeof data.framework === "string" ? data.framework : void 0,
@@ -3889,7 +4138,8 @@ function readFilesystemAgentDoc(dir) {
 	const agentContent = resolveDocsAudienceMdxContent(content, "agent");
 	return {
 		agentContent: stripMarkdownForMcp(agentContent),
-		agentRawContent: agentContent
+		agentRawContent: agentContent,
+		agentLastModified: fs.statSync(agentPath).mtime.toISOString()
 	};
 }
 function resolveRelatedForMcpPages(pages) {
@@ -4005,25 +4255,7 @@ function dedupePages(pages) {
 	return [...seen.values()];
 }
 function toSearchSourcePages(pages) {
-	return pages.map((page) => ({
-		title: page.title,
-		url: page.url,
-		content: page.content,
-		rawContent: page.rawContent,
-		sourcePath: page.sourcePath,
-		lastModified: page.lastModified,
-		locale: page.locale,
-		framework: page.framework,
-		version: page.version,
-		tags: page.tags,
-		agentContent: page.agentContent,
-		agentRawContent: page.agentRawContent,
-		agentFallbackContent: page.agentFallbackContent,
-		agentFallbackRawContent: page.agentFallbackRawContent,
-		description: page.description,
-		related: page.related,
-		agent: page.agent
-	}));
+	return pages;
 }
 function getDocsConfigSchema(filters = {}) {
 	const option = filters.option?.trim();
@@ -4570,6 +4802,35 @@ function toStructuredDocsMcpPage(page) {
 		tags: page.tags
 	};
 }
+function withDocsMcpUrlLocale(value, locale) {
+	if (!locale) return value;
+	const absolute = /^[a-z][a-z\d+.-]*:/iu.test(value);
+	try {
+		const url = new URL(value, "https://docs.invalid");
+		if (!url.searchParams.has("lang")) url.searchParams.set("lang", locale);
+		return absolute ? url.toString() : `${url.pathname}${url.search}${url.hash}`;
+	} catch {
+		return value;
+	}
+}
+function toDocsMcpPageMarkdownUrl(value, locale) {
+	const absolute = /^[a-z][a-z\d+.-]*:/iu.test(value);
+	try {
+		const url = new URL(value, "https://docs.invalid");
+		const markdownPath = toDocsMarkdownUrl(`${url.pathname}${url.search}${url.hash}`, { locale });
+		return absolute ? new URL(markdownPath, url.origin).toString() : markdownPath;
+	} catch {
+		return toDocsMarkdownUrl(value, { locale });
+	}
+}
+function resolveDocsMcpPublicUrl(value, baseUrl) {
+	if (!baseUrl || /^[a-z][a-z\d+.-]*:/iu.test(value)) return value;
+	try {
+		return new URL(value, `${baseUrl.replace(/\/+$/u, "")}/`).toString();
+	} catch {
+		return value;
+	}
+}
 function getDocsMcpSourceMarkdown(page) {
 	return page.agentRawContent ?? page.agentFallbackRawContent ?? page.agentContent ?? page.agentFallbackContent ?? page.rawContent ?? page.content;
 }
@@ -4637,10 +4898,13 @@ async function buildDocsMcpContext(options) {
 		}] : [];
 	});
 	const scopedPages = scopedPageEntries.map(({ page }) => page);
+	const allSearchPages = toSearchSourcePages([...options.pages]);
+	const searchPageBySource = new Map(options.pages.map((page, index) => [page, allSearchPages[index]]));
 	const scopeByPage = new Map(scopedPageEntries.map(({ page, scope }) => [page, scope]));
 	const maxResults = typeof options.maxResults === "number" && Number.isFinite(options.maxResults) ? Math.max(1, Math.min(50, Math.floor(options.maxResults))) : 50;
 	const orderedResults = [...await performDocsSearch({
-		pages: toSearchSourcePages(scopedPages),
+		pages: scopedPages.map((page) => searchPageBySource.get(page)),
+		generationPages: allSearchPages,
 		query: options.query,
 		search: {
 			enabled: true,
@@ -4651,6 +4915,7 @@ async function buildDocsMcpContext(options) {
 		audience: "agent",
 		locale: options.locale,
 		siteTitle: options.siteTitle,
+		baseUrl: options.baseUrl,
 		limit: 50
 	})].sort((left, right) => {
 		const scoreDelta = (right.score ?? 0) - (left.score ?? 0);
@@ -4696,7 +4961,7 @@ async function buildDocsMcpContext(options) {
 	let usedUtf8Bytes = 0;
 	for (const { result, page, scope, selectedSection, rawContent } of resolvedCandidates) {
 		const anchor = selectedSection?.anchor;
-		const sourceUrl = anchor ? `${page.url.split("#", 1)[0]}#${encodeURIComponent(anchor)}` : page.url;
+		const sourceUrl = result.source?.canonicalUrl ?? (anchor ? `${page.url.split("#", 1)[0]}#${encodeURIComponent(anchor)}` : page.url);
 		const headerLines = [`## ${page.title}`, `Source: ${sourceUrl}`];
 		if (selectedSection?.title) headerLines.push(`Section: ${selectedSection.title}`);
 		if (scope.framework) headerLines.push(`Framework: ${scope.framework}`);
@@ -4723,12 +4988,13 @@ async function buildDocsMcpContext(options) {
 			section: selectedSection?.title,
 			anchor,
 			sourcePath: page.sourcePath,
-			lastModified: page.lastModified,
+			lastModified: result.source?.lastModified ?? page.lastModified,
 			locale: scope.locale,
 			framework: scope.framework,
 			version: scope.version,
 			package: scope.package.length > 0 ? [...scope.package] : void 0,
 			tags: scope.tags.length > 0 ? [...scope.tags] : void 0,
+			source: result.source,
 			score: result.score,
 			content: limited.text,
 			chars: limited.text.length,
@@ -4770,11 +5036,25 @@ async function buildDocsMcpContext(options) {
 	};
 }
 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;
+	const normalizedRequest = normalizeDocsMcpPageIdentity(requestedPath, entry, true);
+	for (const page of pages) if (normalizeDocsMcpPageIdentity(page.url, entry, true) === normalizedRequest) return page;
+	const normalizedRequestPath = normalizeDocsMcpPageIdentity(requestedPath, entry, false);
+	const pathMatches = pages.filter((page) => normalizeDocsMcpPageIdentity(page.url, entry, false) === normalizedRequestPath);
+	if (pathMatches.length === 1) return pathMatches[0];
+	if (pathMatches.length > 1) return null;
+	const normalizedSlug = normalizePathSegment(normalizeDocsMcpPageIdentity(requestedPath, void 0, false).replace(/^\//u, ""));
+	const slugMatches = pages.filter((page) => normalizePathSegment(page.slug) === normalizedSlug);
+	return slugMatches.length === 1 ? slugMatches[0] : null;
+}
+function normalizeDocsMcpPageIdentity(value, entry, includeSearch) {
+	try {
+		const url = new URL(value, "https://docs.local");
+		if (includeSearch) url.searchParams.sort();
+		return `${normalizeRequestedPath(url.pathname, entry)}${includeSearch ? url.search : ""}`;
+	} catch {
+		const [pathname = value, search = ""] = value.split("?", 2);
+		return `${normalizeRequestedPath(pathname, entry)}${includeSearch && search ? `?${search}` : ""}`;
+	}
 }
 function normalizeRequestedPath(requestedPath, entry) {
 	const trimmed = requestedPath.trim();

package/dist/{prompt-references-Cz35rlOa.mjs → prompt-references-CfyYOa_W.mjs}

@@ -1,7 +1,7 @@
-import { It as DEFAULT_SITEMAP_XML_ROUTE, Pt as DEFAULT_SITEMAP_MD_ROUTE, Zt as DEFAULT_MCP_WELL_KNOWN_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, f as DEFAULT_DOCS_CONFIG_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, m as DEFAULT_DOCS_DIAGNOSTICS_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, x as DEFAULT_SKILL_MD_ROUTE } from "./agent-o9OTadrf.mjs";
+import { It as DEFAULT_SITEMAP_XML_ROUTE, Pt as DEFAULT_SITEMAP_MD_ROUTE, Zt as DEFAULT_MCP_WELL_KNOWN_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, f as DEFAULT_DOCS_CONFIG_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, m as DEFAULT_DOCS_DIAGNOSTICS_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, x as DEFAULT_SKILL_MD_ROUTE } from "./agent-BHqaZx-X.mjs";
 import { isDocsAgentSkillName, validateDocsAgentSkillFrontmatter } from "./agent-skills-spec.mjs";
 import { C as DOCS_AGENT_MANIFEST_SCHEMA_MEDIA_TYPE, S as DOCS_AGENT_MANIFEST_FORMAT, T as DOCS_AGENT_MANIFEST_VERSION, f as DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, n as API_CATALOG_MEDIA_TYPE, r as API_CATALOG_PROFILE_URI, t as AGENT_SKILLS_DISCOVERY_SCHEMA_URI, u as DEFAULT_AGENT_SKILLS_INDEX_ROUTE, v as DEFAULT_API_CATALOG_ROUTE, w as DOCS_AGENT_MANIFEST_SCHEMA_URI } from "./standards-discovery-BwL5ffGx.mjs";
-import { n as DEFAULT_ROBOTS_TXT_ROUTE } from "./robots-BcuxnZqZ.mjs";
+import { n as DEFAULT_ROBOTS_TXT_ROUTE } from "./robots-DaYBoy_A.mjs";
 import matter from "gray-matter";
 
 //#region src/define-docs.ts