mcp-http-webhook 1.0.29 → 1.0.30

package/STANDARD_SUBSCRIPTIONS.md

@@ -1,268 +0,0 @@
-# Standard MCP Subscriptions with Webhook Support
-
-This library now supports **standard MCP `resources/subscribe`** with webhook callbacks, eliminating the need for custom endpoints!
-
-## 🎯 Two Ways to Subscribe
-
-### Method 1: Standard MCP Subscribe (Recommended) ✅
-
-Use the standard `resources/subscribe` method with webhook URL in `_meta`:
-
-```bash
-curl -X POST http://localhost:3000/mcp \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 1,
-    "method": "resources/subscribe",
-    "params": {
-      "uri": "github://repo/owner/repo/issues",
-      "_meta": {
-        "webhookUrl": "https://your-app.com/webhooks/mcp",
-        "webhookSecret": "your-secret-123"
-      }
-    }
-  }'
-```
-
-**Response:**
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "result": {
-    "subscriptionId": "sub_abc123xyz",
-    "_meta": {
-      "subscriptionId": "sub_abc123xyz",
-      "webhookEnabled": true
-    }
-  }
-}
-```
-
-### Method 2: Legacy Custom Endpoint (Still Supported)
-
-```bash
-curl -X POST http://localhost:3000/mcp/resources/subscribe \
-  -H "Content-Type: application/json" \
-  -d '{
-    "uri": "github://repo/owner/repo/issues",
-    "callbackUrl": "https://your-app.com/webhooks/mcp",
-    "callbackSecret": "your-secret-123"
-  }'
-```
-
-## 📬 Webhook Notifications (Standard MCP Format)
-
-When a resource changes, your webhook URL receives a **standard MCP notification**:
-
-```json
-{
-  "jsonrpc": "2.0",
-  "method": "notifications/resources/updated",
-  "params": {
-    "uri": "github://repo/owner/repo/issues",
-    "title": "Repository Issues Updated",
-    "_meta": {
-      "changeType": "created",
-      "subscriptionId": "sub_abc123xyz",
-      "timestamp": "2025-10-14T13:30:00Z",
-      "issue": {
-        "number": 42,
-        "title": "New feature request",
-        "state": "open"
-      }
-    }
-  }
-}
-```
-
-## 🔄 Full Workflow Example
-
-### 1. Subscribe to Resource
-
-```typescript
-// Using standard MCP client
-const response = await mcpClient.request({
-  method: 'resources/subscribe',
-  params: {
-    uri: 'github://repo/surajbhan/test/issues',
-    _meta: {
-      webhookUrl: 'https://my-app.com/mcp/notifications',
-      webhookSecret: 'my-secret-key'
-    }
-  }
-});
-
-console.log('Subscription ID:', response._meta.subscriptionId);
-```
-
-### 2. Receive Notifications
-
-```typescript
-// Your webhook endpoint
-app.post('/mcp/notifications', (req, res) => {
-  const notification = req.body;
-  
-  if (notification.method === 'notifications/resources/updated') {
-    const { uri, title, _meta } = notification.params;
-    
-    console.log('Resource updated:', uri);
-    console.log('Change type:', _meta.changeType); // 'created', 'updated', or 'deleted'
-    console.log('Details:', _meta);
-    
-    // Handle the update
-    handleResourceUpdate(uri, _meta);
-  }
-  
-  res.status(200).send('OK');
-});
-```
-
-### 3. Unsubscribe
-
-```typescript
-// Standard MCP unsubscribe
-await mcpClient.request({
-  method: 'resources/unsubscribe',
-  params: {
-    uri: 'github://repo/surajbhan/test/issues',
-    _meta: {
-      subscriptionId: 'sub_abc123xyz'
-    }
-  }
-});
-```
-
-## 🔐 Webhook Security
-
-### Signature Verification
-
-All webhook notifications include a signature header for verification:
-
-```typescript
-import crypto from 'crypto';
-
-function verifyWebhookSignature(
-  payload: any,
-  signature: string,
-  secret: string
-): boolean {
-  const hmac = crypto.createHmac('sha256', secret);
-  hmac.update(JSON.stringify(payload));
-  const expected = `sha256=${hmac.digest('hex')}`;
-  
-  return crypto.timingSafeEqual(
-    Buffer.from(signature),
-    Buffer.from(expected)
-  );
-}
-
-// In your webhook handler
-app.post('/mcp/notifications', (req, res) => {
-  const signature = req.headers['x-webhook-signature'];
-  const isValid = verifyWebhookSignature(
-    req.body,
-    signature,
-    'my-secret-key'
-  );
-  
-  if (!isValid) {
-    return res.status(401).send('Invalid signature');
-  }
-  
-  // Process notification...
-});
-```
-
-## 🎨 MCP Inspector Integration
-
-The standard subscribe method works seamlessly with MCP Inspector:
-
-1. Open MCP Inspector: `npx @modelcontextprotocol/inspector http://localhost:3000/mcp`
-2. List resources
-3. Click "Subscribe" on a resource
-4. **NEW**: Inspector can pass webhook URL via `_meta`
-
-## 📊 Comparison
-
-| Feature | Standard MCP Subscribe | Legacy Endpoint |
-|---------|----------------------|-----------------|
-| **Endpoint** | `POST /mcp` | `POST /mcp/resources/subscribe` |
-| **Method** | `resources/subscribe` | N/A (direct POST) |
-| **Webhook URL** | `params._meta.webhookUrl` | `params.callbackUrl` |
-| **MCP Compliant** | ✅ Yes | ❌ No (custom extension) |
-| **Inspector Compatible** | ✅ Yes | ⚠️ Partial |
-| **Notification Format** | `notifications/resources/updated` | Custom |
-| **Recommended** | ✅ **Use this** | ⚠️ Legacy support |
-
-## 🚀 Quick Start
-
-### For MCP Clients
-
-```typescript
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-
-const client = new Client({
-  name: 'my-app',
-  version: '1.0.0'
-});
-
-// Connect to MCP server
-await client.connect(transport);
-
-// Subscribe with webhook
-const subscription = await client.request({
-  method: 'resources/subscribe',
-  params: {
-    uri: 'github://repo/owner/repo/issues',
-    _meta: {
-      webhookUrl: 'https://my-app.com/webhooks/mcp',
-      webhookSecret: 'secret123'
-    }
-  }
-});
-
-console.log('Subscribed:', subscription._meta.subscriptionId);
-```
-
-### For HTTP Clients
-
-```bash
-# Subscribe
-curl -X POST http://localhost:3000/mcp \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 1,
-    "method": "resources/subscribe",
-    "params": {
-      "uri": "github://repo/owner/repo/issues",
-      "_meta": {
-        "webhookUrl": "https://webhook.site/your-unique-url",
-        "webhookSecret": "test123"
-      }
-    }
-  }'
-
-# Watch webhook.site for notifications!
-```
-
-## 🎯 Benefits
-
-1. **✅ Standard Compliant**: Works with all MCP clients
-2. **🔌 Universal**: No custom endpoints needed
-3. **📡 Webhook-based**: No SSE connection required
-4. **🔒 Secure**: Built-in signature verification
-5. **🎨 Inspector Ready**: Full MCP Inspector support
-6. **📚 Spec Aligned**: Follows MCP 2025-06-18 specification
-
-## 📖 Learn More
-
-- **MCP Spec**: https://modelcontextprotocol.io/specification/2025-06-18/server/resources#subscriptions
-- **Full Example**: See `examples/github-server-live.ts`
-- **Architecture**: See `ARCHITECTURE.md`
-
----
-
-**🎉 Now you have standard MCP subscriptions with webhook support!**

package/STANDARD_SUBSCRIPTIONS_COMPLETE.md

@@ -1,309 +0,0 @@
-# ✅ Standard MCP Subscriptions Implementation Complete
-
-## 🎯 What Was Implemented
-
-Successfully integrated **standard MCP `resources/subscribe`** with webhook callback support, making the library fully MCP-compliant while preserving all webhook functionality.
-
-## 🔄 How It Works
-
-### Before (Custom Endpoint)
-```bash
-POST /mcp/resources/subscribe
-{
-  "uri": "github://repo/owner/repo/issues",
-  "callbackUrl": "https://client.com/webhook",
-  "callbackSecret": "secret"
-}
-```
-
-### After (Standard MCP) ✅
-```bash
-POST /mcp
-{
-  "jsonrpc": "2.0",
-  "method": "resources/subscribe",
-  "params": {
-    "uri": "github://repo/owner/repo/issues",
-    "_meta": {
-      "webhookUrl": "https://client.com/webhook",
-      "webhookSecret": "secret"
-    }
-  }
-}
-```
-
-## 📋 Key Changes
-
-### 1. Server Intercepts Standard MCP Subscribe
-
-In `src/server.ts`, the main `/mcp` endpoint now intercepts `resources/subscribe`:
-
-```typescript
-// Intercept resources/subscribe to support webhook callbacks
-if (req.body.method === 'resources/subscribe') {
-  const webhookUrl = req.body.params?._meta?.webhookUrl;
-  
-  if (webhookUrl) {
-    // Handle webhook-based subscription
-    const result = await subscriptionManager.createSubscription({
-      uri,
-      clientCallbackUrl: webhookUrl,
-      clientCallbackSecret: webhookSecret,
-      context,
-    });
-    
-    // Return standard MCP response
-    return res.json({
-      jsonrpc: '2.0',
-      id: req.body.id,
-      result: {
-        ...result,
-        _meta: { subscriptionId: result.subscriptionId, webhookEnabled: true }
-      }
-    });
-  }
-}
-```
-
-### 2. Standard MCP Notification Format
-
-Updated `src/webhooks/WebhookManager.ts` to send notifications in standard MCP format:
-
-```typescript
-// Standard MCP notification
-const payload = {
-  jsonrpc: '2.0',
-  method: 'notifications/resources/updated',
-  params: {
-    uri: changeInfo.resourceUri,
-    title: changeInfo.data?.title,
-    _meta: {
-      changeType: changeInfo.changeType,
-      subscriptionId: subscription.uri,
-      timestamp: new Date().toISOString(),
-      ...changeInfo.data
-    }
-  }
-};
-```
-
-### 3. Both Methods Supported
-
-- ✅ **Standard MCP**: `POST /mcp` with `resources/subscribe` method
-- ✅ **Legacy Custom**: `POST /mcp/resources/subscribe` (backward compatible)
-
-## 🎉 Benefits
-
-### 1. MCP Compliance
-- ✅ Follows MCP specification 2025-06-18
-- ✅ Works with all standard MCP clients
-- ✅ Compatible with MCP Inspector
-- ✅ Uses `notifications/resources/updated` format
-
-### 2. Webhook-Based (Not SSE)
-- ✅ No persistent connection required
-- ✅ Client provides webhook URL in `_meta`
-- ✅ Server sends HTTP POST to client webhook
-- ✅ Fully stateless and scalable
-
-### 3. Backward Compatible
-- ✅ Custom endpoints still work (`/mcp/resources/subscribe`)
-- ✅ Existing integrations unaffected
-- ✅ Gradual migration path
-
-## 📚 Usage Examples
-
-### Example 1: Subscribe via Standard MCP
-
-```typescript
-// MCP Client
-const response = await client.request({
-  method: 'resources/subscribe',
-  params: {
-    uri: 'github://repo/owner/repo/issues',
-    _meta: {
-      webhookUrl: 'https://my-app.com/mcp/notifications',
-      webhookSecret: 'secret123'
-    }
-  }
-});
-
-// Response
-{
-  subscriptionId: 'sub_abc123',
-  _meta: {
-    subscriptionId: 'sub_abc123',
-    webhookEnabled: true
-  }
-}
-```
-
-### Example 2: Receive Notifications
-
-```typescript
-// Your webhook endpoint
-app.post('/mcp/notifications', (req, res) => {
-  const notification = req.body;
-  
-  // Standard MCP notification
-  if (notification.method === 'notifications/resources/updated') {
-    console.log('Resource:', notification.params.uri);
-    console.log('Change:', notification.params._meta.changeType);
-    console.log('Data:', notification.params._meta);
-  }
-  
-  res.send('OK');
-});
-```
-
-### Example 3: Unsubscribe
-
-```typescript
-await client.request({
-  method: 'resources/unsubscribe',
-  params: {
-    uri: 'github://repo/owner/repo/issues',
-    _meta: {
-      subscriptionId: 'sub_abc123'
-    }
-  }
-});
-```
-
-## 🧪 Testing
-
-### Test with curl
-
-```bash
-# 1. Subscribe
-curl -X POST http://localhost:3000/mcp \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 1,
-    "method": "resources/subscribe",
-    "params": {
-      "uri": "github://repo/surajbhan/test/issues",
-      "_meta": {
-        "webhookUrl": "https://webhook.site/unique-url",
-        "webhookSecret": "test123"
-      }
-    }
-  }'
-
-# 2. Create issue (triggers webhook)
-# Go to GitHub and create an issue
-
-# 3. Check webhook.site for notification!
-```
-
-### Test with MCP Inspector
-
-```bash
-npx @modelcontextprotocol/inspector http://localhost:3000/mcp
-```
-
-1. List resources
-2. Subscribe to a resource
-3. Provide webhook URL in metadata
-4. Trigger resource change
-5. See notification arrive!
-
-## 📊 Notification Flow
-
-```
-┌─────────────┐
-│   Client    │
-│  (Your App) │
-└──────┬──────┘
-       │
-       │ 1. POST /mcp
-       │    method: resources/subscribe
-       │    params._meta.webhookUrl: "https://client.com/webhook"
-       │
-       ▼
-┌─────────────────┐
-│   MCP Server    │
-│ (This Library)  │
-└────────┬────────┘
-         │
-         │ 2. Create subscription
-         │    Setup GitHub webhook
-         │
-         ▼
-┌─────────────────┐
-│     GitHub      │
-│   (3rd Party)   │
-└────────┬────────┘
-         │
-         │ 3. Issue created
-         │    POST /webhooks/incoming/sub_123
-         │
-         ▼
-┌─────────────────┐
-│   MCP Server    │
-└────────┬────────┘
-         │
-         │ 4. Send MCP notification
-         │    POST https://client.com/webhook
-         │    {
-         │      "jsonrpc": "2.0",
-         │      "method": "notifications/resources/updated",
-         │      "params": { ... }
-         │    }
-         │
-         ▼
-┌─────────────┐
-│   Client    │
-│  Receives   │
-│Notification │
-└─────────────┘
-```
-
-## 🔐 Security
-
-### Signature Verification
-
-All notifications include HMAC signature:
-
-```typescript
-const signature = headers['x-webhook-signature'];
-// Format: "sha256=<hmac_hex>"
-
-const hmac = crypto.createHmac('sha256', secret);
-hmac.update(JSON.stringify(payload));
-const expected = `sha256=${hmac.digest('hex')}`;
-
-if (signature !== expected) {
-  throw new Error('Invalid signature');
-}
-```
-
-## 📖 Documentation
-
-- **Standard Subscriptions Guide**: `STANDARD_SUBSCRIPTIONS.md`
-- **GitHub Live Example**: `examples/github-server-live.ts`
-- **MCP Specification**: https://modelcontextprotocol.io/specification/2025-06-18/server/resources#subscriptions
-
-## ✅ Checklist
-
-- [x] Standard `resources/subscribe` intercept
-- [x] Webhook URL via `_meta` parameter
-- [x] Standard MCP notification format (`notifications/resources/updated`)
-- [x] Backward compatible with custom endpoints
-- [x] Signature verification
-- [x] Retry logic with exponential backoff
-- [x] MCP Inspector compatible
-- [x] Documentation and examples
-- [x] Live GitHub integration tested
-
-## 🚀 Result
-
-You now have:
-1. ✅ **Standard MCP compliance** - works with all MCP clients
-2. ✅ **Webhook-based subscriptions** - no SSE needed
-3. ✅ **Third-party integration** - GitHub, Slack, etc.
-4. ✅ **Backward compatible** - existing code still works
-5. ✅ **Production ready** - retry, security, monitoring
-
-**The best of both worlds: Standard MCP + Webhook Power! 🎉**