mcp-http-webhook 1.0.6 → 1.0.7

package/examples/completion-example.ts

@@ -0,0 +1,339 @@
+import { createMCPServer, InMemoryStore, PromptDefinition, ResourceDefinition, CompletionRef, AuthContext } from '../src';
+
+/**
+ * Example: Completion Support for Prompts and Resources
+ * 
+ * This example demonstrates how to implement autocomplete/completion
+ * for prompt arguments and resource URI parameters in MCP.
+ */
+
+// Mock data for completion suggestions
+const availableLanguages = ['python', 'javascript', 'typescript', 'java', 'go', 'rust'];
+const availableFrameworks = {
+  python: ['django', 'flask', 'fastapi'],
+  javascript: ['express', 'nestjs', 'koa'],
+  typescript: ['express', 'nestjs', 'nest'],
+  java: ['spring', 'quarkus', 'micronaut'],
+  go: ['gin', 'echo', 'fiber'],
+  rust: ['actix', 'rocket', 'axum'],
+};
+
+const repositories = [
+  { owner: 'facebook', name: 'react', description: 'A JavaScript library for building user interfaces' },
+  { owner: 'microsoft', name: 'typescript', description: 'TypeScript is a superset of JavaScript' },
+  { owner: 'nodejs', name: 'node', description: 'Node.js JavaScript runtime' },
+  { owner: 'denoland', name: 'deno', description: 'A modern runtime for JavaScript and TypeScript' },
+];
+
+// Example 1: Prompt with Completion Support
+const codeGeneratorPrompt: PromptDefinition = {
+  name: 'generate-code',
+  description: 'Generate code based on language and framework',
+  arguments: [
+    {
+      name: 'language',
+      description: 'Programming language',
+      required: true,
+    },
+    {
+      name: 'framework',
+      description: 'Framework to use',
+      required: false,
+    },
+    {
+      name: 'feature',
+      description: 'Feature to implement',
+      required: true,
+    },
+  ],
+
+  handler: async (args: Record<string, any>, context: AuthContext) => {
+    const { language, framework, feature } = args;
+    
+    return {
+      messages: [
+        {
+          role: 'user' as const,
+          content: `Generate ${language}${framework ? ` ${framework}` : ''} code for: ${feature}`,
+        },
+        {
+          role: 'assistant' as const,
+          content: `Here's a ${language}${framework ? ` ${framework}` : ''} implementation for ${feature}...`,
+        },
+      ],
+    };
+  },
+
+  // Completion handler for prompt arguments
+  completion: async (ref: CompletionRef, argument: string, context: AuthContext) => {
+    if (ref.type !== 'ref/prompt') {
+      return [];
+    }
+
+    console.log(`Providing completions for argument: ${argument}`);
+
+    // Complete 'language' argument
+    if (argument === 'language') {
+      return availableLanguages.map(lang => ({
+        value: lang,
+        label: lang.charAt(0).toUpperCase() + lang.slice(1),
+        description: `Use ${lang} for code generation`,
+        type: 'value' as const,
+      }));
+    }
+
+    // Complete 'framework' argument (context-aware based on language)
+    if (argument === 'framework') {
+      const selectedLanguage = ref.arguments?.language;
+      if (selectedLanguage && selectedLanguage in availableFrameworks) {
+        const frameworks = availableFrameworks[selectedLanguage as keyof typeof availableFrameworks];
+        return frameworks.map(fw => ({
+          value: fw,
+          label: fw.charAt(0).toUpperCase() + fw.slice(1),
+          description: `${fw} framework for ${selectedLanguage}`,
+          type: 'value' as const,
+        }));
+      }
+      // If no language selected, show all frameworks
+      return Object.values(availableFrameworks)
+        .flat()
+        .filter((v, i, a) => a.indexOf(v) === i) // unique
+        .map(fw => ({
+          value: fw,
+          label: fw.charAt(0).toUpperCase() + fw.slice(1),
+          type: 'value' as const,
+        }));
+    }
+
+    // Complete 'feature' argument with common features
+    if (argument === 'feature') {
+      const commonFeatures = [
+        'REST API',
+        'Authentication',
+        'Database CRUD',
+        'File Upload',
+        'Websockets',
+        'Caching',
+      ];
+      return commonFeatures.map(feat => ({
+        value: feat,
+        label: feat,
+        description: `Implement ${feat}`,
+        type: 'value' as const,
+      }));
+    }
+
+    return [];
+  },
+};
+
+// Example 2: Resource with Completion for URI Parameters
+const githubResource: ResourceDefinition = {
+  uri: 'github://repos/{owner}/{repo}/issues',
+  name: 'github-issues',
+  description: 'GitHub repository issues',
+  mimeType: 'application/json',
+
+  list: async (context: AuthContext) => {
+    return {
+      resources: repositories.map(repo => ({
+        uri: `github://repos/${repo.owner}/${repo.name}/issues`,
+        name: `${repo.owner}/${repo.name} Issues`,
+        description: repo.description,
+      })),
+    };
+  },
+
+  read: async (uri: string, context: AuthContext) => {
+    const match = uri.match(/github:\/\/repos\/([^/]+)\/([^/]+)\/issues/);
+    if (!match) {
+      throw new Error('Invalid GitHub URI');
+    }
+
+    const [, owner, repo] = match;
+    
+    return {
+      contents: {
+        repository: `${owner}/${repo}`,
+        issues: [
+          { id: 1, title: 'Bug fix needed', state: 'open' },
+          { id: 2, title: 'Feature request', state: 'open' },
+        ],
+      },
+    };
+  },
+
+  // Completion handler for URI parameters
+  completion: async (ref: CompletionRef, argument: string, context: AuthContext) => {
+    if (ref.type !== 'ref/resource') {
+      return [];
+    }
+
+    console.log(`Providing resource completions for: ${ref.uri}, argument: ${argument}`);
+
+    // Extract current values from URI
+    const match = ref.uri.match(/github:\/\/repos\/([^/]*)\/([^/]*)/);
+    const currentOwner = match?.[1] || '';
+    const currentRepo = match?.[2] || '';
+
+    // Complete 'owner' parameter
+    if (argument === 'owner' || !currentOwner) {
+      const owners = [...new Set(repositories.map(r => r.owner))];
+      return owners.map(owner => ({
+        value: owner,
+        label: owner,
+        description: `GitHub user/organization: ${owner}`,
+        type: 'value' as const,
+      }));
+    }
+
+    // Complete 'repo' parameter (filtered by owner)
+    if (argument === 'repo' || !currentRepo) {
+      const filtered = currentOwner
+        ? repositories.filter(r => r.owner === currentOwner)
+        : repositories;
+      
+      return filtered.map(repo => ({
+        value: repo.name,
+        label: repo.name,
+        description: repo.description,
+        type: 'value' as const,
+      }));
+    }
+
+    return [];
+  },
+};
+
+// Example 3: Global Completion Handler
+// This provides completions for any prompt/resource that doesn't have its own handler
+async function globalCompletionHandler(
+  ref: CompletionRef,
+  argument: string,
+  context: AuthContext
+) {
+  console.log('Global completion handler called', { ref, argument });
+
+  // Provide generic suggestions
+  return [
+    {
+      value: 'default',
+      label: 'Default Value',
+      description: 'Use default value',
+      type: 'value' as const,
+    },
+    {
+      value: 'custom',
+      label: 'Custom Value',
+      description: 'Enter custom value',
+      type: 'value' as const,
+    },
+  ];
+}
+
+// Create and start the server
+async function main() {
+  const server = createMCPServer({
+    name: 'completion-example',
+    version: '1.0.0',
+    publicUrl: 'http://localhost:3000',
+    port: 3000,
+    
+    store: new InMemoryStore(),
+    
+    tools: [],
+    
+    prompts: [codeGeneratorPrompt],
+    
+    resources: [githubResource],
+    
+    // Global completion handler (optional, used as fallback)
+    completions: globalCompletionHandler,
+  });
+
+  await server.start();
+  console.log('🚀 Completion example server started!');
+  console.log('\nCompletion features:');
+  console.log('\n1. Prompt Argument Completion:');
+  console.log('   - Try typing in "language" field → suggests: python, javascript, typescript, etc.');
+  console.log('   - Try typing in "framework" field → context-aware suggestions based on selected language');
+  console.log('   - Try typing in "feature" field → suggests common features');
+  console.log('\n2. Resource URI Completion:');
+  console.log('   - Type github://repos/ → suggests owners: facebook, microsoft, nodejs, etc.');
+  console.log('   - Type github://repos/facebook/ → suggests repos: react');
+  console.log('   - Type github://repos/microsoft/ → suggests repos: typescript');
+  console.log('\n3. Global Fallback:');
+  console.log('   - Any argument without specific handler gets default suggestions');
+}
+
+/**
+ * USAGE NOTES:
+ * 
+ * CLIENT REQUEST FORMAT:
+ * 
+ * To request completions, clients send:
+ * {
+ *   "jsonrpc": "2.0",
+ *   "method": "completion/complete",
+ *   "params": {
+ *     "ref": {
+ *       "type": "ref/prompt",  // or "ref/resource"
+ *       "name": "generate-code",  // prompt name
+ *       "arguments": {  // current argument values (for context)
+ *         "language": "python"
+ *       }
+ *     },
+ *     "argument": {
+ *       "name": "framework",  // which argument to complete
+ *       "value": "fla"  // partial value typed so far
+ *     }
+ *   }
+ * }
+ * 
+ * COMPLETION RESPONSE:
+ * 
+ * Server responds with:
+ * {
+ *   "jsonrpc": "2.0",
+ *   "result": {
+ *     "completion": {
+ *       "values": [
+ *         "flask",
+ *         "fastapi"
+ *       ],
+ *       "total": 2,
+ *       "hasMore": false
+ *     }
+ *   }
+ * }
+ * 
+ * IMPLEMENTATION TIPS:
+ * 
+ * 1. **Context-Aware Completions**: Use ref.arguments to provide context-aware suggestions
+ *    (e.g., frameworks filtered by selected language)
+ * 
+ * 2. **Fuzzy Matching**: Implement fuzzy search for better user experience
+ *    (e.g., "ts" matches "typescript", "nestjs")
+ * 
+ * 3. **Async Data**: Completion handlers can be async, so you can fetch suggestions
+ *    from databases, APIs, or other sources
+ * 
+ * 4. **Caching**: Cache frequent completions to improve performance
+ * 
+ * 5. **Hierarchical**: For resources with nested parameters (like GitHub repos),
+ *    provide completions in order (owner first, then repos for that owner)
+ * 
+ * 6. **Performance**: Keep completion handlers fast (<100ms) for good UX
+ * 
+ * 7. **Fallback**: Use global completion handler for arguments without
+ *    specific handlers
+ * 
+ * 8. **Type Safety**: Use TypeScript types to ensure completion items
+ *    match the expected format
+ */
+
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+export { codeGeneratorPrompt, githubResource, globalCompletionHandler };

package/examples/pagination-example.ts

@@ -0,0 +1,261 @@
+import { createMCPServer, InMemoryStore, ResourceDefinition, PaginationMetadata } from '../src';
+
+/**
+ * Example: Pagination Support in MCP Resources
+ * 
+ * This example demonstrates how to implement pagination in both list() and read()
+ * methods for MCP resources. Pagination helps handle large datasets efficiently.
+ */
+
+// Mock data for demonstration
+const allItems = Array.from({ length: 100 }, (_, i) => ({
+  id: `item-${i + 1}`,
+  name: `Item ${i + 1}`,
+  description: `Description for item ${i + 1}`,
+  timestamp: Date.now() - i * 1000,
+}));
+
+// Helper function to paginate array data
+function paginateArray<T>(
+  items: T[],
+  page: number = 1,
+  limit: number = 10
+): { items: T[]; pagination: PaginationMetadata } {
+  const offset = (page - 1) * limit;
+  const paginatedItems = items.slice(offset, offset + limit);
+  
+  return {
+    items: paginatedItems,
+    pagination: {
+      page,
+      limit,
+      total: items.length,
+      hasMore: offset + limit < items.length,
+    },
+  };
+}
+
+// Example 1: Paginated List Resource
+const paginatedListResource: ResourceDefinition = {
+  uri: 'items://list',
+  name: 'items-list',
+  description: 'List of items with pagination support',
+  mimeType: 'application/json',
+
+  // List handler with pagination
+  list: async (context, options) => {
+    const page = options?.pagination?.page || 1;
+    const limit = options?.pagination?.limit || 10;
+
+    console.log(`Listing items: page=${page}, limit=${limit}`);
+
+    const { items, pagination } = paginateArray(allItems, page, limit);
+
+    return {
+      resources: items.map(item => ({
+        uri: `items://list/${item.id}`,
+        name: item.name,
+        description: item.description,
+      })),
+      pagination,
+    };
+  },
+
+  // Read handler (single item, no pagination needed)
+  read: async (uri, context) => {
+    const itemId = uri.split('/').pop();
+    const item = allItems.find(i => i.id === itemId);
+
+    if (!item) {
+      throw new Error(`Item not found: ${itemId}`);
+    }
+
+    return {
+      contents: item,
+    };
+  },
+};
+
+// Example 2: Paginated Read Resource (for large content)
+const paginatedReadResource: ResourceDefinition = {
+  uri: 'logs://stream/{streamId}',
+  name: 'log-stream',
+  description: 'Log stream with paginated read',
+  mimeType: 'text/plain',
+
+  list: async (context) => {
+    return {
+      resources: [
+        { uri: 'logs://stream/app-logs', name: 'Application Logs' },
+        { uri: 'logs://stream/error-logs', name: 'Error Logs' },
+        { uri: 'logs://stream/access-logs', name: 'Access Logs' },
+      ],
+    };
+  },
+
+  // Read handler with pagination for large log files
+  read: async (uri, context, options) => {
+    const streamId = uri.split('/').pop();
+    const page = options?.pagination?.page || 1;
+    const limit = options?.pagination?.limit || 50;
+
+    console.log(`Reading logs: stream=${streamId}, page=${page}, limit=${limit}`);
+
+    // Simulate fetching log lines
+    const allLogLines = Array.from(
+      { length: 500 },
+      (_, i) => `[${new Date(Date.now() - i * 1000).toISOString()}] Log entry ${i + 1}`
+    );
+
+    const { items: logLines, pagination } = paginateArray(allLogLines, page, limit);
+
+    return {
+      contents: logLines.join('\n'),
+      pagination,
+    };
+  },
+};
+
+// Example 3: Cursor-based Pagination (for real-time data)
+interface CursorData {
+  items: any[];
+  nextCursor?: string;
+  prevCursor?: string;
+}
+
+const cursorPaginatedResource: ResourceDefinition = {
+  uri: 'feed://updates',
+  name: 'updates-feed',
+  description: 'Real-time updates with cursor-based pagination',
+  mimeType: 'application/json',
+
+  list: async (context) => {
+    return {
+      resources: [
+        { uri: 'feed://updates', name: 'Updates Feed' },
+      ],
+    };
+  },
+
+  read: async (uri, context, options) => {
+    const cursor = options?.pagination?.cursor;
+    const limit = options?.pagination?.limit || 20;
+
+    console.log(`Reading feed: cursor=${cursor}, limit=${limit}`);
+
+    // In a real implementation, you would:
+    // 1. Decode the cursor to get the last seen item ID/timestamp
+    // 2. Query items after that cursor
+    // 3. Generate a new cursor for the next page
+
+    // Simulate cursor-based pagination
+    const cursorIndex = cursor ? parseInt(cursor, 10) : 0;
+    const feedItems = allItems.slice(cursorIndex, cursorIndex + limit);
+    
+    const hasMore = cursorIndex + limit < allItems.length;
+    const nextCursor = hasMore ? String(cursorIndex + limit) : undefined;
+    const prevCursor = cursorIndex > 0 ? String(Math.max(0, cursorIndex - limit)) : undefined;
+
+    return {
+      contents: feedItems,
+      pagination: {
+        page: 1, // Not used in cursor pagination
+        limit,
+        total: allItems.length,
+        hasMore,
+        nextCursor,
+        prevCursor,
+      },
+    };
+  },
+};
+
+// Create and start the server
+async function main() {
+  const server = createMCPServer({
+    name: 'pagination-example',
+    version: '1.0.0',
+    publicUrl: 'http://localhost:3000',
+    port: 3000,
+    
+    store: new InMemoryStore(),
+    
+    tools: [],
+    
+    resources: [
+      paginatedListResource,
+      paginatedReadResource,
+      cursorPaginatedResource,
+    ],
+  });
+
+  await server.start();
+  console.log('🚀 Pagination example server started!');
+  console.log('\nTry these requests:');
+  console.log('\n1. List items with pagination:');
+  console.log('   POST http://localhost:3000/mcp');
+  console.log('   Body: {"method": "resources/list", "_meta": {"page": 1, "limit": 5}}');
+  console.log('\n2. Read logs with pagination:');
+  console.log('   POST http://localhost:3000/mcp');
+  console.log('   Body: {"method": "resources/read", "params": {"uri": "logs://stream/app-logs"}, "_meta": {"page": 2, "limit": 10}}');
+  console.log('\n3. Feed with cursor pagination:');
+  console.log('   POST http://localhost:3000/mcp');
+  console.log('   Body: {"method": "resources/read", "params": {"uri": "feed://updates"}, "_meta": {"cursor": "20", "limit": 20}}');
+}
+
+// Usage notes:
+/**
+ * PAGINATION REQUEST FORMAT:
+ * 
+ * Clients should send pagination parameters in the _meta field:
+ * 
+ * {
+ *   "jsonrpc": "2.0",
+ *   "id": 1,
+ *   "method": "resources/list",
+ *   "params": {},
+ *   "_meta": {
+ *     "page": 1,      // Page number (1-based)
+ *     "limit": 10,    // Items per page
+ *     "cursor": "..."  // For cursor-based pagination
+ *   }
+ * }
+ * 
+ * PAGINATION RESPONSE FORMAT:
+ * 
+ * The response will include pagination metadata in _meta:
+ * 
+ * {
+ *   "jsonrpc": "2.0",
+ *   "id": 1,
+ *   "result": {
+ *     "resources": [...],
+ *     "_meta": {
+ *       "pagination": {
+ *         "page": 1,
+ *         "limit": 10,
+ *         "total": 100,
+ *         "hasMore": true,
+ *         "nextCursor": "...",
+ *         "prevCursor": "..."
+ *       }
+ *     }
+ *   }
+ * }
+ * 
+ * IMPLEMENTATION TIPS:
+ * 
+ * 1. Always provide sensible defaults (e.g., page=1, limit=10)
+ * 2. Set maximum limits to prevent abuse (e.g., max 100 items per page)
+ * 3. Return total count when possible (helps clients show "X of Y")
+ * 4. Use cursor-based pagination for real-time/streaming data
+ * 5. Use offset-based pagination for stable, sorted datasets
+ * 6. Include hasMore flag to indicate if more data is available
+ * 7. Consider caching paginated results for frequently accessed pages
+ */
+
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+export { paginatedListResource, paginatedReadResource, cursorPaginatedResource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-http-webhook",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Production-ready MCP server framework with HTTP + webhook-based subscriptions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -32,10 +32,10 @@
     "@ngrok/ngrok": "^1.5.2",
     "@octokit/rest": "^20.0.0",
     "cors": "^2.8.5",
+    "googleapis": "^144.0.0",
     "nanoid": "^5.0.0",
     "ngrok": "^4.3.3",
-    "zod": "^3.22.0",
-    "googleapis": "^144.0.0"
+    "zod": "^3.22.0"
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",
@@ -47,6 +47,7 @@
     "eslint": "^8.0.0",
     "jest": "^29.5.0",
     "prettier": "^3.0.0",
+    "supertest": "^7.1.4",
     "ts-jest": "^29.1.0",
     "typescript": "^5.0.0"
   },
@@ -54,4 +55,4 @@
     "ioredis": "^5.3.0",
     "prom-client": "^15.0.0"
   }
-}
+}