@farming-labs/docs 0.2.50 → 0.2.53

package/dist/mcp.mjs

@@ -1,6 +1,7 @@
 import { a as emitDocsAnalyticsEvent, i as emitDocsAgentTraceEvent, n as createDocsAgentTraceContext, r as createDocsAgentTraceId } from "./analytics-BZEwTK-8.mjs";
-import { Nt as normalizeDocsRelated, Pt as renderDocsRelatedMarkdownLines } from "./agent-CaOBIVFy.mjs";
-import { D as emitDocsTelemetryProjectEvent, E as emitDocsTelemetryMcpToolEvent, u as performDocsSearch, w as emitDocsTelemetryAgentSurfaceEvent, x as resolvePageSidebarFolderIndexBehavior, y as stripGeneratedAgentProvenance } from "./search-BWuU70B0.mjs";
+import { a as normalizePageAgentFrontmatter, i as hasStructuredPageAgentContract, l as upsertPageAgentContractMarkdown } from "./agent-contract-b0akaPcg.mjs";
+import { It as normalizeDocsRelated, Lt as renderDocsRelatedMarkdownLines } from "./agent-BMxMpEa0.mjs";
+import { C as resolvePageSidebarFolderIndexBehavior, E as emitDocsTelemetryAgentSurfaceEvent, O as emitDocsTelemetryMcpToolEvent, k as emitDocsTelemetryProjectEvent, m as parseDocsMarkdownSections, p as findDocsMarkdownSection, u as performDocsSearch, x as stripGeneratedAgentProvenance } from "./search-CJNLkdjX.mjs";
 import matter from "gray-matter";
 import fs from "node:fs";
 import path from "node:path";
@@ -14,6 +15,25 @@ import * as z from "zod/v4";
 const DEFAULT_MCP_ROUTE = "/api/docs/mcp";
 const DEFAULT_MCP_VERSION = "0.0.0";
 const DEFAULT_MCP_NAME = "@farming-labs/docs";
+const DEFAULT_MCP_CONTEXT_TOKEN_BUDGET = 4e3;
+const MIN_MCP_CONTEXT_TOKEN_BUDGET = 256;
+const MAX_MCP_CONTEXT_TOKEN_BUDGET = 32e3;
+const UTF8_ENCODER = new TextEncoder();
+const DEFAULT_DOCS_MCP_MAX_BODY_BYTES = 1024 * 1024;
+const DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS = 600;
+const DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS = Object.freeze([
+	"Accept",
+	"Authorization",
+	"Content-Type",
+	"Last-Event-ID",
+	"MCP-Protocol-Version",
+	"MCP-Session-Id"
+]);
+const DEFAULT_DOCS_MCP_CORS_EXPOSED_HEADERS = Object.freeze([
+	"MCP-Protocol-Version",
+	"MCP-Session-Id",
+	"WWW-Authenticate"
+]);
 const DOCS_CONFIG_SCHEMA_OPTIONS = [
 	{
 		path: "entry",
@@ -328,6 +348,70 @@ const DOCS_CONFIG_SCHEMA_OPTIONS = [
 				default: "0.0.0",
 				description: "Version string reported to MCP clients."
 			},
+			{
+				path: "mcp.security",
+				name: "security",
+				type: "DocsMcpSecurityConfig",
+				description: "Streamable HTTP Origin validation, optional authentication, and request-size controls. The stdio transport is unaffected.",
+				children: [
+					{
+						path: "mcp.security.allowedOrigins",
+						name: "allowedOrigins",
+						type: "\"same-origin\" | string[] | callback",
+						default: "same-origin",
+						description: "Allow a supplied Origin header when it matches the MCP request origin, an explicit list, or a custom policy callback. Origin-less non-browser clients remain supported."
+					},
+					{
+						path: "mcp.security.authenticate",
+						name: "authenticate",
+						type: "DocsMcpAuthenticate",
+						default: "public (callback omitted)",
+						description: "Opt-in HTTP authentication callback. Return a principal to continue, null for 401, or a Response to control the rejection."
+					},
+					{
+						path: "mcp.security.maxBodyBytes",
+						name: "maxBodyBytes",
+						type: "number",
+						default: DEFAULT_DOCS_MCP_MAX_BODY_BYTES,
+						description: "Maximum accepted Streamable HTTP POST body size in bytes."
+					},
+					{
+						path: "mcp.security.cors",
+						name: "cors",
+						type: "boolean | DocsMcpCorsConfig",
+						default: true,
+						description: "Emit exact-Origin CORS responses for Origins accepted by allowedOrigins. Use an object for credentials, additional headers, and preflight cache controls.",
+						children: [
+							{
+								path: "mcp.security.cors.allowedHeaders",
+								name: "allowedHeaders",
+								type: "string[]",
+								description: "Additional request headers accepted during browser preflight."
+							},
+							{
+								path: "mcp.security.cors.exposedHeaders",
+								name: "exposedHeaders",
+								type: "string[]",
+								description: "Additional MCP response headers exposed to browser JavaScript."
+							},
+							{
+								path: "mcp.security.cors.allowCredentials",
+								name: "allowCredentials",
+								type: "boolean",
+								default: false,
+								description: "Allow credentialed browser requests using the validated exact Origin. Wildcard credentials are never emitted."
+							},
+							{
+								path: "mcp.security.cors.maxAgeSeconds",
+								name: "maxAgeSeconds",
+								type: "number",
+								default: DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS,
+								description: "Browser preflight cache lifetime in seconds."
+							}
+						]
+					}
+				]
+			},
 			{
 				path: "mcp.tools",
 				name: "tools",
@@ -349,6 +433,20 @@ const DOCS_CONFIG_SCHEMA_OPTIONS = [
 						default: true,
 						description: "Expose the list_pages tool."
 					},
+					{
+						path: "mcp.tools.listTasks",
+						name: "listTasks",
+						type: "boolean",
+						default: true,
+						description: "Expose the list_tasks tool."
+					},
+					{
+						path: "mcp.tools.readTask",
+						name: "readTask",
+						type: "boolean",
+						default: true,
+						description: "Expose the read_task tool."
+					},
 					{
 						path: "mcp.tools.getNavigation",
 						name: "getNavigation",
@@ -383,6 +481,13 @@ const DOCS_CONFIG_SCHEMA_OPTIONS = [
 						type: "boolean",
 						default: true,
 						description: "Expose the get_config_schema tool."
+					},
+					{
+						path: "mcp.tools.getContext",
+						name: "getContext",
+						type: "boolean",
+						default: true,
+						description: "Expose deterministic get_context retrieval with a conservative UTF-8 byte ceiling."
 					}
 				]
 			}
@@ -492,6 +597,19 @@ export default defineDocs({
       getCodeExamples: true,
     },
   },
+});`
+	},
+	{
+		title: "Opt-in MCP authentication",
+		code: `export default defineDocs({
+  mcp: {
+    security: {
+      async authenticate({ request }) {
+        const user = await authenticateRequest(request);
+        return user ? { id: user.id, scopes: ["docs:read"] } : null;
+      },
+    },
+  },
 });`
 	},
 	{
@@ -524,8 +642,74 @@ const searchDocsInputSchema = z.object({
 });
 const readPageInputSchema = z.object({
 	path: z.string().min(1),
+	locale: z.string().min(1).optional(),
+	section: z.string().trim().min(1).optional(),
+	maxChars: z.number().int().min(256).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()
 });
+const readTaskInputSchema = readPageInputSchema;
+const pageAgentAppliesToOutputSchema = z.object({
+	framework: z.array(z.string()).optional(),
+	version: z.array(z.string()).optional(),
+	package: z.array(z.string()).optional()
+});
+const pageAgentCommandOutputSchema = z.union([z.string(), z.object({
+	run: z.string(),
+	cwd: z.string().optional(),
+	description: z.string().optional()
+})]);
+const pageAgentVerificationOutputSchema = z.union([z.string(), z.object({
+	description: z.string().optional(),
+	run: z.string().optional(),
+	expect: z.string().optional()
+})]);
+const pageAgentFailureModeOutputSchema = z.union([z.string(), z.object({
+	symptom: z.string(),
+	resolution: z.string().optional()
+})]);
+const pageAgentContractOutputSchema = z.object({
+	tokenBudget: z.number().optional(),
+	task: z.string().optional(),
+	outcome: z.string().optional(),
+	appliesTo: pageAgentAppliesToOutputSchema.optional(),
+	prerequisites: z.array(z.string()).optional(),
+	files: z.array(z.string()).optional(),
+	commands: z.array(pageAgentCommandOutputSchema).optional(),
+	sideEffects: z.array(z.string()).optional(),
+	verification: z.array(pageAgentVerificationOutputSchema).optional(),
+	rollback: z.array(z.string()).optional(),
+	failureModes: z.array(pageAgentFailureModeOutputSchema).optional()
+});
+const taskSummaryOutputSchema = z.object({
+	slug: z.string(),
+	url: z.string(),
+	title: z.string(),
+	description: z.string().optional(),
+	task: z.string().optional(),
+	outcome: z.string().optional(),
+	appliesTo: pageAgentAppliesToOutputSchema.optional()
+});
+const listTasksOutputSchema = z.object({
+	resultCount: z.number().int().nonnegative(),
+	tasks: z.array(taskSummaryOutputSchema)
+});
+const readTaskOutputSchema = z.object({
+	page: z.object({
+		slug: z.string(),
+		url: z.string(),
+		title: z.string(),
+		description: z.string().optional(),
+		sourcePath: z.string().optional(),
+		lastModified: z.string().optional()
+	}),
+	contract: pageAgentContractOutputSchema
+});
 const listPagesInputSchema = z.object({ locale: z.string().min(1).optional() });
 const listDocsInputSchema = z.object({
 	section: z.string().trim().min(1).optional(),
@@ -546,6 +730,195 @@ const getCodeExamplesInputSchema = z.object({
 	limit: z.number().int().min(1).max(50).optional(),
 	locale: z.string().min(1).optional()
 });
+const getContextInputSchema = z.object({
+	query: z.string().trim().min(1),
+	framework: z.string().trim().min(1).optional(),
+	version: z.string().trim().min(1).optional(),
+	locale: z.string().trim().min(1).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() });
+const pageAgentContractSummaryOutputSchema = z.object({
+	hasContract: z.boolean(),
+	task: z.string().optional(),
+	outcome: z.string().optional(),
+	appliesTo: pageAgentAppliesToOutputSchema.optional()
+});
+const pageSummaryOutputSchema = z.object({
+	slug: z.string(),
+	url: z.string(),
+	title: z.string(),
+	description: z.string().optional(),
+	agent: pageAgentContractSummaryOutputSchema.optional(),
+	icon: z.string().optional(),
+	sourcePath: z.string().optional(),
+	lastModified: z.string().optional()
+});
+const docsSectionOutputSchema = z.lazy(() => z.object({
+	slug: z.string(),
+	title: z.string(),
+	url: z.string().optional(),
+	description: z.string().optional(),
+	icon: z.string().optional(),
+	pageCount: z.number().int().nonnegative(),
+	pages: z.array(pageSummaryOutputSchema),
+	sections: z.array(docsSectionOutputSchema)
+}));
+const listPagesOutputSchema = z.object({ pages: z.array(pageSummaryOutputSchema) });
+const listDocsOutputSchema = z.object({
+	section: z.string().optional(),
+	resultCount: z.number().int().nonnegative(),
+	sectionCount: z.number().int().nonnegative(),
+	pages: z.array(pageSummaryOutputSchema),
+	rootPages: z.array(pageSummaryOutputSchema),
+	sections: z.array(docsSectionOutputSchema)
+});
+const navigationPageOutputSchema = z.object({
+	type: z.literal("page"),
+	name: z.string(),
+	url: z.string(),
+	icon: z.string().optional(),
+	description: z.string().optional()
+});
+const navigationNodeOutputSchema = z.lazy(() => z.discriminatedUnion("type", [navigationPageOutputSchema, z.object({
+	type: z.literal("folder"),
+	name: z.string(),
+	icon: z.string().optional(),
+	index: navigationPageOutputSchema.optional(),
+	children: z.array(navigationNodeOutputSchema)
+})]));
+const navigationOutputSchema = z.object({
+	navigation: z.object({
+		name: z.string(),
+		children: z.array(navigationNodeOutputSchema)
+	}),
+	markdown: z.string()
+});
+const searchResultOutputSchema = z.object({
+	id: z.string(),
+	url: z.string(),
+	content: z.string(),
+	description: z.string().optional(),
+	type: z.enum([
+		"page",
+		"heading",
+		"text"
+	]),
+	score: z.number().optional(),
+	section: z.string().optional()
+});
+const searchDocsOutputSchema = z.object({ results: z.array(searchResultOutputSchema) });
+const codeExampleOutputSchema = z.object({
+	id: z.string(),
+	page: z.object({
+		slug: z.string(),
+		url: z.string(),
+		title: z.string(),
+		description: z.string().optional(),
+		sourcePath: z.string().optional(),
+		lastModified: z.string().optional()
+	}),
+	language: z.string().optional(),
+	title: z.string().optional(),
+	framework: z.string().optional(),
+	packageManager: z.string().optional(),
+	runnable: z.boolean(),
+	meta: z.record(z.string(), z.union([z.string(), z.boolean()])),
+	code: z.string()
+});
+const codeExamplesOutputSchema = z.object({ examples: z.array(codeExampleOutputSchema) });
+const configSchemaOptionOutputSchema = z.lazy(() => z.object({
+	path: z.string(),
+	name: z.string(),
+	type: z.string(),
+	default: z.union([
+		z.string(),
+		z.boolean(),
+		z.number(),
+		z.null()
+	]).optional(),
+	description: z.string(),
+	docs: z.string().optional(),
+	values: z.array(z.string()).optional(),
+	children: z.array(configSchemaOptionOutputSchema).optional()
+}));
+const configSchemaOutputSchema = z.object({
+	schemaVersion: z.literal(1),
+	configFile: z.literal("docs.config.ts"),
+	description: z.string(),
+	filters: z.object({
+		option: z.string().optional(),
+		query: z.string().optional()
+	}).optional(),
+	resultCount: z.number().int().nonnegative(),
+	options: z.array(configSchemaOptionOutputSchema),
+	examples: z.array(z.object({
+		title: z.string(),
+		code: z.string()
+	}))
+});
+const readPageOutputSchema = z.object({
+	page: z.object({
+		slug: z.string(),
+		url: z.string(),
+		title: z.string(),
+		description: z.string().optional(),
+		related: z.array(relatedLinkOutputSchema).optional(),
+		icon: z.string().optional(),
+		sourcePath: z.string().optional(),
+		lastModified: z.string().optional(),
+		locale: z.string().optional(),
+		framework: z.string().optional(),
+		version: z.string().optional(),
+		tags: z.array(z.string()).optional()
+	}),
+	document: z.string(),
+	section: z.string().optional(),
+	anchor: z.string().optional(),
+	chars: z.number().int().nonnegative(),
+	totalChars: z.number().int().nonnegative(),
+	truncated: z.boolean()
+});
+const contextSourceOutputSchema = z.object({
+	id: z.string(),
+	title: z.string(),
+	pageUrl: z.string(),
+	url: z.string(),
+	section: z.string().optional(),
+	anchor: z.string().optional(),
+	sourcePath: z.string().optional(),
+	lastModified: z.string().optional(),
+	locale: z.string().optional(),
+	framework: z.string().optional(),
+	version: z.string().optional(),
+	tags: z.array(z.string()).optional(),
+	score: z.number().optional(),
+	content: z.string(),
+	chars: z.number().int().nonnegative(),
+	utf8Bytes: z.number().int().nonnegative(),
+	truncated: z.boolean()
+});
+const contextOutputSchema = z.object({
+	query: z.string(),
+	filters: z.object({
+		framework: z.string().optional(),
+		version: z.string().optional(),
+		locale: z.string().optional()
+	}),
+	budget: z.object({
+		requestedTokens: z.number().int().positive(),
+		strategy: z.literal("utf8-bytes"),
+		maxUtf8Bytes: z.number().int().positive(),
+		usedUtf8Bytes: z.number().int().nonnegative(),
+		conservativeTokenUpperBound: z.number().int().nonnegative(),
+		remainingUtf8Bytes: z.number().int().nonnegative(),
+		truncated: z.boolean()
+	}),
+	resultCount: z.number().int().nonnegative(),
+	candidateCount: z.number().int().nonnegative(),
+	context: z.string(),
+	sources: z.array(contextSourceOutputSchema)
+});
 function normalizeDocsMcpRoute(route) {
 	if (!route || route.trim().length === 0) return DEFAULT_MCP_ROUTE;
 	const normalized = `/${route}`.replace(/\/+/g, "/");
@@ -561,11 +934,15 @@ function resolveDocsMcpConfig(mcp, defaults = {}) {
 			listDocs: true,
 			listPages: true,
 			readPage: true,
+			listTasks: true,
+			readTask: true,
 			searchDocs: true,
 			getNavigation: true,
 			getCodeExamples: true,
-			getConfigSchema: true
-		}
+			getConfigSchema: true,
+			getContext: true
+		},
+		security: resolveDocsMcpSecurityConfig()
 	};
 	const config = mcp && typeof mcp === "object" ? mcp : {};
 	return {
@@ -577,13 +954,49 @@ function resolveDocsMcpConfig(mcp, defaults = {}) {
 			listDocs: config.tools?.listDocs ?? true,
 			listPages: config.tools?.listPages ?? true,
 			readPage: config.tools?.readPage ?? true,
+			listTasks: config.tools?.listTasks ?? true,
+			readTask: config.tools?.readTask ?? true,
 			searchDocs: config.tools?.searchDocs ?? true,
 			getNavigation: config.tools?.getNavigation ?? true,
 			getCodeExamples: config.tools?.getCodeExamples ?? true,
-			getConfigSchema: config.tools?.getConfigSchema ?? true
-		}
+			getConfigSchema: config.tools?.getConfigSchema ?? true,
+			getContext: config.tools?.getContext ?? true
+		},
+		security: resolveDocsMcpSecurityConfig(config.security)
 	};
 }
+function resolveDocsMcpSecurityConfig(security) {
+	const configuredMaxBodyBytes = security?.maxBodyBytes;
+	const maxBodyBytes = typeof configuredMaxBodyBytes === "number" && Number.isFinite(configuredMaxBodyBytes) && configuredMaxBodyBytes > 0 ? Math.floor(configuredMaxBodyBytes) : DEFAULT_DOCS_MCP_MAX_BODY_BYTES;
+	return {
+		allowedOrigins: security?.allowedOrigins ?? "same-origin",
+		authenticate: security?.authenticate,
+		maxBodyBytes,
+		cors: resolveDocsMcpCorsConfig(security?.cors)
+	};
+}
+function resolveDocsMcpCorsConfig(cors) {
+	const config = cors && typeof cors === "object" ? cors : {};
+	const configuredMaxAge = config.maxAgeSeconds;
+	const maxAgeSeconds = typeof configuredMaxAge === "number" && Number.isFinite(configuredMaxAge) && configuredMaxAge >= 0 ? Math.floor(configuredMaxAge) : DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS;
+	return {
+		enabled: cors !== false,
+		allowedHeaders: mergeHttpHeaderNames(DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS, config.allowedHeaders),
+		exposedHeaders: mergeHttpHeaderNames(DEFAULT_DOCS_MCP_CORS_EXPOSED_HEADERS, config.exposedHeaders),
+		allowCredentials: config.allowCredentials === true,
+		maxAgeSeconds
+	};
+}
+function mergeHttpHeaderNames(defaults, configured) {
+	const headers = /* @__PURE__ */ new Map();
+	for (const header of [...defaults, ...configured ?? []]) {
+		const normalized = header.trim();
+		if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(normalized)) continue;
+		const key = normalized.toLowerCase();
+		if (!headers.has(key)) headers.set(key, normalized);
+	}
+	return [...headers.values()];
+}
 function createFilesystemDocsMcpSource(options = {}) {
 	const rootDir = options.rootDir ?? process.cwd();
 	const entry = normalizePathSegment(options.entry ?? "docs") || "docs";
@@ -618,6 +1031,15 @@ function nowMs() {
 function durationMs(startedAt) {
 	return Math.max(0, Date.now() - startedAt);
 }
+function createStructuredTextResult(structuredContent, text) {
+	return {
+		content: [{
+			type: "text",
+			text: text ?? JSON.stringify(structuredContent, null, 2)
+		}],
+		structuredContent
+	};
+}
 async function createDocsMcpServer(options) {
 	const resolved = resolveDocsMcpConfig(options.mcp, {
 		defaultName: options.defaultName ?? options.source.siteTitle ?? DEFAULT_MCP_NAME,
@@ -634,6 +1056,12 @@ async function createDocsMcpServer(options) {
 		search: options.search
 	};
 	const telemetryFramework = options.telemetryFramework ?? "mcp";
+	function getSourcePages(locale) {
+		return options.source.getPages(locale, options.requestContext);
+	}
+	function getSourceNavigation(locale) {
+		return options.source.getNavigation(locale, options.requestContext);
+	}
 	function trackMcpTool(tool, values) {
 		emitDocsTelemetryMcpToolEvent(telemetryConfig, {
 			framework: telemetryFramework,
@@ -642,8 +1070,8 @@ async function createDocsMcpServer(options) {
 			resultCount: values?.resultCount
 		});
 	}
-	const defaultPages = dedupePages(await options.source.getPages());
-	const defaultTree = await options.source.getNavigation();
+	const defaultPages = dedupePages(await getSourcePages());
+	const defaultTree = await getSourceNavigation();
 	server.registerResource("docs-navigation", "docs://navigation", {
 		title: "Docs Navigation",
 		description: "Structured navigation tree for the documentation site.",
@@ -669,6 +1097,7 @@ async function createDocsMcpServer(options) {
 		title: "List docs pages",
 		description: "List the known documentation pages with titles, slugs, and URLs.",
 		inputSchema: listPagesInputSchema,
+		outputSchema: listPagesOutputSchema,
 		annotations: { readOnlyHint: true }
 	}, async ({ locale }) => {
 		const startedAt = nowMs();
@@ -687,7 +1116,7 @@ async function createDocsMcpServer(options) {
 			metadata: { tool: "list_pages" }
 		});
 		try {
-			const pages = toPageSummaries(dedupePages(await options.source.getPages(locale)));
+			const pages = toPageSummaries(dedupePages(await getSourcePages(locale)));
 			const elapsed = durationMs(startedAt);
 			await emitDocsAnalyticsEvent(options.analytics, {
 				type: "mcp_tool",
@@ -717,10 +1146,7 @@ async function createDocsMcpServer(options) {
 				outputPreview: { resultCount: pages.length },
 				metadata: { tool: "list_pages" }
 			});
-			return { content: [{
-				type: "text",
-				text: JSON.stringify({ pages }, null, 2)
-			}] };
+			return createStructuredTextResult({ pages });
 		} catch (error) {
 			const elapsed = durationMs(startedAt);
 			await emitDocsAgentTraceEvent(options.observability, {
@@ -744,6 +1170,7 @@ async function createDocsMcpServer(options) {
 		title: "List docs by section",
 		description: "List documentation pages grouped by section, optionally narrowed to one section.",
 		inputSchema: listDocsInputSchema,
+		outputSchema: listDocsOutputSchema,
 		annotations: { readOnlyHint: true }
 	}, async ({ section, locale }) => {
 		const startedAt = nowMs();
@@ -765,7 +1192,7 @@ async function createDocsMcpServer(options) {
 			metadata: { tool: "list_docs" }
 		});
 		try {
-			const docs = listDocsBySection(dedupePages(await options.source.getPages(locale)), {
+			const docs = listDocsBySection(dedupePages(await getSourcePages(locale)), {
 				section,
 				entry: options.source.entry
 			});
@@ -803,10 +1230,7 @@ async function createDocsMcpServer(options) {
 				},
 				metadata: { tool: "list_docs" }
 			});
-			return { content: [{
-				type: "text",
-				text: JSON.stringify(docs, null, 2)
-			}] };
+			return createStructuredTextResult(docs);
 		} catch (error) {
 			const elapsed = durationMs(startedAt);
 			await emitDocsAgentTraceEvent(options.observability, {
@@ -826,10 +1250,257 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
+	if (resolved.tools.listTasks) server.registerTool("list_tasks", {
+		title: "List documented tasks",
+		description: "List pages with actionable agent contracts, optionally filtered by text or applicability.",
+		inputSchema: listTasksInputSchema,
+		outputSchema: listTasksOutputSchema,
+		annotations: { readOnlyHint: true }
+	}, async ({ query, framework, version, package: packageName, locale }) => {
+		const startedAt = nowMs();
+		const trace = createDocsAgentTraceContext("mcp.tool.list_tasks");
+		const callSpanId = createDocsAgentTraceId("span");
+		await emitDocsAgentTraceEvent(options.observability, {
+			type: "tool.call",
+			source: "mcp",
+			traceId: trace.traceId,
+			spanId: callSpanId,
+			name: "list_tasks",
+			startedAt: trace.startedAt,
+			status: "started",
+			locale,
+			inputPreview: {
+				queryLength: query?.length,
+				framework,
+				version,
+				package: packageName
+			},
+			metadata: { tool: "list_tasks" }
+		});
+		try {
+			const tasks = listDocsTasks(dedupePages(await getSourcePages(locale)), {
+				query,
+				framework,
+				version,
+				package: packageName
+			});
+			const result = {
+				resultCount: tasks.length,
+				tasks
+			};
+			const elapsed = durationMs(startedAt);
+			await emitDocsAnalyticsEvent(options.analytics, {
+				type: "mcp_tool",
+				source: "mcp",
+				locale,
+				input: query ? { query } : void 0,
+				properties: {
+					tool: "list_tasks",
+					framework,
+					version,
+					package: packageName,
+					resultCount: tasks.length,
+					durationMs: elapsed
+				}
+			});
+			trackMcpTool("list_tasks", {
+				locale,
+				resultCount: tasks.length
+			});
+			await emitDocsAgentTraceEvent(options.observability, {
+				type: "tool.result",
+				source: "mcp",
+				traceId: trace.traceId,
+				parentSpanId: callSpanId,
+				name: "list_tasks",
+				startedAt: trace.startedAt,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				durationMs: elapsed,
+				status: "success",
+				locale,
+				outputPreview: { resultCount: tasks.length },
+				metadata: { tool: "list_tasks" }
+			});
+			return {
+				structuredContent: result,
+				content: [{
+					type: "text",
+					text: JSON.stringify(result, null, 2)
+				}]
+			};
+		} catch (error) {
+			const elapsed = durationMs(startedAt);
+			await emitDocsAgentTraceEvent(options.observability, {
+				type: "tool.error",
+				source: "mcp",
+				traceId: trace.traceId,
+				parentSpanId: callSpanId,
+				name: "list_tasks",
+				startedAt: trace.startedAt,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				durationMs: elapsed,
+				status: "error",
+				locale,
+				outputPreview: { message: error instanceof Error ? error.message : "Unknown error" },
+				metadata: { tool: "list_tasks" }
+			});
+			throw error;
+		}
+	});
+	if (resolved.tools.readTask) server.registerTool("read_task", {
+		title: "Read a documented task",
+		description: "Read the full structured agent contract for a page by slug or URL path.",
+		inputSchema: readTaskInputSchema,
+		outputSchema: readTaskOutputSchema,
+		annotations: { readOnlyHint: true }
+	}, async ({ path: requestedPath, locale }) => {
+		const startedAt = nowMs();
+		const trace = createDocsAgentTraceContext("mcp.tool.read_task");
+		const callSpanId = createDocsAgentTraceId("span");
+		await emitDocsAgentTraceEvent(options.observability, {
+			type: "tool.call",
+			source: "mcp",
+			traceId: trace.traceId,
+			spanId: callSpanId,
+			name: "read_task",
+			startedAt: trace.startedAt,
+			status: "started",
+			locale,
+			inputPreview: {
+				path: requestedPath,
+				locale
+			},
+			metadata: { tool: "read_task" }
+		});
+		try {
+			const page = findDocsPage(dedupePages(await getSourcePages(locale)), requestedPath, options.source.entry);
+			const contract = normalizePageAgentFrontmatter(page?.agent);
+			if (!page || !contract || !hasStructuredPageAgentContract(contract)) {
+				const elapsed = durationMs(startedAt);
+				const reason = page ? "contract_not_found" : "page_not_found";
+				const errorResult = { error: page ? `The docs page matched "${requestedPath}", but it has no actionable agent contract.` : `No docs page matched "${requestedPath}".` };
+				await emitDocsAnalyticsEvent(options.analytics, {
+					type: "mcp_tool",
+					source: "mcp",
+					locale,
+					properties: {
+						tool: "read_task",
+						path: requestedPath,
+						found: false,
+						reason,
+						durationMs: elapsed
+					}
+				});
+				trackMcpTool("read_task", {
+					locale,
+					resultCount: 0
+				});
+				await emitDocsAgentTraceEvent(options.observability, {
+					type: "tool.error",
+					source: "mcp",
+					traceId: trace.traceId,
+					parentSpanId: callSpanId,
+					name: "read_task",
+					startedAt: trace.startedAt,
+					endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+					durationMs: elapsed,
+					status: "error",
+					locale,
+					outputPreview: {
+						found: false,
+						path: requestedPath
+					},
+					metadata: {
+						tool: "read_task",
+						reason
+					}
+				});
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(errorResult, null, 2)
+					}],
+					isError: true
+				};
+			}
+			const result = {
+				page: {
+					slug: page.slug,
+					url: page.url,
+					title: page.title,
+					...page.description ? { description: page.description } : {},
+					...page.sourcePath ? { sourcePath: page.sourcePath } : {},
+					...page.lastModified ? { lastModified: page.lastModified } : {}
+				},
+				contract
+			};
+			const elapsed = durationMs(startedAt);
+			await emitDocsAnalyticsEvent(options.analytics, {
+				type: "mcp_tool",
+				source: "mcp",
+				locale,
+				path: page.url,
+				properties: {
+					tool: "read_task",
+					requestedPath,
+					slug: page.slug,
+					found: true,
+					durationMs: elapsed
+				}
+			});
+			trackMcpTool("read_task", {
+				locale,
+				resultCount: 1
+			});
+			await emitDocsAgentTraceEvent(options.observability, {
+				type: "tool.result",
+				source: "mcp",
+				traceId: trace.traceId,
+				parentSpanId: callSpanId,
+				name: "read_task",
+				startedAt: trace.startedAt,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				durationMs: elapsed,
+				status: "success",
+				locale,
+				path: page.url,
+				outputPreview: {
+					found: true,
+					slug: page.slug
+				},
+				metadata: { tool: "read_task" }
+			});
+			return {
+				structuredContent: result,
+				content: [{
+					type: "text",
+					text: JSON.stringify(result, null, 2)
+				}]
+			};
+		} catch (error) {
+			const elapsed = durationMs(startedAt);
+			await emitDocsAgentTraceEvent(options.observability, {
+				type: "tool.error",
+				source: "mcp",
+				traceId: trace.traceId,
+				parentSpanId: callSpanId,
+				name: "read_task",
+				startedAt: trace.startedAt,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				durationMs: elapsed,
+				status: "error",
+				locale,
+				outputPreview: { message: error instanceof Error ? error.message : "Unknown error" },
+				metadata: { tool: "read_task" }
+			});
+			throw error;
+		}
+	});
 	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,
+		outputSchema: navigationOutputSchema,
 		annotations: { readOnlyHint: true }
 	}, async ({ locale }) => {
 		const startedAt = nowMs();
@@ -848,7 +1519,8 @@ async function createDocsMcpServer(options) {
 			metadata: { tool: "get_navigation" }
 		});
 		try {
-			const text = renderNavigationTree(await options.source.getNavigation(locale));
+			const tree = await getSourceNavigation(locale);
+			const text = renderNavigationTree(tree);
 			const elapsed = durationMs(startedAt);
 			await emitDocsAnalyticsEvent(options.analytics, {
 				type: "mcp_tool",
@@ -874,10 +1546,10 @@ async function createDocsMcpServer(options) {
 				outputPreview: { chars: text.length },
 				metadata: { tool: "get_navigation" }
 			});
-			return { content: [{
-				type: "text",
-				text
-			}] };
+			return createStructuredTextResult({
+				navigation: tree,
+				markdown: text
+			}, text);
 		} catch (error) {
 			const elapsed = durationMs(startedAt);
 			await emitDocsAgentTraceEvent(options.observability, {
@@ -901,6 +1573,7 @@ async function createDocsMcpServer(options) {
 		title: "Get docs config schema",
 		description: "Return structured docs.config.ts option metadata, optionally filtered by option path or query.",
 		inputSchema: getConfigSchemaInputSchema,
+		outputSchema: configSchemaOutputSchema,
 		annotations: { readOnlyHint: true }
 	}, async ({ option, query }) => {
 		const startedAt = nowMs();
@@ -952,10 +1625,7 @@ async function createDocsMcpServer(options) {
 				outputPreview: { resultCount: schema.resultCount },
 				metadata: { tool: "get_config_schema" }
 			});
-			return { content: [{
-				type: "text",
-				text: JSON.stringify(schema, null, 2)
-			}] };
+			return createStructuredTextResult(schema);
 		} catch (error) {
 			const elapsed = durationMs(startedAt);
 			await emitDocsAgentTraceEvent(options.observability, {
@@ -978,6 +1648,7 @@ async function createDocsMcpServer(options) {
 		title: "Search documentation",
 		description: "Search the docs by keyword across titles, descriptions, and page content.",
 		inputSchema: searchDocsInputSchema,
+		outputSchema: searchDocsOutputSchema,
 		annotations: { readOnlyHint: true }
 	}, async ({ query, limit, locale }) => {
 		const startedAt = nowMs();
@@ -1002,7 +1673,7 @@ async function createDocsMcpServer(options) {
 		});
 		try {
 			const results = await performDocsSearch({
-				pages: toSearchSourcePages(dedupePages(await options.source.getPages(locale))),
+				pages: toSearchSourcePages(dedupePages(await getSourcePages(locale))),
 				query,
 				search: toolSearchConfig ?? true,
 				locale,
@@ -1041,10 +1712,7 @@ async function createDocsMcpServer(options) {
 				outputPreview: { resultCount: results.length },
 				metadata: { tool: "search_docs" }
 			});
-			return { content: [{
-				type: "text",
-				text: JSON.stringify({ results }, null, 2)
-			}] };
+			return createStructuredTextResult({ results });
 		} catch (error) {
 			const elapsed = durationMs(startedAt);
 			await emitDocsAgentTraceEvent(options.observability, {
@@ -1068,6 +1736,7 @@ async function createDocsMcpServer(options) {
 		title: "Get docs code examples",
 		description: "Return fenced code examples from the docs with parsed metadata such as title, framework, packageManager, and runnable.",
 		inputSchema: getCodeExamplesInputSchema,
+		outputSchema: codeExamplesOutputSchema,
 		annotations: { readOnlyHint: true }
 	}, async ({ query, path: requestedPath, framework, packageManager, language, runnable, limit, locale }) => {
 		const startedAt = nowMs();
@@ -1095,7 +1764,7 @@ async function createDocsMcpServer(options) {
 			metadata: { tool: "get_code_examples" }
 		});
 		try {
-			const pages = dedupePages(await options.source.getPages(locale));
+			const pages = dedupePages(await getSourcePages(locale));
 			const matchedPage = requestedPath ? findDocsPage(pages, requestedPath, options.source.entry) : null;
 			const examples = filterDocsCodeExamples((requestedPath ? matchedPage ? [matchedPage] : [] : pages).flatMap((page) => extractDocsMcpCodeExamples(page)), {
 				query,
@@ -1142,10 +1811,7 @@ async function createDocsMcpServer(options) {
 				outputPreview: { resultCount: examples.length },
 				metadata: { tool: "get_code_examples" }
 			});
-			return { content: [{
-				type: "text",
-				text: JSON.stringify({ examples }, null, 2)
-			}] };
+			return createStructuredTextResult({ examples });
 		} catch (error) {
 			const elapsed = durationMs(startedAt);
 			await emitDocsAgentTraceEvent(options.observability, {
@@ -1165,12 +1831,115 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
+	if (resolved.tools.getContext) server.registerTool("get_context", {
+		title: "Get budgeted docs context",
+		description: "Build deterministic, section-level documentation context for a query within a conservative UTF-8 byte ceiling derived from the requested token budget, with source URLs and accounting metadata.",
+		inputSchema: getContextInputSchema,
+		outputSchema: contextOutputSchema,
+		annotations: { readOnlyHint: true }
+	}, async ({ query, framework, version, locale, tokenBudget }) => {
+		const startedAt = nowMs();
+		const trace = createDocsAgentTraceContext("mcp.tool.get_context");
+		const callSpanId = createDocsAgentTraceId("span");
+		await emitDocsAgentTraceEvent(options.observability, {
+			type: "tool.call",
+			source: "mcp",
+			traceId: trace.traceId,
+			spanId: callSpanId,
+			name: "get_context",
+			startedAt: trace.startedAt,
+			status: "started",
+			locale,
+			inputPreview: {
+				queryLength: query.length,
+				framework,
+				version,
+				locale,
+				tokenBudget
+			},
+			metadata: { tool: "get_context" }
+		});
+		try {
+			const result = await buildDocsMcpContext({
+				pages: dedupePages(await getSourcePages(locale)),
+				query,
+				framework,
+				version,
+				locale,
+				tokenBudget,
+				entry: options.source.entry,
+				siteTitle: options.source.siteTitle
+			});
+			const elapsed = durationMs(startedAt);
+			await emitDocsAnalyticsEvent(options.analytics, {
+				type: "mcp_tool",
+				source: "mcp",
+				locale,
+				input: { query },
+				properties: {
+					tool: "get_context",
+					queryLength: query.length,
+					framework,
+					version,
+					tokenBudget,
+					usedUtf8Bytes: result.budget.usedUtf8Bytes,
+					conservativeTokenUpperBound: result.budget.conservativeTokenUpperBound,
+					truncated: result.budget.truncated,
+					resultCount: result.resultCount,
+					durationMs: elapsed
+				}
+			});
+			trackMcpTool("get_context", {
+				locale,
+				resultCount: result.resultCount
+			});
+			await emitDocsAgentTraceEvent(options.observability, {
+				type: "tool.result",
+				source: "mcp",
+				traceId: trace.traceId,
+				parentSpanId: callSpanId,
+				name: "get_context",
+				startedAt: trace.startedAt,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				durationMs: elapsed,
+				status: "success",
+				locale,
+				outputPreview: {
+					resultCount: result.resultCount,
+					candidateCount: result.candidateCount,
+					utf8Bytes: result.budget.usedUtf8Bytes,
+					conservativeTokenUpperBound: result.budget.conservativeTokenUpperBound,
+					truncated: result.budget.truncated
+				},
+				metadata: { tool: "get_context" }
+			});
+			return createStructuredTextResult(result, result.context || JSON.stringify(result, null, 2));
+		} catch (error) {
+			const elapsed = durationMs(startedAt);
+			await emitDocsAgentTraceEvent(options.observability, {
+				type: "tool.error",
+				source: "mcp",
+				traceId: trace.traceId,
+				parentSpanId: callSpanId,
+				name: "get_context",
+				startedAt: trace.startedAt,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				durationMs: elapsed,
+				status: "error",
+				locale,
+				outputPreview: { message: error instanceof Error ? error.message : "Unknown error" },
+				metadata: { tool: "get_context" }
+			});
+			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.",
+		description: "Read a documentation page by slug or URL path, optionally selecting one heading and limiting returned characters.",
 		inputSchema: readPageInputSchema,
+		outputSchema: readPageOutputSchema,
 		annotations: { readOnlyHint: true }
-	}, async ({ path: requestedPath, locale }) => {
+	}, async ({ path: requestedPath, locale, section, maxChars }) => {
 		const startedAt = nowMs();
 		const trace = createDocsAgentTraceContext("mcp.tool.read_page");
 		const callSpanId = createDocsAgentTraceId("span");
@@ -1185,12 +1954,14 @@ async function createDocsMcpServer(options) {
 			locale,
 			inputPreview: {
 				path: requestedPath,
-				locale
+				locale,
+				section,
+				maxChars
 			},
 			metadata: { tool: "read_page" }
 		});
 		try {
-			const page = findDocsPage(dedupePages(await options.source.getPages(locale)), requestedPath, options.source.entry);
+			const page = findDocsPage(dedupePages(await getSourcePages(locale)), requestedPath, options.source.entry);
 			if (!page) {
 				const elapsed = durationMs(startedAt);
 				await emitDocsAnalyticsEvent(options.analytics, {
@@ -1248,7 +2019,59 @@ async function createDocsMcpServer(options) {
 					isError: true
 				};
 			}
-			const document = renderPageDocument(page);
+			const fullDocument = renderPageDocument(page);
+			const sectionDocument = getDocsMcpSourceMarkdown(page);
+			const selectedSection = section ? findDocsMarkdownSection(sectionDocument, section) ?? (sectionDocument !== fullDocument ? findDocsMarkdownSection(fullDocument, section) : void 0) : void 0;
+			if (section && !selectedSection) {
+				const sourceSections = parseDocsMarkdownSections(sectionDocument);
+				const availableSections = (sourceSections.length > 0 ? sourceSections : parseDocsMarkdownSections(fullDocument)).map((item) => ({
+					title: item.title,
+					anchor: item.anchor
+				}));
+				const errorText = renderBoundedDocsMcpSectionError({
+					requestedSection: section,
+					pageUrl: page.url,
+					availableSections,
+					maxChars
+				});
+				const elapsed = durationMs(startedAt);
+				trackMcpTool("read_page", {
+					locale,
+					resultCount: 0
+				});
+				await emitDocsAgentTraceEvent(options.observability, {
+					type: "tool.error",
+					source: "mcp",
+					traceId: trace.traceId,
+					parentSpanId: callSpanId,
+					name: "read_page",
+					startedAt: trace.startedAt,
+					endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+					durationMs: elapsed,
+					status: "error",
+					locale,
+					path: page.url,
+					outputPreview: {
+						found: true,
+						sectionFound: false,
+						section
+					},
+					metadata: {
+						tool: "read_page",
+						reason: "section_not_found"
+					}
+				});
+				return {
+					content: [{
+						type: "text",
+						text: errorText
+					}],
+					isError: true
+				};
+			}
+			const selectedDocument = selectedSection?.content ?? fullDocument;
+			const limitedDocument = limitDocsMcpText(selectedDocument, maxChars);
+			const document = limitedDocument.text;
 			const elapsed = durationMs(startedAt);
 			await emitDocsAnalyticsEvent(options.analytics, {
 				type: "agent_read",
@@ -1261,7 +2084,10 @@ async function createDocsMcpServer(options) {
 					requestedPath,
 					slug: page.slug,
 					found: true,
+					section: selectedSection?.title,
 					contentLength: document.length,
+					totalContentLength: selectedDocument.length,
+					truncated: limitedDocument.truncated,
 					durationMs: elapsed
 				}
 			});
@@ -1275,7 +2101,10 @@ async function createDocsMcpServer(options) {
 					requestedPath,
 					slug: page.slug,
 					found: true,
+					section: selectedSection?.title,
 					contentLength: document.length,
+					totalContentLength: selectedDocument.length,
+					truncated: limitedDocument.truncated,
 					durationMs: elapsed
 				}
 			});
@@ -1298,14 +2127,22 @@ async function createDocsMcpServer(options) {
 				outputPreview: {
 					found: true,
 					chars: document.length,
+					totalChars: selectedDocument.length,
+					truncated: limitedDocument.truncated,
+					section: selectedSection?.title,
 					slug: page.slug
 				},
 				metadata: { tool: "read_page" }
 			});
-			return { content: [{
-				type: "text",
-				text: document
-			}] };
+			return createStructuredTextResult({
+				page: toStructuredDocsMcpPage(page),
+				document,
+				section: selectedSection?.title,
+				anchor: selectedSection?.anchor,
+				chars: document.length,
+				totalChars: selectedDocument.length,
+				truncated: limitedDocument.truncated
+			}, document);
 		} catch (error) {
 			const elapsed = durationMs(startedAt);
 			await emitDocsAgentTraceEvent(options.observability, {
@@ -1348,10 +2185,14 @@ function createDocsMcpHttpHandler(options) {
 			id: readJsonRpcId(await parseJsonBody(request)),
 			data: { reason: "mcp_disabled" }
 		}),
-		DELETE: async () => createJsonErrorResponse(404, disabledMessage)
+		DELETE: async () => createJsonErrorResponse(404, disabledMessage),
+		OPTIONS: async () => createJsonErrorResponse(404, disabledMessage)
 	};
-	async function createStatelessTransport() {
-		const server = await createDocsMcpServer(options);
+	async function createStatelessTransport(requestContext) {
+		const server = await createDocsMcpServer({
+			...options,
+			requestContext
+		});
 		const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
 		await server.connect(transport);
 		return {
@@ -1362,15 +2203,38 @@ function createDocsMcpHttpHandler(options) {
 	async function handle(request) {
 		const url = new URL(request.url);
 		const method = request.method.toUpperCase();
-		const sessionId = request.headers.get("mcp-session-id") ?? request.headers.get("Mcp-Session-Id");
-		let parsedBody;
-		let bodyParseFailed = false;
-		if (method === "POST") try {
-			parsedBody = await request.clone().json();
+		const security = resolved.security ?? resolveDocsMcpSecurityConfig();
+		const prepared = await prepareDocsMcpHttpRequest(request, security.maxBodyBytes);
+		if (prepared.status === "too-large") return createMcpRequestTooLargeResponse(security.maxBodyBytes);
+		request = prepared.request;
+		let originAllowed;
+		try {
+			originAllowed = await isDocsMcpOriginAllowed(request.clone(), security.allowedOrigins);
 		} catch {
-			bodyParseFailed = true;
-			parsedBody = void 0;
+			return createMcpHttpSecurityErrorResponse(500, "MCP Origin policy failed");
 		}
+		if (!originAllowed) return createMcpHttpSecurityErrorResponse(403, "Forbidden Origin");
+		if (method === "OPTIONS") return createDocsMcpOptionsResponse(request, security.cors);
+		const withCors = (response) => applyDocsMcpCorsHeaders(response, request, security.cors);
+		let auth;
+		if (security.authenticate) {
+			let authentication;
+			try {
+				authentication = await security.authenticate({
+					request: request.clone(),
+					pathname: url.pathname
+				});
+			} catch {
+				return withCors(createMcpHttpSecurityErrorResponse(500, "MCP authentication failed"));
+			}
+			if (authentication instanceof Response) return withCors(authentication);
+			if (authentication === null || authentication === void 0) return withCors(createMcpHttpSecurityErrorResponse(401, "Unauthorized"));
+			if (!isDocsMcpAuthPrincipal(authentication)) return withCors(createMcpHttpSecurityErrorResponse(500, "MCP authentication returned an invalid principal"));
+			auth = authentication;
+		}
+		const sessionId = request.headers.get("mcp-session-id") ?? request.headers.get("Mcp-Session-Id");
+		const parsedBody = prepared.parsedBody;
+		const bodyParseFailed = prepared.bodyParseFailed;
 		const initializeRequest = method === "POST" && parsedBody && isInitializeRequest(parsedBody);
 		emitDocsTelemetryProjectEvent(telemetryConfig, {
 			framework: telemetryFramework,
@@ -1397,24 +2261,220 @@ function createDocsMcpHttpHandler(options) {
 				initialize: Boolean(initializeRequest)
 			}
 		});
-		if (method === "POST" && bodyParseFailed) return createJsonRpcErrorResponse({
+		if (method === "POST" && bodyParseFailed) return withCors(createJsonRpcErrorResponse({
 			status: 400,
 			code: -32700,
 			message: "Parse error: Invalid JSON"
-		});
-		return (await createStatelessTransport()).transport.handleRequest(request, parsedBody === void 0 ? void 0 : { parsedBody });
+		}));
+		return withCors(await (await createStatelessTransport({
+			transport: "http",
+			request: request.clone(),
+			auth
+		})).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)
+		DELETE: async ({ request }) => handle(request),
+		OPTIONS: async ({ request }) => handle(request)
 	};
 }
 async function runDocsMcpStdio(options) {
-	const server = await createDocsMcpServer(options);
+	const server = await createDocsMcpServer({
+		...options,
+		requestContext: { transport: "stdio" }
+	});
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
 }
+async function isDocsMcpOriginAllowed(request, allowedOrigins) {
+	const origin = request.headers.get("origin");
+	if (!origin) return true;
+	if (typeof allowedOrigins === "function") return allowedOrigins({
+		origin,
+		request
+	});
+	const normalizedOrigin = normalizeHttpOrigin(origin);
+	if (allowedOrigins === "same-origin") return normalizedOrigin === new URL(request.url).origin;
+	return allowedOrigins.some((allowedOrigin) => normalizeHttpOrigin(allowedOrigin) === normalizedOrigin);
+}
+function normalizeHttpOrigin(value) {
+	try {
+		return new URL(value).origin;
+	} catch {
+		return value.trim();
+	}
+}
+function isDocsMcpAuthPrincipal(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const principal = value;
+	if (typeof principal.id !== "string" || principal.id.trim().length === 0) return false;
+	if (principal.scopes !== void 0 && (!Array.isArray(principal.scopes) || principal.scopes.some((scope) => typeof scope !== "string"))) return false;
+	return principal.claims === void 0 || typeof principal.claims === "object" && principal.claims !== null && !Array.isArray(principal.claims);
+}
+async function prepareDocsMcpHttpRequest(request, maxBodyBytes) {
+	if (request.method.toUpperCase() !== "POST") return {
+		status: "ok",
+		request,
+		bodyParseFailed: false
+	};
+	if (isContentLengthOverLimit(request, maxBodyBytes)) return { status: "too-large" };
+	const body = request.body;
+	if (!body) return {
+		status: "ok",
+		request,
+		bodyParseFailed: true
+	};
+	const reader = body.getReader();
+	const chunks = [];
+	let byteLength = 0;
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		byteLength += value.byteLength;
+		if (byteLength > maxBodyBytes) {
+			reader.cancel();
+			return { status: "too-large" };
+		}
+		chunks.push(value);
+	}
+	const bodyBytes = new Uint8Array(byteLength);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bodyBytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	const boundedRequest = new Request(request.url, {
+		method: request.method,
+		headers: new Headers(request.headers),
+		body: bodyBytes,
+		redirect: request.redirect,
+		signal: request.signal
+	});
+	try {
+		return {
+			status: "ok",
+			request: boundedRequest,
+			parsedBody: JSON.parse(new TextDecoder().decode(bodyBytes)),
+			bodyParseFailed: false
+		};
+	} catch {
+		return {
+			status: "ok",
+			request: boundedRequest,
+			bodyParseFailed: true
+		};
+	}
+}
+function isContentLengthOverLimit(request, maxBodyBytes) {
+	const rawContentLength = request.headers.get("content-length");
+	if (rawContentLength === null) return false;
+	const contentLength = Number(rawContentLength);
+	return Number.isFinite(contentLength) && contentLength > maxBodyBytes;
+}
+const DOCS_MCP_CORS_METHODS = [
+	"GET",
+	"POST",
+	"DELETE",
+	"OPTIONS"
+];
+const DOCS_MCP_CORS_REQUEST_METHODS = new Set([
+	"GET",
+	"POST",
+	"DELETE"
+]);
+function createDocsMcpOptionsResponse(request, cors) {
+	const allow = DOCS_MCP_CORS_METHODS.join(", ");
+	if (!request.headers.get("origin") || !cors.enabled) return new Response(null, {
+		status: 204,
+		headers: { Allow: allow }
+	});
+	const requestedMethod = request.headers.get("access-control-request-method")?.trim().toUpperCase();
+	if (requestedMethod && !DOCS_MCP_CORS_REQUEST_METHODS.has(requestedMethod)) return applyDocsMcpPreflightCorsHeaders(createMcpHttpSecurityErrorResponse(405, "CORS request method is not allowed"), request, cors);
+	const allowedHeaders = new Set(cors.allowedHeaders.map((header) => header.toLowerCase()));
+	const rejectedHeader = parseCorsRequestedHeaders(request.headers.get("access-control-request-headers")).find((header) => !allowedHeaders.has(header.toLowerCase()));
+	if (rejectedHeader) return applyDocsMcpPreflightCorsHeaders(createMcpHttpSecurityErrorResponse(403, `CORS request header is not allowed: ${rejectedHeader}`), request, cors);
+	return applyDocsMcpPreflightCorsHeaders(new Response(null, {
+		status: 204,
+		headers: { Allow: allow }
+	}), request, cors);
+}
+function parseCorsRequestedHeaders(value) {
+	if (!value) return [];
+	return value.split(",").map((header) => header.trim()).filter(Boolean);
+}
+function applyDocsMcpPreflightCorsHeaders(response, request, cors) {
+	const headers = buildDocsMcpCorsHeaders(response.headers, request, cors);
+	headers.set("Access-Control-Allow-Methods", DOCS_MCP_CORS_METHODS.join(", "));
+	headers.set("Access-Control-Allow-Headers", cors.allowedHeaders.join(", "));
+	headers.set("Access-Control-Max-Age", String(cors.maxAgeSeconds));
+	appendVaryHeader(headers, "Access-Control-Request-Method");
+	appendVaryHeader(headers, "Access-Control-Request-Headers");
+	return cloneResponseWithHeaders(response, headers);
+}
+function applyDocsMcpCorsHeaders(response, request, cors) {
+	if (!request.headers.has("origin") || !cors.enabled) return response;
+	const headers = buildDocsMcpCorsHeaders(response.headers, request, cors);
+	if (!headers.has("Access-Control-Allow-Origin")) return response;
+	if (cors.exposedHeaders.length > 0) headers.set("Access-Control-Expose-Headers", cors.exposedHeaders.join(", "));
+	return cloneResponseWithHeaders(response, headers);
+}
+function buildDocsMcpCorsHeaders(source, request, cors) {
+	const headers = new Headers(source);
+	headers.delete("Access-Control-Allow-Origin");
+	headers.delete("Access-Control-Allow-Credentials");
+	const origin = serializeCorsOrigin(request.headers.get("origin"));
+	if (!origin) return headers;
+	headers.set("Access-Control-Allow-Origin", origin);
+	if (cors.allowCredentials) headers.set("Access-Control-Allow-Credentials", "true");
+	else headers.delete("Access-Control-Allow-Credentials");
+	appendVaryHeader(headers, "Origin");
+	return headers;
+}
+function serializeCorsOrigin(value) {
+	if (!value) return null;
+	if (value.trim() === "null") return "null";
+	try {
+		const origin = new URL(value).origin;
+		return origin === "null" ? null : origin;
+	} catch {
+		return null;
+	}
+}
+function appendVaryHeader(headers, value) {
+	const values = (headers.get("Vary") ?? "").split(",").map((entry) => entry.trim()).filter(Boolean);
+	if (!values.some((entry) => entry.toLowerCase() === value.toLowerCase())) values.push(value);
+	headers.set("Vary", values.join(", "));
+}
+function cloneResponseWithHeaders(response, headers) {
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers
+	});
+}
+function createMcpRequestTooLargeResponse(maxBodyBytes) {
+	const response = createJsonRpcErrorResponse({
+		status: 413,
+		code: -32e3,
+		message: `Request body exceeds the ${maxBodyBytes} byte limit`,
+		data: {
+			reason: "request_too_large",
+			maxBodyBytes
+		}
+	});
+	response.headers.set("Cache-Control", "no-store");
+	return response;
+}
+function createMcpHttpSecurityErrorResponse(status, error) {
+	return new Response(JSON.stringify({ error }), {
+		status,
+		headers: {
+			"Content-Type": "application/json",
+			"Cache-Control": "no-store"
+		}
+	});
+}
 function createJsonErrorResponse(status, error) {
 	return new Response(JSON.stringify({ error }), {
 		status,
@@ -1570,9 +2630,14 @@ function scanFilesystemDocsPages(contentDirAbs, entry, rootDir) {
 				title,
 				description: data.description,
 				relatedInput: data.related,
+				agent: normalizePageAgentFrontmatter(data.agent),
 				icon: data.icon,
 				sourcePath: path.relative(rootDir, full).replace(/\\/g, "/"),
 				lastModified: stat.mtime.toISOString(),
+				locale: typeof data.locale === "string" ? data.locale : void 0,
+				framework: typeof data.framework === "string" ? data.framework : void 0,
+				version: typeof data.version === "string" ? data.version : void 0,
+				tags: Array.isArray(data.tags) ? data.tags.filter((tag) => typeof tag === "string") : void 0,
 				content: stripMarkdownForMcp(humanRawContent),
 				rawContent: humanRawContent,
 				agentFallbackContent: pageAgentContent,
@@ -1714,12 +2779,17 @@ function toSearchSourcePages(pages) {
 		rawContent: page.agentRawContent ?? page.agentFallbackRawContent ?? 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
+		related: page.related,
+		agent: page.agent
 	}));
 }
 function getDocsConfigSchema(filters) {
@@ -1803,13 +2873,24 @@ function resolveMcpToolSearchConfig(search, route) {
 		chunking: config.chunking
 	};
 }
+function toAgentContractSummary(value) {
+	const agent = normalizePageAgentFrontmatter(value);
+	const hasContract = hasStructuredPageAgentContract(agent);
+	return {
+		hasContract,
+		...hasContract && agent?.task ? { task: agent.task } : {},
+		...hasContract && agent?.outcome ? { outcome: agent.outcome } : {},
+		...hasContract && agent?.appliesTo ? { appliesTo: agent.appliesTo } : {}
+	};
+}
 function toPageSummaries(pages) {
 	return pages.map((page) => ({
 		slug: page.slug,
 		url: page.url,
 		title: page.title,
 		description: page.description,
-		icon: page.icon
+		icon: page.icon,
+		agent: toAgentContractSummary(page.agent)
 	}));
 }
 function toDocsListPageSummary(page) {
@@ -1818,11 +2899,47 @@ function toDocsListPageSummary(page) {
 		url: page.url,
 		title: page.title,
 		description: page.description,
+		agent: toAgentContractSummary(page.agent),
 		icon: page.icon,
 		sourcePath: page.sourcePath,
 		lastModified: page.lastModified
 	};
 }
+function listDocsTasks(pages, filters) {
+	const query = filters.query?.toLowerCase();
+	const applicabilityFilters = [
+		["framework", filters.framework],
+		["version", filters.version],
+		["package", filters.package]
+	];
+	return pages.flatMap((page) => {
+		const agent = normalizePageAgentFrontmatter(page.agent);
+		if (!agent || !hasStructuredPageAgentContract(agent)) return [];
+		for (const [field, expected] of applicabilityFilters) {
+			if (!expected) continue;
+			const actualValue = agent.appliesTo?.[field];
+			if (!(typeof actualValue === "string" ? [actualValue] : actualValue ?? []).some((value) => value.toLowerCase() === expected.toLowerCase())) return [];
+		}
+		if (query) {
+			if (![
+				page.slug,
+				page.url,
+				page.title,
+				page.description,
+				JSON.stringify(agent)
+			].filter(Boolean).join("\n").toLowerCase().includes(query)) return [];
+		}
+		return [{
+			slug: page.slug,
+			url: page.url,
+			title: page.title,
+			...page.description ? { description: page.description } : {},
+			...agent.task ? { task: agent.task } : {},
+			...agent.outcome ? { outcome: agent.outcome } : {},
+			...agent.appliesTo ? { appliesTo: agent.appliesTo } : {}
+		}];
+	});
+}
 function listDocsBySection(pages, filters) {
 	const allPages = pages.map(toDocsListPageSummary);
 	const tree = buildDocsSectionTree(pages);
@@ -2113,6 +3230,269 @@ function getCodeExampleSearchText(example) {
 		example.code
 	].filter((value) => typeof value === "string").join("\n");
 }
+function limitDocsMcpText(value, maxChars) {
+	if (maxChars === void 0 || value.length <= maxChars) return {
+		text: value,
+		truncated: false
+	};
+	if (maxChars <= 1) return {
+		text: value.slice(0, maxChars),
+		truncated: true
+	};
+	const suffix = "…";
+	const available = Math.max(0, maxChars - 1);
+	let selected = value.slice(0, available);
+	const paragraphBreak = selected.lastIndexOf("\n\n");
+	const lineBreak = selected.lastIndexOf("\n");
+	const preferredBreak = paragraphBreak >= available * .6 ? paragraphBreak : lineBreak;
+	if (preferredBreak >= available * .6) selected = selected.slice(0, preferredBreak);
+	return {
+		text: `${selected.trimEnd()}${suffix}`.slice(0, maxChars),
+		truncated: true
+	};
+}
+function docsMcpUtf8Bytes(value) {
+	return UTF8_ENCODER.encode(value).byteLength;
+}
+function limitDocsMcpUtf8Bytes(value, maxUtf8Bytes) {
+	if (docsMcpUtf8Bytes(value) <= maxUtf8Bytes) return {
+		text: value,
+		truncated: false
+	};
+	if (maxUtf8Bytes <= 0) return {
+		text: "",
+		truncated: true
+	};
+	const suffix = "…";
+	const suffixBytes = docsMcpUtf8Bytes(suffix);
+	const availableBytes = Math.max(0, maxUtf8Bytes - suffixBytes);
+	let selected = "";
+	let selectedBytes = 0;
+	for (const character of value) {
+		const characterBytes = docsMcpUtf8Bytes(character);
+		if (selectedBytes + characterBytes > availableBytes) break;
+		selected += character;
+		selectedBytes += characterBytes;
+	}
+	const paragraphBreak = selected.lastIndexOf("\n\n");
+	const lineBreak = selected.lastIndexOf("\n");
+	const preferredBreak = paragraphBreak >= selected.length * .6 ? paragraphBreak : lineBreak;
+	if (preferredBreak >= selected.length * .6) selected = selected.slice(0, preferredBreak);
+	if (suffixBytes > maxUtf8Bytes) return {
+		text: ".".repeat(maxUtf8Bytes),
+		truncated: true
+	};
+	return {
+		text: `${selected.trimEnd()}${suffix}`,
+		truncated: true
+	};
+}
+function renderBoundedDocsMcpSectionError(options) {
+	const maxChars = options.maxChars ?? Number.POSITIVE_INFINITY;
+	const shorten = (value, max) => limitDocsMcpText(value, max).text;
+	const availableSections = [];
+	const base = {
+		error: "section_not_found",
+		message: `No section matched "${shorten(options.requestedSection, 80)}" in "${shorten(options.pageUrl, 80)}".`,
+		availableSections,
+		truncated: false
+	};
+	const serialize = () => JSON.stringify(base, null, 2);
+	for (const section of options.availableSections) {
+		availableSections.push({
+			title: shorten(section.title, 80),
+			anchor: shorten(section.anchor, 80)
+		});
+		if (serialize().length > maxChars) {
+			availableSections.pop();
+			base.truncated = true;
+			break;
+		}
+	}
+	if (availableSections.length < options.availableSections.length) base.truncated = true;
+	if (serialize().length <= maxChars) return serialize();
+	const minimalText = JSON.stringify({
+		error: "section_not_found",
+		message: "The requested section was not found.",
+		availableSections: [],
+		truncated: true
+	});
+	if (minimalText.length <= maxChars) return minimalText;
+	return JSON.stringify({ error: "section_not_found" });
+}
+function toStructuredDocsMcpPage(page) {
+	return {
+		slug: page.slug,
+		url: page.url,
+		title: page.title,
+		description: page.description,
+		related: page.related,
+		icon: page.icon,
+		sourcePath: page.sourcePath,
+		lastModified: page.lastModified,
+		locale: page.locale,
+		framework: page.framework,
+		version: page.version,
+		tags: page.tags
+	};
+}
+function getDocsMcpSourceMarkdown(page) {
+	return page.agentRawContent ?? page.agentFallbackRawContent ?? page.rawContent ?? page.agentContent ?? page.agentFallbackContent ?? page.content;
+}
+function normalizeDocsMcpFramework(value) {
+	const normalized = value.toLowerCase().replace(/[^a-z0-9]/gu, "");
+	if (["next", "nextjs"].includes(normalized)) return "nextjs";
+	if (["tanstack", "tanstackstart"].includes(normalized)) return "tanstackstart";
+	if (["svelte", "sveltekit"].includes(normalized)) return "sveltekit";
+	return normalized;
+}
+function normalizeDocsMcpVersion(value) {
+	return value.trim().toLowerCase().replace(/^v(?=\d)/u, "");
+}
+function normalizeDocsMcpLocale(value) {
+	return value.trim().toLowerCase().replace(/_/gu, "-");
+}
+function pageMatchesDocsMcpContextScope(page, filters) {
+	if (filters.framework && page.framework && normalizeDocsMcpFramework(page.framework) !== normalizeDocsMcpFramework(filters.framework)) return false;
+	if (filters.version && page.version && normalizeDocsMcpVersion(page.version) !== normalizeDocsMcpVersion(filters.version)) return false;
+	if (filters.locale && page.locale && normalizeDocsMcpLocale(page.locale) !== normalizeDocsMcpLocale(filters.locale)) return false;
+	return true;
+}
+function getDocsMcpResultPageUrl(value) {
+	return value.split("#", 1)[0] ?? value;
+}
+function getDocsMcpResultAnchor(value) {
+	const anchor = value.split("#", 2)[1];
+	if (!anchor) return void 0;
+	try {
+		return decodeURIComponent(anchor);
+	} catch {
+		return anchor;
+	}
+}
+async function buildDocsMcpContext(options) {
+	const scopedPages = options.pages.filter((page) => pageMatchesDocsMcpContextScope(page, {
+		framework: options.framework,
+		version: options.version,
+		locale: options.locale
+	}));
+	const orderedResults = [...await performDocsSearch({
+		pages: toSearchSourcePages(scopedPages),
+		query: options.query,
+		search: {
+			enabled: true,
+			provider: "simple",
+			maxResults: 50,
+			chunking: { strategy: "section" }
+		},
+		locale: options.locale,
+		siteTitle: options.siteTitle,
+		limit: 50
+	})].sort((left, right) => {
+		const scoreDelta = (right.score ?? 0) - (left.score ?? 0);
+		if (scoreDelta !== 0) return scoreDelta;
+		if (left.url !== right.url) return left.url < right.url ? -1 : 1;
+		if ((left.section ?? "") !== (right.section ?? "")) return (left.section ?? "") < (right.section ?? "") ? -1 : 1;
+		if (left.id === right.id) return 0;
+		return left.id < right.id ? -1 : 1;
+	});
+	const sectionPageUrls = new Set(orderedResults.filter((result) => result.section).map((result) => normalizeUrlPath(getDocsMcpResultPageUrl(result.url))));
+	const seen = /* @__PURE__ */ new Set();
+	const resolvedCandidates = orderedResults.filter((result) => {
+		const pageUrl = normalizeUrlPath(getDocsMcpResultPageUrl(result.url));
+		if (!result.section && sectionPageUrls.has(pageUrl)) return false;
+		const key = `${pageUrl}#${getDocsMcpResultAnchor(result.url) ?? result.section ?? ""}`;
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	}).flatMap((result) => {
+		const page = findDocsPage(scopedPages, getDocsMcpResultPageUrl(result.url), options.entry);
+		if (!page) return [];
+		const document = upsertPageAgentContractMarkdown(getDocsMcpSourceMarkdown(page), page.agent);
+		const resultAnchor = getDocsMcpResultAnchor(result.url);
+		const selectedSection = resultAnchor ? findDocsMarkdownSection(document, resultAnchor) : result.section ? findDocsMarkdownSection(document, result.section) : void 0;
+		if ((resultAnchor || result.section) && !selectedSection) return [];
+		const rawContent = (selectedSection?.content ?? document).trim();
+		if (!rawContent) return [];
+		return [{
+			result,
+			page,
+			selectedSection,
+			rawContent
+		}];
+	});
+	const maxUtf8Bytes = options.tokenBudget;
+	const separator = "\n\n---\n\n";
+	const separatorUtf8Bytes = docsMcpUtf8Bytes(separator);
+	const blocks = [];
+	const sources = [];
+	let usedUtf8Bytes = 0;
+	for (const { result, page, selectedSection, rawContent } of resolvedCandidates) {
+		const anchor = selectedSection?.anchor;
+		const sourceUrl = anchor ? `${page.url}#${anchor}` : page.url;
+		const headerLines = [`## ${page.title}`, `Source: ${sourceUrl}`];
+		if (selectedSection?.title) headerLines.push(`Section: ${selectedSection.title}`);
+		if (page.framework) headerLines.push(`Framework: ${page.framework}`);
+		if (page.version) headerLines.push(`Version: ${page.version}`);
+		if (page.locale) headerLines.push(`Locale: ${page.locale}`);
+		const header = headerLines.join("\n");
+		const separatorBytes = blocks.length === 0 ? 0 : separatorUtf8Bytes;
+		const headerBytes = docsMcpUtf8Bytes(`${header}\n\n`);
+		const availableForContent = maxUtf8Bytes - usedUtf8Bytes - separatorBytes - headerBytes;
+		if (availableForContent <= 0) break;
+		const limited = limitDocsMcpUtf8Bytes(rawContent, availableForContent);
+		if (!limited.text) break;
+		const block = `${header}\n\n${limited.text}`;
+		const blockUtf8Bytes = docsMcpUtf8Bytes(block);
+		blocks.push(block);
+		usedUtf8Bytes += separatorBytes + blockUtf8Bytes;
+		sources.push({
+			id: result.id,
+			title: page.title,
+			pageUrl: page.url,
+			url: sourceUrl,
+			section: selectedSection?.title,
+			anchor,
+			sourcePath: page.sourcePath,
+			lastModified: page.lastModified,
+			locale: page.locale,
+			framework: page.framework,
+			version: page.version,
+			tags: page.tags,
+			score: result.score,
+			content: limited.text,
+			chars: limited.text.length,
+			utf8Bytes: docsMcpUtf8Bytes(limited.text),
+			truncated: limited.truncated
+		});
+		if (limited.truncated) break;
+	}
+	const context = blocks.join(separator);
+	usedUtf8Bytes = docsMcpUtf8Bytes(context);
+	const remainingUtf8Bytes = Math.max(0, maxUtf8Bytes - usedUtf8Bytes);
+	const truncated = sources.some((source) => source.truncated) || sources.length < resolvedCandidates.length;
+	return {
+		query: options.query,
+		filters: {
+			framework: options.framework,
+			version: options.version,
+			locale: options.locale
+		},
+		budget: {
+			requestedTokens: options.tokenBudget,
+			strategy: "utf8-bytes",
+			maxUtf8Bytes,
+			usedUtf8Bytes,
+			conservativeTokenUpperBound: usedUtf8Bytes,
+			remainingUtf8Bytes,
+			truncated
+		},
+		resultCount: sources.length,
+		candidateCount: resolvedCandidates.length,
+		context,
+		sources
+	};
+}
 function findDocsPage(pages, requestedPath, entry) {
 	const normalizedRequest = normalizeRequestedPath(requestedPath, entry);
 	for (const page of pages) if (normalizeUrlPath(page.url) === normalizedRequest) return page;
@@ -2141,12 +3521,12 @@ function normalizeUrlPath(value) {
 	return normalized.replace(/\/+$/, "");
 }
 function renderPageDocument(page) {
-	if (page.agentRawContent !== void 0) return page.agentRawContent;
+	if (page.agentRawContent !== void 0) return upsertPageAgentContractMarkdown(page.agentRawContent, page.agent);
 	const relatedLines = renderDocsRelatedMarkdownLines(page.related);
 	const lines = [`# ${page.title}`, `URL: ${page.url}`];
 	if (page.description) lines.push(`Description: ${page.description}`);
 	lines.push(...relatedLines);
-	lines.push("", page.agentFallbackRawContent ?? page.rawContent ?? page.content);
+	lines.push("", upsertPageAgentContractMarkdown(page.agentFallbackRawContent ?? page.rawContent ?? page.content, page.agent));
 	return lines.join("\n");
 }
 function renderNavigationTree(tree) {
@@ -2175,4 +3555,4 @@ function toPageResourceUri(url) {
 }
 
 //#endregion
-export { createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio };
+export { DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS, DEFAULT_DOCS_MCP_CORS_EXPOSED_HEADERS, DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS, DEFAULT_DOCS_MCP_MAX_BODY_BYTES, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio };