mcp-http-webhook 1.0.0

package/MIGRATION_TO_SDK.md

@@ -0,0 +1,263 @@
+# Migration to Standard MCP SDK
+
+This library has been updated to use the official `@modelcontextprotocol/sdk` while preserving all webhook subscription, authentication, and persistence features.
+
+## What Changed
+
+### ✅ Preserved Features
+- **Webhook Subscriptions**: Still fully supported via `/mcp/resources/subscribe` and `/mcp/resources/unsubscribe`
+- **Authentication**: All auth mechanisms work exactly the same
+- **Persistence**: KV store abstraction (Redis, in-memory) unchanged
+- **Resource Subscriptions**: Same subscription lifecycle management
+- **Webhook Processing**: Same retry logic and notification system
+
+### 🔄 Updated Architecture
+
+#### Before (Custom Protocol)
+```typescript
+// Custom endpoints for each operation
+POST /mcp/tools/call
+POST /mcp/resources/read
+POST /mcp/prompts/get
+```
+
+#### After (Standard MCP)
+```typescript
+// Single standard MCP endpoint
+POST /mcp
+
+// Webhook extensions preserved
+POST /mcp/resources/subscribe
+POST /mcp/resources/unsubscribe
+```
+
+### 📦 Dependency Changes
+
+**Removed:**
+- `ajv` - JSON Schema validation
+
+**Added:**
+- `zod` - Schema validation (required by MCP SDK)
+
+**Required Peer Dependencies:**
+- `@modelcontextprotocol/sdk@^1.0.0`
+- `express@^4.18.0`
+
+## Migration Steps
+
+### 1. Update Dependencies
+
+```bash
+npm install zod@^3.22.0
+npm uninstall ajv
+```
+
+### 2. No Code Changes Required
+
+Your existing server configuration works without changes:
+
+```typescript
+import { createMCPServer, InMemoryStore } from 'mcp-http-webhook';
+
+const server = createMCPServer({
+  name: 'my-server',
+  version: '1.0.0',
+  store: new InMemoryStore(),
+  publicUrl: 'https://api.example.com',
+  
+  // All existing config works the same
+  tools: [...],
+  resources: [...],
+  prompts: [...],
+  webhooks: {...},
+  authentication: {...}
+});
+
+await server.start();
+```
+
+### 3. Client Integration Updates
+
+#### MCP Inspector / Claude Desktop / VS Code
+
+Your server now works with **all standard MCP clients** out of the box:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "node",
+      "args": ["path/to/server.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+#### HTTP Clients
+
+Update your endpoint from custom paths to the standard `/mcp` endpoint:
+
+**Before:**
+```typescript
+// Custom endpoints
+POST https://api.example.com/mcp/tools/call
+POST https://api.example.com/mcp/resources/read
+```
+
+**After:**
+```typescript
+// Standard MCP endpoint
+POST https://api.example.com/mcp
+
+// Webhook subscriptions still work the same
+POST https://api.example.com/mcp/resources/subscribe
+POST https://api.example.com/mcp/resources/unsubscribe
+```
+
+### 4. Schema Definition Updates
+
+JSON Schema format remains the same, but it's now converted to Zod internally:
+
+```typescript
+{
+  tools: [{
+    name: 'search',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string' },
+        limit: { type: 'number' }
+      },
+      required: ['query']
+    },
+    handler: async (args, auth) => {
+      // Handler unchanged
+      return { results: [] };
+    }
+  }]
+}
+```
+
+## Benefits of Migration
+
+### 🎯 Standard Compliance
+- Works with all MCP clients (Inspector, Claude Desktop, VS Code, Cursor)
+- Follows official MCP protocol specification
+- Future-proof as MCP ecosystem evolves
+
+### 🔌 Better Interoperability
+- Standard transport layer (`StreamableHTTPServerTransport`)
+- Consistent error handling
+- Standard message formats
+
+### 🚀 Enhanced Features
+- Automatic JSON Schema to Zod conversion
+- Better type safety with Zod
+- Improved validation error messages
+
+### 🔄 Preserved Extensions
+- All webhook functionality intact
+- Resource subscriptions work as before
+- Authentication mechanisms unchanged
+- Storage abstraction untouched
+
+## Testing Your Migration
+
+### 1. Build and Run
+
+```bash
+npm run build
+node dist/examples/basic-setup.js
+```
+
+### 2. Test Standard MCP Endpoint
+
+```bash
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/list"
+  }'
+```
+
+### 3. Test Webhook Subscriptions
+
+```bash
+# Subscribe to a resource
+curl -X POST http://localhost:3000/mcp/resources/subscribe \
+  -H "Content-Type: application/json" \
+  -d '{
+    "uri": "resource://example/data",
+    "callbackUrl": "https://client.example.com/webhooks",
+    "callbackSecret": "secret123"
+  }'
+```
+
+### 4. Test with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector http://localhost:3000/mcp
+```
+
+## Troubleshooting
+
+### Schema Conversion Issues
+
+If you have complex nested schemas, verify the conversion:
+
+```typescript
+// Complex nested object
+{
+  type: 'object',
+  properties: {
+    user: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'number' }
+      }
+    },
+    tags: {
+      type: 'array',
+      items: { type: 'string' }
+    }
+  }
+}
+```
+
+This is automatically converted to proper Zod schemas.
+
+### Type Errors
+
+If you encounter TypeScript errors, ensure you're using:
+- `typescript@^5.0.0`
+- `zod@^3.22.0`
+- `@modelcontextprotocol/sdk@^1.0.0`
+
+### Client Connection Issues
+
+If clients can't connect:
+
+1. Verify the endpoint is `/mcp` (not `/mcp/tools/call`)
+2. Check CORS settings if using browser clients
+3. Ensure authentication headers are passed correctly
+
+## Support
+
+For issues or questions:
+- Check the [README](./README.md) for updated examples
+- Review [ARCHITECTURE.md](./ARCHITECTURE.md) for system design
+- See [examples/](./examples/) for working code
+
+## Rollback (Not Recommended)
+
+If you need to rollback temporarily, use version `0.9.x`:
+
+```bash
+npm install mcp-http-webhook@0.9.0
+```
+
+However, we strongly recommend migrating as the custom protocol implementation is deprecated.