@farming-labs/docs 0.2.75 → 0.2.77

package/dist/mcp.mjs

@@ -1,15 +1,15 @@
 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-BHqaZx-X.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 { S as upsertPageAgentContractMarkdown, _ as hasStructuredPageAgentContract, o as findDocsMarkdownSection, s as parseDocsMarkdownSections, v as normalizePageAgentFrontmatter } from "./markdown-sections-7OoA7ylx.mjs";
-import "./standards-discovery-BwL5ffGx.mjs";
-import { C as agentVersionConstraintsOverlap, E as normalizeAgentScopeValues, I as stripGeneratedAgentProvenance, R as resolvePageSidebarFolderIndexBehavior, S as agentVersionConstraintMatches, T as normalizeAgentLocale, U as emitDocsTelemetryMcpToolEvent, V as emitDocsTelemetryAgentSurfaceEvent, W as emitDocsTelemetryProjectEvent, f as normalizeDocsSearchFilters, k as isDocsRetrievalCanonicalUrl, m as performDocsSearchWithMetadata, p as performDocsSearch, w as normalizeAgentFramework } from "./search-BmC8wVr0.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 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 { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { ErrorCode, ListPromptsRequestSchema, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import * as z from "zod/v4";
 
 //#region src/mcp.ts
@@ -18,6 +18,9 @@ const DEFAULT_MCP_NAME = "@farming-labs/docs";
 const DEFAULT_MCP_CONTEXT_TOKEN_BUDGET = 4e3;
 const MIN_MCP_CONTEXT_TOKEN_BUDGET = 256;
 const MAX_MCP_CONTEXT_TOKEN_BUDGET = 32e3;
+const 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 UTF8_ENCODER = new TextEncoder();
 const DEFAULT_DOCS_MCP_MAX_BODY_BYTES = 1024 * 1024;
 const DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS = 600;
@@ -1562,17 +1565,26 @@ const DOCS_CONFIG_SCHEMA_OPTIONS_TEMPLATE = [
 		default: false,
 		description: "Generated API reference pages from framework route conventions or a hosted OpenAPI document.",
 		docs: "/docs/customization/api-reference",
-		children: [{
-			path: "apiReference.specUrl",
-			name: "specUrl",
-			type: "string",
-			description: "Remote OpenAPI JSON URL when the backend owns the schema."
-		}, {
-			path: "apiReference.path",
-			name: "path",
-			type: "string",
-			description: "Docs route where the API reference is rendered."
-		}]
+		children: [
+			{
+				path: "apiReference.specUrl",
+				name: "specUrl",
+				type: "string",
+				description: "Remote OpenAPI JSON URL when the backend owns the schema."
+			},
+			{
+				path: "apiReference.path",
+				name: "path",
+				type: "string",
+				description: "Docs route where the API reference is rendered."
+			},
+			{
+				path: "apiReference.catalogTargets",
+				name: "catalogTargets",
+				type: "string[]",
+				description: "Product API base URLs that the OpenAPI document describes in the RFC 9727 catalog."
+			}
+		]
 	},
 	{
 		path: "codeBlocks",
@@ -1704,9 +1716,11 @@ export default defineDocs({
 	}
 ]);
 const searchFilterValueSchema = z.union([z.string().trim().min(1).max(128), z.array(z.string().trim().min(1).max(128)).min(1).max(16)]);
+const paginationCursorInputSchema = z.string().min(1).max(4096).describe("Opaque nextCursor from the preceding response page.").optional();
 const searchDocsInputSchema = z.object({
 	query: z.string().trim().min(1),
 	limit: z.number().int().min(1).max(25).optional(),
+	cursor: paginationCursorInputSchema,
 	locale: z.string().trim().min(1).max(128).optional(),
 	audience: z.enum(["human", "agent"]).optional(),
 	framework: searchFilterValueSchema.optional(),
@@ -1724,14 +1738,16 @@ const listPageSectionsInputSchema = z.object({
 	path: z.string().min(1),
 	locale: z.string().trim().min(1).max(128).optional(),
 	tokenBudget: z.number().int().min(1).max(1e6).optional(),
-	byteBudget: z.number().int().min(1).max(1e6).optional()
+	byteBudget: z.number().int().min(1).max(1e6).optional(),
+	cursor: paginationCursorInputSchema
 });
 const listTasksInputSchema = z.object({
 	query: z.string().trim().min(1).optional(),
 	framework: z.string().trim().min(1).optional(),
 	version: z.string().trim().min(1).optional(),
 	package: z.string().trim().min(1).optional(),
-	locale: z.string().trim().min(1).max(128).optional()
+	locale: z.string().trim().min(1).max(128).optional(),
+	cursor: paginationCursorInputSchema
 });
 const readTaskInputSchema = readPageInputSchema;
 const pageAgentAppliesToOutputSchema = z.object({
@@ -1775,8 +1791,14 @@ const taskSummaryOutputSchema = z.object({
 	outcome: z.string().optional(),
 	appliesTo: pageAgentAppliesToOutputSchema.optional()
 });
+const paginationOutputShape = {
+	resultCount: z.number().int().nonnegative().describe("Items returned in this response page."),
+	total: z.number().int().nonnegative().describe("Items in the complete filtered result set."),
+	hasMore: z.boolean().describe("Whether another response page is available."),
+	nextCursor: z.string().describe("Opaque cursor to pass as cursor on the next request.").optional()
+};
 const listTasksOutputSchema = z.object({
-	resultCount: z.number().int().nonnegative(),
+	...paginationOutputShape,
 	tasks: z.array(taskSummaryOutputSchema)
 });
 const readTaskOutputSchema = z.object({
@@ -1790,10 +1812,14 @@ const readTaskOutputSchema = z.object({
 	}),
 	contract: pageAgentContractOutputSchema
 });
-const listPagesInputSchema = z.object({ locale: z.string().trim().min(1).max(128).optional() });
+const listPagesInputSchema = z.object({
+	locale: z.string().trim().min(1).max(128).optional(),
+	cursor: paginationCursorInputSchema
+});
 const listDocsInputSchema = z.object({
 	section: z.string().trim().min(1).optional(),
-	locale: z.string().trim().min(1).max(128).optional()
+	locale: z.string().trim().min(1).max(128).optional(),
+	cursor: paginationCursorInputSchema
 });
 const getNavigationInputSchema = z.object({ locale: z.string().trim().min(1).max(128).optional() });
 const getConfigSchemaInputSchema = z.object({
@@ -1846,10 +1872,13 @@ const docsSectionOutputSchema = z.lazy(() => z.object({
 	pages: z.array(pageSummaryOutputSchema),
 	sections: z.array(docsSectionOutputSchema)
 }));
-const listPagesOutputSchema = z.object({ pages: z.array(pageSummaryOutputSchema) });
+const listPagesOutputSchema = z.object({
+	...paginationOutputShape,
+	pages: z.array(pageSummaryOutputSchema)
+});
 const listDocsOutputSchema = z.object({
+	...paginationOutputShape,
 	section: z.string().optional(),
-	resultCount: z.number().int().nonnegative(),
 	sectionCount: z.number().int().nonnegative(),
 	pages: z.array(pageSummaryOutputSchema),
 	rootPages: z.array(pageSummaryOutputSchema),
@@ -1951,7 +1980,7 @@ const searchDocsOutputSchema = z.object({
 	audience: z.enum(["human", "agent"]),
 	filters: searchFiltersOutputSchema,
 	indexGeneration: retrievalSourceDigestOutputSchema,
-	resultCount: z.number().int().nonnegative(),
+	...paginationOutputShape,
 	results: z.array(searchResultOutputSchema),
 	warnings: z.array(searchWarningOutputSchema)
 });
@@ -2046,6 +2075,7 @@ const pageSectionIndexOutputSchema = z.object({
 	sectionIndexUrl: z.string(),
 	lineNumbering: z.literal("body"),
 	sectionCount: z.number().int().nonnegative(),
+	...paginationOutputShape,
 	estimatedTokens: z.number().int().nonnegative(),
 	utf8Bytes: z.number().int().nonnegative(),
 	fetchBudget: z.object({
@@ -2263,16 +2293,155 @@ function createStructuredTextResult(structuredContent, text) {
 		structuredContent
 	};
 }
+function stableDocsMcpPaginationScope(values) {
+	return JSON.stringify(values);
+}
+function docsMcpPaginationSnapshot(values) {
+	return JSON.stringify(values);
+}
+function paginateDocsMcpItems(items, options) {
+	return paginateDocsItems(items, {
+		kind: options.kind,
+		scope: options.scope,
+		snapshot: docsMcpPaginationSnapshot(items),
+		cursor: options.cursor,
+		pageSize: options.pageSize ?? DOCS_MCP_TOOL_LIST_PAGE_SIZE
+	});
+}
+function paginateDocsMcpProtocolItems(items, options) {
+	try {
+		return paginateDocsMcpItems(items, {
+			...options,
+			pageSize: DOCS_MCP_PROTOCOL_LIST_PAGE_SIZE
+		});
+	} catch (error) {
+		if (error instanceof DocsPaginationCursorError) throw new McpError(ErrorCode.InvalidParams, error.message);
+		throw error;
+	}
+}
+function toDocsMcpProtocolPaginationMeta(result) {
+	return { [DOCS_MCP_PAGINATION_META_KEY]: {
+		hasMore: result.hasMore,
+		total: result.total
+	} };
+}
+function paginateDocsMcpSdkListResult(result, field, options) {
+	const page = paginateDocsMcpProtocolItems([...result[field]].sort(options.compare), options);
+	return {
+		...result,
+		[field]: page.items,
+		nextCursor: page.nextCursor,
+		_meta: {
+			...result._meta,
+			...toDocsMcpProtocolPaginationMeta(page)
+		}
+	};
+}
+/**
+* The MCP SDK owns the live registries and descriptor serialization. Intercepting the
+* handlers it installs lets pagination operate on that live output without copying private
+* registry state or drifting from SDK behavior when callers register, update, or disable
+* tools/resources after this factory returns.
+*/
+function installDocsMcpSdkListPaginationInterceptor(server, scope) {
+	const originalSetRequestHandler = server.server.setRequestHandler;
+	const setRequestHandler = originalSetRequestHandler.bind(server.server);
+	const interceptedSetRequestHandler = ((requestSchema, handler) => {
+		const sdkHandler = handler;
+		if (Object.is(requestSchema, ListResourcesRequestSchema)) {
+			setRequestHandler(ListResourcesRequestSchema, async (request, extra) => {
+				return paginateDocsMcpSdkListResult(await sdkHandler(request, extra), "resources", {
+					kind: "mcp.protocol/resources-list",
+					scope,
+					cursor: request.params?.cursor,
+					compare: (left, right) => {
+						const uriOrder = left.uri.localeCompare(right.uri);
+						return uriOrder !== 0 ? uriOrder : left.name.localeCompare(right.name);
+					}
+				});
+			});
+			return;
+		}
+		if (Object.is(requestSchema, ListResourceTemplatesRequestSchema)) {
+			setRequestHandler(ListResourceTemplatesRequestSchema, async (request, extra) => {
+				return paginateDocsMcpSdkListResult(await sdkHandler(request, extra), "resourceTemplates", {
+					kind: "mcp.protocol/resource-templates-list",
+					scope,
+					cursor: request.params?.cursor,
+					compare: (left, right) => {
+						const uriOrder = left.uriTemplate.localeCompare(right.uriTemplate);
+						return uriOrder !== 0 ? uriOrder : left.name.localeCompare(right.name);
+					}
+				});
+			});
+			return;
+		}
+		if (Object.is(requestSchema, ListToolsRequestSchema)) {
+			setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+				return paginateDocsMcpSdkListResult(await sdkHandler(request, extra), "tools", {
+					kind: "mcp.protocol/tools-list",
+					scope,
+					cursor: request.params?.cursor,
+					compare: (left, right) => left.name.localeCompare(right.name)
+				});
+			});
+			return;
+		}
+		if (Object.is(requestSchema, ListPromptsRequestSchema)) {
+			setRequestHandler(ListPromptsRequestSchema, async (request, extra) => {
+				return paginateDocsMcpSdkListResult(await sdkHandler(request, extra), "prompts", {
+					kind: "mcp.protocol/prompts-list",
+					scope,
+					cursor: request.params?.cursor,
+					compare: (left, right) => left.name.localeCompare(right.name)
+				});
+			});
+			return;
+		}
+		setRequestHandler(requestSchema, handler);
+	});
+	server.server.setRequestHandler = interceptedSetRequestHandler;
+	return () => {
+		if (server.server.setRequestHandler === interceptedSetRequestHandler) server.server.setRequestHandler = originalSetRequestHandler;
+	};
+}
+function installDocsMcpSdkRegistrationPagination(server, scope) {
+	const wrapRegistration = (registration) => new Proxy(registration, { apply(target, thisArg, argArray) {
+		const restore = installDocsMcpSdkListPaginationInterceptor(server, scope);
+		try {
+			return Reflect.apply(target, thisArg, argArray);
+		} finally {
+			restore();
+		}
+	} });
+	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, {
 		defaultName: options.defaultName ?? options.source.siteTitle ?? DEFAULT_MCP_NAME,
 		defaultVersion: options.defaultVersion
 	});
 	const toolSearchConfig = resolveMcpToolSearchConfig(options.search, resolved.route);
+	const protocolScope = stableDocsMcpPaginationScope({
+		name: resolved.name,
+		version: resolved.version
+	});
 	const server = new McpServer({
 		name: resolved.name,
 		version: resolved.version
 	});
+	installDocsMcpSdkRegistrationPagination(server, protocolScope);
+	const registerResource = (name, uri, metadata, callback) => {
+		return server.registerResource(name, uri, metadata, callback);
+	};
+	const registerTool = (name, config, callback) => {
+		return server.registerTool(name, config, callback);
+	};
 	const telemetryConfig = {
 		telemetry: options.telemetry,
 		mcp: options.mcp,
@@ -2303,7 +2472,7 @@ async function createDocsMcpServer(options) {
 	const defaultPages = dedupePages(await getSourcePages());
 	const defaultTree = await getSourceNavigation();
 	const defaultSkills = await getSourceSkills();
-	server.registerResource("docs-navigation", "docs://navigation", {
+	registerResource("docs-navigation", "docs://navigation", {
 		title: "Docs Navigation",
 		description: "Structured navigation tree for the documentation site.",
 		mimeType: "text/plain"
@@ -2314,7 +2483,7 @@ async function createDocsMcpServer(options) {
 	}] }));
 	for (const page of defaultPages) {
 		const resourceUri = toPageResourceUri(page.url);
-		server.registerResource(`page-${slugToKey(page.slug)}`, resourceUri, {
+		registerResource(`page-${slugToKey(page.slug)}`, resourceUri, {
 			title: page.title,
 			description: page.description,
 			mimeType: "text/markdown"
@@ -2327,7 +2496,7 @@ async function createDocsMcpServer(options) {
 	for (const skill of defaultSkills) for (const file of skill.files) {
 		const encodedPath = file.path.split("/").map((segment) => encodeURIComponent(segment)).join("/");
 		const resourceUri = `docs://skills/${encodeURIComponent(skill.name)}/${encodedPath}`;
-		server.registerResource(`skill-${encodeURIComponent(skill.name)}-${Buffer.from(file.path).toString("base64url")}`, resourceUri, {
+		registerResource(`skill-${encodeURIComponent(skill.name)}-${Buffer.from(file.path).toString("base64url")}`, resourceUri, {
 			title: `${skill.name}: ${file.path}`,
 			description: `${skill.description} (${file.digest})`,
 			mimeType: file.mediaType
@@ -2341,14 +2510,15 @@ async function createDocsMcpServer(options) {
 			blob: Buffer.from(file.content).toString("base64")
 		}] }));
 	}
-	if (resolved.tools.listPages) server.registerTool("list_pages", {
+	if (resolved.tools.listPages) registerTool("list_pages", {
 		title: "List docs pages",
 		description: "List the known documentation pages with titles, slugs, and URLs.",
 		inputSchema: listPagesInputSchema,
 		outputSchema: listPagesOutputSchema,
 		annotations: { readOnlyHint: true }
-	}, async ({ locale }) => {
+	}, async ({ locale, cursor }) => {
 		const startedAt = nowMs();
+		const resolvedLocale = resolveSourceLocale(locale);
 		const trace = createDocsAgentTraceContext("mcp.tool.list_pages");
 		const callSpanId = createDocsAgentTraceId("span");
 		await emitDocsAgentTraceEvent(options.observability, {
@@ -2360,11 +2530,25 @@ async function createDocsMcpServer(options) {
 			startedAt: trace.startedAt,
 			status: "started",
 			locale,
-			inputPreview: { locale },
+			inputPreview: {
+				locale,
+				hasCursor: cursor !== void 0
+			},
 			metadata: { tool: "list_pages" }
 		});
 		try {
-			const pages = toPageSummaries(dedupePages(await getSourcePages(locale)));
+			const page = paginateDocsMcpItems(toPageSummaries(dedupePages(await options.source.getPages(resolvedLocale, options.requestContext))).sort(compareDocsMcpPageSummaries), {
+				kind: "mcp.tool/list_pages",
+				scope: stableDocsMcpPaginationScope({ locale: resolvedLocale ?? null }),
+				cursor
+			});
+			const result = {
+				resultCount: page.resultCount,
+				total: page.total,
+				hasMore: page.hasMore,
+				...page.nextCursor ? { nextCursor: page.nextCursor } : {},
+				pages: page.items
+			};
 			const elapsed = durationMs(startedAt);
 			await emitDocsAnalyticsEvent(options.analytics, {
 				type: "mcp_tool",
@@ -2372,13 +2556,15 @@ async function createDocsMcpServer(options) {
 				locale,
 				properties: {
 					tool: "list_pages",
-					resultCount: pages.length,
+					resultCount: page.resultCount,
+					total: page.total,
+					hasMore: page.hasMore,
 					durationMs: elapsed
 				}
 			});
 			trackMcpTool("list_pages", {
 				locale,
-				resultCount: pages.length
+				resultCount: page.resultCount
 			});
 			await emitDocsAgentTraceEvent(options.observability, {
 				type: "tool.result",
@@ -2391,10 +2577,14 @@ async function createDocsMcpServer(options) {
 				durationMs: elapsed,
 				status: "success",
 				locale,
-				outputPreview: { resultCount: pages.length },
+				outputPreview: {
+					resultCount: page.resultCount,
+					total: page.total,
+					hasMore: page.hasMore
+				},
 				metadata: { tool: "list_pages" }
 			});
-			return createStructuredTextResult({ pages });
+			return createStructuredTextResult(result);
 		} catch (error) {
 			const elapsed = durationMs(startedAt);
 			await emitDocsAgentTraceEvent(options.observability, {
@@ -2414,14 +2604,15 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
-	if (resolved.tools.listDocs) server.registerTool("list_docs", {
+	if (resolved.tools.listDocs) registerTool("list_docs", {
 		title: "List docs by section",
 		description: "List documentation pages grouped by section, optionally narrowed to one section.",
 		inputSchema: listDocsInputSchema,
 		outputSchema: listDocsOutputSchema,
 		annotations: { readOnlyHint: true }
-	}, async ({ section, locale }) => {
+	}, async ({ section, locale, cursor }) => {
 		const startedAt = nowMs();
+		const resolvedLocale = resolveSourceLocale(locale);
 		const trace = createDocsAgentTraceContext("mcp.tool.list_docs");
 		const callSpanId = createDocsAgentTraceId("span");
 		await emitDocsAgentTraceEvent(options.observability, {
@@ -2435,14 +2626,21 @@ async function createDocsMcpServer(options) {
 			locale,
 			inputPreview: {
 				section,
-				locale
+				locale,
+				hasCursor: cursor !== void 0
 			},
 			metadata: { tool: "list_docs" }
 		});
 		try {
-			const docs = listDocsBySection(dedupePages(await getSourcePages(locale)), {
+			const docs = paginateDocsMcpDocsList(listDocsBySection(dedupePages(await options.source.getPages(resolvedLocale, options.requestContext)), {
 				section,
 				entry: options.source.entry
+			}), {
+				cursor,
+				scope: stableDocsMcpPaginationScope({
+					locale: resolvedLocale ?? null,
+					section: normalizeDocsListMatchValue(section ?? "")
+				})
 			});
 			const elapsed = durationMs(startedAt);
 			await emitDocsAnalyticsEvent(options.analytics, {
@@ -2453,6 +2651,8 @@ async function createDocsMcpServer(options) {
 					tool: "list_docs",
 					section,
 					resultCount: docs.resultCount,
+					total: docs.total,
+					hasMore: docs.hasMore,
 					sectionCount: docs.sectionCount,
 					durationMs: elapsed
 				}
@@ -2474,6 +2674,8 @@ async function createDocsMcpServer(options) {
 				locale,
 				outputPreview: {
 					resultCount: docs.resultCount,
+					total: docs.total,
+					hasMore: docs.hasMore,
 					sectionCount: docs.sectionCount
 				},
 				metadata: { tool: "list_docs" }
@@ -2498,14 +2700,15 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
-	if (resolved.tools.listTasks) server.registerTool("list_tasks", {
+	if (resolved.tools.listTasks) registerTool("list_tasks", {
 		title: "List documented tasks",
 		description: "List pages with actionable agent contracts, optionally filtered by text or applicability.",
 		inputSchema: listTasksInputSchema,
 		outputSchema: listTasksOutputSchema,
 		annotations: { readOnlyHint: true }
-	}, async ({ query, framework, version, package: packageName, locale }) => {
+	}, async ({ query, framework, version, package: packageName, locale, cursor }) => {
 		const startedAt = nowMs();
+		const resolvedLocale = resolveSourceLocale(locale);
 		const trace = createDocsAgentTraceContext("mcp.tool.list_tasks");
 		const callSpanId = createDocsAgentTraceId("span");
 		await emitDocsAgentTraceEvent(options.observability, {
@@ -2521,20 +2724,34 @@ async function createDocsMcpServer(options) {
 				queryLength: query?.length,
 				framework,
 				version,
-				package: packageName
+				package: packageName,
+				hasCursor: cursor !== void 0
 			},
 			metadata: { tool: "list_tasks" }
 		});
 		try {
-			const tasks = listDocsTasks(dedupePages(await getSourcePages(locale)), {
+			const page = paginateDocsMcpItems(listDocsTasks(dedupePages(await options.source.getPages(resolvedLocale, options.requestContext)), {
 				query,
 				framework,
 				version,
 				package: packageName
+			}).sort(compareDocsMcpTaskSummaries), {
+				kind: "mcp.tool/list_tasks",
+				scope: stableDocsMcpPaginationScope({
+					locale: resolvedLocale ?? null,
+					query: query?.trim().toLowerCase() ?? null,
+					framework: framework?.trim().toLowerCase() ?? null,
+					version: version?.trim().toLowerCase() ?? null,
+					package: packageName?.trim().toLowerCase() ?? null
+				}),
+				cursor
 			});
 			const result = {
-				resultCount: tasks.length,
-				tasks
+				resultCount: page.resultCount,
+				total: page.total,
+				hasMore: page.hasMore,
+				...page.nextCursor ? { nextCursor: page.nextCursor } : {},
+				tasks: page.items
 			};
 			const elapsed = durationMs(startedAt);
 			await emitDocsAnalyticsEvent(options.analytics, {
@@ -2547,13 +2764,15 @@ async function createDocsMcpServer(options) {
 					framework,
 					version,
 					package: packageName,
-					resultCount: tasks.length,
+					resultCount: page.resultCount,
+					total: page.total,
+					hasMore: page.hasMore,
 					durationMs: elapsed
 				}
 			});
 			trackMcpTool("list_tasks", {
 				locale,
-				resultCount: tasks.length
+				resultCount: page.resultCount
 			});
 			await emitDocsAgentTraceEvent(options.observability, {
 				type: "tool.result",
@@ -2566,7 +2785,11 @@ async function createDocsMcpServer(options) {
 				durationMs: elapsed,
 				status: "success",
 				locale,
-				outputPreview: { resultCount: tasks.length },
+				outputPreview: {
+					resultCount: page.resultCount,
+					total: page.total,
+					hasMore: page.hasMore
+				},
 				metadata: { tool: "list_tasks" }
 			});
 			return {
@@ -2595,7 +2818,7 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
-	if (resolved.tools.readTask) server.registerTool("read_task", {
+	if (resolved.tools.readTask) registerTool("read_task", {
 		title: "Read a documented task",
 		description: "Read the full structured agent contract for a page by slug or URL path.",
 		inputSchema: readTaskInputSchema,
@@ -2744,7 +2967,7 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
-	if (resolved.tools.getNavigation) server.registerTool("get_navigation", {
+	if (resolved.tools.getNavigation) registerTool("get_navigation", {
 		title: "Get docs navigation",
 		description: "Return the documentation navigation tree for the current docs site.",
 		inputSchema: getNavigationInputSchema,
@@ -2817,7 +3040,7 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
-	if (resolved.tools.getConfigSchema) server.registerTool("get_config_schema", {
+	if (resolved.tools.getConfigSchema) registerTool("get_config_schema", {
 		title: "Get docs config schema",
 		description: "Return structured docs.config.ts option metadata, optionally filtered by option path or query.",
 		inputSchema: getConfigSchemaInputSchema,
@@ -2892,13 +3115,13 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
-	if (resolved.tools.searchDocs) server.registerTool("search_docs", {
+	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.",
 		inputSchema: searchDocsInputSchema,
 		outputSchema: searchDocsOutputSchema,
 		annotations: { readOnlyHint: true }
-	}, async ({ query, limit, locale, audience, framework, version, package: packageName, tags }) => {
+	}, async ({ query, limit, cursor, locale, audience, framework, version, package: packageName, tags }) => {
 		const startedAt = nowMs();
 		const resolvedLimit = limit ?? 10;
 		const resolvedAudience = audience ?? "agent";
@@ -2923,6 +3146,7 @@ async function createDocsMcpServer(options) {
 			inputPreview: {
 				queryLength: query.length,
 				limit: resolvedLimit,
+				hasCursor: cursor !== void 0,
 				locale,
 				audience: resolvedAudience,
 				filterFields: Object.entries(filters).filter(([, value]) => value !== void 0).map(([field]) => field)
@@ -2940,7 +3164,8 @@ async function createDocsMcpServer(options) {
 				siteTitle: options.source.siteTitle,
 				baseUrl: options.source.baseUrl ?? (options.requestContext?.request ? new URL(options.requestContext.request.url).origin : void 0),
 				syncBaseUrl: options.source.baseUrl ?? null,
-				limit: resolvedLimit
+				limit: resolvedLimit,
+				cursor
 			});
 			const elapsed = durationMs(startedAt);
 			await emitDocsAnalyticsEvent(options.analytics, {
@@ -2954,6 +3179,8 @@ async function createDocsMcpServer(options) {
 					limit: resolvedLimit,
 					audience: resolvedAudience,
 					resultCount: searchResponse.resultCount,
+					total: searchResponse.total,
+					hasMore: searchResponse.hasMore,
 					warningCount: searchResponse.warnings.length,
 					durationMs: elapsed
 				}
@@ -2975,6 +3202,8 @@ async function createDocsMcpServer(options) {
 				locale,
 				outputPreview: {
 					resultCount: searchResponse.resultCount,
+					total: searchResponse.total,
+					hasMore: searchResponse.hasMore,
 					warningCount: searchResponse.warnings.length
 				},
 				metadata: { tool: "search_docs" }
@@ -2999,7 +3228,7 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
-	if (resolved.tools.getCodeExamples) server.registerTool("get_code_examples", {
+	if (resolved.tools.getCodeExamples) registerTool("get_code_examples", {
 		title: "Get docs code examples",
 		description: "Return fenced code examples from the docs with parsed metadata such as title, framework, packageManager, and runnable.",
 		inputSchema: getCodeExamplesInputSchema,
@@ -3098,7 +3327,7 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
-	if (resolved.tools.getContext) server.registerTool("get_context", {
+	if (resolved.tools.getContext) registerTool("get_context", {
 		title: "Get budgeted docs context",
 		description: "Build deterministic, section-level documentation context for a query within a conservative UTF-8 byte ceiling derived from the requested token budget, with source URLs and accounting metadata.",
 		inputSchema: getContextInputSchema,
@@ -3208,13 +3437,13 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
-	if (resolved.tools.listPageSections !== false) server.registerTool("list_page_sections", {
+	if (resolved.tools.listPageSections !== false) registerTool("list_page_sections", {
 		title: "List sections in a docs page",
 		description: "Discover a page's canonical headings, anchors, hierarchy, line ranges, size estimates, and budget-aware fetch URLs without returning the page body.",
 		inputSchema: listPageSectionsInputSchema,
 		outputSchema: pageSectionIndexOutputSchema,
 		annotations: { readOnlyHint: true }
-	}, async ({ path: requestedPath, locale, tokenBudget, byteBudget }) => {
+	}, async ({ path: requestedPath, locale, tokenBudget, byteBudget, cursor }) => {
 		const startedAt = nowMs();
 		const resolvedLocale = resolveSourceLocale(locale);
 		const trace = createDocsAgentTraceContext("mcp.tool.list_page_sections");
@@ -3233,7 +3462,8 @@ async function createDocsMcpServer(options) {
 				locale,
 				resolvedLocale,
 				tokenBudget,
-				byteBudget
+				byteBudget,
+				hasCursor: cursor !== void 0
 			},
 			metadata: { tool: "list_page_sections" }
 		});
@@ -3286,12 +3516,31 @@ async function createDocsMcpServer(options) {
 			}
 			const document = upsertPageAgentContractMarkdown(getDocsMcpSourceMarkdown(page), page.agent);
 			const publicBaseUrl = options.source.baseUrl ?? (options.requestContext?.request ? new URL(options.requestContext.request.url).origin : void 0);
-			const sectionIndex = buildDocsMarkdownSectionIndex(document, {
+			const completeSectionIndex = buildDocsMarkdownSectionIndex(document, {
 				canonicalUrl: resolveDocsMcpPublicUrl(withDocsMcpUrlLocale(page.url, resolvedLocale), publicBaseUrl),
 				markdownUrl: resolveDocsMcpPublicUrl(toDocsMcpPageMarkdownUrl(page.url, resolvedLocale), publicBaseUrl),
 				tokenBudget,
 				byteBudget
 			});
+			const sectionPage = paginateDocsMcpItems(completeSectionIndex.sections, {
+				kind: "mcp.tool/list_page_sections",
+				scope: stableDocsMcpPaginationScope({
+					path: page.url,
+					locale: resolvedLocale ?? null,
+					tokenBudget: tokenBudget ?? null,
+					byteBudget: byteBudget ?? null
+				}),
+				cursor
+			});
+			const sectionIndex = {
+				...completeSectionIndex,
+				sectionCount: completeSectionIndex.sectionCount,
+				resultCount: sectionPage.resultCount,
+				total: sectionPage.total,
+				hasMore: sectionPage.hasMore,
+				...sectionPage.nextCursor ? { nextCursor: sectionPage.nextCursor } : {},
+				sections: sectionPage.items
+			};
 			const elapsed = durationMs(startedAt);
 			await emitDocsAnalyticsEvent(options.analytics, {
 				type: "mcp_tool",
@@ -3304,6 +3553,8 @@ async function createDocsMcpServer(options) {
 					slug: page.slug,
 					found: true,
 					sectionCount: sectionIndex.sectionCount,
+					total: sectionIndex.total,
+					hasMore: sectionIndex.hasMore,
 					estimatedTokens: sectionIndex.estimatedTokens,
 					utf8Bytes: sectionIndex.utf8Bytes,
 					tokenBudget,
@@ -3313,7 +3564,7 @@ async function createDocsMcpServer(options) {
 			});
 			trackMcpTool("list_page_sections", {
 				locale: resolvedLocale,
-				resultCount: sectionIndex.sectionCount
+				resultCount: sectionIndex.resultCount
 			});
 			await emitDocsAgentTraceEvent(options.observability, {
 				type: "tool.result",
@@ -3331,6 +3582,8 @@ async function createDocsMcpServer(options) {
 					found: true,
 					slug: page.slug,
 					sectionCount: sectionIndex.sectionCount,
+					total: sectionIndex.total,
+					hasMore: sectionIndex.hasMore,
 					estimatedTokens: sectionIndex.estimatedTokens,
 					utf8Bytes: sectionIndex.utf8Bytes
 				},
@@ -3356,7 +3609,7 @@ async function createDocsMcpServer(options) {
 			throw error;
 		}
 	});
-	if (resolved.tools.readPage) server.registerTool("read_page", {
+	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.",
 		inputSchema: readPageInputSchema,
@@ -4371,6 +4624,18 @@ function toDocsListPageSummary(page) {
 		lastModified: page.lastModified
 	};
 }
+function compareDocsMcpPageSummaries(left, right) {
+	const urlOrder = left.url.localeCompare(right.url);
+	if (urlOrder !== 0) return urlOrder;
+	const slugOrder = left.slug.localeCompare(right.slug);
+	return slugOrder !== 0 ? slugOrder : left.title.localeCompare(right.title);
+}
+function compareDocsMcpTaskSummaries(left, right) {
+	const urlOrder = left.url.localeCompare(right.url);
+	if (urlOrder !== 0) return urlOrder;
+	const slugOrder = left.slug.localeCompare(right.slug);
+	return slugOrder !== 0 ? slugOrder : left.title.localeCompare(right.title);
+}
 function listDocsTasks(pages, filters) {
 	const query = filters.query?.toLowerCase();
 	const applicabilityFilters = [
@@ -4412,6 +4677,8 @@ function listDocsBySection(pages, filters) {
 	const requestedSection = filters.section?.trim();
 	if (!requestedSection) return {
 		resultCount: allPages.length,
+		total: allPages.length,
+		hasMore: false,
 		sectionCount: countDocsSections(tree.sections),
 		pages: allPages,
 		rootPages: tree.rootPages,
@@ -4424,6 +4691,8 @@ function listDocsBySection(pages, filters) {
 		return {
 			section: requestedSection,
 			resultCount: matchedPages.length,
+			total: matchedPages.length,
+			hasMore: false,
 			sectionCount: countDocsSections(sections),
 			pages: matchedPages,
 			rootPages: [],
@@ -4434,6 +4703,8 @@ function listDocsBySection(pages, filters) {
 	if (page) return {
 		section: requestedSection,
 		resultCount: 1,
+		total: 1,
+		hasMore: false,
 		sectionCount: 0,
 		pages: [page],
 		rootPages: [page],
@@ -4442,12 +4713,46 @@ function listDocsBySection(pages, filters) {
 	return {
 		section: requestedSection,
 		resultCount: 0,
+		total: 0,
+		hasMore: false,
 		sectionCount: 0,
 		pages: [],
 		rootPages: [],
 		sections: []
 	};
 }
+function paginateDocsMcpDocsList(docs, options) {
+	const page = paginateDocsMcpItems([...docs.pages].sort(compareDocsMcpPageSummaries), {
+		kind: "mcp.tool/list_docs",
+		scope: options.scope,
+		cursor: options.cursor
+	});
+	const pageUrls = new Set(page.items.map((item) => item.url));
+	const sections = pruneDocsMcpSections(docs.sections, pageUrls);
+	return {
+		...docs,
+		resultCount: page.resultCount,
+		total: page.total,
+		hasMore: page.hasMore,
+		...page.nextCursor ? { nextCursor: page.nextCursor } : {},
+		pages: page.items,
+		rootPages: docs.rootPages.filter((item) => pageUrls.has(item.url)),
+		sections,
+		sectionCount: docs.sectionCount
+	};
+}
+function pruneDocsMcpSections(sections, pageUrls) {
+	return sections.flatMap((section) => {
+		const pages = section.pages.filter((page) => pageUrls.has(page.url));
+		const childSections = pruneDocsMcpSections(section.sections, pageUrls);
+		if (pages.length === 0 && childSections.length === 0) return [];
+		return [{
+			...section,
+			pages,
+			sections: childSections
+		}];
+	});
+}
 function buildDocsSectionTree(pages) {
 	const sectionSlugs = /* @__PURE__ */ new Set();
 	for (const page of pages) {