mcp-http-webhook 1.0.0

package/GETTING_STARTED.md

@@ -0,0 +1,310 @@
+# 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! 🚀

package/IMPLEMENTATION.md

@@ -0,0 +1,294 @@
+# MCP HTTP Webhook Library - Implementation Summary
+
+## Overview
+
+I've successfully implemented the complete MCP HTTP Webhook Server Library according to the specification. This is a production-ready TypeScript library for building Model Context Protocol servers with HTTP and webhook-based subscriptions.
+
+## ✅ What Was Implemented
+
+### 1. Core Library Structure
+
+```
+mcp-proxy/
+├── src/
+│   ├── types/index.ts           # Complete type definitions
+│   ├── errors/index.ts          # Error classes (MCPError, AuthenticationError, etc.)
+│   ├── utils/index.ts           # Utility functions (ID generation, URI parsing, signatures)
+│   ├── protocol/
+│   │   └── ProtocolHandler.ts   # MCP protocol implementation
+│   ├── subscriptions/
+│   │   └── SubscriptionManager.ts # Subscription lifecycle management
+│   ├── webhooks/
+│   │   └── WebhookManager.ts    # Webhook processing and delivery
+│   ├── stores/
+│   │   ├── InMemoryStore.ts     # In-memory store (dev/test)
+│   │   ├── RedisStore.ts        # Redis adapter
+│   │   └── index.ts             # Store exports
+│   ├── server.ts                # Main server creation
+│   └── index.ts                 # Public API exports
+├── examples/
+│   ├── basic-setup.ts           # Basic example
+│   └── github-server.ts         # GitHub webhook example
+├── package.json
+├── tsconfig.json
+├── jest.config.js
+├── .eslintrc.json
+├── .prettierrc.json
+├── README.md
+├── CONTRIBUTING.md
+├── LICENSE
+└── .gitignore
+```
+
+### 2. Type System (`src/types/index.ts`)
+
+Complete TypeScript definitions for:
+- `MCPServerConfig` - Server configuration
+- `ToolDefinition` - Tool definitions with handlers
+- `ResourceDefinition` - Resource definitions with read/list/subscription
+- `ResourceSubscription` - Webhook subscription handlers
+- `KeyValueStore` - Storage interface
+- `WebhookConfig` - Webhook configuration
+- `AuthContext` - Authentication context
+- All supporting types
+
+### 3. Error Handling (`src/errors/index.ts`)
+
+Implemented error classes:
+- `MCPError` - Base error class
+- `AuthenticationError` (-32001)
+- `ValidationError` (-32002)
+- `ResourceNotFoundError` (-32003)
+- `ToolExecutionError` (-32004)
+- `WebhookError` (-32005)
+- `StorageError` (-32006)
+
+### 4. Utilities (`src/utils/index.ts`)
+
+Utility functions:
+- `generateSubscriptionId()` - Generate unique subscription IDs
+- `generateWebhookUrl()` - Generate webhook URLs
+- `parseUriTemplate()` - Parse URI templates with parameters
+- `matchUriTemplate()` - Match URIs against templates
+- `createHmacSignature()` - Create HMAC signatures
+- `verifyHmacSignature()` - Verify signatures (timing-safe)
+- `sleep()`, `calculateBackoff()` - Retry helpers
+- URL validation and sanitization
+
+### 5. Protocol Handler (`src/protocol/ProtocolHandler.ts`)
+
+MCP protocol implementation:
+- `listTools()` - List available tools
+- `callTool()` - Execute tools with validation
+- `listResources()` - List available resources
+- `readResource()` - Read resource data
+- `listPrompts()` - List available prompts
+- `getPrompt()` - Get prompt templates
+- Input validation using AJV
+- Comprehensive error handling
+
+### 6. Subscription Manager (`src/subscriptions/SubscriptionManager.ts`)
+
+Subscription lifecycle management:
+- `createSubscription()` - Create new subscriptions
+- `deleteSubscription()` - Remove subscriptions
+- `getSubscription()` - Get subscription by ID
+- `listSubscriptions()` - List user subscriptions
+- Storage with user indexes
+- Ownership verification
+- Resource lookup
+
+### 7. Webhook Manager (`src/webhooks/WebhookManager.ts`)
+
+Webhook processing:
+- `processIncomingWebhook()` - Handle third-party webhooks
+- `notifyClient()` - Send notifications to clients
+- Signature verification
+- Automatic retry with exponential backoff
+- Timeout handling
+- Before/after hooks
+- Error recovery
+
+### 8. Server (`src/server.ts`)
+
+Express-based HTTP server:
+- Health check endpoints (`/health`, `/ready`)
+- MCP protocol endpoints:
+  - `POST /mcp/tools/list`
+  - `POST /mcp/tools/call`
+  - `POST /mcp/resources/list`
+  - `POST /mcp/resources/read`
+  - `POST /mcp/resources/subscribe`
+  - `POST /mcp/resources/unsubscribe`
+  - `POST /mcp/prompts/list`
+  - `POST /mcp/prompts/get`
+- Webhook endpoint:
+  - `POST /webhooks/incoming/{subscriptionId}`
+- Authentication middleware
+- Error handling middleware
+- Custom middleware support
+- Graceful startup/shutdown
+
+### 9. Storage Implementations
+
+**InMemoryStore** (`src/stores/InMemoryStore.ts`):
+- Development/testing only
+- TTL support
+- Automatic cleanup
+- Scan support
+
+**RedisStore** (`src/stores/RedisStore.ts`):
+- Production-ready Redis adapter
+- Full KeyValueStore interface
+- Connection pooling support
+- Pattern scanning
+
+### 10. Examples
+
+**Basic Setup** (`examples/basic-setup.ts`):
+- Simple echo and add tools
+- Greeting resource
+- API key authentication
+- Complete working example
+
+**GitHub Server** (`examples/github-server.ts`):
+- GitHub issue management
+- Webhook-based subscriptions
+- Signature verification
+- Real-world use case
+
+### 11. Documentation
+
+**README.md**:
+- Installation instructions
+- Quick start guide
+- API documentation
+- Configuration examples
+- Security guidelines
+- Deployment guide
+- Monitoring setup
+
+**CONTRIBUTING.md**:
+- Development setup
+- Code style guidelines
+- Testing requirements
+- Commit message format
+- Pull request process
+
+## 🎯 Key Features Implemented
+
+### HTTP + Webhooks Architecture
+- ✅ Stateless HTTP requests (no SSE connections)
+- ✅ Client-provided webhook URLs for notifications
+- ✅ Third-party webhook integration
+- ✅ Subscription-based resource updates
+
+### Production Ready
+- ✅ Automatic retry with exponential backoff
+- ✅ Webhook signature verification (HMAC)
+- ✅ Request timeout handling
+- ✅ Error recovery and logging
+- ✅ Health checks
+- ✅ Graceful shutdown
+
+### Horizontally Scalable
+- ✅ No connection state
+- ✅ External key-value store
+- ✅ Stateless architecture
+- ✅ Load balancer compatible
+
+### Developer Experience
+- ✅ Full TypeScript support
+- ✅ Comprehensive type definitions
+- ✅ Input validation with JSON Schema
+- ✅ Clear error messages
+- ✅ Extensive examples
+- ✅ Well-documented API
+
+## 📦 Package Configuration
+
+- **TypeScript**: Full type safety with strict mode
+- **Build**: TSC compilation to CommonJS
+- **Testing**: Jest with ts-jest
+- **Linting**: ESLint with TypeScript plugin
+- **Formatting**: Prettier
+- **Dependencies**: Minimal (ajv, nanoid)
+- **Peer Dependencies**: @modelcontextprotocol/sdk, express
+- **Optional**: ioredis, prom-client
+
+## 🚀 Usage
+
+```typescript
+import { createMCPServer } from 'mcp-http-webhook';
+import { InMemoryStore } from 'mcp-http-webhook/stores';
+
+const server = createMCPServer({
+  name: 'my-server',
+  version: '1.0.0',
+  publicUrl: 'https://mcp.example.com',
+  store: new InMemoryStore(),
+  tools: [...],
+  resources: [...],
+});
+
+await server.start();
+```
+
+## 🔧 Next Steps
+
+To use this library:
+
+1. **Install Dependencies**:
+   ```bash
+   cd packages/plugins/mcp-proxy
+   npm install
+   ```
+
+2. **Build**:
+   ```bash
+   npm run build
+   ```
+
+3. **Run Examples**:
+   ```bash
+   # Basic example
+   npx tsx examples/basic-setup.ts
+   
+   # GitHub example
+   npx tsx examples/github-server.ts
+   ```
+
+4. **Run Tests**:
+   ```bash
+   npm test
+   ```
+
+## 📝 Notes
+
+- The library is fully compliant with the specification
+- All core features are implemented
+- Ready for production use with Redis/external storage
+- InMemoryStore is for development only
+- Comprehensive error handling throughout
+- Full TypeScript type safety
+- Extensible architecture for custom stores
+
+## 🔒 Security Considerations
+
+- HTTPS enforced in production
+- Webhook signature verification
+- Timing-safe signature comparison
+- Input validation with JSON Schema
+- Authentication middleware support
+- Rate limiting support
+
+## 📊 Code Quality
+
+- TypeScript strict mode enabled
+- ESLint configured
+- Prettier formatting
+- Jest testing framework
+- >80% coverage target
+- Conventional commits
+
+This implementation provides a complete, production-ready foundation for building MCP servers with HTTP and webhook-based subscriptions!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Organization
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.