@farming-labs/docs 0.2.102 → 0.2.104

package/dist/mcp.mjs

@@ -1,8 +1,8 @@
 import { a as emitDocsAnalyticsEvent, i as emitDocsAgentTraceEvent, n as createDocsAgentTraceContext, r as createDocsAgentTraceId } from "./analytics-Bx44lg6d.mjs";
-import { $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 { $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, Tt as validateDocsAgentFeedbackPayload, Ut as DocsContentChangesRequestError, Wt as createDocsContentChangeFeed, Xn as isDocsMcpResourcePath, Zn as normalizeDocsMcpAuthorizationServerUrls, ar as normalizeDocsOkfTrustMetadataInput, dn as performDocsSearch, er as resolveDocsMcpResourceLocation, fn as performDocsSearchWithMetadata, ir as buildDocsOkfBundle, jn as normalizeAgentScopeValues, kn as normalizeAgentFramework, lt as resolveDocsAgentFeedbackConfig, or as resolveDocsOkfConfig, qn as isDocsMcpOAuthScopeToken, tn as buildDocsSearchFacets, un as normalizeDocsSearchFilters, wt as toDocsMarkdownUrl, yn as resolveLocalDocsMcpSearchConfig } from "./agent-PSrgiJD8.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 { _ as emitDocsTelemetryMcpToolEvent, a as MAX_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, h as emitDocsTelemetryAgentSurfaceEvent, i as DOCS_CONTENT_CHANGE_HYDRATION_FORMAT, m as stripGeneratedAgentProvenance, n as resolveDocsOpenApiMcpOperations, o as MIN_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, r as DEFAULT_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, s as hydrateDocsContentChanges, t as resolveDocsOpenApiMcpBaseUrl, v as emitDocsTelemetryProjectEvent } from "./openapi-mcp-B7u7Y0gB.mjs";
 import { n as resolvePageSidebarFolderIndexBehavior } from "./sidebar-IcpElOVH.mjs";
 import matter from "gray-matter";
 import fs from "node:fs";
@@ -20,6 +20,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 +235,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 +1429,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 +1842,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 +1876,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 +1913,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 +2122,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 +2454,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 +2673,45 @@ 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(),
+	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 +2799,8 @@ function resolveDocsMcpConfig(mcp, defaults = {}) {
 			listPages: true,
 			listPageSections: true,
 			readPage: true,
+			readPages: true,
+			submitFeedback: true,
 			listTasks: true,
 			readTask: true,
 			searchDocs: true,
@@ -2618,7 +2810,8 @@ function resolveDocsMcpConfig(mcp, defaults = {}) {
 			getNavigation: true,
 			getCodeExamples: true,
 			getConfigSchema: true,
-			getContext: true
+			getContext: true,
+			getTrustMetadata: true
 		},
 		prompts: resolveDocsMcpPromptsConfig(),
 		security: resolveDocsMcpSecurityConfig()
@@ -2634,6 +2827,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 +2838,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 +3274,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,
@@ -3146,10 +3343,126 @@ 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);
+		if (requestUrl.protocol !== "https:" && requestUrl.protocol !== "http:") throw new ProtocolError(ProtocolErrorCode.InvalidParams, "OpenAPI MCP server URLs must use HTTP or HTTPS.");
+		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);
+		try {
+			const response = await fetch(requestUrl, {
+				method: operation.method,
+				headers: requestHeaders,
+				...body !== void 0 ? { body: JSON.stringify(body) } : {},
+				signal: controller.signal
+			});
+			const contentType = response.headers.get("content-type") ?? void 0;
+			const text = (await response.text()).slice(0, 1e6);
+			let responseBody = text;
+			if (contentType?.includes("json") && text) try {
+				responseBody = JSON.parse(text);
+			} catch {
+				responseBody = text;
+			}
+			const result = {
+				operationId: operation.operationId,
+				status: response.status,
+				ok: response.ok,
+				...contentType ? { contentType } : {},
+				body: responseBody
+			};
+			trackMcpTool(operation.toolName, { resultCount: 1 });
+			return {
+				...createStructuredTextResult(result),
+				...response.ok ? {} : { isError: true }
+			};
+		} finally {
+			clearTimeout(timeout);
+		}
+	});
 	for (const definition of contractPromptDefinitions) {
 		const { page, contract, resourceUri } = definition;
 		server.registerPrompt(definition.name, {
@@ -4580,6 +4893,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.",
@@ -5440,6 +5858,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),