mcp-http-webhook 1.0.6 → 1.0.7

package/COMPLETION_IMPLEMENTATION.md

@@ -0,0 +1,280 @@
+# MCP Completion Support Implementation
+
+## Summary
+
+Implemented comprehensive completion (autocomplete) support for MCP resources and prompts. Completions provide intelligent suggestions for prompt arguments and resource URI parameters, enabling better user experience in MCP clients.
+
+## Changes Made
+
+### 1. Type Definitions (`src/types/index.ts`)
+
+#### Added New Types:
+
+- **`CompletionItem`**: Individual completion suggestion
+  - `value`: The actual value to use
+  - `label`: Optional display label
+  - `description`: Optional description
+  - `type`: Type hint (value, function, variable, constant, other)
+
+- **`CompletionRef`**: Reference to what's being completed
+  - Prompt reference: `{ type: 'ref/prompt', name, arguments }`
+  - Resource reference: `{ type: 'ref/resource', uri }`
+
+- **`CompletionHandler`**: Function signature for completion handlers
+  ```typescript
+  (ref: CompletionRef, argument: string, context: AuthContext) => Promise<CompletionItem[]>
+  ```
+
+#### Updated Types:
+
+- **`PromptDefinition`**: Added optional `completion` handler
+- **`ResourceDefinition`**: Added optional `completion` handler  
+- **`MCPServerConfig`**: Added optional global `completions` handler
+
+### 2. Server Implementation (`src/server.ts`)
+
+#### Imports:
+- Added `completable` from `@modelcontextprotocol/sdk/server/completable.js`
+
+#### Prompt Registration:
+- Wraps prompt argument schemas with `completable()` when completion handler is provided
+- Completion callback receives:
+  - Current argument value
+  - Context with other argument values (for context-aware suggestions)
+- Returns array of completion values
+
+#### Completion Flow:
+1. Client requests completions for a specific argument
+2. Server identifies the relevant completion handler:
+   - Prompt-specific handler
+   - Resource-specific handler
+   - Global fallback handler
+3. Handler returns suggestions based on:
+   - Current partial value
+   - Other argument values (context)
+   - User authentication context
+4. Server formats and returns completion items
+
+### 3. Documentation
+
+#### Updated README.md:
+- Added **Completions** section with:
+  - Prompt completion example (context-aware)
+  - Resource URI completion example (hierarchical)
+  - Global completion handler example
+  - Reference to example file
+
+### 4. Examples
+
+Created `examples/completion-example.ts` demonstrating:
+
+1. **Prompt Argument Completion**:
+   - Language selection → suggests: python, javascript, typescript, etc.
+   - Framework selection → context-aware based on language
+   - Feature selection → common features
+
+2. **Resource URI Completion**:
+   - Owner parameter → suggests GitHub organizations
+   - Repo parameter → filtered by selected owner
+   - Hierarchical completion
+
+3. **Global Completion Handler**:
+   - Fallback for arguments without specific handlers
+   - Provides default suggestions
+
+## Usage
+
+### Prompt with Completion
+
+```typescript
+const promptDef: PromptDefinition = {
+  name: 'generate-code',
+  arguments: [
+    { name: 'language', required: true },
+    { name: 'framework', required: false }
+  ],
+  
+  handler: async (args, context) => {
+    // Generate code based on args
+    return { messages: [...] };
+  },
+  
+  completion: async (ref, argument, context) => {
+    if (argument === 'language') {
+      return [
+        { value: 'python', label: 'Python' },
+        { value: 'javascript', label: 'JavaScript' }
+      ];
+    }
+    
+    // Context-aware: framework based on language
+    if (argument === 'framework' && ref.arguments?.language) {
+      const lang = ref.arguments.language;
+      return getFrameworksForLanguage(lang);
+    }
+    
+    return [];
+  }
+};
+```
+
+### Resource with Completion
+
+```typescript
+const resourceDef: ResourceDefinition = {
+  uri: 'github://repos/{owner}/{repo}',
+  name: 'github-repos',
+  
+  read: async (uri, context) => { /* ... */ },
+  
+  completion: async (ref, argument, context) => {
+    if (argument === 'owner') {
+      return await fetchGitHubOrganizations();
+    }
+    
+    if (argument === 'repo') {
+      // Extract owner from current URI
+      const owner = ref.uri.match(/repos\/([^/]+)/)?.[1];
+      return await fetchReposForOwner(owner);
+    }
+    
+    return [];
+  }
+};
+```
+
+### Global Completion Handler
+
+```typescript
+createMCPServer({
+  // ... other config
+  completions: async (ref, argument, context) => {
+    // Fallback for any argument without specific handler
+    if (ref.type === 'ref/prompt') {
+      return getPromptCompletions(ref.name, argument);
+    }
+    if (ref.type === 'ref/resource') {
+      return getResourceCompletions(ref.uri, argument);
+    }
+    return [];
+  }
+});
+```
+
+## Client Request/Response
+
+### Request Completions
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "completion/complete",
+  "params": {
+    "ref": {
+      "type": "ref/prompt",
+      "name": "generate-code",
+      "arguments": {
+        "language": "python"
+      }
+    },
+    "argument": {
+      "name": "framework",
+      "value": "fla"
+    }
+  }
+}
+```
+
+### Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "result": {
+    "completion": {
+      "values": ["flask", "fastapi"],
+      "total": 2,
+      "hasMore": false
+    }
+  }
+}
+```
+
+## Key Features
+
+### 1. Context-Aware Completions
+- Suggestions based on other argument values
+- Example: Framework suggestions filtered by selected language
+
+### 2. Hierarchical Completions
+- Step-by-step suggestions for complex URIs
+- Example: Owner → Repo → Branch
+
+### 3. Async Data Sources
+- Completion handlers can fetch from databases/APIs
+- Supports dynamic, real-time suggestions
+
+### 4. Type Safety
+- Full TypeScript support
+- Strongly typed completion items and handlers
+
+### 5. Fallback Support
+- Global handler for arguments without specific handlers
+- Prevents empty completion lists
+
+### 6. Performance Optimized
+- Completions use Zod's completable wrapper
+- Efficient MCP SDK integration
+
+## Best Practices
+
+1. **Fast Handlers**: Keep completion handlers under 100ms for good UX
+2. **Context-Aware**: Use `ref.arguments` to provide relevant suggestions
+3. **Caching**: Cache frequent completions (e.g., language lists)
+4. **Fuzzy Matching**: Implement fuzzy search for better matches
+5. **Async Loading**: Fetch suggestions from APIs/databases as needed
+6. **Graceful Fallback**: Always return empty array instead of throwing errors
+7. **Rich Metadata**: Include labels and descriptions for better UX
+8. **Hierarchical Flow**: For nested parameters, complete in logical order
+
+## Examples of Use Cases
+
+1. **Code Generation**: Language → Framework → Library completions
+2. **File Browsers**: Drive → Folder → File hierarchical completion
+3. **Database Queries**: Database → Schema → Table → Column completion
+4. **API Endpoints**: Service → Resource → Method completion
+5. **Git Operations**: Remote → Branch → Commit completion
+6. **Cloud Resources**: Provider → Region → Resource type completion
+
+## Integration with MCP SDK
+
+- Uses `completable()` wrapper from `@modelcontextprotocol/sdk`
+- Integrates seamlessly with Zod schemas
+- Compatible with all MCP clients that support completions capability
+- Follows official MCP completion protocol
+
+## Files Modified
+
+- `src/types/index.ts` - Type definitions for completions
+- `src/server.ts` - Server-side completion implementation
+- `README.md` - Documentation
+- `examples/completion-example.ts` - Comprehensive examples (NEW)
+
+## Testing
+
+Build successful:
+```bash
+cd packages/plugins/mcp-proxy
+npm run build  # ✓ No errors
+```
+
+## Next Steps
+
+Consider:
+1. Add fuzzy matching library for better user experience
+2. Implement completion result caching
+3. Add completion metrics/analytics
+4. Support for completion pagination (for large result sets)
+5. Add completion templates/presets
+6. Integration tests with MCP clients
+7. Performance benchmarks for completion handlers

package/PAGINATION_IMPLEMENTATION.md

@@ -0,0 +1,221 @@
+# MCP Resources Pagination Implementation
+
+## Summary
+
+Implemented comprehensive pagination support for MCP (Model Context Protocol) resources in the `mcp-proxy` package. Both `list()` and `read()` operations now support offset-based and cursor-based pagination.
+
+## Changes Made
+
+### 1. Type Definitions (`src/types/index.ts`)
+
+#### Added New Types:
+- **`PaginationMetadata`**: Response metadata for paginated results
+  - `page`: Current page number
+  - `limit`: Items per page
+  - `total`: Total number of items (optional)
+  - `hasMore`: Whether more items exist
+  - `nextCursor`: Token for next page (cursor-based)
+  - `prevCursor`: Token for previous page (cursor-based)
+
+- **`ResourceListResult`**: New return type for paginated list operations
+  - `resources`: Array of resource items
+  - `pagination`: Optional pagination metadata
+
+#### Updated Types:
+- **`ResourceReadOptions`**: Added `cursor` field to pagination options
+  ```typescript
+  pagination?: {
+    page?: number;
+    limit?: number;
+    cursor?: string;  // NEW
+  }
+  ```
+
+- **`ResourceReadResult`**: Added optional pagination metadata
+  ```typescript
+  pagination?: PaginationMetadata;  // NEW
+  ```
+
+- **`ResourceDefinition`**: Updated signatures
+  - `list()`: Now accepts `options?: ResourceReadOptions` parameter
+  - `list()`: Can return `ResourceListResult` (with pagination) or `ResourceListItem[]` (backward compatible)
+
+### 2. Server Implementation (`src/server.ts`)
+
+#### Templated Resources (line ~258):
+- Extract pagination params from `extra?._meta`
+- Pass options to `list()` handler
+- Handle both array and paginated responses
+- Add `_meta.pagination` to response when present
+
+#### Resource Read Handlers (lines ~311, ~370):
+- Extract pagination params from `_extra?._meta`
+- Pass options to `read()` handler
+- Include pagination metadata in response via `_meta.pagination`
+
+### 3. Documentation
+
+#### Updated README.md:
+- Added dedicated **Pagination** section with:
+  - Client request format
+  - Server implementation examples
+  - Response format
+  - Reference to examples
+
+#### Updated Resource Examples:
+- Modified basic resource example to show pagination usage
+- Demonstrated both `list()` and `read()` pagination
+
+### 4. Examples
+
+Created `examples/pagination-example.ts` demonstrating:
+1. **Offset-based pagination** in `list()`:
+   - Page/limit parameters
+   - Total count and hasMore flags
+   
+2. **Paginated read** for large content:
+   - Useful for logs, large documents
+   - Same pagination approach as list
+
+3. **Cursor-based pagination**:
+   - Next/previous cursor tokens
+   - Better for real-time/streaming data
+   - Handles dynamic datasets
+
+### 5. Tests
+
+Created `src/__tests__/pagination.test.ts` covering:
+- Default pagination behavior
+- Custom page/limit parameters
+- Last page detection (hasMore: false)
+- Cursor-based navigation
+- Backward compatibility (non-paginated resources)
+
+## Usage
+
+### Client Request Format
+
+```typescript
+{
+  "jsonrpc": "2.0",
+  "method": "resources/list",
+  "params": {},
+  "_meta": {
+    "page": 1,
+    "limit": 10,
+    "cursor": "optional-token"
+  }
+}
+```
+
+### Server Implementation
+
+```typescript
+const resource: ResourceDefinition = {
+  uri: 'items://list',
+  name: 'items',
+  description: 'Items with pagination',
+  
+  list: async (context, options) => {
+    const page = options?.pagination?.page || 1;
+    const limit = options?.pagination?.limit || 10;
+    
+    // Fetch paginated data
+    const items = await fetchItems(page, limit);
+    const total = await countItems();
+    
+    return {
+      resources: items.map(toResource),
+      pagination: {
+        page,
+        limit,
+        total,
+        hasMore: page * limit < total,
+      }
+    };
+  },
+  
+  read: async (uri, context, options) => {
+    const cursor = options?.pagination?.cursor;
+    const limit = options?.pagination?.limit || 50;
+    
+    const data = await fetchWithCursor(cursor, limit);
+    
+    return {
+      contents: data.items,
+      pagination: {
+        page: 1,
+        limit,
+        hasMore: data.hasMore,
+        nextCursor: data.nextCursor,
+      }
+    };
+  }
+};
+```
+
+### Response Format
+
+```json
+{
+  "jsonrpc": "2.0",
+  "result": {
+    "resources": [...],
+    "_meta": {
+      "pagination": {
+        "page": 1,
+        "limit": 10,
+        "total": 100,
+        "hasMore": true,
+        "nextCursor": "token-123",
+        "prevCursor": "token-122"
+      }
+    }
+  }
+}
+```
+
+## Backward Compatibility
+
+✅ **Fully backward compatible**:
+- Pagination is optional - resources can omit it
+- `list()` can return array or paginated result
+- `read()` can omit pagination metadata
+- Old resources continue to work without changes
+
+## Best Practices
+
+1. **Default Values**: Always provide sensible defaults (e.g., page=1, limit=10)
+2. **Maximum Limits**: Set upper bounds to prevent abuse (e.g., max 100 items)
+3. **Total Count**: Include when feasible for better UX
+4. **hasMore Flag**: Always indicate if more data exists
+5. **Cursor vs Offset**: Use cursors for real-time/dynamic data, offsets for stable datasets
+6. **Caching**: Consider caching frequently accessed pages
+7. **Documentation**: Document pagination support in resource descriptions
+
+## Files Modified
+
+- `src/types/index.ts` - Type definitions
+- `src/server.ts` - Server implementation
+- `README.md` - Documentation
+- `examples/pagination-example.ts` - Comprehensive examples (NEW)
+- `src/__tests__/pagination.test.ts` - Test suite (NEW)
+
+## Testing
+
+Build successful:
+```bash
+cd packages/plugins/mcp-proxy
+npm run build  # ✓ No errors
+```
+
+All type checking passes with no compilation errors.
+
+## Next Steps
+
+Consider:
+1. Add integration tests with real MCP clients
+2. Add metrics/monitoring for pagination usage
+3. Implement page size limits per resource
+4. Add pagination presets (small/medium/large)
+5. Support for GraphQL-style pagination (edges/nodes)

package/README.md

@@ -179,14 +179,38 @@ Resources represent data that can be read and subscribed to:
   name: 'GitHub Issues',
   description: 'Repository issues',
   
-  read: async (uri, context) => {
-    return { contents: [...] };
+  read: async (uri, context, options) => {
+    // Access pagination options
+    const page = options?.pagination?.page || 1;
+    const limit = options?.pagination?.limit || 10;
+    
+    return { 
+      contents: [...],
+      pagination: {
+        page,
+        limit,
+        total: 100,
+        hasMore: true
+      }
+    };
   },
   
-  list: async (context) => {
-    return [
-      { uri: '...', name: '...' }
-    ];
+  list: async (context, options) => {
+    // Pagination support in list
+    const page = options?.pagination?.page || 1;
+    const limit = options?.pagination?.limit || 10;
+    
+    return {
+      resources: [
+        { uri: '...', name: '...' }
+      ],
+      pagination: {
+        page,
+        limit,
+        total: 50,
+        hasMore: true
+      }
+    };
   },
   
   subscription: {
@@ -242,6 +266,170 @@ class MyStore implements KeyValueStore {
 }
 ```
 
+### Pagination
+
+Resources support pagination for both `list()` and `read()` operations:
+
+**Client Request:**
+```typescript
+// Send pagination params in _meta
+{
+  "jsonrpc": "2.0",
+  "method": "resources/list",
+  "params": {},
+  "_meta": {
+    "page": 1,
+    "limit": 10,
+    "cursor": "optional-cursor"
+  }
+}
+```
+
+**Server Implementation:**
+```typescript
+{
+  list: async (context, options) => {
+    const page = options?.pagination?.page || 1;
+    const limit = options?.pagination?.limit || 10;
+    
+    // Fetch paginated data
+    const { items, total } = await fetchItems(page, limit);
+    
+    return {
+      resources: items,
+      pagination: {
+        page,
+        limit,
+        total,
+        hasMore: page * limit < total,
+        nextCursor: 'next-page-token', // Optional
+      }
+    };
+  },
+  
+  read: async (uri, context, options) => {
+    // Pagination also works for large content in read()
+    const cursor = options?.pagination?.cursor;
+    const limit = options?.pagination?.limit || 50;
+    
+    return {
+      contents: paginatedData,
+      pagination: {
+        page: 1,
+        limit,
+        hasMore: true,
+        nextCursor: 'token-for-next-page',
+      }
+    };
+  }
+}
+```
+
+**Response Format:**
+```json
+{
+  "resources": [...],
+  "_meta": {
+    "pagination": {
+      "page": 1,
+      "limit": 10,
+      "total": 100,
+      "hasMore": true,
+      "nextCursor": "...",
+      "prevCursor": "..."
+    }
+  }
+}
+```
+
+See [examples/pagination-example.ts](./examples/pagination-example.ts) for complete examples including cursor-based pagination.
+
+### Completions
+
+Completions provide autocomplete suggestions for prompt arguments and resource URI parameters:
+
+**Prompt with Completion:**
+
+```typescript
+{
+  name: 'generate-code',
+  arguments: [
+    { name: 'language', required: true },
+    { name: 'framework', required: false }
+  ],
+  handler: async (args, context) => { /* ... */ },
+  
+  // Completion handler for arguments
+  completion: async (ref, argument, context) => {
+    if (argument === 'language') {
+      return [
+        { value: 'python', label: 'Python' },
+        { value: 'javascript', label: 'JavaScript' },
+        { value: 'typescript', label: 'TypeScript' }
+      ];
+    }
+    
+    // Context-aware: suggest frameworks based on language
+    if (argument === 'framework') {
+      const lang = ref.arguments?.language;
+      if (lang === 'python') {
+        return [
+          { value: 'django', label: 'Django' },
+          { value: 'flask', label: 'Flask' }
+        ];
+      }
+    }
+    
+    return [];
+  }
+}
+```
+
+**Resource with Completion:**
+
+```typescript
+{
+  uri: 'github://repos/{owner}/{repo}',
+  name: 'github-repos',
+  /* ... */
+  
+  // Completion for URI parameters
+  completion: async (ref, argument, context) => {
+    if (argument === 'owner') {
+      return [
+        { value: 'facebook', label: 'Facebook' },
+        { value: 'microsoft', label: 'Microsoft' }
+      ];
+    }
+    
+    if (argument === 'repo') {
+      // Get owner from current URI
+      const owner = ref.uri.match(/repos\/([^/]+)/)?.[1];
+      // Return repos for that owner
+      return fetchReposForOwner(owner);
+    }
+    
+    return [];
+  }
+}
+```
+
+**Global Completion Handler:**
+
+```typescript
+createMCPServer({
+  // ...
+  completions: async (ref, argument, context) => {
+    // Fallback for any prompt/resource without specific handler
+    return [
+      { value: 'default', label: 'Default Value' }
+    ];
+  }
+});
+```
+
+See [examples/completion-example.ts](./examples/completion-example.ts) for comprehensive completion examples.
+
 ### Authentication
 
 ```typescript

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAiD,MAAM,SAAS,CAAC;AAkKpG;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAogBlE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAiD,MAAM,SAAS,CAAC;AAkKpG;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAslBlE"}