mcp-http-webhook 1.0.6 → 1.0.7

package/src/__tests__/pagination.test.ts

@@ -0,0 +1,323 @@
+import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
+import request from 'supertest';
+import { createMCPServer, InMemoryStore, ResourceDefinition, AuthContext, ResourceReadOptions } from '../index';
+
+describe('Pagination Support', () => {
+  let server: any;
+  let app: any;
+
+  // Mock data
+  const mockItems = Array.from({ length: 50 }, (_, i) => ({
+    id: `item-${i + 1}`,
+    name: `Item ${i + 1}`,
+    data: `Data for item ${i + 1}`,
+  }));
+
+  beforeAll(async () => {
+    const paginatedResource: ResourceDefinition = {
+      uri: 'test://items',
+      name: 'test-items',
+      description: 'Test resource with pagination',
+      mimeType: 'application/json',
+
+      list: async (context: AuthContext, options?: ResourceReadOptions) => {
+        const page = options?.pagination?.page || 1;
+        const limit = options?.pagination?.limit || 10;
+        const offset = (page - 1) * limit;
+
+        const paginatedItems = mockItems.slice(offset, offset + limit);
+
+        return {
+          resources: paginatedItems.map(item => ({
+            uri: `test://items/${item.id}`,
+            name: item.name,
+          })),
+          pagination: {
+            page,
+            limit,
+            total: mockItems.length,
+            hasMore: offset + limit < mockItems.length,
+          },
+        };
+      },
+
+      read: async (uri: string, context: AuthContext, options?: ResourceReadOptions) => {
+        const itemId = uri.split('/').pop();
+        const item = mockItems.find(i => i.id === itemId);
+
+        if (!item) {
+          throw new Error('Item not found');
+        }
+
+        // Support pagination for large content
+        const page = options?.pagination?.page || 1;
+        const limit = options?.pagination?.limit || 100;
+
+        return {
+          contents: item,
+          pagination: options?.pagination
+            ? {
+                page,
+                limit,
+                total: 1,
+                hasMore: false,
+              }
+            : undefined,
+        };
+      },
+    };
+
+    const cursorResource: ResourceDefinition = {
+      uri: 'test://cursor',
+      name: 'test-cursor',
+      description: 'Test resource with cursor pagination',
+      mimeType: 'application/json',
+
+      list: async (_context: AuthContext) => {
+        return {
+          resources: [{ uri: 'test://cursor', name: 'Cursor Resource' }],
+        };
+      },
+
+      read: async (uri: string, context: AuthContext, options?: ResourceReadOptions) => {
+        const cursor = options?.pagination?.cursor;
+        const limit = options?.pagination?.limit || 10;
+        const cursorIndex = cursor ? parseInt(cursor, 10) : 0;
+
+        const paginatedItems = mockItems.slice(cursorIndex, cursorIndex + limit);
+        const hasMore = cursorIndex + limit < mockItems.length;
+
+        return {
+          contents: paginatedItems,
+          pagination: {
+            page: 1,
+            limit,
+            total: mockItems.length,
+            hasMore,
+            nextCursor: hasMore ? String(cursorIndex + limit) : undefined,
+            prevCursor: cursorIndex > 0 ? String(Math.max(0, cursorIndex - limit)) : undefined,
+          },
+        };
+      },
+    };
+
+    server = createMCPServer({
+      name: 'pagination-test',
+      version: '1.0.0',
+      publicUrl: 'http://localhost:3001',
+      port: 3001,
+      store: new InMemoryStore(),
+      tools: [],
+      resources: [paginatedResource, cursorResource],
+    });
+
+    await server.start();
+    app = server.getApp();
+  });
+
+  afterAll(async () => {
+    await server.stop();
+  });
+
+  describe('List with Pagination', () => {
+    it('should return first page by default', async () => {
+      const response = await request(app)
+        .post('/mcp')
+        .send({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'resources/list',
+          params: {},
+        });
+
+      expect(response.status).toBe(200);
+      expect(response.body.result).toBeDefined();
+      expect(response.body.result.resources).toHaveLength(10); // Default limit
+      expect(response.body.result._meta?.pagination).toMatchObject({
+        page: 1,
+        limit: 10,
+        total: 50,
+        hasMore: true,
+      });
+    });
+
+    it('should return specific page with custom limit', async () => {
+      const response = await request(app)
+        .post('/mcp')
+        .send({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'resources/list',
+          params: {},
+          _meta: {
+            page: 2,
+            limit: 5,
+          },
+        });
+
+      expect(response.status).toBe(200);
+      expect(response.body.result.resources).toHaveLength(5);
+      expect(response.body.result._meta?.pagination).toMatchObject({
+        page: 2,
+        limit: 5,
+        total: 50,
+        hasMore: true,
+      });
+    });
+
+    it('should indicate no more pages on last page', async () => {
+      const response = await request(app)
+        .post('/mcp')
+        .send({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'resources/list',
+          params: {},
+          _meta: {
+            page: 5,
+            limit: 10,
+          },
+        });
+
+      expect(response.status).toBe(200);
+      expect(response.body.result.resources).toHaveLength(10);
+      expect(response.body.result._meta?.pagination.hasMore).toBe(false);
+    });
+  });
+
+  describe('Read with Pagination', () => {
+    it('should read without pagination by default', async () => {
+      const response = await request(app)
+        .post('/mcp')
+        .send({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'resources/read',
+          params: {
+            uri: 'test://items/item-1',
+          },
+        });
+
+      expect(response.status).toBe(200);
+      expect(response.body.result.contents).toBeDefined();
+      expect(response.body.result._meta?.pagination).toBeUndefined();
+    });
+
+    it('should support pagination when requested', async () => {
+      const response = await request(app)
+        .post('/mcp')
+        .send({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'resources/read',
+          params: {
+            uri: 'test://items/item-1',
+          },
+          _meta: {
+            page: 1,
+            limit: 50,
+          },
+        });
+
+      expect(response.status).toBe(200);
+      expect(response.body.result.contents).toBeDefined();
+      expect(response.body.result._meta?.pagination).toMatchObject({
+        page: 1,
+        limit: 50,
+        total: 1,
+        hasMore: false,
+      });
+    });
+  });
+
+  describe('Cursor-based Pagination', () => {
+    it('should support cursor pagination', async () => {
+      const response = await request(app)
+        .post('/mcp')
+        .send({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'resources/read',
+          params: {
+            uri: 'test://cursor',
+          },
+          _meta: {
+            limit: 10,
+          },
+        });
+
+      expect(response.status).toBe(200);
+      expect(response.body.result.contents).toHaveLength(10);
+      expect(response.body.result._meta?.pagination).toMatchObject({
+        page: 1,
+        limit: 10,
+        total: 50,
+        hasMore: true,
+      });
+      expect(response.body.result._meta?.pagination.nextCursor).toBe('10');
+      expect(response.body.result._meta?.pagination.prevCursor).toBeUndefined();
+    });
+
+    it('should navigate using cursor', async () => {
+      const response = await request(app)
+        .post('/mcp')
+        .send({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'resources/read',
+          params: {
+            uri: 'test://cursor',
+          },
+          _meta: {
+            cursor: '20',
+            limit: 10,
+          },
+        });
+
+      expect(response.status).toBe(200);
+      expect(response.body.result.contents).toHaveLength(10);
+      expect(response.body.result._meta?.pagination.nextCursor).toBe('30');
+      expect(response.body.result._meta?.pagination.prevCursor).toBe('10');
+    });
+
+    it('should handle last page with cursor', async () => {
+      const response = await request(app)
+        .post('/mcp')
+        .send({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'resources/read',
+          params: {
+            uri: 'test://cursor',
+          },
+          _meta: {
+            cursor: '45',
+            limit: 10,
+          },
+        });
+
+      expect(response.status).toBe(200);
+      expect(response.body.result.contents).toHaveLength(5);
+      expect(response.body.result._meta?.pagination.hasMore).toBe(false);
+      expect(response.body.result._meta?.pagination.nextCursor).toBeUndefined();
+      expect(response.body.result._meta?.pagination.prevCursor).toBe('35');
+    });
+  });
+
+  describe('Backward Compatibility', () => {
+    it('should handle resources without pagination support', async () => {
+      // This tests that old resources still work
+      const response = await request(app)
+        .post('/mcp')
+        .send({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'resources/list',
+          params: {},
+        });
+
+      expect(response.status).toBe(200);
+      expect(response.body.result.resources).toBeDefined();
+    });
+  });
+});

package/src/server.ts

@@ -2,6 +2,7 @@ import express, { Express, Request, Response, NextFunction } from 'express';
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { z } from 'zod';
+import { completable } from '@modelcontextprotocol/sdk/server/completable.js';
 import { MCPServerConfig, MCPServer, Logger, JSONSchema, CredentialFieldDefinition } from './types';
 import { SubscriptionManager } from './subscriptions/SubscriptionManager';
 import { WebhookManager } from './webhooks/WebhookManager';
@@ -205,6 +206,7 @@ export function createMCPServer(config: MCPServerConfig): MCPServer {
         experimental: {
           isConnector: true,
         },
+        "completions": {}
       },
     }
   );
@@ -255,12 +257,28 @@ export function createMCPServer(config: MCPServerConfig): MCPServer {
     if (isTemplate && resourceDef.list) {
       // Use ResourceTemplate for templated URIs
       const template = new ResourceTemplate(resourceDef.uri, {
-        list: async () => {
+        list: async (extra?: any) => {
           const context = (sdkServer as any)._currentContext || { userId: 'anonymous' };
-          const resources = await resourceDef.list!(context);
+          
+          // Extract pagination options from extra metadata
+          const options: any = {};
+          const meta = extra?._meta as any;
+          if (meta?.page || meta?.limit || meta?.cursor) {
+            options.pagination = {
+              page: meta.page ? parseInt(String(meta.page), 10) : undefined,
+              limit: meta.limit ? parseInt(String(meta.limit), 10) : undefined,
+              cursor: meta.cursor,
+            };
+          }
+          
+          const result = await resourceDef.list!(context, options);
+
+          // Handle both array and paginated responses
+          const resources = Array.isArray(result) ? result : result.resources;
+          const pagination = Array.isArray(result) ? undefined : result.pagination;
 
           // Map to MCP SDK Resource format with index signature
-          return {
+          const response: any = {
             resources: resources.map((r: any) => ({
               uri: r.uri,
               name: r.name,
@@ -270,6 +288,13 @@ export function createMCPServer(config: MCPServerConfig): MCPServer {
               ...r, // Spread to add index signature
             })),
           };
+          
+          // Add pagination metadata if present
+          if (pagination) {
+            response._meta = { pagination };
+          }
+          
+          return response;
         },
       });
       sdkServer.registerResource(
@@ -279,9 +304,21 @@ export function createMCPServer(config: MCPServerConfig): MCPServer {
           description: resourceDef.description,
           mimeType: resourceDef.mimeType || 'application/json',
         },
-        async (uri: any, _variables: any, _extra: any) => {
+        async (uri, _variables, _extra) => {
           const context = (sdkServer as any)._currentContext || { userId: 'anonymous' };
-          const result = await resourceDef.read(uri.href, { ...context, ...(_variables || {}) });
+          
+          // Extract pagination options from _extra metadata
+          const options: any = {};
+          const meta = _extra?._meta as any;
+          if (meta?.page || meta?.limit || meta?.cursor) {
+            options.pagination = {
+              page: meta.page ? parseInt(String(meta.page), 10) : undefined,
+              limit: meta.limit ? parseInt(String(meta.limit), 10) : undefined,
+              cursor: meta.cursor,
+            };
+          }
+          
+          const result = await resourceDef.read(uri.href, { ...context, ...(_variables || {}) }, options);
 
           const metadata =
             result.metadata ||
@@ -311,6 +348,11 @@ export function createMCPServer(config: MCPServerConfig): MCPServer {
           if (metadata) {
             response.metadata = metadata;
           }
+          
+          // Add pagination metadata if present
+          if (result.pagination) {
+            response._meta = { pagination: result.pagination };
+          }
 
           return response;
         }
@@ -326,7 +368,19 @@ export function createMCPServer(config: MCPServerConfig): MCPServer {
         },
         async (uri: any, _extra: any) => {
           const context = (sdkServer as any)._currentContext || { userId: 'anonymous' };
-          const result = await resourceDef.read(uri.href, context);
+          
+          // Extract pagination options from _extra metadata
+          const options: any = {};
+          const meta = _extra?._meta as any;
+          if (meta?.page || meta?.limit || meta?.cursor) {
+            options.pagination = {
+              page: meta.page ? parseInt(String(meta.page), 10) : undefined,
+              limit: meta.limit ? parseInt(String(meta.limit), 10) : undefined,
+              cursor: meta.cursor,
+            };
+          }
+          
+          const result = await resourceDef.read(uri.href, context, options);
 
           const metadata =
             result.metadata ||
@@ -356,6 +410,11 @@ export function createMCPServer(config: MCPServerConfig): MCPServer {
           if (metadata) {
             response.metadata = metadata;
           }
+          
+          // Add pagination metadata if present
+          if (result.pagination) {
+            response._meta = { pagination: result.pagination };
+          }
 
           return response;
         }
@@ -366,19 +425,43 @@ export function createMCPServer(config: MCPServerConfig): MCPServer {
   // Register prompts with MCP SDK
   if (config.prompts) {
     config.prompts.forEach((promptDef) => {
+      const argsSchema: Record<string, any> = {};
+      
+      // Build args schema with completion support
+      if (promptDef.arguments) {
+        promptDef.arguments.forEach((arg) => {
+          let argSchema = z.string();
+          
+          // Add completion support if handler is provided
+          if (promptDef.completion) {
+            argSchema = completable(z.string(), async (value, context) => {
+              const ctx = (sdkServer as any)._currentContext || { userId: 'anonymous' };
+              const ref = {
+                type: 'ref/prompt' as const,
+                name: promptDef.name,
+                arguments: context?.arguments || {},
+              };
+              
+              try {
+                const completions = await promptDef.completion!(ref, arg.name, ctx);
+                return completions.map(c => c.value);
+              } catch (error) {
+                logger.error('Completion error', { error });
+                return [];
+              }
+            }) as any;
+          }
+          
+          argsSchema[arg.name] = argSchema;
+        });
+      }
+
       sdkServer.registerPrompt(
         promptDef.name,
         {
           title: promptDef.name,
           description: promptDef.description,
-          argsSchema:
-            promptDef.arguments?.reduce(
-              (schema, arg) => {
-                schema[arg.name] = z.string();
-                return schema;
-              },
-              {} as Record<string, any>
-            ) || {},
+          argsSchema,
         },
         async (args: any) => {
           const context = (sdkServer as any)._currentContext || { userId: 'anonymous' };

package/src/types/index.ts

@@ -197,9 +197,33 @@ export interface ResourceListItem {
 /**
  * Resource read result
  */
+/**
+ * Pagination metadata for responses
+ */
+export interface PaginationMetadata {
+  page: number;
+  limit: number;
+  total?: number;
+  hasMore?: boolean;
+  nextCursor?: string;
+  prevCursor?: string;
+}
+
+/**
+ * Resource read result with optional pagination
+ */
 export interface ResourceReadResult<TData = any> {
   contents: TData;
   metadata?: ResourceMetadata;
+  pagination?: PaginationMetadata;
+}
+
+/**
+ * Resource list result with optional pagination
+ */
+export interface ResourceListResult {
+  resources: ResourceListItem[];
+  pagination?: PaginationMetadata;
 }
 
 /**
@@ -209,6 +233,7 @@ export interface ResourceReadOptions {
   pagination?: {
     page?: number;
     limit?: number;
+    cursor?: string;
   };
 }
 
@@ -280,11 +305,52 @@ export interface ResourceDefinition<TData = any> {
     options?: ResourceReadOptions
   ) => Promise<ResourceReadResult<TData>>;
 
-  list?: (context: AuthContext) => Promise<ResourceListItem[]>;
+  list?: (
+    context: AuthContext,
+    options?: ResourceReadOptions
+  ) => Promise<ResourceListResult | ResourceListItem[]>;
 
   subscription?: ResourceSubscription;
+  
+  /**
+   * Optional completion handler for resource URI parameters
+   */
+  completion?: CompletionHandler;
 }
 
+/**
+ * Completion item returned by completion handlers
+ */
+export interface CompletionItem {
+  value: string;
+  label?: string;
+  description?: string;
+  type?: 'value' | 'function' | 'variable' | 'constant' | 'other';
+}
+
+/**
+ * Completion reference - identifies what to complete
+ */
+export type CompletionRef =
+  | {
+      type: 'ref/prompt';
+      name: string;
+      arguments?: Record<string, string>;
+    }
+  | {
+      type: 'ref/resource';
+      uri: string;
+    };
+
+/**
+ * Completion handler function
+ */
+export type CompletionHandler = (
+  ref: CompletionRef,
+  argument: string,
+  context: AuthContext
+) => Promise<CompletionItem[]>;
+
 /**
  * Prompt definition
  */
@@ -302,6 +368,10 @@ export interface PromptDefinition {
       content: string;
     }>;
   }>;
+  /**
+   * Optional completion handler for prompt arguments
+   */
+  completion?: CompletionHandler;
 }
 
 /**
@@ -391,6 +461,9 @@ export interface MCPServerConfig {
   tools: ToolDefinition[];
   resources: ResourceDefinition[];
   prompts?: PromptDefinition[];
+  
+  // Completions
+  completions?: CompletionHandler;
 
   // Storage
   store: KeyValueStore;