mcp-http-webhook 1.0.28 → 1.0.30

package/COMPLETION_IMPLEMENTATION.md

@@ -1,280 +0,0 @@
-# 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/CONTRIBUTING.md

@@ -1,136 +0,0 @@
-# Contributing to MCP HTTP Webhook
-
-Thank you for your interest in contributing! This document provides guidelines and instructions for contributing.
-
-## Development Setup
-
-1. **Fork and Clone**
-   ```bash
-   git clone https://github.com/your-username/mcp-http-webhook.git
-   cd mcp-http-webhook
-   ```
-
-2. **Install Dependencies**
-   ```bash
-   npm install
-   # or
-   pnpm install
-   ```
-
-3. **Build**
-   ```bash
-   npm run build
-   ```
-
-4. **Run Tests**
-   ```bash
-   npm test
-   ```
-
-## Code Style
-
-We use ESLint and Prettier for code formatting:
-
-```bash
-# Lint code
-npm run lint
-
-# Format code
-npm run format
-
-# Type check
-npm run type-check
-```
-
-### TypeScript Guidelines
-
-- Use explicit types for public APIs
-- Prefer `const` over `let`
-- Use async/await over promises
-- Document public APIs with JSDoc comments
-
-Example:
-
-```typescript
-/**
- * Creates a new MCP server instance
- * @param config - Server configuration
- * @returns Configured MCP server
- */
-export function createMCPServer(config: MCPServerConfig): MCPServer {
-  // ...
-}
-```
-
-## Testing
-
-- Write tests for all new features
-- Maintain >80% code coverage
-- Use descriptive test names
-
-```typescript
-describe('SubscriptionManager', () => {
-  it('should create a new subscription', async () => {
-    // Test implementation
-  });
-});
-```
-
-## Commit Messages
-
-We follow [Conventional Commits](https://www.conventionalcommits.org/):
-
-```bash
-feat: add webhook retry backoff configuration
-fix: resolve subscription cleanup race condition
-docs: update subscription flow diagram
-test: add tests for webhook signature verification
-chore: update dependencies
-```
-
-## Pull Request Process
-
-1. **Create a Branch**
-   ```bash
-   git checkout -b feature/my-new-feature
-   ```
-
-2. **Make Changes**
-   - Write code following style guidelines
-   - Add/update tests
-   - Update documentation
-
-3. **Run Quality Checks**
-   ```bash
-   npm run lint
-   npm run format
-   npm test
-   npm run type-check
-   ```
-
-4. **Commit Changes**
-   ```bash
-   git commit -m "feat: add my new feature"
-   ```
-
-5. **Push to Fork**
-   ```bash
-   git push origin feature/my-new-feature
-   ```
-
-6. **Create Pull Request**
-   - Provide clear description of changes
-   - Link related issues
-   - Include screenshots/examples if applicable
-
-## Code of Conduct
-
-This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
-
-## Questions?
-
-Feel free to open an issue or ask in our [Discord community](https://discord.gg/mcp-webhook).
-
-## License
-
-By contributing, you agree that your contributions will be licensed under the MIT License.

package/GETTING_STARTED.md

@@ -1,310 +0,0 @@
-# Getting Started with MCP HTTP Webhook
-
-This guide will help you create your first MCP HTTP server with webhook-based subscriptions.
-
-## Prerequisites
-
-- Node.js 18+ or 20+
-- npm, pnpm, or yarn
-- TypeScript knowledge
-
-## Step 1: Installation
-
-```bash
-cd packages/plugins/mcp-proxy
-npm install
-```
-
-## Step 2: Install Peer Dependencies
-
-```bash
-npm install @modelcontextprotocol/sdk express @types/express
-```
-
-## Step 3: Build the Library
-
-```bash
-npm run build
-```
-
-## Step 4: Create Your First Server
-
-Create a file `my-server.ts`:
-
-```typescript
-import { createMCPServer } from './src';
-import { InMemoryStore } from './src/stores';
-
-const server = createMCPServer({
-  name: 'my-first-server',
-  version: '1.0.0',
-  publicUrl: process.env.PUBLIC_URL || 'http://localhost:3000',
-  port: 3000,
-  store: new InMemoryStore(),
-
-  tools: [
-    {
-      name: 'greet',
-      description: 'Greet someone by name',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          name: { type: 'string', description: 'Name to greet' }
-        },
-        required: ['name']
-      },
-      handler: async (input) => {
-        return {
-          greeting: `Hello, ${input.name}!`,
-          timestamp: new Date().toISOString()
-        };
-      }
-    }
-  ],
-
-  resources: [
-    {
-      uri: 'time://current',
-      name: 'Current Time',
-      description: 'Returns the current server time',
-      read: async () => {
-        return {
-          contents: {
-            time: new Date().toISOString(),
-            timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
-          }
-        };
-      }
-    }
-  ]
-});
-
-server.start().then(() => {
-  console.log('✅ Server started on http://localhost:3000');
-  console.log('');
-  console.log('Try these endpoints:');
-  console.log('  GET  http://localhost:3000/health');
-  console.log('  POST http://localhost:3000/mcp/tools/list');
-  console.log('  POST http://localhost:3000/mcp/tools/call');
-});
-```
-
-## Step 5: Run Your Server
-
-```bash
-npx tsx my-server.ts
-```
-
-## Step 6: Test Your Server
-
-**Test health check:**
-```bash
-curl http://localhost:3000/health
-```
-
-**List tools:**
-```bash
-curl -X POST http://localhost:3000/mcp/tools/list \
-  -H "Content-Type: application/json"
-```
-
-**Call a tool:**
-```bash
-curl -X POST http://localhost:3000/mcp/tools/call \
-  -H "Content-Type: application/json" \
-  -d '{
-    "method": "tools/call",
-    "params": {
-      "name": "greet",
-      "arguments": {
-        "name": "World"
-      }
-    }
-  }'
-```
-
-**Read a resource:**
-```bash
-curl -X POST http://localhost:3000/mcp/resources/read \
-  -H "Content-Type: application/json" \
-  -d '{
-    "method": "resources/read",
-    "params": {
-      "uri": "time://current"
-    }
-  }'
-```
-
-## Step 7: Add Production Storage
-
-For production, use Redis instead of InMemoryStore:
-
-```bash
-npm install ioredis
-```
-
-Update your server:
-
-```typescript
-import { createRedisStore } from './src/stores';
-import Redis from 'ioredis';
-
-const redis = new Redis(process.env.REDIS_URL || 'redis://localhost:6379');
-const store = createRedisStore(redis);
-
-const server = createMCPServer({
-  // ... same config
-  store,  // Use Redis instead of InMemoryStore
-});
-```
-
-## Step 8: Add Authentication
-
-Add authentication to your server:
-
-```typescript
-const server = createMCPServer({
-  // ... same config
-  
-  authenticate: async (req) => {
-    const apiKey = req.headers['x-api-key'];
-    
-    if (!apiKey) {
-      throw new Error('Missing API key');
-    }
-    
-    // Validate against your database
-    if (apiKey !== 'secret-key-123') {
-      throw new Error('Invalid API key');
-    }
-    
-    return {
-      userId: 'user-123',
-      apiKey: apiKey as string
-    };
-  }
-});
-```
-
-Test with authentication:
-
-```bash
-curl -X POST http://localhost:3000/mcp/tools/call \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key: secret-key-123" \
-  -d '{ ... }'
-```
-
-## Step 9: Add Webhook Subscriptions
-
-Create a resource with webhook support:
-
-```typescript
-resources: [
-  {
-    uri: 'events://updates',
-    name: 'Event Updates',
-    description: 'Stream of event updates',
-    
-    read: async () => {
-      return { contents: [] };
-    },
-    
-    subscription: {
-      onSubscribe: async (uri, subscriptionId, webhookUrl, context) => {
-        console.log('Client subscribed!');
-        console.log('Webhook URL:', webhookUrl);
-        
-        // In production: register with third-party service
-        // For demo: store in database
-        
-        return {
-          thirdPartyWebhookId: 'demo-webhook-123'
-        };
-      },
-      
-      onUnsubscribe: async (uri, subscriptionId, storedData, context) => {
-        console.log('Client unsubscribed');
-        
-        // In production: remove webhook from third-party
-      },
-      
-      onWebhook: async (subscriptionId, payload, headers) => {
-        console.log('Webhook received:', payload);
-        
-        // Process webhook and return changes
-        return {
-          resourceUri: 'events://updates',
-          changeType: 'created',
-          data: payload
-        };
-      }
-    }
-  }
-]
-```
-
-Subscribe to updates:
-
-```bash
-curl -X POST http://localhost:3000/mcp/resources/subscribe \
-  -H "Content-Type: application/json" \
-  -d '{
-    "method": "resources/subscribe",
-    "params": {
-      "uri": "events://updates",
-      "callbackUrl": "https://your-app.com/webhook",
-      "callbackSecret": "your-secret"
-    }
-  }'
-```
-
-## Next Steps
-
-- Explore the [examples/](./examples) directory
-- Read the [full API documentation](./README.md)
-- Check out the [specification](./Spec.md)
-- Add monitoring and logging
-- Deploy to production with Docker
-
-## Common Issues
-
-**Port already in use:**
-```typescript
-const server = createMCPServer({
-  port: 3001,  // Change port
-  // ...
-});
-```
-
-**CORS issues:**
-```typescript
-import cors from 'cors';
-
-const server = createMCPServer({
-  middleware: [cors()],
-  // ...
-});
-```
-
-**TypeScript errors:**
-Make sure you have installed all dependencies and built the library:
-```bash
-npm install
-npm run build
-```
-
-## Resources
-
-- [MCP Specification](https://spec.modelcontextprotocol.io/)
-- [TypeScript Documentation](https://www.typescriptlang.org/)
-- [Express.js Guide](https://expressjs.com/)
-- [Redis Documentation](https://redis.io/docs/)
-
-## Support
-
-- GitHub Issues: Report bugs and request features
-- Examples: Check the examples/ directory
-- Specification: Read Spec.md for detailed documentation
-
-Happy coding! 🚀