@farming-labs/docs 0.2.103 → 0.2.105

package/dist/mcp.mjs

@@ -1,9 +1,11 @@
-import { a as emitDocsAnalyticsEvent, i as emitDocsAgentTraceEvent, n as createDocsAgentTraceContext, r as createDocsAgentTraceId } from "./analytics-Bx44lg6d.mjs";
-import { $n as resolveDocsMcpProtectedResourceMetadataLocation, An as normalizeAgentLocale, Dn as agentVersionConstraintMatches, E as DOCS_MARKDOWN_SECTION_INDEX_FORMAT, Fn as paginateDocsItems, Jn as isDocsMcpProtectedResourceMetadataPath, Jt as resolveDocsContentChangesConfig, Kt as isDocsContentChangeGeneration, Ln as normalizeDocsRelated, Nn as DocsPaginationCursorError, On as agentVersionConstraintsOverlap, P as buildDocsMarkdownSectionIndex, Qn as normalizeDocsMcpEndpointPath, Rn as renderDocsRelatedMarkdownLines, Tn as resolveDocsAudienceMdxContent, Ut as DocsContentChangesRequestError, Wt as createDocsContentChangeFeed, Xn as isDocsMcpResourcePath, Zn as normalizeDocsMcpAuthorizationServerUrls, dn as performDocsSearch, er as resolveDocsMcpResourceLocation, fn as performDocsSearchWithMetadata, jn as normalizeAgentScopeValues, kn as normalizeAgentFramework, qn as isDocsMcpOAuthScopeToken, tn as buildDocsSearchFacets, un as normalizeDocsSearchFilters, wt as toDocsMarkdownUrl, yn as resolveLocalDocsMcpSearchConfig } from "./agent-CFqECAG0.mjs";
-import { S as upsertPageAgentContractMarkdown, _ as hasStructuredPageAgentContract, o as findDocsMarkdownSection, s as parseDocsMarkdownSections, v as normalizePageAgentFrontmatter, y as renderPageAgentContractMarkdown } from "./markdown-sections-7OoA7ylx.mjs";
-import { q as isDocsRetrievalCanonicalUrl } from "./standards-discovery-Ckx0tN7B.mjs";
-import { a as hydrateDocsContentChanges, f as stripGeneratedAgentProvenance, g as emitDocsTelemetryProjectEvent, h as emitDocsTelemetryMcpToolEvent, i as MIN_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, n as DOCS_CONTENT_CHANGE_HYDRATION_FORMAT, p as emitDocsTelemetryAgentSurfaceEvent, r as MAX_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, t as DEFAULT_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET } from "./content-change-hydration-BsbBXAUi.mjs";
-import { n as resolvePageSidebarFolderIndexBehavior } from "./sidebar-IcpElOVH.mjs";
+import { C as filterDocsPagesByAccess, S as upsertPageAgentContractMarkdown, _ as hasStructuredPageAgentContract, o as findDocsMarkdownSection, s as parseDocsMarkdownSections, v as normalizePageAgentFrontmatter, y as renderPageAgentContractMarkdown } from "./markdown-sections-BKy4labo.mjs";
+import { a as emitDocsAnalyticsEvent, i as emitDocsAgentTraceEvent, n as createDocsAgentTraceContext, r as createDocsAgentTraceId } from "./analytics-CqfcIBdg.mjs";
+import { $n as normalizeDocsMcpEndpointPath, An as normalizeAgentFramework, E as DOCS_MARKDOWN_SECTION_INDEX_FORMAT, En as resolveDocsAudienceMdxContent, Et as validateDocsAgentFeedbackPayload, Gt as createDocsContentChangeFeed, In as paginateDocsItems, Jn as isDocsMcpOAuthScopeToken, Mn as normalizeAgentScopeValues, On as agentVersionConstraintMatches, P as buildDocsMarkdownSectionIndex, Pn as DocsPaginationCursorError, Qn as normalizeDocsMcpAuthorizationServerUrls, Rn as normalizeDocsRelated, Tt as toDocsMarkdownUrl, Wt as DocsContentChangesRequestError, Yn as isDocsMcpProtectedResourceMetadataPath, Yt as resolveDocsContentChangesConfig, Zn as isDocsMcpResourcePath, ar as buildDocsOkfBundle, bn as resolveLocalDocsMcpSearchConfig, dn as normalizeDocsSearchFilters, er as resolveDocsMcpProtectedResourceMetadataLocation, fn as performDocsSearch, jn as normalizeAgentLocale, kn as agentVersionConstraintsOverlap, nn as buildDocsSearchFacets, or as normalizeDocsOkfTrustMetadataInput, pn as performDocsSearchWithMetadata, qt as isDocsContentChangeGeneration, sr as resolveDocsOkfConfig, tr as resolveDocsMcpResourceLocation, ut as resolveDocsAgentFeedbackConfig, zn as renderDocsRelatedMarkdownLines } from "./agent-DCTGj6J7.mjs";
+import { r as isDocsRetrievalCanonicalUrl } from "./retrieval-digest-B-SgtXKK.mjs";
+import "./standards-discovery-Bpz90VYq.mjs";
+import { _ as emitDocsTelemetryAgentSurfaceEvent, a as DEFAULT_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, b as emitDocsTelemetryProjectEvent, c as MIN_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, g as stripGeneratedAgentProvenance, i as resolveDocsOpenApiMcpOperations, l as hydrateDocsContentChanges, n as readDocsOpenApiMcpResponse, o as DOCS_CONTENT_CHANGE_HYDRATION_FORMAT, r as resolveDocsOpenApiMcpBaseUrl, s as MAX_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, t as acquireDocsOpenApiMcpBudget, y as emitDocsTelemetryMcpToolEvent } from "./openapi-mcp-DQ3xptKo.mjs";
+import { n as resolvePageSidebarFolderIndexBehavior } from "./sidebar-3W51s2sF.mjs";
+import { t as validateDocsOpenApiMcpUrl } from "./openapi-mcp-node-vO3IXVGI.mjs";
 import matter from "gray-matter";
 import fs from "node:fs";
 import path from "node:path";
@@ -12,6 +14,23 @@ import { InMemoryServerEventBus, McpServer, ProtocolError, ProtocolErrorCode, Re
 import * as z from "zod/v4";
 
 //#region src/mcp.ts
+function filterDocsMcpNavigation(tree, allowedUrls) {
+	const filterNodes = (nodes) => nodes.flatMap((node) => {
+		if (node.type === "page") return allowedUrls.has(node.url) ? [node] : [];
+		const children = filterNodes(node.children);
+		const index = node.index && allowedUrls.has(node.index.url) ? node.index : void 0;
+		const { index: _unfilteredIndex, ...folder } = node;
+		return children.length > 0 || index ? [{
+			...folder,
+			...index ? { index } : {},
+			children
+		}] : [];
+	});
+	return {
+		...tree,
+		children: filterNodes(tree.children)
+	};
+}
 const DEFAULT_MCP_VERSION = "0.0.0";
 const DEFAULT_MCP_NAME = "@farming-labs/docs";
 const DOCS_MCP_DISCOVERY_CACHE_TTL_MS = 300 * 1e3;
@@ -20,6 +39,8 @@ const DOCS_MCP_RESOURCE_CACHE_TTL_MS = 60 * 1e3;
 const DEFAULT_MCP_CONTEXT_TOKEN_BUDGET = 4e3;
 const MIN_MCP_CONTEXT_TOKEN_BUDGET = 256;
 const MAX_MCP_CONTEXT_TOKEN_BUDGET = 32e3;
+const DEFAULT_MCP_READ_PAGES_TOKEN_BUDGET = 8e3;
+const MAX_MCP_READ_PAGES_COUNT = 20;
 const DOCS_MCP_PROTOCOL_LIST_PAGE_SIZE = 10;
 const DOCS_MCP_TOOL_LIST_PAGE_SIZE = 25;
 const DOCS_MCP_PAGINATION_META_KEY = "dev.farming-labs/pagination";
@@ -233,6 +254,53 @@ const DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE = [
 		description: "Agent synchronization, reusable skills, compaction defaults, and offline-by-default usefulness evaluations.",
 		docs: "/docs/getting-started/agent-ready-docs",
 		children: [
+			{
+				path: "agent.okf",
+				name: "okf",
+				type: "boolean | DocsOkfConfig",
+				default: false,
+				description: "Publish Open Knowledge Format v0.2 source, generation, verification, lifecycle, and staleness metadata.",
+				children: [
+					{
+						path: "agent.okf.route",
+						name: "route",
+						type: "string",
+						default: "/.well-known/okf.json",
+						description: "Public route used by static Agent Bundle export."
+					},
+					{
+						path: "agent.okf.generatedBy",
+						name: "generatedBy",
+						type: "string",
+						default: "software:@farming-labs/docs",
+						description: "Generator actor used when a page omits okf.generated."
+					},
+					{
+						path: "agent.okf.staleAfterDays",
+						name: "staleAfterDays",
+						type: "number",
+						description: "Derive stale_after this many days after the best page timestamp."
+					},
+					{
+						path: "agent.okf.sources",
+						name: "sources",
+						type: "readonly DocsOkfSource[]",
+						description: "Default source provenance inherited by pages without authored sources."
+					},
+					{
+						path: "agent.okf.verified",
+						name: "verified",
+						type: "readonly DocsOkfActorTimestamp[]",
+						description: "Default machine or human verification records."
+					},
+					{
+						path: "agent.okf.status",
+						name: "status",
+						type: "\"draft\" | \"stable\" | \"deprecated\"",
+						description: "Default lifecycle status for knowledge documents."
+					}
+				]
+			},
 			{
 				path: "agent.contentChanges",
 				name: "contentChanges",
@@ -1380,40 +1448,55 @@ const DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE = [
 		path: "pageActions",
 		name: "pageActions",
 		type: "PageActionsConfig",
-		description: "Copy Markdown and Open in LLM actions for docs pages.",
+		description: "Copy, Open in LLM, MCP connection, and Agent Skills setup actions.",
 		docs: "/docs/customization/page-actions",
-		children: [{
-			path: "pageActions.copyMarkdown",
-			name: "copyMarkdown",
-			type: "boolean | PageActionConfig",
-			description: "Show a Copy Markdown action for the current page."
-		}, {
-			path: "pageActions.openDocs",
-			name: "openDocs",
-			type: "boolean | OpenDocsActionConfig",
-			description: "Show provider actions that open the current docs page in an LLM.",
-			children: [
-				{
-					path: "pageActions.openDocs.target",
-					name: "target",
-					type: "\"page\" | \"markdown\"",
-					default: "page",
-					description: "Whether provider URLs receive the rendered page URL or the .md markdown route."
-				},
-				{
-					path: "pageActions.openDocs.providers",
-					name: "providers",
-					type: "Array<string | PromptProviderConfig>",
-					description: "Provider IDs or provider objects. Built-ins include chatgpt, claude, cursor, and t3."
-				},
-				{
-					path: "pageActions.openDocs.prompt",
-					name: "prompt",
-					type: "string",
-					description: "Prompt text prepended to the provider URL when opening docs."
-				}
-			]
-		}]
+		children: [
+			{
+				path: "pageActions.copyMarkdown",
+				name: "copyMarkdown",
+				type: "boolean | PageActionConfig",
+				description: "Show a Copy Markdown action for the current page."
+			},
+			{
+				path: "pageActions.openDocs",
+				name: "openDocs",
+				type: "boolean | OpenDocsActionConfig",
+				description: "Show provider actions that open the current docs page in an LLM.",
+				children: [
+					{
+						path: "pageActions.openDocs.target",
+						name: "target",
+						type: "\"page\" | \"markdown\"",
+						default: "page",
+						description: "Whether provider URLs receive the rendered page URL or the .md markdown route."
+					},
+					{
+						path: "pageActions.openDocs.providers",
+						name: "providers",
+						type: "Array<string | PromptProviderConfig>",
+						description: "Provider IDs or provider objects. Built-ins include chatgpt, claude, cursor, and t3."
+					},
+					{
+						path: "pageActions.openDocs.prompt",
+						name: "prompt",
+						type: "string",
+						description: "Prompt text prepended to the provider URL when opening docs."
+					}
+				]
+			},
+			{
+				path: "pageActions.connectMcp",
+				name: "connectMcp",
+				type: "boolean | PageActionConnectMcpConfig",
+				description: "Show copyable MCP setup for Claude Code, Cursor, VS Code, Codex, or a raw endpoint."
+			},
+			{
+				path: "pageActions.installSkills",
+				name: "installSkills",
+				type: "boolean | PageActionInstallSkillsConfig",
+				description: "Discover the published Agent Skills index and provide a copyable skills install command."
+			}
+		]
 	},
 	{
 		path: "ai",
@@ -1778,6 +1861,20 @@ const DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE = [
 						default: true,
 						description: "Expose the read_page tool."
 					},
+					{
+						path: "mcp.tools.readPages",
+						name: "readPages",
+						type: "boolean",
+						default: true,
+						description: "Expose the budget-aware read_pages batch tool."
+					},
+					{
+						path: "mcp.tools.submitFeedback",
+						name: "submitFeedback",
+						type: "boolean",
+						default: true,
+						description: "Expose submit_feedback when feedback.agent is enabled and validate payloads with its configured schema."
+					},
 					{
 						path: "mcp.tools.getCodeExamples",
 						name: "getCodeExamples",
@@ -1798,6 +1895,13 @@ const DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE = [
 						type: "boolean",
 						default: true,
 						description: "Expose deterministic get_context retrieval with a conservative UTF-8 byte ceiling."
+					},
+					{
+						path: "mcp.tools.getTrustMetadata",
+						name: "getTrustMetadata",
+						type: "boolean",
+						default: true,
+						description: "Expose OKF v0.2 trust metadata when agent.okf is enabled."
 					}
 				]
 			}
@@ -1828,6 +1932,47 @@ const DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE = [
 				name: "catalogTargets",
 				type: "string[]",
 				description: "Product API base URLs that the OpenAPI document describes in the RFC 9727 catalog."
+			},
+			{
+				path: "apiReference.mcp",
+				name: "mcp",
+				type: "boolean | DocsOpenApiMcpConfig",
+				default: false,
+				description: "Project explicitly allowlisted OpenAPI operations into server-executed MCP tools.",
+				children: [
+					{
+						path: "apiReference.mcp.operations",
+						name: "operations",
+						type: "readonly string[]",
+						description: "Allowed operationIds or METHOD /path selectors; empty exposes nothing."
+					},
+					{
+						path: "apiReference.mcp.baseUrl",
+						name: "baseUrl",
+						type: "string",
+						description: "Override the first OpenAPI server URL used for tool requests."
+					},
+					{
+						path: "apiReference.mcp.allowMutations",
+						name: "allowMutations",
+						type: "boolean",
+						default: false,
+						description: "Permit explicitly allowlisted write operations."
+					},
+					{
+						path: "apiReference.mcp.headers",
+						name: "headers",
+						type: "DocsOpenApiMcpHeaders",
+						description: "Server-owned credential headers applied after model-provided input."
+					},
+					{
+						path: "apiReference.mcp.timeoutMs",
+						name: "timeoutMs",
+						type: "number",
+						default: 1e4,
+						description: "Per-operation HTTP timeout."
+					}
+				]
 			}
 		]
 	},
@@ -1996,6 +2141,30 @@ const readPageInputSchema = z.object({
 	section: z.string().trim().min(1).optional(),
 	maxChars: z.number().int().min(256).max(1e6).optional()
 });
+const trustMetadataInputSchema = z.object({
+	path: z.string().trim().min(1).optional(),
+	locale: z.string().trim().min(1).max(128).optional()
+});
+const openApiOperationInputSchema = z.object({
+	parameters: z.record(z.string(), z.unknown()).optional(),
+	body: z.unknown().optional()
+});
+const readPagesInputSchema = z.object({
+	paths: z.array(z.string().trim().min(1)).min(1).max(MAX_MCP_READ_PAGES_COUNT).describe("Page slugs or URL paths to read in the requested order."),
+	locale: z.string().trim().min(1).max(128).optional(),
+	tokenBudget: z.number().int().min(MIN_MCP_CONTEXT_TOKEN_BUDGET).max(MAX_MCP_CONTEXT_TOKEN_BUDGET).optional(),
+	maxCharsPerPage: z.number().int().min(256).max(1e6).optional()
+});
+const submitFeedbackInputSchema = z.object({
+	context: z.object({
+		page: z.string().optional(),
+		url: z.string().optional(),
+		slug: z.string().optional(),
+		locale: z.string().optional(),
+		source: z.string().optional()
+	}).optional(),
+	payload: z.record(z.string(), z.unknown())
+});
 const listPageSectionsInputSchema = z.object({
 	path: z.string().min(1),
 	locale: z.string().trim().min(1).max(128).optional(),
@@ -2304,7 +2473,8 @@ const searchResultOutputSchema = z.object({
 	]),
 	score: z.number().optional(),
 	section: z.string().optional(),
-	source: retrievalSourceOutputSchema.optional()
+	source: retrievalSourceOutputSchema.optional(),
+	trust: z.record(z.string(), z.unknown()).optional()
 });
 const searchFiltersOutputSchema = z.object({
 	framework: z.array(z.string()).optional(),
@@ -2522,6 +2692,46 @@ const readPageOutputSchema = z.object({
 	totalChars: z.number().int().nonnegative(),
 	truncated: z.boolean()
 });
+const trustMetadataOutputSchema = z.object({
+	format: z.literal("open-knowledge-format.v0.2"),
+	spec_version: z.literal("0.2"),
+	generated: z.object({
+		by: z.string(),
+		at: z.string()
+	}),
+	documents: z.array(z.record(z.string(), z.unknown()))
+});
+const openApiOperationOutputSchema = z.object({
+	operationId: z.string(),
+	status: z.number().int(),
+	ok: z.boolean(),
+	contentType: z.string().optional(),
+	responseTruncated: z.boolean().optional(),
+	body: z.unknown()
+});
+const readPagesOutputSchema = z.object({
+	format: z.literal("docs-read-pages.v1"),
+	budget: z.object({
+		requestedTokens: z.number().int().positive(),
+		strategy: z.literal("utf8-bytes"),
+		maxUtf8Bytes: z.number().int().positive(),
+		usedUtf8Bytes: z.number().int().nonnegative(),
+		remainingUtf8Bytes: z.number().int().nonnegative(),
+		truncated: z.boolean()
+	}),
+	resultCount: z.number().int().nonnegative(),
+	requestedCount: z.number().int().positive(),
+	pages: z.array(readPageOutputSchema.extend({ requestedPath: z.string() })),
+	errors: z.array(z.object({
+		path: z.string(),
+		error: z.string()
+	})),
+	remainingPaths: z.array(z.string())
+});
+const submitFeedbackOutputSchema = z.object({
+	accepted: z.literal(true),
+	message: z.string()
+});
 const pageSectionMetadataOutputSchema = z.object({
 	id: z.string(),
 	heading: z.string(),
@@ -2609,6 +2819,8 @@ function resolveDocsMcpConfig(mcp, defaults = {}) {
 			listPages: true,
 			listPageSections: true,
 			readPage: true,
+			readPages: true,
+			submitFeedback: true,
 			listTasks: true,
 			readTask: true,
 			searchDocs: true,
@@ -2618,7 +2830,8 @@ function resolveDocsMcpConfig(mcp, defaults = {}) {
 			getNavigation: true,
 			getCodeExamples: true,
 			getConfigSchema: true,
-			getContext: true
+			getContext: true,
+			getTrustMetadata: true
 		},
 		prompts: resolveDocsMcpPromptsConfig(),
 		security: resolveDocsMcpSecurityConfig()
@@ -2634,6 +2847,8 @@ function resolveDocsMcpConfig(mcp, defaults = {}) {
 			listPages: config.tools?.listPages ?? true,
 			listPageSections: config.tools?.listPageSections ?? true,
 			readPage: config.tools?.readPage ?? true,
+			readPages: config.tools?.readPages ?? true,
+			submitFeedback: config.tools?.submitFeedback ?? true,
 			listTasks: config.tools?.listTasks ?? true,
 			readTask: config.tools?.readTask ?? true,
 			searchDocs: config.tools?.searchDocs ?? true,
@@ -2643,7 +2858,8 @@ function resolveDocsMcpConfig(mcp, defaults = {}) {
 			getNavigation: config.tools?.getNavigation ?? true,
 			getCodeExamples: config.tools?.getCodeExamples ?? true,
 			getConfigSchema: config.tools?.getConfigSchema ?? true,
-			getContext: config.tools?.getContext ?? true
+			getContext: config.tools?.getContext ?? true,
+			getTrustMetadata: config.tools?.getTrustMetadata ?? true
 		},
 		prompts: resolveDocsMcpPromptsConfig(config.prompts),
 		security: resolveDocsMcpSecurityConfig(config.security)
@@ -3078,6 +3294,7 @@ async function createDocsMcpServer(options) {
 	});
 	const contentChangesEnabled = resolveDocsContentChangesConfig(options.contentChanges).enabled && resolved.tools.listContentChanges !== false;
 	const contentChangeHydrationEnabled = contentChangesEnabled && resolved.tools.hydrateContentChanges !== false;
+	const agentFeedback = resolveDocsAgentFeedbackConfig(options.feedback);
 	const cacheScope = options.requestContext?.auth ? "private" : "public";
 	const server = new McpServer({
 		name: resolved.name,
@@ -3122,11 +3339,16 @@ async function createDocsMcpServer(options) {
 		search: options.search
 	};
 	const telemetryFramework = options.telemetryFramework ?? "mcp";
-	function getSourcePages(locale) {
-		return options.source.getPages(resolveSourceLocale(locale), options.requestContext);
+	async function getSourcePages(locale) {
+		return getResolvedSourcePages(resolveSourceLocale(locale));
 	}
-	function getSourceNavigation(locale) {
-		return options.source.getNavigation(resolveSourceLocale(locale), options.requestContext);
+	async function getResolvedSourcePages(locale) {
+		return filterDocsPagesByAccess(await options.source.getPages(locale, options.requestContext), options.requestContext?.auth);
+	}
+	async function getSourceNavigation(locale) {
+		const resolvedLocale = resolveSourceLocale(locale);
+		const [tree, pages] = await Promise.all([options.source.getNavigation(resolvedLocale, options.requestContext), getResolvedSourcePages(resolvedLocale)]);
+		return filterDocsMcpNavigation(tree, new Set(pages.map((page) => page.url)));
 	}
 	function resolveSourceLocale(locale) {
 		return options.source.resolveLocale ? options.source.resolveLocale(locale, options.requestContext) : locale;
@@ -3146,10 +3368,157 @@ async function createDocsMcpServer(options) {
 	const defaultPages = dedupePages(await getSourcePages());
 	const defaultTree = await getSourceNavigation();
 	const defaultSkills = await getSourceSkills();
+	const okfConfig = resolveDocsOkfConfig(options.okf);
+	const openapiDocument = options.openapi ? typeof options.openapi.document === "function" ? await options.openapi.document() : options.openapi.document : void 0;
+	const openapiConfig = options.openapi?.config;
+	const openapiOperations = openapiDocument && openapiConfig ? resolveDocsOpenApiMcpOperations(openapiDocument, openapiConfig) : [];
 	const prompts = resolved.prompts ?? resolveDocsMcpPromptsConfig();
 	const contractPromptDefinitions = prompts.enabled ? resolveDocsMcpContractPromptDefinitions(defaultPages, prompts.contracts, options.source.entry) : [];
 	const goldenPromptDefinitions = prompts.enabled ? resolveDocsMcpGoldenPromptDefinitions(prompts.goldenTasks, options.evaluations) : [];
 	if (contractPromptDefinitions.length > 0 || goldenPromptDefinitions.length > 0) server.server.registerCapabilities({ prompts: { listChanged: false } });
+	if (okfConfig.enabled && resolved.tools.getTrustMetadata !== false) registerTool("get_trust_metadata", {
+		title: "Get documentation trust metadata",
+		description: "Return OKF v0.2 sources, generation, verification, lifecycle status, trust tier, and staleness for one page or the docs corpus.",
+		inputSchema: trustMetadataInputSchema,
+		outputSchema: trustMetadataOutputSchema,
+		annotations: { readOnlyHint: true }
+	}, async ({ path: requestedPath, locale }) => {
+		const pages = dedupePages(await getSourcePages(locale));
+		const selected = requestedPath ? pages.filter((page) => Boolean(findDocsPage([page], requestedPath, options.source.entry))) : pages;
+		if (requestedPath && selected.length === 0) return {
+			content: [{
+				type: "text",
+				text: `No docs page matched "${requestedPath}".`
+			}],
+			isError: true
+		};
+		const bundle = buildDocsOkfBundle(selected, okfConfig);
+		trackMcpTool("get_trust_metadata", {
+			locale,
+			resultCount: bundle.documents.length
+		});
+		return createStructuredTextResult(bundle);
+	});
+	for (const operation of openapiOperations) registerTool(operation.toolName, {
+		title: operation.title,
+		description: operation.description ?? `${operation.method} ${operation.path} (${operation.operationId})`,
+		inputSchema: openApiOperationInputSchema,
+		outputSchema: openApiOperationOutputSchema,
+		annotations: {
+			readOnlyHint: operation.readOnly,
+			destructiveHint: operation.destructive,
+			idempotentHint: operation.idempotent,
+			openWorldHint: true
+		},
+		_meta: { "dev.farming-labs/openapi": {
+			operationId: operation.operationId,
+			method: operation.method,
+			path: operation.path,
+			security: operation.security,
+			securitySchemes: operation.securitySchemes
+		} }
+	}, async ({ parameters = {}, body }) => {
+		if (!openapiDocument || !openapiConfig) throw new ProtocolError(ProtocolErrorCode.InternalError, "OpenAPI MCP is unavailable.");
+		const baseUrl = resolveDocsOpenApiMcpBaseUrl(openapiDocument, openapiConfig);
+		if (!baseUrl) throw new ProtocolError(ProtocolErrorCode.InvalidParams, `OpenAPI operation ${operation.operationId} has no server URL. Configure apiReference.mcp.baseUrl.`);
+		let requestPath = operation.path;
+		const query = new URLSearchParams();
+		const requestHeaders = new Headers({ Accept: "application/json, text/plain, */*" });
+		const requestCookies = new URLSearchParams();
+		for (const parameter of operation.parameters) {
+			const value = parameters[parameter.name];
+			if (value === void 0 || value === null || value === "") {
+				if (parameter.required) return {
+					content: [{
+						type: "text",
+						text: `Missing required ${parameter.in} parameter: ${parameter.name}`
+					}],
+					isError: true
+				};
+				continue;
+			}
+			const values = Array.isArray(value) ? value : [value];
+			if (parameter.in === "path") requestPath = requestPath.replaceAll(`{${parameter.name}}`, encodeURIComponent(String(values[0])));
+			else if (parameter.in === "query") for (const item of values) query.append(parameter.name, String(item));
+			else if (parameter.in === "header") requestHeaders.set(parameter.name, String(values[0]));
+			else if (parameter.in === "cookie") requestCookies.set(parameter.name, String(values[0]));
+		}
+		const requestUrl = new URL(requestPath.replace(/^\/+/, ""), `${baseUrl.replace(/\/+$/u, "")}/`);
+		for (const [name, value] of query) requestUrl.searchParams.append(name, value);
+		try {
+			await validateDocsOpenApiMcpUrl(requestUrl, openapiConfig);
+		} catch (error) {
+			throw new ProtocolError(ProtocolErrorCode.InvalidParams, error instanceof Error ? error.message : "OpenAPI MCP destination was blocked.");
+		}
+		const configuredHeaders = typeof openapiConfig.headers === "function" ? await openapiConfig.headers({
+			operationId: operation.operationId,
+			method: operation.method,
+			path: operation.path,
+			security: operation.security
+		}) : openapiConfig.headers;
+		for (const [name, value] of Object.entries(configuredHeaders ?? {})) requestHeaders.set(name, value);
+		if (requestCookies.size > 0) requestHeaders.set("Cookie", [...requestCookies].map(([name, value]) => `${name}=${value}`).join("; "));
+		if (body !== void 0) requestHeaders.set("Content-Type", "application/json");
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), openapiConfig.timeoutMs ?? 1e4);
+		const budgetKey = `${options.requestContext?.auth?.id ?? "anonymous"}:${operation.operationId}`;
+		let releaseBudget;
+		try {
+			releaseBudget = acquireDocsOpenApiMcpBudget(budgetKey, openapiConfig);
+			let response;
+			let destination = requestUrl;
+			const maxRedirects = Math.max(0, openapiConfig.maxRedirects ?? 0);
+			for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount += 1) {
+				response = await fetch(destination, {
+					method: operation.method,
+					headers: requestHeaders,
+					...body !== void 0 ? { body: JSON.stringify(body) } : {},
+					redirect: "manual",
+					signal: controller.signal
+				});
+				if (![
+					301,
+					302,
+					303,
+					307,
+					308
+				].includes(response.status)) break;
+				const location = response.headers.get("location");
+				if (!location || redirectCount >= maxRedirects) throw new ProtocolError(ProtocolErrorCode.InvalidRequest, "OpenAPI MCP redirect blocked. Increase maxRedirects to follow validated redirects.");
+				destination = new URL(location, destination);
+				try {
+					await validateDocsOpenApiMcpUrl(destination, openapiConfig);
+				} catch (error) {
+					throw new ProtocolError(ProtocolErrorCode.InvalidRequest, error instanceof Error ? error.message : "OpenAPI MCP redirect was blocked.");
+				}
+			}
+			if (!response) throw new ProtocolError(ProtocolErrorCode.InternalError, "No API response.");
+			const contentType = response.headers.get("content-type") ?? void 0;
+			const { text, truncated } = await readDocsOpenApiMcpResponse(response, openapiConfig.maxResponseBytes);
+			let responseBody = text;
+			if (contentType?.includes("json") && text && !truncated) try {
+				responseBody = JSON.parse(text);
+			} catch {
+				responseBody = text;
+			}
+			const result = {
+				operationId: operation.operationId,
+				status: response.status,
+				ok: response.ok,
+				...contentType ? { contentType } : {},
+				...truncated ? { responseTruncated: true } : {},
+				body: responseBody
+			};
+			trackMcpTool(operation.toolName, { resultCount: 1 });
+			return {
+				...createStructuredTextResult(result),
+				...response.ok ? {} : { isError: true }
+			};
+		} finally {
+			releaseBudget?.();
+			clearTimeout(timeout);
+		}
+	});
 	for (const definition of contractPromptDefinitions) {
 		const { page, contract, resourceUri } = definition;
 		server.registerPrompt(definition.name, {
@@ -3208,11 +3577,12 @@ async function createDocsMcpServer(options) {
 		if (!contentChangesEnabled) throw new ProtocolError(ProtocolErrorCode.MethodNotFound, "Content changes are disabled.");
 		if (since && !isDocsContentChangeGeneration(since)) throw new ProtocolError(ProtocolErrorCode.InvalidParams, "Content-change `since` must be a SHA-256 index generation.");
 		const resolvedLocale = resolveSourceLocale(locale);
-		const pages = dedupePages(await options.source.getPages(resolvedLocale, options.requestContext));
+		const pages = dedupePages(await getResolvedSourcePages(resolvedLocale));
 		try {
 			return {
 				result: await contentChangeFeed.resolve({
 					pages: toSearchSourcePages(pages),
+					principal: options.requestContext?.auth,
 					search: options.search,
 					audience: "agent",
 					locale: resolvedLocale,
@@ -3400,7 +3770,7 @@ async function createDocsMcpServer(options) {
 			metadata: { tool: "list_pages" }
 		});
 		try {
-			const page = paginateDocsMcpItems(toPageSummaries(dedupePages(await options.source.getPages(resolvedLocale, options.requestContext))).sort(compareDocsMcpPageSummaries), {
+			const page = paginateDocsMcpItems(toPageSummaries(dedupePages(await getResolvedSourcePages(resolvedLocale))).sort(compareDocsMcpPageSummaries), {
 				kind: "mcp.tool/list_pages",
 				scope: stableDocsMcpPaginationScope({ locale: resolvedLocale ?? null }),
 				cursor
@@ -3495,7 +3865,7 @@ async function createDocsMcpServer(options) {
 			metadata: { tool: "list_docs" }
 		});
 		try {
-			const docs = paginateDocsMcpDocsList(listDocsBySection(dedupePages(await options.source.getPages(resolvedLocale, options.requestContext)), {
+			const docs = paginateDocsMcpDocsList(listDocsBySection(dedupePages(await getResolvedSourcePages(resolvedLocale)), {
 				section,
 				entry: options.source.entry
 			}), {
@@ -3593,7 +3963,7 @@ async function createDocsMcpServer(options) {
 			metadata: { tool: "list_tasks" }
 		});
 		try {
-			const page = paginateDocsMcpItems(listDocsTasks(dedupePages(await options.source.getPages(resolvedLocale, options.requestContext)), {
+			const page = paginateDocsMcpItems(listDocsTasks(dedupePages(await getResolvedSourcePages(resolvedLocale)), {
 				query,
 				framework,
 				version,
@@ -4017,7 +4387,8 @@ async function createDocsMcpServer(options) {
 		});
 		try {
 			const facets = await buildDocsSearchFacets({
-				pages: toSearchSourcePages(dedupePages(await options.source.getPages(resolvedLocale, options.requestContext))),
+				pages: toSearchSourcePages(dedupePages(await getResolvedSourcePages(resolvedLocale))),
+				principal: options.requestContext?.auth,
 				search: toolSearchConfig ?? true,
 				audience: resolvedAudience,
 				filters,
@@ -4125,7 +4496,8 @@ async function createDocsMcpServer(options) {
 		});
 		try {
 			const searchResponse = await performDocsSearchWithMetadata({
-				pages: toSearchSourcePages(dedupePages(await options.source.getPages(resolvedLocale, options.requestContext))),
+				pages: toSearchSourcePages(dedupePages(await getResolvedSourcePages(resolvedLocale))),
+				principal: options.requestContext?.auth,
 				query,
 				search: toolSearchConfig ?? true,
 				audience: resolvedAudience,
@@ -4331,7 +4703,8 @@ async function createDocsMcpServer(options) {
 		});
 		try {
 			const result = await buildDocsMcpContext({
-				pages: dedupePages(await options.source.getPages(resolvedLocale, options.requestContext)),
+				pages: dedupePages(await getResolvedSourcePages(resolvedLocale)),
+				principal: options.requestContext?.auth,
 				query,
 				framework,
 				version,
@@ -4439,7 +4812,7 @@ async function createDocsMcpServer(options) {
 			metadata: { tool: "list_page_sections" }
 		});
 		try {
-			const page = findDocsPage(dedupePages(await options.source.getPages(resolvedLocale, options.requestContext)), requestedPath, options.source.entry);
+			const page = findDocsPage(dedupePages(await getResolvedSourcePages(resolvedLocale)), requestedPath, options.source.entry);
 			if (!page) {
 				const elapsed = durationMs(startedAt);
 				await emitDocsAnalyticsEvent(options.analytics, {
@@ -4580,6 +4953,111 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
+	if (resolved.tools.readPages !== false) registerTool("read_pages", {
+		title: "Read several docs pages",
+		description: "Read up to 20 documentation pages in one round trip. Results preserve request order and share a conservative UTF-8 token budget.",
+		inputSchema: readPagesInputSchema,
+		outputSchema: readPagesOutputSchema,
+		annotations: { readOnlyHint: true }
+	}, async ({ paths: requestedPaths, locale, tokenBudget = DEFAULT_MCP_READ_PAGES_TOKEN_BUDGET, maxCharsPerPage }) => {
+		const pages = dedupePages(await getSourcePages(locale));
+		const maxUtf8Bytes = tokenBudget * 4;
+		let usedUtf8Bytes = 0;
+		let processedCount = 0;
+		let truncated = false;
+		const results = [];
+		const errors = [];
+		for (const requestedPath of requestedPaths) {
+			if (usedUtf8Bytes >= maxUtf8Bytes) {
+				truncated = true;
+				break;
+			}
+			processedCount += 1;
+			const page = findDocsPage(pages, requestedPath, options.source.entry);
+			if (!page) {
+				errors.push({
+					path: requestedPath,
+					error: `No docs page matched "${requestedPath}".`
+				});
+				continue;
+			}
+			const fullDocument = renderPageDocument(page);
+			const perPage = limitDocsMcpText(fullDocument, maxCharsPerPage);
+			const remainingUtf8Bytes = maxUtf8Bytes - usedUtf8Bytes;
+			const budgeted = limitDocsMcpUtf8Bytes(perPage.text, remainingUtf8Bytes);
+			const document = budgeted.text;
+			const documentBytes = docsMcpUtf8Bytes(document);
+			usedUtf8Bytes += documentBytes;
+			const pageTruncated = perPage.truncated || budgeted.truncated;
+			truncated ||= pageTruncated;
+			results.push({
+				requestedPath,
+				page: toStructuredDocsMcpPage(page),
+				document,
+				chars: document.length,
+				totalChars: fullDocument.length,
+				truncated: pageTruncated
+			});
+		}
+		const result = {
+			format: "docs-read-pages.v1",
+			budget: {
+				requestedTokens: tokenBudget,
+				strategy: "utf8-bytes",
+				maxUtf8Bytes,
+				usedUtf8Bytes,
+				remainingUtf8Bytes: Math.max(0, maxUtf8Bytes - usedUtf8Bytes),
+				truncated: truncated || processedCount < requestedPaths.length
+			},
+			resultCount: results.length,
+			requestedCount: requestedPaths.length,
+			pages: results,
+			errors,
+			remainingPaths: requestedPaths.slice(processedCount)
+		};
+		trackMcpTool("read_pages", {
+			locale,
+			resultCount: results.length
+		});
+		return createStructuredTextResult(result);
+	});
+	if (resolved.tools.submitFeedback !== false && agentFeedback.enabled) registerTool("submit_feedback", {
+		title: "Submit documentation feedback",
+		description: "Submit machine-readable documentation feedback. The payload is validated against the site's configured agent feedback schema before delivery.",
+		inputSchema: submitFeedbackInputSchema,
+		outputSchema: submitFeedbackOutputSchema,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		},
+		_meta: { "dev.farming-labs/feedbackSchema": agentFeedback.schema }
+	}, async ({ context, payload }) => {
+		const validationError = validateDocsAgentFeedbackPayload(payload, agentFeedback.payloadSchema);
+		if (validationError) return {
+			content: [{
+				type: "text",
+				text: validationError
+			}],
+			isError: true
+		};
+		const feedbackContext = {
+			...context,
+			source: context?.source ?? "mcp"
+		};
+		await agentFeedback.onFeedback?.({
+			...Object.keys(feedbackContext).length > 0 ? { context: feedbackContext } : {},
+			payload
+		});
+		trackMcpTool("submit_feedback", {
+			locale: feedbackContext.locale,
+			resultCount: 1
+		});
+		return createStructuredTextResult({
+			accepted: true,
+			message: "Feedback accepted."
+		});
+	});
 	if (resolved.tools.readPage) registerTool("read_page", {
 		title: "Read a docs page",
 		description: "Read a documentation page by slug or URL path, optionally selecting one heading and limiting returned characters.",
@@ -4857,9 +5335,10 @@ function createDocsMcpHttpHandler(options) {
 	const contentChangePollIntervalMs = typeof configuredPollInterval === "number" && Number.isFinite(configuredPollInterval) && configuredPollInterval >= 10 ? Math.floor(configuredPollInterval) : DEFAULT_DOCS_MCP_CONTENT_CHANGE_POLL_INTERVAL_MS;
 	async function readMonitoredState(context) {
 		const locale = options.source.resolveLocale?.(void 0, context);
-		const pages = dedupePages(await options.source.getPages(locale, context));
+		const pages = dedupePages(filterDocsPagesByAccess(await options.source.getPages(locale, context), context.auth));
 		const result = await contentChangeFeed.resolve({
 			pages: toSearchSourcePages(pages),
+			principal: context.auth,
 			search: options.search,
 			audience: "agent",
 			locale,
@@ -5018,9 +5497,10 @@ async function runDocsMcpStdio(options) {
 		if (!contentChangesEnabled) return server;
 		const readState = async () => {
 			const locale = options.source.resolveLocale?.(void 0, requestContext);
-			const pages = dedupePages(await options.source.getPages(locale, requestContext));
+			const pages = dedupePages(filterDocsPagesByAccess(await options.source.getPages(locale, requestContext), requestContext.auth));
 			const result = await contentChangeFeed.resolve({
 				pages: toSearchSourcePages(pages),
+				principal: requestContext.auth,
 				search: options.search,
 				audience: "agent",
 				locale,
@@ -5440,6 +5920,7 @@ function scanFilesystemDocsPages(contentDirAbs, entry, rootDir) {
 				description: data.description,
 				relatedInput: data.related,
 				agent: normalizePageAgentFrontmatter(data.agent),
+				okf: normalizeDocsOkfTrustMetadataInput(data.okf),
 				icon: data.icon,
 				sourcePath: path.relative(rootDir, full).replace(/\\/g, "/"),
 				lastmod: normalizeFrontmatterLastmod(data.lastmod),
@@ -6270,6 +6751,7 @@ async function buildDocsMcpContext(options) {
 	const orderedResults = [...await performDocsSearch({
 		pages: scopedPages.map((page) => searchPageBySource.get(page)),
 		generationPages: allSearchPages,
+		principal: options.principal,
 		query: options.query,
 		search: {
 			enabled: true,