@farming-labs/docs 0.2.77 → 0.2.79

package/dist/mcp.mjs

@@ -1,15 +1,13 @@
 import { a as emitDocsAnalyticsEvent, i as emitDocsAgentTraceEvent, n as createDocsAgentTraceContext, r as createDocsAgentTraceId } from "./analytics-Bx44lg6d.mjs";
-import { E as DOCS_MARKDOWN_SECTION_INDEX_FORMAT, Kt as normalizeDocsRelated, P as buildDocsMarkdownSectionIndex, an as isDocsMcpResourcePath, cn as resolveDocsMcpProtectedResourceMetadataLocation, jt as resolveDocsAudienceMdxContent, ln as resolveDocsMcpResourceLocation, nn as isDocsMcpOAuthScopeToken, on as normalizeDocsMcpAuthorizationServerUrls, qt as renderDocsRelatedMarkdownLines, rn as isDocsMcpProtectedResourceMetadataPath, sn as normalizeDocsMcpEndpointPath, wt as toDocsMarkdownUrl } from "./agent-SRIJ-oF8.mjs";
+import { $n as resolveDocsMcpProtectedResourceMetadataLocation, An as normalizeAgentLocale, Dn as agentVersionConstraintMatches, E as DOCS_MARKDOWN_SECTION_INDEX_FORMAT, In as isDocsRetrievalCanonicalUrl, Jn as isDocsMcpProtectedResourceMetadataPath, Jt as resolveDocsContentChangesConfig, Kt as isDocsContentChangeGeneration, Ln as normalizeDocsRelated, Nn as DocsPaginationCursorError, On as agentVersionConstraintsOverlap, P as buildDocsMarkdownSectionIndex, Pn as paginateDocsItems, 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 } from "./agent-DejGcJfb.mjs";
 import { S as upsertPageAgentContractMarkdown, _ as hasStructuredPageAgentContract, o as findDocsMarkdownSection, s as parseDocsMarkdownSections, v as normalizePageAgentFrontmatter } from "./markdown-sections-7OoA7ylx.mjs";
 import "./standards-discovery-BKlEnK_H.mjs";
-import { A as DocsPaginationCursorError, B as stripGeneratedAgentProvenance, D as normalizeAgentLocale, E as normalizeAgentFramework, G as emitDocsTelemetryAgentSurfaceEvent, H as resolvePageSidebarFolderIndexBehavior, J as emitDocsTelemetryProjectEvent, N as isDocsRetrievalCanonicalUrl, O as normalizeAgentScopeValues, T as agentVersionConstraintsOverlap, h as performDocsSearchWithMetadata, j as paginateDocsItems, m as performDocsSearch, p as normalizeDocsSearchFilters, q as emitDocsTelemetryMcpToolEvent, w as agentVersionConstraintMatches } from "./search-Da2AKaFJ.mjs";
+import { f as emitDocsTelemetryAgentSurfaceEvent, h as emitDocsTelemetryProjectEvent, l as resolvePageSidebarFolderIndexBehavior, m as emitDocsTelemetryMcpToolEvent, s as stripGeneratedAgentProvenance } from "./agent-provenance-DEyAr22i.mjs";
 import matter from "gray-matter";
 import fs from "node:fs";
 import path from "node:path";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
-import { ErrorCode, ListPromptsRequestSchema, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { InMemoryServerEventBus, McpServer, ProtocolError, ProtocolErrorCode, ResourceTemplate, createMcpHandler, isInitializeRequest } from "@modelcontextprotocol/server";
 import * as z from "zod/v4";
 
 //#region src/mcp.ts
@@ -21,6 +19,9 @@ const MAX_MCP_CONTEXT_TOKEN_BUDGET = 32e3;
 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";
+const DOCS_MCP_CONTENT_CHANGES_CURRENT_URI = "docs://changes/current";
+const DOCS_MCP_CONTENT_CHANGES_URI_TEMPLATE = "docs://changes/{generation}";
+const DEFAULT_DOCS_MCP_CONTENT_CHANGE_POLL_INTERVAL_MS = 3e4;
 const UTF8_ENCODER = new TextEncoder();
 const DEFAULT_DOCS_MCP_MAX_BODY_BYTES = 1024 * 1024;
 const DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS = 600;
@@ -29,6 +30,8 @@ const DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS = Object.freeze([
 	"Authorization",
 	"Content-Type",
 	"Last-Event-ID",
+	"MCP-Method",
+	"MCP-Name",
 	"MCP-Protocol-Version",
 	"MCP-Session-Id"
 ]);
@@ -223,9 +226,44 @@ const DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE = [
 		path: "agent",
 		name: "agent",
 		type: "DocsAgentConfig",
-		description: "Agent compaction defaults and offline-by-default usefulness evaluations.",
+		description: "Agent synchronization, reusable skills, compaction defaults, and offline-by-default usefulness evaluations.",
 		docs: "/docs/getting-started/agent-ready-docs",
 		children: [
+			{
+				path: "agent.contentChanges",
+				name: "contentChanges",
+				type: "boolean | DocsAgentContentChangesConfig",
+				default: true,
+				description: "Body-free runtime document synchronization feed. Disable it with false, or configure bounded and durable snapshot history.",
+				children: [
+					{
+						path: "agent.contentChanges.enabled",
+						name: "enabled",
+						type: "boolean",
+						default: true,
+						description: "Whether runtime adapters serve response=changes."
+					},
+					{
+						path: "agent.contentChanges.maxSnapshots",
+						name: "maxSnapshots",
+						type: "number",
+						default: 8,
+						description: "Metadata-only snapshots retained in this server process; accepted range is 1 through 64."
+					},
+					{
+						path: "agent.contentChanges.loadSnapshot",
+						name: "loadSnapshot",
+						type: "DocsContentChangeSnapshotLoader",
+						description: "Optional callback that loads a prior generation from durable storage for exact cross-deployment deltas."
+					},
+					{
+						path: "agent.contentChanges.saveSnapshot",
+						name: "saveSnapshot",
+						type: "DocsContentChangeSnapshotSaver",
+						description: "Optional callback that persists each current metadata snapshot to durable storage."
+					}
+				]
+			},
 			{
 				path: "agent.skills",
 				name: "skills",
@@ -1526,6 +1564,20 @@ const DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE = [
 						default: true,
 						description: "Expose the search_docs tool."
 					},
+					{
+						path: "mcp.tools.searchFacets",
+						name: "searchFacets",
+						type: "boolean",
+						default: true,
+						description: "Expose the list_search_facets tool for body-free framework, version, package, and tag discovery."
+					},
+					{
+						path: "mcp.tools.listContentChanges",
+						name: "listContentChanges",
+						type: "boolean",
+						default: true,
+						description: "Expose list_content_changes polling and docs://changes resources when agent.contentChanges is enabled."
+					},
 					{
 						path: "mcp.tools.readPage",
 						name: "readPage",
@@ -1728,6 +1780,22 @@ const searchDocsInputSchema = z.object({
 	package: searchFilterValueSchema.optional(),
 	tags: searchFilterValueSchema.optional()
 });
+const searchFacetsInputSchema = z.object({
+	locale: z.string().trim().min(1).max(128).optional(),
+	audience: z.enum(["human", "agent"]).optional(),
+	facet: z.enum([
+		"framework",
+		"version",
+		"package",
+		"tags"
+	]).optional(),
+	limit: z.number().int().min(1).max(100).optional(),
+	cursor: paginationCursorInputSchema,
+	framework: searchFilterValueSchema.optional(),
+	version: searchFilterValueSchema.optional(),
+	package: searchFilterValueSchema.optional(),
+	tags: searchFilterValueSchema.optional()
+});
 const readPageInputSchema = z.object({
 	path: z.string().min(1),
 	locale: z.string().trim().min(1).max(128).optional(),
@@ -1822,6 +1890,10 @@ const listDocsInputSchema = z.object({
 	cursor: paginationCursorInputSchema
 });
 const getNavigationInputSchema = z.object({ locale: z.string().trim().min(1).max(128).optional() });
+const listContentChangesInputSchema = z.object({
+	since: z.string().refine(isDocsContentChangeGeneration, "Expected a SHA-256 index generation").optional(),
+	locale: z.string().trim().min(1).max(128).optional()
+});
 const getConfigSchemaInputSchema = z.object({
 	option: z.string().trim().min(1).optional(),
 	query: z.string().trim().min(1).optional()
@@ -1929,6 +2001,37 @@ const retrievalSourceScopeOutputSchema = z.object({
 	])).max(4).optional()
 });
 const retrievalSourceDigestOutputSchema = z.string().regex(/^sha256:[a-f\d]{64}$/iu);
+const contentChangeDocumentOutputSchema = z.object({
+	url: z.string(),
+	canonicalUrl: z.string().max(4096).refine(isDocsRetrievalCanonicalUrl, "Expected a safe HTTP(S) URL or root-relative path"),
+	digest: retrievalSourceDigestOutputSchema,
+	lastModified: z.string().optional()
+});
+const contentChangesOutputSchema = z.object({
+	format: z.literal("docs-content-changes.v1"),
+	audience: z.enum(["human", "agent"]),
+	locale: z.string().optional(),
+	since: retrievalSourceDigestOutputSchema.nullable(),
+	indexGeneration: retrievalSourceDigestOutputSchema,
+	mode: z.enum([
+		"snapshot",
+		"delta",
+		"reset"
+	]),
+	resetRequired: z.boolean(),
+	documentCount: z.number().int().nonnegative(),
+	counts: z.object({
+		added: z.number().int().nonnegative(),
+		changed: z.number().int().nonnegative(),
+		deleted: z.number().int().nonnegative()
+	}),
+	added: z.array(contentChangeDocumentOutputSchema),
+	changed: z.array(contentChangeDocumentOutputSchema.extend({
+		previousDigest: retrievalSourceDigestOutputSchema,
+		previousLastModified: z.string().optional()
+	})),
+	deleted: z.array(contentChangeDocumentOutputSchema)
+});
 const retrievalSourceOutputSchema = z.object({
 	canonicalUrl: z.string().max(4096).refine(isDocsRetrievalCanonicalUrl, "Expected a safe HTTP(S) URL or root-relative path"),
 	scope: retrievalSourceScopeOutputSchema,
@@ -1984,6 +2087,30 @@ const searchDocsOutputSchema = z.object({
 	results: z.array(searchResultOutputSchema),
 	warnings: z.array(searchWarningOutputSchema)
 });
+const searchFacetOutputSchema = z.object({
+	valueCount: z.number().int().nonnegative(),
+	total: z.number().int().nonnegative(),
+	hasMore: z.boolean(),
+	nextCursor: z.string().optional(),
+	truncated: z.boolean(),
+	values: z.array(z.object({
+		value: z.string(),
+		count: z.number().int().nonnegative()
+	}))
+});
+const searchFacetsOutputSchema = z.object({
+	format: z.literal("docs-search-facets.v1"),
+	audience: z.enum(["human", "agent"]),
+	filters: searchFiltersOutputSchema,
+	indexGeneration: retrievalSourceDigestOutputSchema,
+	matchedPageCount: z.number().int().nonnegative(),
+	facets: z.object({
+		framework: searchFacetOutputSchema,
+		version: searchFacetOutputSchema,
+		package: searchFacetOutputSchema,
+		tags: searchFacetOutputSchema
+	})
+});
 const codeExampleOutputSchema = z.object({
 	id: z.string(),
 	page: z.object({
@@ -2145,6 +2272,8 @@ function resolveDocsMcpConfig(mcp, defaults = {}) {
 			listTasks: true,
 			readTask: true,
 			searchDocs: true,
+			searchFacets: true,
+			listContentChanges: true,
 			getNavigation: true,
 			getCodeExamples: true,
 			getConfigSchema: true,
@@ -2166,6 +2295,8 @@ function resolveDocsMcpConfig(mcp, defaults = {}) {
 			listTasks: config.tools?.listTasks ?? true,
 			readTask: config.tools?.readTask ?? true,
 			searchDocs: config.tools?.searchDocs ?? true,
+			searchFacets: config.tools?.searchFacets ?? true,
+			listContentChanges: config.tools?.listContentChanges ?? true,
 			getNavigation: config.tools?.getNavigation ?? true,
 			getCodeExamples: config.tools?.getCodeExamples ?? true,
 			getConfigSchema: config.tools?.getConfigSchema ?? true,
@@ -2284,6 +2415,54 @@ function nowMs() {
 function durationMs(startedAt) {
 	return Math.max(0, Date.now() - startedAt);
 }
+function createDocsMcpContentChangeMonitor(options) {
+	let context;
+	let generation;
+	let timer;
+	let running = false;
+	let closed = false;
+	const schedule = () => {
+		if (closed || timer || running || options.isActive?.() === false) return;
+		timer = setTimeout(async () => {
+			timer = void 0;
+			if (closed || context === void 0 || options.isActive?.() === false) return;
+			running = true;
+			try {
+				const nextGeneration = await options.readGeneration(context);
+				if (generation && nextGeneration !== generation) {
+					generation = nextGeneration;
+					await options.notify();
+				} else generation = nextGeneration;
+			} catch {} finally {
+				running = false;
+				schedule();
+			}
+		}, options.pollIntervalMs);
+		if (options.unrefTimer) timer.unref?.();
+	};
+	return {
+		async start(nextContext) {
+			if (closed) return;
+			context = nextContext;
+			if (timer) {
+				clearTimeout(timer);
+				timer = void 0;
+			}
+			try {
+				generation = await options.readGeneration(nextContext);
+			} catch {
+				generation = void 0;
+			}
+			schedule();
+		},
+		close() {
+			closed = true;
+			context = void 0;
+			if (timer) clearTimeout(timer);
+			timer = void 0;
+		}
+	};
+}
 function createStructuredTextResult(structuredContent, text) {
 	return {
 		content: [{
@@ -2315,7 +2494,7 @@ function paginateDocsMcpProtocolItems(items, options) {
 			pageSize: DOCS_MCP_PROTOCOL_LIST_PAGE_SIZE
 		});
 	} catch (error) {
-		if (error instanceof DocsPaginationCursorError) throw new McpError(ErrorCode.InvalidParams, error.message);
+		if (error instanceof DocsPaginationCursorError) throw new ProtocolError(ProtocolErrorCode.InvalidParams, error.message);
 		throw error;
 	}
 }
@@ -2346,10 +2525,10 @@ function paginateDocsMcpSdkListResult(result, field, options) {
 function installDocsMcpSdkListPaginationInterceptor(server, scope) {
 	const originalSetRequestHandler = server.server.setRequestHandler;
 	const setRequestHandler = originalSetRequestHandler.bind(server.server);
-	const interceptedSetRequestHandler = ((requestSchema, handler) => {
+	const interceptedSetRequestHandler = ((method, handler) => {
 		const sdkHandler = handler;
-		if (Object.is(requestSchema, ListResourcesRequestSchema)) {
-			setRequestHandler(ListResourcesRequestSchema, async (request, extra) => {
+		if (method === "resources/list") {
+			setRequestHandler("resources/list", async (request, extra) => {
 				return paginateDocsMcpSdkListResult(await sdkHandler(request, extra), "resources", {
 					kind: "mcp.protocol/resources-list",
 					scope,
@@ -2362,8 +2541,8 @@ function installDocsMcpSdkListPaginationInterceptor(server, scope) {
 			});
 			return;
 		}
-		if (Object.is(requestSchema, ListResourceTemplatesRequestSchema)) {
-			setRequestHandler(ListResourceTemplatesRequestSchema, async (request, extra) => {
+		if (method === "resources/templates/list") {
+			setRequestHandler("resources/templates/list", async (request, extra) => {
 				return paginateDocsMcpSdkListResult(await sdkHandler(request, extra), "resourceTemplates", {
 					kind: "mcp.protocol/resource-templates-list",
 					scope,
@@ -2376,8 +2555,8 @@ function installDocsMcpSdkListPaginationInterceptor(server, scope) {
 			});
 			return;
 		}
-		if (Object.is(requestSchema, ListToolsRequestSchema)) {
-			setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+		if (method === "tools/list") {
+			setRequestHandler("tools/list", async (request, extra) => {
 				return paginateDocsMcpSdkListResult(await sdkHandler(request, extra), "tools", {
 					kind: "mcp.protocol/tools-list",
 					scope,
@@ -2387,8 +2566,8 @@ function installDocsMcpSdkListPaginationInterceptor(server, scope) {
 			});
 			return;
 		}
-		if (Object.is(requestSchema, ListPromptsRequestSchema)) {
-			setRequestHandler(ListPromptsRequestSchema, async (request, extra) => {
+		if (method === "prompts/list") {
+			setRequestHandler("prompts/list", async (request, extra) => {
 				return paginateDocsMcpSdkListResult(await sdkHandler(request, extra), "prompts", {
 					kind: "mcp.protocol/prompts-list",
 					scope,
@@ -2398,7 +2577,7 @@ function installDocsMcpSdkListPaginationInterceptor(server, scope) {
 			});
 			return;
 		}
-		setRequestHandler(requestSchema, handler);
+		setRequestHandler(method, handler);
 	});
 	server.server.setRequestHandler = interceptedSetRequestHandler;
 	return () => {
@@ -2415,11 +2594,8 @@ function installDocsMcpSdkRegistrationPagination(server, scope) {
 		}
 	} });
 	server.registerTool = wrapRegistration(server.registerTool);
-	server.tool = wrapRegistration(server.tool);
 	server.registerResource = wrapRegistration(server.registerResource);
-	server.resource = wrapRegistration(server.resource);
 	server.registerPrompt = wrapRegistration(server.registerPrompt);
-	server.prompt = wrapRegistration(server.prompt);
 }
 async function createDocsMcpServer(options) {
 	const resolved = resolveDocsMcpConfig(options.mcp, {
@@ -2431,11 +2607,13 @@ async function createDocsMcpServer(options) {
 		name: resolved.name,
 		version: resolved.version
 	});
+	const contentChangesEnabled = resolveDocsContentChangesConfig(options.contentChanges).enabled && resolved.tools.listContentChanges !== false;
 	const server = new McpServer({
 		name: resolved.name,
 		version: resolved.version
 	});
 	installDocsMcpSdkRegistrationPagination(server, protocolScope);
+	if (contentChangesEnabled) server.server.registerCapabilities({ resources: { subscribe: true } });
 	const registerResource = (name, uri, metadata, callback) => {
 		return server.registerResource(name, uri, metadata, callback);
 	};
@@ -2472,6 +2650,26 @@ async function createDocsMcpServer(options) {
 	const defaultPages = dedupePages(await getSourcePages());
 	const defaultTree = await getSourceNavigation();
 	const defaultSkills = await getSourceSkills();
+	const contentChangeFeed = options.contentChangeFeed ?? createDocsContentChangeFeed(options.contentChanges);
+	async function resolveContentChanges(since, locale) {
+		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);
+		try {
+			return await contentChangeFeed.resolve({
+				pages: toSearchSourcePages(dedupePages(await options.source.getPages(resolvedLocale, options.requestContext))),
+				search: options.search,
+				audience: "agent",
+				locale: resolvedLocale,
+				baseUrl: options.source.baseUrl ?? (options.requestContext?.request ? new URL(options.requestContext.request.url).origin : void 0),
+				...since ? { since } : {},
+				...options.requestContext?.request ? { request: options.requestContext.request.clone() } : {}
+			});
+		} catch (error) {
+			if (error instanceof DocsContentChangesRequestError) throw new ProtocolError(ProtocolErrorCode.InvalidParams, error.message);
+			throw error;
+		}
+	}
 	registerResource("docs-navigation", "docs://navigation", {
 		title: "Docs Navigation",
 		description: "Structured navigation tree for the documentation site.",
@@ -2481,6 +2679,65 @@ async function createDocsMcpServer(options) {
 		mimeType: "text/plain",
 		text: renderNavigationTree(defaultTree)
 	}] }));
+	if (contentChangesEnabled) {
+		const readChanges = async (generation) => {
+			const result = await resolveContentChanges(generation && generation !== "current" ? generation : void 0);
+			return { contents: [{
+				uri: generation && generation !== "current" ? `docs://changes/${generation}` : DOCS_MCP_CONTENT_CHANGES_CURRENT_URI,
+				mimeType: "application/json",
+				text: JSON.stringify(result, null, 2)
+			}] };
+		};
+		registerResource("docs-content-changes-current", DOCS_MCP_CONTENT_CHANGES_CURRENT_URI, {
+			title: "Current docs content changes",
+			description: "Stable subscription target for body-free documentation change notifications.",
+			mimeType: "application/json"
+		}, async () => readChanges());
+		server.registerResource("docs-content-changes-by-generation", new ResourceTemplate(DOCS_MCP_CONTENT_CHANGES_URI_TEMPLATE, { list: async () => {
+			return { resources: [{
+				uri: `docs://changes/${(await resolveContentChanges()).indexGeneration}`,
+				name: "Docs changes from current generation",
+				title: "Docs changes from current generation",
+				description: "Read this URI later to retrieve changes since the listed generation.",
+				mimeType: "application/json"
+			}] };
+		} }), {
+			title: "Docs content changes by generation",
+			description: "Body-free documentation changes from a SHA-256 index generation to the current generation.",
+			mimeType: "application/json"
+		}, async (_uri, variables) => {
+			const generation = variables.generation;
+			if (typeof generation !== "string" || !isDocsContentChangeGeneration(generation)) throw new ProtocolError(ProtocolErrorCode.InvalidParams, "Change resource generation must be a SHA-256 index generation.");
+			return readChanges(generation);
+		});
+		registerTool("list_content_changes", {
+			title: "List docs content changes",
+			description: "Synchronize body-free document metadata. Save indexGeneration and pass it as since on the next poll. A reset response means the named snapshot is no longer available.",
+			inputSchema: listContentChangesInputSchema,
+			outputSchema: contentChangesOutputSchema,
+			annotations: { readOnlyHint: true }
+		}, async ({ since, locale }) => {
+			const startedAt = nowMs();
+			const result = await resolveContentChanges(since, locale);
+			trackMcpTool("list_content_changes", {
+				locale,
+				resultCount: result.counts.added + result.counts.changed + result.counts.deleted
+			});
+			await emitDocsAnalyticsEvent(options.analytics, {
+				type: "mcp_tool",
+				source: "mcp",
+				locale,
+				properties: {
+					tool: "list_content_changes",
+					mode: result.mode,
+					resetRequired: result.resetRequired,
+					resultCount: result.counts.added + result.counts.changed + result.counts.deleted,
+					durationMs: durationMs(startedAt)
+				}
+			});
+			return createStructuredTextResult(result);
+		});
+	}
 	for (const page of defaultPages) {
 		const resourceUri = toPageResourceUri(page.url);
 		registerResource(`page-${slugToKey(page.slug)}`, resourceUri, {
@@ -3115,6 +3372,112 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
+	if (resolved.tools.searchFacets) registerTool("list_search_facets", {
+		title: "List documentation search facets",
+		description: "List valid framework, version, package, and tag filters with matching page counts before calling search_docs. Use facet, limit, and cursor to continue a large facet without document bodies.",
+		inputSchema: searchFacetsInputSchema,
+		outputSchema: searchFacetsOutputSchema,
+		annotations: { readOnlyHint: true }
+	}, async ({ locale, audience, facet, limit, cursor, framework, version, package: packageName, tags }) => {
+		const startedAt = nowMs();
+		const resolvedAudience = audience ?? "agent";
+		const resolvedLocale = resolveSourceLocale(locale);
+		const filters = {
+			framework,
+			version,
+			package: packageName,
+			tags
+		};
+		const trace = createDocsAgentTraceContext("mcp.tool.list_search_facets");
+		const callSpanId = createDocsAgentTraceId("span");
+		await emitDocsAgentTraceEvent(options.observability, {
+			type: "tool.call",
+			source: "mcp",
+			traceId: trace.traceId,
+			spanId: callSpanId,
+			name: "list_search_facets",
+			startedAt: trace.startedAt,
+			status: "started",
+			locale,
+			inputPreview: {
+				locale,
+				audience: resolvedAudience,
+				facet,
+				limit,
+				hasCursor: cursor !== void 0,
+				filterFields: Object.entries(filters).filter(([, value]) => value !== void 0).map(([field]) => field)
+			},
+			metadata: { tool: "list_search_facets" }
+		});
+		try {
+			const facets = await buildDocsSearchFacets({
+				pages: toSearchSourcePages(dedupePages(await options.source.getPages(resolvedLocale, options.requestContext))),
+				search: toolSearchConfig ?? true,
+				audience: resolvedAudience,
+				filters,
+				facet,
+				limit,
+				cursor,
+				locale: resolvedLocale,
+				baseUrl: options.source.baseUrl ?? (options.requestContext?.request ? new URL(options.requestContext.request.url).origin : void 0)
+			});
+			const elapsed = durationMs(startedAt);
+			await emitDocsAnalyticsEvent(options.analytics, {
+				type: "mcp_tool",
+				source: "mcp",
+				locale,
+				properties: {
+					tool: "list_search_facets",
+					audience: resolvedAudience,
+					matchedPageCount: facets.matchedPageCount,
+					frameworkCount: facets.facets.framework.valueCount,
+					versionCount: facets.facets.version.valueCount,
+					packageCount: facets.facets.package.valueCount,
+					tagCount: facets.facets.tags.valueCount,
+					durationMs: elapsed
+				}
+			});
+			trackMcpTool("list_search_facets", {
+				locale,
+				resultCount: facets.matchedPageCount
+			});
+			await emitDocsAgentTraceEvent(options.observability, {
+				type: "tool.result",
+				source: "mcp",
+				traceId: trace.traceId,
+				parentSpanId: callSpanId,
+				name: "list_search_facets",
+				startedAt: trace.startedAt,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				durationMs: elapsed,
+				status: "success",
+				locale,
+				outputPreview: {
+					matchedPageCount: facets.matchedPageCount,
+					facetValueCount: Object.values(facets.facets).reduce((total, facet) => total + facet.valueCount, 0)
+				},
+				metadata: { tool: "list_search_facets" }
+			});
+			return createStructuredTextResult(facets);
+		} catch (error) {
+			const elapsed = durationMs(startedAt);
+			await emitDocsAgentTraceEvent(options.observability, {
+				type: "tool.error",
+				source: "mcp",
+				traceId: trace.traceId,
+				parentSpanId: callSpanId,
+				name: "list_search_facets",
+				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_search_facets" }
+			});
+			throw error;
+		}
+	});
 	if (resolved.tools.searchDocs) registerTool("search_docs", {
 		title: "Search documentation",
 		description: "Search the docs by keyword with optional framework, version, package, and tag filters. Returns structured ambiguity and metadata warnings.",
@@ -3861,20 +4224,48 @@ function createDocsMcpHttpHandler(options) {
 			data: { reason: "mcp_disabled" }
 		}),
 		DELETE: async () => createJsonErrorResponse(404, disabledMessage),
-		OPTIONS: async () => createJsonErrorResponse(404, disabledMessage)
+		OPTIONS: async () => createJsonErrorResponse(404, disabledMessage),
+		close: async () => {}
 	};
-	async function createStatelessTransport(requestContext) {
-		const server = await createDocsMcpServer({
+	const contentChangesEnabled = resolveDocsContentChangesConfig(options.contentChanges).enabled && resolved.tools.listContentChanges !== false;
+	const contentChangeFeed = options.contentChangeFeed ?? createDocsContentChangeFeed(options.contentChanges);
+	const eventBus = new InMemoryServerEventBus();
+	const mcpHandler = createMcpHandler(async (context) => {
+		const internalAuth = context.authInfo;
+		return createDocsMcpServer({
 			...options,
-			requestContext
+			contentChangeFeed,
+			requestContext: {
+				transport: "http",
+				...context.requestInfo ? { request: context.requestInfo.clone() } : {},
+				...internalAuth?.principal ? { auth: internalAuth.principal } : {}
+			}
 		});
-		const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
-		await server.connect(transport);
-		return {
-			server,
-			transport
-		};
+	}, {
+		legacy: "stateless",
+		bus: eventBus
+	});
+	const configuredPollInterval = options.contentChangePollIntervalMs;
+	const contentChangePollIntervalMs = typeof configuredPollInterval === "number" && Number.isFinite(configuredPollInterval) && configuredPollInterval >= 10 ? Math.floor(configuredPollInterval) : DEFAULT_DOCS_MCP_CONTENT_CHANGE_POLL_INTERVAL_MS;
+	async function readMonitoredGeneration(context) {
+		const locale = options.source.resolveLocale?.(void 0, context);
+		const pages = dedupePages(await options.source.getPages(locale, context));
+		return (await contentChangeFeed.resolve({
+			pages: toSearchSourcePages(pages),
+			search: options.search,
+			audience: "agent",
+			locale,
+			baseUrl: options.source.baseUrl ?? (context.request ? new URL(context.request.url).origin : void 0),
+			...context.request ? { request: context.request.clone() } : {}
+		})).indexGeneration;
 	}
+	const contentChangeMonitor = createDocsMcpContentChangeMonitor({
+		pollIntervalMs: contentChangePollIntervalMs,
+		readGeneration: readMonitoredGeneration,
+		notify: () => mcpHandler.notify.resourceUpdated(DOCS_MCP_CONTENT_CHANGES_CURRENT_URI),
+		isActive: () => eventBus.listenerCount > 0,
+		unrefTimer: true
+	});
 	async function handle(request) {
 		const originalUrl = new URL(request.url);
 		const method = request.method.toUpperCase();
@@ -3957,26 +4348,77 @@ function createDocsMcpHttpHandler(options) {
 			code: -32700,
 			message: "Parse error: Invalid JSON"
 		}));
-		return withCors(await (await createStatelessTransport({
+		const requestContext = {
 			transport: "http",
 			request: request.clone(),
 			auth
-		})).transport.handleRequest(request, parsedBody === void 0 ? void 0 : { parsedBody }));
+		};
+		const isContentChangeSubscription = contentChangesEnabled && method === "POST" && typeof parsedBody === "object" && parsedBody !== null && !Array.isArray(parsedBody) && parsedBody.method === "subscriptions/listen";
+		const authInfo = auth ? {
+			token: "",
+			clientId: auth.id,
+			scopes: auth.scopes ?? [],
+			principal: auth
+		} : void 0;
+		const response = await mcpHandler.fetch(request, {
+			...parsedBody === void 0 ? {} : { parsedBody },
+			...authInfo ? { authInfo } : {}
+		});
+		if (isContentChangeSubscription) await contentChangeMonitor.start(requestContext);
+		return withCors(response);
 	}
 	return {
 		GET: async ({ request }) => handle(request),
 		POST: async ({ request }) => handle(request),
 		DELETE: async ({ request }) => handle(request),
-		OPTIONS: async ({ request }) => handle(request)
+		OPTIONS: async ({ request }) => handle(request),
+		close: async () => {
+			contentChangeMonitor.close();
+			await mcpHandler.close();
+		}
 	};
 }
 async function runDocsMcpStdio(options) {
-	const server = await createDocsMcpServer({
-		...options,
-		requestContext: { transport: "stdio" }
+	const resolved = resolveDocsMcpConfig(options.mcp, {
+		defaultName: options.defaultName ?? options.source.siteTitle ?? DEFAULT_MCP_NAME,
+		defaultVersion: options.defaultVersion
+	});
+	const contentChangesEnabled = resolveDocsContentChangesConfig(options.contentChanges).enabled && resolved.tools.listContentChanges !== false;
+	const contentChangeFeed = options.contentChangeFeed ?? createDocsContentChangeFeed(options.contentChanges);
+	const configuredPollInterval = options.contentChangePollIntervalMs;
+	const pollIntervalMs = typeof configuredPollInterval === "number" && Number.isFinite(configuredPollInterval) && configuredPollInterval >= 10 ? Math.floor(configuredPollInterval) : DEFAULT_DOCS_MCP_CONTENT_CHANGE_POLL_INTERVAL_MS;
+	serveStdio(async () => {
+		const requestContext = { transport: "stdio" };
+		const server = await createDocsMcpServer({
+			...options,
+			contentChangeFeed,
+			requestContext
+		});
+		if (!contentChangesEnabled) return server;
+		const readGeneration = async () => {
+			const locale = options.source.resolveLocale?.(void 0, requestContext);
+			const pages = dedupePages(await options.source.getPages(locale, requestContext));
+			return (await contentChangeFeed.resolve({
+				pages: toSearchSourcePages(pages),
+				search: options.search,
+				audience: "agent",
+				locale,
+				baseUrl: options.source.baseUrl
+			})).indexGeneration;
+		};
+		const monitor = createDocsMcpContentChangeMonitor({
+			pollIntervalMs,
+			readGeneration: () => readGeneration(),
+			notify: () => server.server.sendResourceUpdated({ uri: DOCS_MCP_CONTENT_CHANGES_CURRENT_URI })
+		});
+		await monitor.start(requestContext);
+		const closeServer = server.close.bind(server);
+		server.close = async () => {
+			monitor.close();
+			await closeServer();
+		};
+		return server;
 	});
-	const transport = new StdioServerTransport();
-	await server.connect(transport);
 }
 async function isDocsMcpOriginAllowed(request, allowedOrigins) {
 	const origin = request.headers.get("origin");
@@ -5417,4 +5859,4 @@ function toPageResourceUri(url) {
 }
 
 //#endregion
-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 };
+export { DEFAULT_DOCS_MCP_CONTENT_CHANGE_POLL_INTERVAL_MS, 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, DOCS_MCP_CONTENT_CHANGES_CURRENT_URI, DOCS_MCP_CONTENT_CHANGES_URI_TEMPLATE, buildDocsMcpContext, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, getDocsConfigSchema, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio };