@farming-labs/docs 0.2.52 → 0.2.54

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 emitDocsAnalyticsEvent, i as emitDocsAgentTraceEvent, n as createDocsAgentTraceContext, r as createDocsAgentTraceId } from "./analytics-Bx44lg6d.mjs";
+import { Gt as hasStructuredPageAgentContract, Kt as normalizePageAgentFrontmatter, Lt as normalizeDocsRelated, Rt as renderDocsRelatedMarkdownLines, Xt as upsertPageAgentContractMarkdown } from "./agent-DXkXi-pS.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-CJIC1Cqo.mjs";
+import { a as normalizeAgentScopeValues, i as normalizeAgentLocale, n as agentVersionConstraintsOverlap, r as normalizeAgentFramework, t as agentVersionConstraintMatches } from "./agent-scope-B8lptqCd.mjs";
 import matter from "gray-matter";
 import fs from "node:fs";
 import path from "node:path";
@@ -14,7 +15,41 @@ 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 DOCS_CONFIG_SCHEMA_OPTIONS = [
+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"
+]);
+function freezeDocsConfigSchemaOptions(options) {
+	for (const option of options) {
+		if (option.values) Object.freeze(option.values);
+		if (option.children) {
+			freezeDocsConfigSchemaOptions([...option.children]);
+			Object.freeze(option.children);
+		}
+		Object.freeze(option);
+	}
+	return Object.freeze(options);
+}
+function freezeDocsConfigSchemaExamples(examples) {
+	for (const example of examples) Object.freeze(example);
+	return Object.freeze(examples);
+}
+const DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE = [
 	{
 		path: "entry",
 		name: "entry",
@@ -23,6 +58,14 @@ const DOCS_CONFIG_SCHEMA_OPTIONS = [
 		description: "URL path prefix for documentation routes, for example \"docs\" creates /docs.",
 		docs: "/docs/overview"
 	},
+	{
+		path: "docsPath",
+		name: "docsPath",
+		type: "string",
+		default: "same as entry",
+		description: "Public route prefix for docs pages when it differs from the source entry directory.",
+		docs: "/docs/overview"
+	},
 	{
 		path: "contentDir",
 		name: "contentDir",
@@ -31,6 +74,13 @@ const DOCS_CONFIG_SCHEMA_OPTIONS = [
 		description: "Path to markdown content files. Adapters outside Next.js usually need this when content does not live under the route prefix.",
 		docs: "/docs/overview"
 	},
+	{
+		path: "i18n",
+		name: "i18n",
+		type: "DocsI18nConfig",
+		description: "Locale discovery, default locale, and localized docs content configuration.",
+		docs: "/docs/reference"
+	},
 	{
 		path: "staticExport",
 		name: "staticExport",
@@ -46,6 +96,25 @@ const DOCS_CONFIG_SCHEMA_OPTIONS = [
 		description: "Theme instance from a theme factory such as fumadocs() or pixelBorder().",
 		docs: "/docs/customization/themes"
 	},
+	{
+		path: "analytics",
+		name: "analytics",
+		type: "boolean | DocsAnalyticsConfig",
+		default: false,
+		description: "Built-in privacy-aware product and agent surface analytics."
+	},
+	{
+		path: "telemetry",
+		name: "telemetry",
+		type: "boolean | DocsTelemetryConfig",
+		description: "Project telemetry controls for framework and agent-surface events."
+	},
+	{
+		path: "observability",
+		name: "observability",
+		type: "boolean | DocsObservabilityConfig",
+		description: "Tracing and observability callbacks for search, AI, and agent operations."
+	},
 	{
 		path: "nav",
 		name: "nav",
@@ -135,12 +204,419 @@ const DOCS_CONFIG_SCHEMA_OPTIONS = [
 		default: false,
 		description: "Opt-in estimated reading time label with per-page overrides and label format."
 	},
+	{
+		path: "lastUpdated",
+		name: "lastUpdated",
+		type: "boolean | LastUpdatedConfig",
+		description: "Last-updated metadata and labels derived from source history or page data."
+	},
+	{
+		path: "ordering",
+		name: "ordering",
+		type: "\"alphabetical\" | \"numeric\" | OrderingItem[]",
+		description: "Navigation ordering strategy or explicit ordered navigation entries."
+	},
 	{
 		path: "agent",
 		name: "agent",
 		type: "DocsAgentConfig",
-		description: "Defaults for docs agent compact and generated agent-facing files.",
-		docs: "/docs/getting-started/agent-ready-docs"
+		description: "Agent compaction defaults and deterministic usefulness evaluations.",
+		docs: "/docs/getting-started/agent-ready-docs",
+		children: [{
+			path: "agent.compact",
+			name: "compact",
+			type: "DocsAgentCompactConfig",
+			description: "Defaults for generated agent.md compaction.",
+			children: [
+				{
+					path: "agent.compact.apiKey",
+					name: "apiKey",
+					type: "string",
+					description: "Direct compaction provider API key; prefer apiKeyEnv."
+				},
+				{
+					path: "agent.compact.apiKeyEnv",
+					name: "apiKeyEnv",
+					type: "string",
+					description: "Environment variable containing the compaction provider API key."
+				},
+				{
+					path: "agent.compact.baseUrl",
+					name: "baseUrl",
+					type: "string",
+					description: "Compaction provider base URL."
+				},
+				{
+					path: "agent.compact.model",
+					name: "model",
+					type: "string",
+					description: "Compaction model identifier."
+				},
+				{
+					path: "agent.compact.aggressiveness",
+					name: "aggressiveness",
+					type: "number",
+					default: .3,
+					description: "Compression aggressiveness from 0 to 1."
+				},
+				{
+					path: "agent.compact.maxOutputTokens",
+					name: "maxOutputTokens",
+					type: "number",
+					description: "Upper output token target."
+				},
+				{
+					path: "agent.compact.minOutputTokens",
+					name: "minOutputTokens",
+					type: "number",
+					description: "Lower output token target."
+				},
+				{
+					path: "agent.compact.protectJson",
+					name: "protectJson",
+					type: "boolean",
+					description: "Preserve JSON objects during compaction when supported."
+				}
+			]
+		}, {
+			path: "agent.evaluations",
+			name: "evaluations",
+			type: "boolean | DocsAgentEvaluationsConfig",
+			description: "Deterministic golden tasks for retrieval, citation, version, example, and budget evaluation.",
+			children: [
+				{
+					path: "agent.evaluations.enabled",
+					name: "enabled",
+					type: "boolean",
+					default: true,
+					description: "Enable configured golden-task evaluation."
+				},
+				{
+					path: "agent.evaluations.tokenBudget",
+					name: "tokenBudget",
+					type: "number",
+					default: 4e3,
+					description: "Default hard UTF-8 context-byte ceiling for golden tasks."
+				},
+				{
+					path: "agent.evaluations.topK",
+					name: "topK",
+					type: "number",
+					default: 5,
+					description: "Default number of ranked search results evaluated per task."
+				},
+				{
+					path: "agent.evaluations.tasks",
+					name: "tasks",
+					type: "DocsAgentGoldenTask[]",
+					description: "Offline golden task fixtures evaluated by docs doctor and docs review.",
+					children: [
+						{
+							path: "agent.evaluations.tasks[]",
+							name: "task",
+							type: "DocsAgentGoldenTask",
+							description: "One golden task entry."
+						},
+						{
+							path: "agent.evaluations.tasks[].id",
+							name: "id",
+							type: "string",
+							description: "Stable task identifier shown in diagnostics."
+						},
+						{
+							path: "agent.evaluations.tasks[].query",
+							name: "query",
+							type: "string",
+							description: "User-shaped retrieval query."
+						},
+						{
+							path: "agent.evaluations.tasks[].tokenBudget",
+							name: "tokenBudget",
+							type: "number",
+							description: "Per-task UTF-8 context-byte ceiling override."
+						},
+						{
+							path: "agent.evaluations.tasks[].topK",
+							name: "topK",
+							type: "number",
+							description: "Per-task ranked retrieval depth override."
+						},
+						{
+							path: "agent.evaluations.tasks[].filters",
+							name: "filters",
+							type: "DocsAgentGoldenTaskFilters",
+							description: "Framework, version, and locale retrieval scope.",
+							children: [
+								{
+									path: "agent.evaluations.tasks[].filters.framework",
+									name: "framework",
+									type: "string",
+									description: "Required framework, such as nextjs or astro."
+								},
+								{
+									path: "agent.evaluations.tasks[].filters.version",
+									name: "version",
+									type: "string",
+									description: "Exact version requested by the task."
+								},
+								{
+									path: "agent.evaluations.tasks[].filters.locale",
+									name: "locale",
+									type: "string",
+									description: "Required locale."
+								}
+							]
+						},
+						{
+							path: "agent.evaluations.tasks[].expect",
+							name: "expect",
+							type: "DocsAgentGoldenTaskExpectation",
+							description: "Deterministic sources, rank, citation, example, and budget expectations.",
+							children: [
+								{
+									path: "agent.evaluations.tasks[].expect.relevantSources",
+									name: "relevantSources",
+									type: "string[]",
+									description: "Canonical page or section URLs that should answer the task."
+								},
+								{
+									path: "agent.evaluations.tasks[].expect.allowedSources",
+									name: "allowedSources",
+									type: "string[]",
+									description: "Additional legitimate citations that do not reduce precision."
+								},
+								{
+									path: "agent.evaluations.tasks[].expect.forbiddenSources",
+									name: "forbiddenSources",
+									type: "string[]",
+									description: "Sources that must not be retrieved or cited."
+								},
+								{
+									path: "agent.evaluations.tasks[].expect.requiredCitations",
+									name: "requiredCitations",
+									type: "string[]",
+									description: "Citations that must appear; defaults to relevantSources."
+								},
+								{
+									path: "agent.evaluations.tasks[].expect.minRecallAtK",
+									name: "minRecallAtK",
+									type: "number",
+									default: 1,
+									description: "Minimum relevant-source recall in the top K results."
+								},
+								{
+									path: "agent.evaluations.tasks[].expect.maxFirstRelevantRank",
+									name: "maxFirstRelevantRank",
+									type: "number",
+									description: "Maximum acceptable rank of the first relevant source."
+								},
+								{
+									path: "agent.evaluations.tasks[].expect.minUsefulByteRatio",
+									name: "minUsefulByteRatio",
+									type: "number",
+									description: "Minimum share of context bytes supplied by relevant sources."
+								},
+								{
+									path: "agent.evaluations.tasks[].expect.examples",
+									name: "examples",
+									type: "DocsAgentGoldenExpectedExample[]",
+									description: "Runnable examples that must be present in returned context.",
+									children: [
+										{
+											path: "agent.evaluations.tasks[].expect.examples[]",
+											name: "example",
+											type: "DocsAgentGoldenExpectedExample",
+											description: "One expected code example."
+										},
+										{
+											path: "agent.evaluations.tasks[].expect.examples[].source",
+											name: "source",
+											type: "string",
+											description: "Canonical source URL containing the example."
+										},
+										{
+											path: "agent.evaluations.tasks[].expect.examples[].language",
+											name: "language",
+											type: "string",
+											description: "Expected code-fence language."
+										},
+										{
+											path: "agent.evaluations.tasks[].expect.examples[].framework",
+											name: "framework",
+											type: "string",
+											description: "Expected framework metadata."
+										},
+										{
+											path: "agent.evaluations.tasks[].expect.examples[].packageManager",
+											name: "packageManager",
+											type: "string",
+											description: "Expected package-manager metadata."
+										},
+										{
+											path: "agent.evaluations.tasks[].expect.examples[].title",
+											name: "title",
+											type: "string",
+											description: "Expected code-fence title metadata."
+										},
+										{
+											path: "agent.evaluations.tasks[].expect.examples[].runnable",
+											name: "runnable",
+											type: "boolean",
+											default: true,
+											description: "Whether the example must be marked runnable."
+										},
+										{
+											path: "agent.evaluations.tasks[].expect.examples[].includes",
+											name: "includes",
+											type: "string[]",
+											description: "Literal code fragments that must appear."
+										}
+									]
+								}
+							]
+						}
+					]
+				}
+			]
+		}]
+	},
+	{
+		path: "review",
+		name: "review",
+		type: "boolean | DocsReviewConfig",
+		description: "Docs review scoring, CI behavior, and diagnostic rule severities.",
+		docs: "/docs/reference",
+		children: [
+			{
+				path: "review.enabled",
+				name: "enabled",
+				type: "boolean",
+				default: true,
+				description: "Enable Docs Review."
+			},
+			{
+				path: "review.score",
+				name: "score",
+				type: "DocsReviewScoreConfig",
+				description: "Healthy threshold and finding severity weights.",
+				children: [{
+					path: "review.score.threshold",
+					name: "threshold",
+					type: "number",
+					default: 80,
+					description: "Minimum healthy review score."
+				}, {
+					path: "review.score.weights",
+					name: "weights",
+					type: "{ error?: number; warn?: number; suggestion?: number }",
+					description: "Point deductions for each finding severity.",
+					children: [
+						{
+							path: "review.score.weights.error",
+							name: "error",
+							type: "number",
+							default: 20,
+							description: "Point deduction for an error finding."
+						},
+						{
+							path: "review.score.weights.warn",
+							name: "warn",
+							type: "number",
+							default: 8,
+							description: "Point deduction for a warning finding."
+						},
+						{
+							path: "review.score.weights.suggestion",
+							name: "suggestion",
+							type: "number",
+							default: 2,
+							description: "Point deduction for a suggestion finding."
+						}
+					]
+				}]
+			},
+			{
+				path: "review.ci",
+				name: "ci",
+				type: "boolean | DocsReviewCiConfig",
+				description: "GitHub Actions reporting and blocking behavior.",
+				children: [
+					{
+						path: "review.ci.enabled",
+						name: "enabled",
+						type: "boolean",
+						default: true,
+						description: "Enable review workflow generation."
+					},
+					{
+						path: "review.ci.name",
+						name: "name",
+						type: "string",
+						default: "docs-review",
+						description: "GitHub Actions job and check name."
+					},
+					{
+						path: "review.ci.mode",
+						name: "mode",
+						type: "\"off\" | \"warn\" | \"block\"",
+						default: "warn",
+						description: "Whether CI is disabled, advisory, or blocking.",
+						values: [
+							"off",
+							"warn",
+							"block"
+						]
+					},
+					{
+						path: "review.ci.annotations",
+						name: "annotations",
+						type: "boolean",
+						default: true,
+						description: "Emit GitHub workflow annotations."
+					},
+					{
+						path: "review.ci.comment",
+						name: "comment",
+						type: "boolean",
+						default: true,
+						description: "Allow the official action or bot to post PR comments."
+					}
+				]
+			},
+			{
+				path: "review.rules",
+				name: "rules",
+				type: "DocsReviewRulesConfig",
+				description: "Per-rule severity overrides.",
+				children: [
+					["brokenLinks", "error"],
+					["frontmatter", "error"],
+					["duplicateSlugs", "error"],
+					["invalidMdx", "error"],
+					["configExamples", "warn"],
+					["codeFenceMetadata", "warn"],
+					["runnableMetadata", "warn"],
+					["agentContext", "warn"],
+					["commandHealth", "warn"],
+					["relatedCoverage", "suggestion"],
+					["configConfidence", "warn"],
+					["agentSurfaceDrift", "error"],
+					["goldenTasks", "warn"]
+				].map(([name, defaultValue]) => ({
+					path: `review.rules.${name}`,
+					name,
+					type: "DocsReviewSeverity",
+					default: defaultValue,
+					description: `Severity override for the ${name} review rule.`,
+					values: [
+						"off",
+						"suggestion",
+						"warn",
+						"error"
+					]
+				}))
+			}
+		]
 	},
 	{
 		path: "pageActions",
@@ -328,6 +804,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 +889,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 +937,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."
 					}
 				]
 			}
@@ -470,7 +1031,8 @@ const DOCS_CONFIG_SCHEMA_OPTIONS = [
 		description: "Dynamic Open Graph image configuration."
 	}
 ];
-const DOCS_CONFIG_SCHEMA_EXAMPLES = [
+const DOCS_CONFIG_SCHEMA_OPTIONS = freezeDocsConfigSchemaOptions(DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE);
+const DOCS_CONFIG_SCHEMA_EXAMPLES = freezeDocsConfigSchemaExamples([
 	{
 		title: "Minimal config",
 		code: `import { defineDocs } from "@farming-labs/docs";
@@ -492,6 +1054,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;
+      },
+    },
+  },
 });`
 	},
 	{
@@ -516,7 +1091,7 @@ export default defineDocs({
   },
 });`
 	}
-];
+]);
 const searchDocsInputSchema = z.object({
 	query: z.string().trim().min(1),
 	limit: z.number().int().min(1).max(25).optional(),
@@ -524,8 +1099,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 +1187,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 +1391,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 +1411,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 +1488,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 +1513,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 +1527,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 +1554,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 +1573,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 +1603,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 +1627,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 +1649,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
 			});
@@ -775,38 +1659,281 @@ async function createDocsMcpServer(options) {
 				source: "mcp",
 				locale,
 				properties: {
-					tool: "list_docs",
-					section,
-					resultCount: docs.resultCount,
-					sectionCount: docs.sectionCount,
+					tool: "list_docs",
+					section,
+					resultCount: docs.resultCount,
+					sectionCount: docs.sectionCount,
+					durationMs: elapsed
+				}
+			});
+			trackMcpTool("list_docs", {
+				locale,
+				resultCount: docs.resultCount
+			});
+			await emitDocsAgentTraceEvent(options.observability, {
+				type: "tool.result",
+				source: "mcp",
+				traceId: trace.traceId,
+				parentSpanId: callSpanId,
+				name: "list_docs",
+				startedAt: trace.startedAt,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				durationMs: elapsed,
+				status: "success",
+				locale,
+				outputPreview: {
+					resultCount: docs.resultCount,
+					sectionCount: docs.sectionCount
+				},
+				metadata: { tool: "list_docs" }
+			});
+			return createStructuredTextResult(docs);
+		} catch (error) {
+			const elapsed = durationMs(startedAt);
+			await emitDocsAgentTraceEvent(options.observability, {
+				type: "tool.error",
+				source: "mcp",
+				traceId: trace.traceId,
+				parentSpanId: callSpanId,
+				name: "list_docs",
+				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_docs" }
+			});
+			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("list_docs", {
+			trackMcpTool("read_task", {
 				locale,
-				resultCount: docs.resultCount
+				resultCount: 1
 			});
 			await emitDocsAgentTraceEvent(options.observability, {
 				type: "tool.result",
 				source: "mcp",
 				traceId: trace.traceId,
 				parentSpanId: callSpanId,
-				name: "list_docs",
+				name: "read_task",
 				startedAt: trace.startedAt,
 				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
 				durationMs: elapsed,
 				status: "success",
 				locale,
+				path: page.url,
 				outputPreview: {
-					resultCount: docs.resultCount,
-					sectionCount: docs.sectionCount
+					found: true,
+					slug: page.slug
 				},
-				metadata: { tool: "list_docs" }
+				metadata: { tool: "read_task" }
 			});
-			return { content: [{
-				type: "text",
-				text: JSON.stringify(docs, null, 2)
-			}] };
+			return {
+				structuredContent: result,
+				content: [{
+					type: "text",
+					text: JSON.stringify(result, null, 2)
+				}]
+			};
 		} catch (error) {
 			const elapsed = durationMs(startedAt);
 			await emitDocsAgentTraceEvent(options.observability, {
@@ -814,14 +1941,14 @@ async function createDocsMcpServer(options) {
 				source: "mcp",
 				traceId: trace.traceId,
 				parentSpanId: callSpanId,
-				name: "list_docs",
+				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: "list_docs" }
+				metadata: { tool: "read_task" }
 			});
 			throw error;
 		}
@@ -830,6 +1957,7 @@ async function createDocsMcpServer(options) {
 		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 +1976,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 +2003,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 +2030,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 +2082,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 +2105,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 +2130,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 +2169,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 +2193,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 +2221,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 +2268,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 +2288,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 +2411,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 +2476,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 +2541,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 +2558,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 +2584,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 +2642,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 +2660,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 +2718,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 +3087,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,15 +3236,20 @@ 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) {
+function getDocsConfigSchema(filters = {}) {
 	const option = filters.option?.trim();
 	const query = filters.query?.trim();
 	let options = DOCS_CONFIG_SCHEMA_OPTIONS.map(cloneConfigSchemaOption);
@@ -1738,12 +3265,13 @@ function getDocsConfigSchema(filters) {
 		} : void 0,
 		resultCount: countConfigSchemaOptions(options),
 		options,
-		examples: DOCS_CONFIG_SCHEMA_EXAMPLES
+		examples: DOCS_CONFIG_SCHEMA_EXAMPLES.map((example) => ({ ...example }))
 	};
 }
 function cloneConfigSchemaOption(option) {
 	return {
 		...option,
+		values: option.values ? [...option.values] : void 0,
 		children: option.children?.map(cloneConfigSchemaOption)
 	};
 }
@@ -1803,13 +3331,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 +3357,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 +3688,288 @@ 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 resolveDocsMcpScopeField(pageValue, contractValue, filter, overlaps, matchesFilter) {
+	const pageValues = normalizeAgentScopeValues(pageValue);
+	const contractValues = normalizeAgentScopeValues(contractValue);
+	const conflict = pageValues.length > 0 && contractValues.length > 0 && !pageValues.some((topLevel) => contractValues.some((contract) => overlaps(topLevel, contract)));
+	const pageMatches = !filter || pageValues.length === 0 || pageValues.some((candidate) => matchesFilter(filter, candidate));
+	const contractMatches = !filter || contractValues.length === 0 || contractValues.some((candidate) => matchesFilter(filter, candidate));
+	const matchedContract = filter ? contractValues.find((candidate) => matchesFilter(filter, candidate)) : void 0;
+	return {
+		conflict,
+		matches: !conflict && pageMatches && contractMatches,
+		value: pageValues[0] ?? matchedContract ?? (contractValues.length === 1 ? contractValues[0] : void 0)
+	};
+}
+function resolveDocsMcpEffectiveScope(page, filters) {
+	const framework = resolveDocsMcpScopeField(page.framework, page.agent?.appliesTo?.framework, filters.framework, (left, right) => normalizeAgentFramework(left) === normalizeAgentFramework(right), (filter, candidate) => normalizeAgentFramework(filter) === normalizeAgentFramework(candidate));
+	const version = resolveDocsMcpScopeField(page.version, page.agent?.appliesTo?.version, filters.version, agentVersionConstraintsOverlap, agentVersionConstraintMatches);
+	const locale = page.locale?.trim() || void 0;
+	const localeMatches = !filters.locale || !locale || normalizeAgentLocale(locale) === normalizeAgentLocale(filters.locale);
+	return {
+		framework: framework.value,
+		version: version.value,
+		locale,
+		conflict: framework.conflict || version.conflict,
+		matches: framework.matches && version.matches && localeMatches
+	};
+}
+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 scopedPageEntries = options.pages.flatMap((page) => {
+		const scope = resolveDocsMcpEffectiveScope(page, {
+			framework: options.framework,
+			version: options.version,
+			locale: options.locale
+		});
+		return scope.matches && !scope.conflict ? [{
+			page,
+			scope
+		}] : [];
+	});
+	const scopedPages = scopedPageEntries.map(({ page }) => page);
+	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),
+		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 scope = scopeByPage.get(page);
+		if (!scope) 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,
+			scope,
+			selectedSection,
+			rawContent
+		}];
+	}).slice(0, maxResults);
+	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, scope, 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 (scope.framework) headerLines.push(`Framework: ${scope.framework}`);
+		if (scope.version) headerLines.push(`Version: ${scope.version}`);
+		if (scope.locale) headerLines.push(`Locale: ${scope.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: scope.locale,
+			framework: scope.framework,
+			version: scope.version,
+			tags: page.tags ? [...page.tags] : void 0,
+			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 +3998,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 +4032,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, DOCS_CONFIG_SCHEMA_OPTIONS, buildDocsMcpContext, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, getDocsConfigSchema, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio };