mcp-http-webhook 1.0.5 → 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,7 +2,8 @@ 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 { MCPServerConfig, MCPServer, Logger, JSONSchema } from './types';
+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';
 import { MCPError, AuthenticationError, ValidationError } from './errors';
@@ -69,6 +70,101 @@ function convertToZodSchema(jsonSchema: JSONSchema): Record<string, z.ZodTypeAny
   return schema;
 }
 
+const VALID_CREDENTIAL_FIELD_TYPES = new Set([
+  'string',
+  'number',
+  'boolean',
+  'object',
+  'array',
+  'date',
+  'file',
+  'binary',
+]);
+
+function sanitizeCredentialFields(
+  fields: unknown,
+  path = 'credentials'
+): CredentialFieldDefinition[] {
+  if (fields === undefined || fields === null) {
+    return [];
+  }
+
+  if (!Array.isArray(fields)) {
+    throw new ValidationError(`MCP configuration ${path} must be an array`);
+  }
+
+  return fields.map((field, index) =>
+    sanitizeCredentialField(field, `${path}[${index}]`)
+  );
+}
+
+function sanitizeCredentialField(
+  field: unknown,
+  path: string
+): CredentialFieldDefinition {
+  if (typeof field !== 'object' || field === null) {
+    throw new ValidationError(`MCP configuration ${path} must be an object`);
+  }
+
+  const candidate = field as Record<string, any>;
+  const rawName = candidate.name;
+  const name = typeof rawName === 'string' ? rawName.trim() : '';
+
+  if (!name) {
+    throw new ValidationError(`MCP configuration ${path}.name is required`);
+  }
+
+  const rawType = typeof candidate.type === 'string'
+    ? candidate.type.toLowerCase()
+    : 'string';
+  const type = (VALID_CREDENTIAL_FIELD_TYPES.has(rawType)
+    ? rawType
+    : 'string') as CredentialFieldDefinition['type'];
+
+  const description =
+    typeof candidate.description === 'string' && candidate.description.trim().length > 0
+      ? candidate.description
+      : undefined;
+
+  const sanitized: CredentialFieldDefinition = {
+    name,
+    type,
+    required: Boolean(candidate.required),
+  };
+
+  if (description) {
+    sanitized.description = description;
+  }
+
+  if (candidate.default !== undefined) {
+    sanitized.default = candidate.default;
+  }
+
+  if (Array.isArray(candidate.innerFields) && candidate.innerFields.length > 0) {
+    const inner = sanitizeCredentialFields(candidate.innerFields, `${path}.innerFields`);
+    if (inner.length > 0) {
+      sanitized.innerFields = inner;
+    }
+  }
+
+  if (Array.isArray(candidate.or) && candidate.or.length > 0) {
+    const alternatives = sanitizeCredentialFields(candidate.or, `${path}.or`);
+    if (alternatives.length > 0) {
+      sanitized.or = alternatives;
+    }
+  }
+
+  if (candidate.config && typeof candidate.config === 'object') {
+    sanitized.config = { ...candidate.config };
+  }
+
+  if (candidate.metadata && typeof candidate.metadata === 'object') {
+    sanitized.metadata = { ...candidate.metadata };
+  }
+
+  return sanitized;
+}
+
 /**
  * Create MCP HTTP Webhook Server using standard MCP SDK
  */
@@ -80,6 +176,8 @@ export function createMCPServer(config: MCPServerConfig): MCPServer {
 
   // Validate configuration
   validateConfig(config);
+  // Validate credential metadata upfront to surface configuration issues early
+  sanitizeCredentialFields(config.credentials);
 
   // Create Express app
   const app: Express = express();
@@ -108,6 +206,7 @@ export function createMCPServer(config: MCPServerConfig): MCPServer {
         experimental: {
           isConnector: true,
         },
+        "completions": {}
       },
     }
   );
@@ -158,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,
@@ -173,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(
@@ -182,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 ||
@@ -214,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;
         }
@@ -229,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 ||
@@ -259,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;
         }
@@ -269,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' };
@@ -481,6 +661,14 @@ export function createMCPServer(config: MCPServerConfig): MCPServer {
     })
   );
 
+  app.get(`${basePath}/.well-known/credentials`, asyncHandler(async (req, res) => {
+    const credentials = sanitizeCredentialFields(config.credentials);
+    res.json({
+      version: config.version,
+      credentials,
+    });
+  }));
+
   // Webhook endpoints
   const webhookPath = config.webhooks?.incomingPath || '/webhooks/incoming';