feat: add withCursorPagination to withStandardDecorators

Moves cursor pagination into the standard decorator chain so all hosts
(stdio, hosted, any future) get it automatically. The return type uses
CursorPaginatedArgs<Args> to correctly reflect the schema transformation
(skip/take → optional cursor) at the TypeScript level.

Updates template list-examples test to use cursor-based pagination.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hifi-phil

.github/workflows/test.yml

@@ -247,51 +247,49 @@ jobs:
         env:
           KEEP_E2E_ASSETS: 'true'
 
-      # Temporarily disabled — API credit balance exhausted
-      # - name: Skill E2E (build tool + integration test)
-      #   if: >-
-      #     github.event.pull_request.base.ref == 'main' &&
-      #     startsWith(github.event.pull_request.head.ref, 'release/')
-      #   run: npm run test:e2e:skills -w packages/create-mcp-server
-      #   timeout-minutes: 10
-      #   env:
-      #     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-      #     CLAUDECODE: ''
+      - name: Skill E2E (build tool + integration test)
+        if: >-
+          github.event.pull_request.base.ref == 'main' &&
+          startsWith(github.event.pull_request.head.ref, 'release/')
+        run: npm run test:e2e:skills -w packages/create-mcp-server
+        timeout-minutes: 10
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDECODE: ''
 
       - name: Clean up E2E assets
         if: always()
         run: npm run test:e2e:cleanup -w packages/create-mcp-server || true
 
-  # Temporarily disabled — API credit balance exhausted
-  # evals:
-  #   name: LLM Eval Tests
-  #   if: >-
-  #     github.event.pull_request.base.ref == 'main' &&
-  #     startsWith(github.event.pull_request.head.ref, 'release/')
-  #   runs-on: ubuntu-latest
-  #
-  #   env:
-  #     NODE_TLS_REJECT_UNAUTHORIZED: '0'
-  #     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-  #
-  #   steps:
-  #     - name: Checkout
-  #       uses: actions/checkout@v4
-  #
-  #     - name: Setup Node.js
-  #       uses: actions/setup-node@v4
-  #       with:
-  #         node-version: '22'
-  #         cache: 'npm'
-  #
-  #     - name: Install npm dependencies
-  #       run: npm ci
-  #
-  #     - name: Build SDK
-  #       run: npm run build
-  #
-  #     - name: Build template
-  #       run: npm run build -w template
-  #
-  #     - name: Run CLI eval tests
-  #       run: npm run test:cli:evals
+  evals:
+    name: LLM Eval Tests
+    if: >-
+      github.event.pull_request.base.ref == 'main' &&
+      startsWith(github.event.pull_request.head.ref, 'release/')
+    runs-on: ubuntu-latest
+
+    env:
+      NODE_TLS_REJECT_UNAUTHORIZED: '0'
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install npm dependencies
+        run: npm ci
+
+      - name: Build SDK
+        run: npm run build
+
+      - name: Build template
+        run: npm run build -w template
+
+      - name: Run CLI eval tests
+        run: npm run test:cli:evals

packages/mcp-server-sdk/src/helpers/cursor-pagination.ts

@@ -121,6 +121,15 @@ export interface CursorPaginationOptions {
   defaultPageSize?: number;
 }
 
+/**
+ * Conditional type that reflects the schema transformation.
+ * If Args has both `skip` and `take`, replaces them with optional `cursor`.
+ * Otherwise returns Args unchanged.
+ */
+export type CursorPaginatedArgs<Args> = Args extends { skip: any; take: any }
+  ? Omit<Args, "skip" | "take"> & { cursor?: z.ZodOptional<z.ZodString> }
+  : Args;
+
 // ============================================================================
 // Decorator
 // ============================================================================
@@ -141,19 +150,19 @@ export interface CursorPaginationOptions {
  * @returns Transformed tool definition (or original if not paginated)
  */
 export function withCursorPagination<
-  InputArgs extends ZodRawShape,
-  OutputArgs extends undefined | ZodRawShape | ZodType,
+  Args extends undefined | ZodRawShape,
+  OutputArgs extends undefined | ZodRawShape | ZodType = undefined,
 >(
-  tool: ToolDefinition<InputArgs, OutputArgs>,
+  tool: ToolDefinition<Args, OutputArgs>,
   options?: CursorPaginationOptions
-): ToolDefinition<ZodRawShape, OutputArgs> {
+): ToolDefinition<CursorPaginatedArgs<Args>, OutputArgs> {
   // Detection: only apply if inputSchema has both skip and take
   if (
     !tool.inputSchema ||
     !("skip" in tool.inputSchema) ||
     !("take" in tool.inputSchema)
   ) {
-    return tool;
+    return tool as ToolDefinition<CursorPaginatedArgs<Args>, OutputArgs>;
   }
 
   const defaultPageSize = options?.defaultPageSize ?? DEFAULT_PAGE_SIZE;
@@ -205,7 +214,7 @@ export function withCursorPagination<
     ...tool,
     inputSchema: newInputSchema,
     outputSchema: newOutputSchema,
-    handler: async (args: any, extra: any) => {
+    handler: (async (args: any, extra: any) => {
       // Decode cursor or use defaults
       const { cursor, ...restArgs } = args;
       let skipVal = 0;
@@ -276,6 +285,6 @@ export function withCursorPagination<
       }
 
       return result;
-    },
-  };
+    }),
+  } as ToolDefinition<CursorPaginatedArgs<Args>, OutputArgs>;
 }

packages/mcp-server-sdk/src/helpers/index.ts

@@ -103,4 +103,5 @@ export {
   decodeCursor,
   computeNextCursor,
   type CursorPaginationOptions,
+  type CursorPaginatedArgs,
 } from "./cursor-pagination.js";

packages/mcp-server-sdk/src/helpers/tool-decorators.ts

@@ -13,6 +13,7 @@ import { UmbracoApiError } from "./api-call-helpers.js";
 import { ToolValidationError } from "./tool-validation-error.js";
 import { withInputSanitization } from "./input-sanitizer.js";
 import { withDryRun } from "./dry-run.js";
+import { withCursorPagination, type CursorPaginatedArgs } from "./cursor-pagination.js";
 
 // Re-export everything from split modules for convenience
 export {
@@ -211,15 +212,28 @@ export function createToolAnnotations(tool: ToolDefinition<any, any>): ToolAnnot
 
 /**
  * Standard decorator composition for all tools.
- * Applies: withErrorHandling → withInputSanitization → withDryRun → withPreExecutionCheck → handler
+ * Applies: withErrorHandling → withCursorPagination → withInputSanitization → withDryRun → withPreExecutionCheck → handler
  *
- * Input sanitization runs before dry-run so agents get validation feedback even in dry-run mode.
+ * Cursor pagination is applied after the inner decorators but before error handling,
+ * so cursor decode errors are caught. Only affects tools with skip/take in their
+ * inputSchema — all others pass through unchanged.
+ *
+ * The return type reflects the schema transformation: tools with skip/take get
+ * CursorPaginatedArgs (skip/take replaced with optional cursor).
  *
  * @example
  * export default withStandardDecorators(myTool);
  */
 export function withStandardDecorators<Args extends undefined | ZodRawShape, OutputArgs extends undefined | ZodRawShape | ZodType = undefined>(
   tool: ToolDefinition<Args, OutputArgs>
-): ToolDefinition<Args, OutputArgs> {
-  return compose<Args, OutputArgs>(withErrorHandling, withInputSanitization, withDryRun, withPreExecutionCheck)(tool);
+): ToolDefinition<CursorPaginatedArgs<Args>, OutputArgs> {
+  // Applied in three steps rather than a single compose() because
+  // withCursorPagination changes the type signature (skip/take → cursor),
+  // which compose() can't express since it requires uniform types throughout.
+  //
+  // Execution order (innermost → outermost):
+  //   1. preExecutionCheck → 2. dryRun → 3. inputSanitization → 4. cursorPagination → 5. errorHandling
+  const decorated = compose<Args, OutputArgs>(withInputSanitization, withDryRun, withPreExecutionCheck)(tool);
+  const paginated = withCursorPagination(decorated);
+  return withErrorHandling(paginated);
 }

packages/mcp-server-sdk/src/index.ts

@@ -107,6 +107,7 @@ export {
   decodeCursor,
   computeNextCursor,
   type CursorPaginationOptions,
+  type CursorPaginatedArgs,
 } from "./helpers/cursor-pagination.js";
 
 // CLI Introspection & Context Generation

template/src/umbraco-api/tools/example/__tests__/list-examples.test.ts

@@ -8,6 +8,7 @@ import {
   ExampleBuilder,
   ExampleTestHelper,
 } from "./setup.js";
+import { encodeCursor } from "@umbraco-cms/mcp-server-sdk";
 import listExamplesTool from "../get/list-examples.js";
 
 describe("list-examples", () => {
@@ -26,7 +27,7 @@ describe("list-examples", () => {
   it("should return paginated list", async () => {
     const context = createMockRequestHandlerExtra();
 
-    const result = await listExamplesTool.handler({ skip: 0, take: 100 }, context);
+    const result = await listExamplesTool.handler({}, context);
 
     expect(result.structuredContent).toBeDefined();
     const content = result.structuredContent as any;
@@ -35,15 +36,18 @@ describe("list-examples", () => {
     expect(Array.isArray(content.items)).toBe(true);
   });
 
-  it("should support pagination parameters", async () => {
+  it("should support cursor-based pagination", async () => {
     const context = createMockRequestHandlerExtra();
 
+    // Request 2 items via cursor encoding
+    const cursor = encodeCursor({ s: 0, t: 2 });
     const result = await listExamplesTool.handler(
-      { skip: 0, take: 2 },
+      { cursor },
       context
     );
 
     const content = result.structuredContent as any;
     expect(content.items.length).toBe(2);
+    expect(content.nextCursor).toBeDefined();
   });
 });

template/src/umbraco-api/tools/example/__tests__/search-examples.test.ts

@@ -36,7 +36,7 @@ describe("search-examples", () => {
     const context = createMockRequestHandlerExtra();
 
     const result = await searchExamplesTool.handler(
-      { query: "Search", skip: 0, take: 100 },
+      { query: "Search" },
       context
     );
 
@@ -50,7 +50,7 @@ describe("search-examples", () => {
     const context = createMockRequestHandlerExtra();
 
     const result = await searchExamplesTool.handler(
-      { query: "First item", skip: 0, take: 100 },
+      { query: "First item" },
       context
     );
 
@@ -62,7 +62,7 @@ describe("search-examples", () => {
     const context = createMockRequestHandlerExtra();
 
     const result = await searchExamplesTool.handler(
-      { query: "NonExistentQuery12345", skip: 0, take: 100 },
+      { query: "NonExistentQuery12345" },
       context
     );