@farming-labs/docs 0.2.72 → 0.2.74

package/dist/{mcp-BNK45dzD.mjs → mcp-YD37HlPY.mjs}

@@ -1,13 +1,15 @@
-import "./agent-pS2nNQS3.mjs";
-import { I as resolveDocsPublishedAgentSkill } from "./standards-discovery-CYfiQE13.mjs";
-import "./search-BbArHODP.mjs";
-import "./sitemap-server-PUoOhplO.mjs";
-import "./agent-evals-CjYzCQMZ.mjs";
+import "./agent-BJ0KXN-A.mjs";
+import "./markdown-sections-7OoA7ylx.mjs";
+import { L as resolveDocsPublishedAgentSkill } from "./standards-discovery-BwL5ffGx.mjs";
+import "./search-DIyIl-tE.mjs";
+import { a as resolveDocsMetadataBaseUrl } from "./metadata-N252j5_a.mjs";
+import "./sitemap-server-BfyBM7_V.mjs";
+import "./agent-evals-LIScgQVm.mjs";
 import { createFilesystemDocsMcpSource, resolveDocsMcpConfig, runDocsMcpStdio } from "./mcp.mjs";
-import "./code-blocks-qe0T8-xe.mjs";
-import { t as resolveConfiguredAgentSkills } from "./agent-skills-server-BPVv4gMg.mjs";
+import "./code-blocks-DnNVNK2M.mjs";
+import { t as resolveConfiguredAgentSkills } from "./agent-skills-server-noFn1l_p.mjs";
 import "./server.mjs";
-import { _ as resolveDocsContentDir, d as readNavTitle, g as resolveDocsConfigPath, i as hasTopLevelProperty, l as readBooleanProperty, n as extractObjectLiteral, o as loadDocsConfigModuleResult, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-z7_R0f86.mjs";
+import { _ as resolveDocsContentDir, d as readNavTitle, g as resolveDocsConfigPath, i as hasTopLevelProperty, l as readBooleanProperty, n as extractObjectLiteral, o as loadDocsConfigModuleResult, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import pc from "picocolors";
@@ -42,7 +44,8 @@ async function runMcp(options = {}) {
 		rootDir,
 		entry,
 		contentDir,
-		siteTitle: navTitle ?? "Documentation"
+		siteTitle: navTitle ?? "Documentation",
+		baseUrl: loadedConfig ? resolveDocsMetadataBaseUrl(loadedConfig) : void 0
 	});
 	const resolvedMcp = resolveDocsMcpConfig(mcp ?? true, { defaultName: navTitle ?? "@farming-labs/docs" });
 	await runDocsMcpStdio({

package/dist/mcp.d.mts

@@ -1,5 +1,5 @@
-import { Ft as DocsMcpAuthenticate, Kt as DocsObservabilityConfig, Nt as DocsMcpAllowedOrigins, Pt as DocsMcpAuthPrincipal, Qn as PageAgentFrontmatter, Rt as DocsMcpConfig, cn as DocsSearchConfig, kn as DocsTelemetryFramework, qn as OrderingItem, rt as DocsAnalyticsConfig, wn as DocsTelemetryConfig, yn as DocsSearchSourcePage } from "./types-B9DNNAdT.mjs";
-import { I as DocsPublishedAgentSkill } from "./standards-discovery-DRJ10g7B.mjs";
+import { En as DocsTelemetryConfig, Ft as DocsMcpAuthenticate, Kt as DocsObservabilityConfig, Nt as DocsMcpAllowedOrigins, Pt as DocsMcpAuthPrincipal, Rt as DocsMcpConfig, Xt as DocsRetrievalSourceProvenance, Yn as OrderingItem, er as PageAgentFrontmatter, jn as DocsTelemetryFramework, rt as DocsAnalyticsConfig, un as DocsSearchConfig, xn as DocsSearchSourcePage } from "./types-clg5J1R4.mjs";
+import { L as DocsPublishedAgentSkill } from "./standards-discovery-CdrOE-05.mjs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 //#region src/mcp.d.ts
@@ -12,6 +12,7 @@ interface DocsMcpPage {
   agent?: PageAgentFrontmatter;
   icon?: string;
   sourcePath?: string;
+  lastmod?: string;
   lastModified?: string;
   locale?: string;
   framework?: string;
@@ -21,6 +22,7 @@ interface DocsMcpPage {
   rawContent?: string;
   agentContent?: string;
   agentRawContent?: string;
+  agentLastModified?: string;
   agentFallbackContent?: string;
   agentFallbackRawContent?: string;
 }
@@ -126,6 +128,8 @@ interface DocsMcpContextSource {
   version?: string;
   package?: string[];
   tags?: string[];
+  /** Canonical, scope-aware provenance for this retrieved source. */
+  source?: DocsRetrievalSourceProvenance;
   score?: number;
   content: string;
   /** JavaScript string length for this source's content only. */
@@ -168,6 +172,8 @@ interface DocsMcpContextOptions {
   tokenBudget: number;
   entry?: string;
   siteTitle?: string;
+  /** Public docs origin used to resolve canonical source URLs. */
+  baseUrl?: string;
   /** Maximum number of ranked, deduplicated candidates to render. Defaults to 50. */
   maxResults?: number;
 }
@@ -193,6 +199,10 @@ interface DocsMcpNavigationTree {
 interface DocsMcpSource {
   entry?: string;
   siteTitle?: string;
+  /** Canonical public docs origin used for retrieval source URLs. */
+  baseUrl?: string;
+  /** Resolve a requested locale to the locale whose pages will actually be returned. */
+  resolveLocale?(locale?: string, context?: DocsMcpRequestContext): string | undefined;
   getPages(locale?: string, context?: DocsMcpRequestContext): DocsMcpPage[] | Promise<DocsMcpPage[]>;
   getNavigation(locale?: string, context?: DocsMcpRequestContext): DocsMcpNavigationTree | Promise<DocsMcpNavigationTree>;
   /** Reusable Agent Skills exposed as progressive-disclosure MCP resources. */
@@ -277,6 +287,7 @@ interface CreateFilesystemDocsMcpSourceOptions {
   entry?: string;
   contentDir?: string;
   siteTitle?: string;
+  baseUrl?: string;
   ordering?: "alphabetical" | "numeric" | OrderingItem[];
 }
 declare const DEFAULT_DOCS_MCP_MAX_BODY_BYTES: number;

package/dist/mcp.mjs

@@ -1,7 +1,8 @@
 import { a as emitDocsAnalyticsEvent, i as emitDocsAgentTraceEvent, n as createDocsAgentTraceContext, r as createDocsAgentTraceId } from "./analytics-Bx44lg6d.mjs";
-import { At as resolveDocsAudienceMdxContent, Gt as findDocsMarkdownSection, Jt as renderDocsRelatedMarkdownLines, Kt as parseDocsMarkdownSections, Sn as resolveDocsMcpResourceLocation, bn as normalizeDocsMcpEndpointPath, gn as isDocsMcpProtectedResourceMetadataPath, hn as isDocsMcpOAuthScopeToken, nn as normalizePageAgentFrontmatter, on as upsertPageAgentContractMarkdown, qt as normalizeDocsRelated, tn as hasStructuredPageAgentContract, vn as isDocsMcpResourcePath, xn as resolveDocsMcpProtectedResourceMetadataLocation, yn as normalizeDocsMcpAuthorizationServerUrls } from "./agent-pS2nNQS3.mjs";
-import "./standards-discovery-CYfiQE13.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-BbArHODP.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-BJ0KXN-A.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 { 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-DIyIl-tE.mjs";
 import matter from "gray-matter";
 import fs from "node:fs";
 import path from "node:path";
@@ -1253,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",
@@ -1690,7 +1700,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(),
@@ -1699,7 +1709,7 @@ 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()
 });
@@ -1708,7 +1718,7 @@ const listTasksInputSchema = z.object({
 	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({
@@ -1767,12 +1777,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()
@@ -1785,7 +1795,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),
@@ -1793,7 +1803,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() });
@@ -1853,6 +1863,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(),
@@ -1864,7 +1905,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(),
@@ -1895,6 +1937,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)
@@ -1984,6 +2027,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(),
@@ -2155,6 +2199,8 @@ function createFilesystemDocsMcpSource(options = {}) {
 	return {
 		entry,
 		siteTitle: options.siteTitle ?? "Documentation",
+		baseUrl: options.baseUrl,
+		resolveLocale: () => void 0,
 		getPages,
 		getNavigation
 	};
@@ -2191,10 +2237,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) ?? [];
@@ -2810,6 +2859,7 @@ async function createDocsMcpServer(options) {
 		const startedAt = nowMs();
 		const resolvedLimit = limit ?? 10;
 		const resolvedAudience = audience ?? "agent";
+		const resolvedLocale = resolveSourceLocale(locale);
 		const filters = {
 			framework,
 			version,
@@ -2838,13 +2888,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);
@@ -3011,6 +3063,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, {
@@ -3035,16 +3088,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, {
@@ -3198,11 +3252,10 @@ async function createDocsMcpServer(options) {
 				};
 			}
 			const fullDocument = renderPageDocument(page);
-			const sectionDocument = getDocsMcpSourceMarkdown(page);
-			const selectedSection = section ? findDocsMarkdownSection(sectionDocument, section) ?? (sectionDocument !== fullDocument ? findDocsMarkdownSection(fullDocument, section) : void 0) : void 0;
+			const sectionDocument = upsertPageAgentContractMarkdown(getDocsMcpSourceMarkdown(page), page.agent);
+			const selectedSection = section ? findDocsMarkdownSection(sectionDocument, section) : void 0;
 			if (section && !selectedSection) {
-				const sourceSections = parseDocsMarkdownSections(sectionDocument);
-				const availableSections = (sourceSections.length > 0 ? sourceSections : parseDocsMarkdownSections(fullDocument)).map((item) => ({
+				const availableSections = parseDocsMarkdownSections(sectionDocument).map((item) => ({
 					title: item.title,
 					anchor: item.anchor
 				}));
@@ -3831,6 +3884,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 +3922,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 +3947,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 +4064,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();
@@ -4613,7 +4654,8 @@ function getDocsMcpResultPageUrl(value) {
 	return value.split("#", 1)[0] ?? value;
 }
 function getDocsMcpResultAnchor(value) {
-	const anchor = value.split("#", 2)[1];
+	const hashIndex = value.indexOf("#");
+	const anchor = hashIndex >= 0 ? value.slice(hashIndex + 1) : "";
 	if (!anchor) return void 0;
 	try {
 		return decodeURIComponent(anchor);
@@ -4636,10 +4678,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,
@@ -4650,6 +4695,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);
@@ -4695,7 +4741,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}#${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}`);
@@ -4722,12 +4768,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 +4817,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 normalizedRequestWithoutLocale = normalizeRequestedPath(removeDocsLocaleQuery(requestedPath), entry);
+	for (const page of pages) {
+		const normalizedPageUrl = normalizeUrlPath(page.url);
+		if (normalizedPageUrl === normalizedRequest || normalizedPageUrl === normalizedRequestWithoutLocale) return page;
+	}
 	const normalizedSlug = normalizePathSegment(requestedPath.replace(/^\//, ""));
 	for (const page of pages) if (normalizePathSegment(page.slug) === normalizedSlug) return page;
 	return null;
 }
+function removeDocsLocaleQuery(value) {
+	try {
+		const absolute = /^[a-z][a-z\d+.-]*:/iu.test(value);
+		const url = new URL(value, "https://docs.local");
+		url.searchParams.delete("lang");
+		return absolute ? url.toString() : `${url.pathname}${url.search}${url.hash}`;
+	} catch {
+		return value;
+	}
+}
 function normalizeRequestedPath(requestedPath, entry) {
 	const trimmed = requestedPath.trim();
 	if (!trimmed) return "/";

package/dist/{metadata-D6qlWDu-.mjs → metadata-N252j5_a.mjs}

@@ -1,4 +1,4 @@
-import { nn as normalizePageAgentFrontmatter, tn as hasStructuredPageAgentContract } from "./agent-pS2nNQS3.mjs";
+import { _ as hasStructuredPageAgentContract, v as normalizePageAgentFrontmatter } from "./markdown-sections-7OoA7ylx.mjs";
 
 //#region src/metadata.ts
 /**

package/dist/{package-version-BXHcIm1T.mjs → package-version-n5AFur8a.mjs}

@@ -1,4 +1,4 @@
-import { i as detectPackageManagerFromProject, l as formatPackageManagerDetection, t as detectFramework, u as installCommand } from "./utils-C4RC8Zq_.mjs";
+import { i as detectPackageManagerFromProject, l as formatPackageManagerDetection, t as detectFramework, u as installCommand } from "./utils-DpiIioYb.mjs";
 import pc from "picocolors";
 import * as p from "@clack/prompts";