mcp-http-webhook 1.0.0

package/src/utils/index.ts

@@ -0,0 +1,156 @@
+import crypto from 'crypto';
+import { nanoid } from 'nanoid';
+
+/**
+ * Generate a unique subscription ID
+ */
+export function generateSubscriptionId(): string {
+  return `sub_${nanoid(16)}`;
+}
+
+/**
+ * Generate webhook URL for third-party services
+ */
+export function generateWebhookUrl(publicUrl: string, subscriptionId: string): string {
+  const baseUrl = publicUrl.endsWith('/') ? publicUrl.slice(0, -1) : publicUrl;
+  return `${baseUrl}/webhooks/incoming/${subscriptionId}`;
+}
+
+/**
+ * Parse URI template
+ * Example: parseUriTemplate('github://repo/{owner}/{repo}', 'github://repo/octocat/hello')
+ * Returns: { owner: 'octocat', repo: 'hello' }
+ */
+export function parseUriTemplate(template: string, uri: string): Record<string, string> {
+  const templateParts = template.split('/');
+  const uriParts = uri.split('/');
+
+  if (templateParts.length !== uriParts.length) {
+    throw new Error(`URI ${uri} does not match template ${template}`);
+  }
+
+  const params: Record<string, string> = {};
+
+  for (let i = 0; i < templateParts.length; i++) {
+    const templatePart = templateParts[i];
+    const uriPart = uriParts[i];
+
+    if (templatePart.startsWith('{') && templatePart.endsWith('}')) {
+      const paramName = templatePart.slice(1, -1);
+      params[paramName] = uriPart;
+    } else if (templatePart !== uriPart) {
+      throw new Error(`URI ${uri} does not match template ${template}`);
+    }
+  }
+
+  return params;
+}
+
+/**
+ * Match URI against template
+ */
+export function matchUriTemplate(template: string, uri: string): boolean {
+  try {
+    parseUriTemplate(template, uri);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create HMAC signature
+ */
+export function createHmacSignature(
+  payload: any,
+  secret: string,
+  algorithm: 'sha256' | 'sha1' = 'sha256'
+): string {
+  const hmac = crypto.createHmac(algorithm, secret);
+  const data = typeof payload === 'string' ? payload : JSON.stringify(payload);
+  hmac.update(data);
+  return `${algorithm}=${hmac.digest('hex')}`;
+}
+
+/**
+ * Verify HMAC signature (timing-safe comparison)
+ */
+export function verifyHmacSignature(
+  payload: any,
+  signature: string,
+  secret: string,
+  algorithm: 'sha256' | 'sha1' = 'sha256'
+): boolean {
+  try {
+    const expected = createHmacSignature(payload, secret, algorithm);
+    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Sleep utility for retry delays
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Exponential backoff calculator
+ */
+export function calculateBackoff(attempt: number, baseDelay: number): number {
+  return baseDelay * Math.pow(2, attempt);
+}
+
+/**
+ * Sanitize URL for logging (remove sensitive query params)
+ */
+export function sanitizeUrl(url: string): string {
+  try {
+    const urlObj = new URL(url);
+    urlObj.searchParams.delete('token');
+    urlObj.searchParams.delete('secret');
+    urlObj.searchParams.delete('api_key');
+    return urlObj.toString();
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Extract error message safely
+ */
+export function extractErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  return 'Unknown error';
+}
+
+/**
+ * Validate URL format
+ */
+export function isValidUrl(url: string): boolean {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate HTTPS URL
+ */
+export function isHttpsUrl(url: string): boolean {
+  try {
+    const urlObj = new URL(url);
+    return urlObj.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}

package/src/webhooks/WebhookManager.ts

@@ -0,0 +1,230 @@
+import {
+  WebhookConfig,
+  StoredSubscription,
+  ResourceDefinition,
+  WebhookChangeInfo,
+  Logger,
+} from '../types';
+import { WebhookError } from '../errors';
+import { sleep, calculateBackoff, extractErrorMessage } from '../utils';
+
+export class WebhookManager {
+  private readonly timeout: number;
+  private readonly retries: number;
+  private readonly retryDelay: number;
+
+  constructor(
+    private config: WebhookConfig | undefined,
+    private resources: ResourceDefinition[],
+    private logger?: Logger
+  ) {
+    this.timeout = config?.outgoing?.timeout ?? 5000;
+    this.retries = config?.outgoing?.retries ?? 3;
+    this.retryDelay = config?.outgoing?.retryDelay ?? 1000;
+  }
+
+  /**
+   * Process incoming webhook from third-party service
+   */
+  async processIncomingWebhook(
+    subscriptionId: string,
+    payload: any,
+    headers: Record<string, string>,
+    subscription: StoredSubscription
+  ): Promise<WebhookChangeInfo | null> {
+    this.logger?.debug('Processing incoming webhook', {
+      subscriptionId,
+      resourceType: subscription.resourceType,
+    });
+
+    // Find resource definition
+    const resource = this.findResourceByName(subscription.resourceType);
+    if (!resource?.subscription) {
+      throw new WebhookError('Resource subscription handler not found');
+    }
+
+    // Verify signature if configured
+    if (this.config?.verifyIncomingSignature) {
+      const signature = headers['x-hub-signature-256'] || headers['x-signature'];
+      if (signature && this.config.incomingSecret) {
+        const isValid = this.config.verifyIncomingSignature(
+          payload,
+          signature,
+          this.config.incomingSecret
+        );
+
+        if (!isValid) {
+          this.logger?.warn('Invalid webhook signature', { subscriptionId });
+          throw new WebhookError('Invalid webhook signature');
+        }
+      }
+    }
+
+    try {
+      // Call resource's onWebhook handler
+      const changeInfo = await resource.subscription.onWebhook(subscriptionId, payload, headers);
+
+      this.logger?.debug('Webhook processed', {
+        subscriptionId,
+        changeType: changeInfo?.changeType,
+      });
+
+      return changeInfo;
+    } catch (error) {
+      this.logger?.error('Failed to process webhook', {
+        subscriptionId,
+        error: extractErrorMessage(error),
+      });
+      throw new WebhookError('Failed to process webhook', { cause: error });
+    }
+  }
+
+  /**
+   * Send notification to client webhook in standard MCP format
+   */
+  async notifyClient(
+    subscription: StoredSubscription,
+    changeInfo: WebhookChangeInfo
+  ): Promise<void> {
+    // Standard MCP notification format
+    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
+        }
+      }
+    };
+
+    this.logger?.info('Notifying client (MCP format)', {
+      url: subscription.clientCallbackUrl,
+      uri: changeInfo.resourceUri,
+      changeType: changeInfo.changeType,
+    });
+
+    // Sign payload if secret is provided
+    let signature: string | undefined;
+    if (subscription.clientCallbackSecret && this.config?.outgoing?.signPayload) {
+      signature = this.config.outgoing.signPayload(payload, subscription.clientCallbackSecret);
+    }
+
+    // Call before hook
+    this.config?.outgoing?.onBeforeCall?.(subscription.clientCallbackUrl, payload);
+
+    // Attempt delivery with retries
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < this.retries; attempt++) {
+      try {
+        const response = await this.callWebhook(
+          subscription.clientCallbackUrl,
+          payload,
+          signature
+        );
+
+        // Call after hook
+        this.config?.outgoing?.onAfterCall?.(subscription.clientCallbackUrl, response);
+
+        this.logger?.info('Client notified successfully (MCP format)', {
+          url: subscription.clientCallbackUrl,
+          attempt: attempt + 1,
+        });
+
+        return; // Success
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        this.logger?.warn('Webhook delivery failed', {
+          url: subscription.clientCallbackUrl,
+          attempt: attempt + 1,
+          error: extractErrorMessage(error),
+        });
+
+        // Don't retry on client errors (4xx)
+        if (error instanceof Error && 'status' in error) {
+          const status = (error as any).status;
+          if (status >= 400 && status < 500) {
+            throw new WebhookError('Client error, not retrying', { status });
+          }
+        }
+
+        // Wait before retry (exponential backoff)
+        if (attempt < this.retries - 1) {
+          const delay = calculateBackoff(attempt, this.retryDelay);
+          await sleep(delay);
+        }
+      }
+    }
+
+    // All retries failed
+    this.config?.outgoing?.onAfterCall?.(subscription.clientCallbackUrl, null, lastError);
+
+    throw new WebhookError('Failed to notify client after all retries', {
+      attempts: this.retries,
+      lastError: extractErrorMessage(lastError),
+    });
+  }
+
+  /**
+   * Call webhook URL
+   */
+  private async callWebhook(
+    url: string,
+    payload: any,
+    signature?: string
+  ): Promise<any> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+      };
+
+      if (signature) {
+        headers['X-MCP-Signature'] = signature;
+      }
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const error: any = new Error(`HTTP ${response.status}: ${response.statusText}`);
+        error.status = response.status;
+        throw error;
+      }
+
+      return {
+        ok: true,
+        status: response.status,
+      };
+    } catch (error) {
+      clearTimeout(timeoutId);
+
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new Error(`Request timeout after ${this.timeout}ms`);
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Find resource by name
+   */
+  private findResourceByName(name: string): ResourceDefinition | undefined {
+    return this.resources.find((r) => r.name === name);
+  }
+}

package/test-sdk-integration.sh

@@ -0,0 +1,157 @@
+#!/bin/bash
+
+# Test MCP SDK Integration
+# This script verifies the server works with standard MCP clients
+
+set -e
+
+echo "🧪 Testing MCP SDK Integration..."
+echo ""
+
+# Build the project
+echo "📦 Building project..."
+npm run build
+echo "✅ Build successful"
+echo ""
+
+# Start the server in background
+echo "🚀 Starting server..."
+node dist/examples/basic-setup.js &
+SERVER_PID=$!
+
+# Wait for server to start
+sleep 3
+
+# Function to cleanup
+cleanup() {
+  echo ""
+  echo "🧹 Cleaning up..."
+  kill $SERVER_PID 2>/dev/null || true
+}
+trap cleanup EXIT
+
+echo "✅ Server started (PID: $SERVER_PID)"
+echo ""
+
+# Test 1: Health check
+echo "Test 1: Health check"
+RESPONSE=$(curl -s http://localhost:3000/health)
+if echo "$RESPONSE" | grep -q "ok"; then
+  echo "✅ Health check passed"
+else
+  echo "❌ Health check failed: $RESPONSE"
+  exit 1
+fi
+echo ""
+
+# Test 2: Standard MCP endpoint - List tools
+echo "Test 2: List tools via standard MCP endpoint"
+RESPONSE=$(curl -s -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/list"
+  }')
+
+if echo "$RESPONSE" | grep -q "echo"; then
+  echo "✅ Tools list successful"
+  echo "   Found tools: $(echo "$RESPONSE" | grep -o '"name":"[^"]*"' | cut -d'"' -f4 | tr '\n' ', ')"
+else
+  echo "❌ Tools list failed: $RESPONSE"
+  exit 1
+fi
+echo ""
+
+# Test 3: Call a tool
+echo "Test 3: Call echo tool"
+RESPONSE=$(curl -s -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "tools/call",
+    "params": {
+      "name": "echo",
+      "arguments": {
+        "message": "Hello from MCP SDK!"
+      }
+    }
+  }')
+
+if echo "$RESPONSE" | grep -q "Hello from MCP SDK"; then
+  echo "✅ Tool call successful"
+else
+  echo "❌ Tool call failed: $RESPONSE"
+  exit 1
+fi
+echo ""
+
+# Test 4: List resources
+echo "Test 4: List resources"
+RESPONSE=$(curl -s -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 3,
+    "method": "resources/list"
+  }')
+
+if echo "$RESPONSE" | grep -q "Greeting Resource"; then
+  echo "✅ Resources list successful"
+else
+  echo "❌ Resources list failed: $RESPONSE"
+  exit 1
+fi
+echo ""
+
+# Test 5: Read a resource
+echo "Test 5: Read a resource"
+RESPONSE=$(curl -s -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 4,
+    "method": "resources/read",
+    "params": {
+      "uri": "example://greeting/world"
+    }
+  }')
+
+if echo "$RESPONSE" | grep -q "Hello"; then
+  echo "✅ Resource read successful"
+else
+  echo "❌ Resource read failed: $RESPONSE"
+  exit 1
+fi
+echo ""
+
+# Test 6: Webhook subscription endpoint (extension)
+echo "Test 6: Webhook subscription endpoint (extension)"
+RESPONSE=$(curl -s -X POST http://localhost:3000/mcp/resources/subscribe \
+  -H "Content-Type: application/json" \
+  -d '{
+    "uri": "example://greeting/alice",
+    "callbackUrl": "https://example.com/webhook",
+    "callbackSecret": "test-secret"
+  }')
+
+if echo "$RESPONSE" | grep -q "subscriptionId"; then
+  echo "✅ Webhook subscription successful"
+  SUBSCRIPTION_ID=$(echo "$RESPONSE" | grep -o '"subscriptionId":"[^"]*"' | cut -d'"' -f4)
+  echo "   Subscription ID: $SUBSCRIPTION_ID"
+else
+  echo "❌ Webhook subscription failed: $RESPONSE"
+  exit 1
+fi
+echo ""
+
+echo "🎉 All tests passed!"
+echo ""
+echo "✨ MCP SDK Integration is working correctly!"
+echo ""
+echo "You can now:"
+echo "  - Use with MCP Inspector: npx @modelcontextprotocol/inspector http://localhost:3000/mcp"
+echo "  - Configure Claude Desktop to use: http://localhost:3000/mcp"
+echo "  - Integrate with any standard MCP client"
+echo ""

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "types": ["node", "jest"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}