mcp-http-webhook 1.0.0

package/src/stores/RedisStore.ts

@@ -0,0 +1,51 @@
+import { KeyValueStore } from '../types';
+
+/**
+ * Redis store implementation
+ * Requires ioredis package
+ */
+export class RedisStore implements KeyValueStore {
+  constructor(private redis: any) {} // ioredis instance
+
+  async get(key: string): Promise<string | null> {
+    return await this.redis.get(key);
+  }
+
+  async set(key: string, value: string, ttl?: number): Promise<void> {
+    if (ttl) {
+      await this.redis.setex(key, ttl, value);
+    } else {
+      await this.redis.set(key, value);
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.redis.del(key);
+  }
+
+  async scan(pattern: string): Promise<string[]> {
+    const keys: string[] = [];
+    let cursor = '0';
+
+    do {
+      const [newCursor, matches] = await this.redis.scan(
+        cursor,
+        'MATCH',
+        pattern,
+        'COUNT',
+        100
+      );
+      cursor = newCursor;
+      keys.push(...matches);
+    } while (cursor !== '0');
+
+    return keys;
+  }
+}
+
+/**
+ * Create Redis store from connection URL
+ */
+export function createRedisStore(redis: any): KeyValueStore {
+  return new RedisStore(redis);
+}

package/src/stores/index.ts

@@ -0,0 +1,2 @@
+export { InMemoryStore } from './InMemoryStore';
+export { RedisStore, createRedisStore } from './RedisStore';

package/src/subscriptions/SubscriptionManager.ts

@@ -0,0 +1,240 @@
+import { StorageError, ValidationError } from '../errors';
+import {
+  AuthContext,
+  KeyValueStore,
+  Logger,
+  ResourceDefinition,
+  StoredSubscription
+} from '../types';
+import { generateSubscriptionId, generateWebhookUrl } from '../utils';
+
+export class SubscriptionManager {
+  constructor(
+    private store: KeyValueStore,
+    private resources: ResourceDefinition[],
+    private publicUrl: string,
+    private logger?: Logger
+  ) {}
+
+  /**
+   * Create a new subscription
+   */
+  async createSubscription(params: {
+    uri: string;
+    clientCallbackUrl: string;
+    clientCallbackSecret?: string;
+    context: AuthContext;
+  }): Promise<{ subscriptionId: string; status: string }> {
+    const { uri, clientCallbackUrl, clientCallbackSecret, context } = params;
+
+    // Find resource definition
+    const resource = this.findResourceForUri(uri);
+    if (!resource) {
+      throw new ValidationError(`No resource found for URI: ${uri}`);
+    }
+
+    if (!resource.subscription) {
+      throw new ValidationError(`Resource ${resource.name} does not support subscriptions`);
+    }
+
+    // Generate subscription ID
+    const subscriptionId = generateSubscriptionId();
+    const thirdPartyWebhookUrl = generateWebhookUrl(this.publicUrl, subscriptionId);
+
+    this.logger?.info('Creating subscription', {
+      subscriptionId,
+      uri,
+      clientCallbackUrl,
+    });
+
+    try {
+      // Call resource's onSubscribe handler
+      const metadata = await resource.subscription.onSubscribe(
+        uri,
+        subscriptionId,
+        thirdPartyWebhookUrl,
+        context
+      );
+
+      // Store subscription data
+      const subscriptionData: StoredSubscription = {
+        uri,
+        resourceType: resource.name,
+        clientCallbackUrl,
+        clientCallbackSecret,
+        userId: context.userId,
+        thirdPartyWebhookId: metadata.thirdPartyWebhookId,
+        metadata: metadata.metadata,
+        createdAt: Date.now(),
+      };
+
+      await this.storeSubscription(subscriptionId, subscriptionData, context.userId);
+
+      this.logger?.info('Subscription created', { subscriptionId });
+
+      return {
+        subscriptionId,
+        status: 'active',
+      };
+    } catch (error) {
+      this.logger?.error('Failed to create subscription', {
+        subscriptionId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw new StorageError('Failed to create subscription', { cause: error });
+    }
+  }
+
+  /**
+   * Delete a subscription
+   */
+  async deleteSubscription(subscriptionId: string, context: AuthContext): Promise<void> {
+    this.logger?.info('Deleting subscription', { subscriptionId });
+
+    // Load subscription
+    const subscription = await this.loadSubscription(subscriptionId);
+    if (!subscription) {
+      throw new ValidationError(`Subscription ${subscriptionId} not found`);
+    }
+
+    // Verify ownership
+    if (subscription.userId !== context.userId) {
+      throw new ValidationError('Unauthorized to delete this subscription');
+    }
+
+    // Find resource
+    const resource = this.findResourceForUri(subscription.uri);
+    if (!resource?.subscription) {
+      throw new StorageError('Resource subscription configuration not found');
+    }
+
+    try {
+      // Call resource's onUnsubscribe handler
+      await resource.subscription.onUnsubscribe(
+        subscription.uri,
+        subscriptionId,
+        {
+          thirdPartyWebhookId: subscription.thirdPartyWebhookId,
+          metadata: subscription.metadata,
+        },
+        context
+      );
+
+      // Delete from store
+      await this.removeSubscription(subscriptionId, context.userId);
+
+      this.logger?.info('Subscription deleted', { subscriptionId });
+    } catch (error) {
+      this.logger?.error('Failed to delete subscription', {
+        subscriptionId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw new StorageError('Failed to delete subscription', { cause: error });
+    }
+  }
+
+  /**
+   * Get subscription by ID
+   */
+  async getSubscription(subscriptionId: string): Promise<StoredSubscription | null> {
+    return this.loadSubscription(subscriptionId);
+  }
+
+  /**
+   * List subscriptions for a user
+   */
+  async listSubscriptions(userId: string): Promise<StoredSubscription[]> {
+    const indexKey = `user:${userId}:subscriptions`;
+    const indexData = await this.store.get(indexKey);
+
+    if (!indexData) {
+      return [];
+    }
+
+    const subscriptionIds: string[] = JSON.parse(indexData);
+
+    const subscriptions = await Promise.all(
+      subscriptionIds.map((id) => this.loadSubscription(id))
+    );
+
+    return subscriptions.filter((s): s is StoredSubscription => s !== null);
+  }
+
+  /**
+   * Store subscription data
+   */
+  private async storeSubscription(
+    subscriptionId: string,
+    data: StoredSubscription,
+    userId: string
+  ): Promise<void> {
+    const key = `subscription:${subscriptionId}`;
+    await this.store.set(key, JSON.stringify(data));
+
+    // Update user index
+    const indexKey = `user:${userId}:subscriptions`;
+    const existing = await this.store.get(indexKey);
+    const subscriptionIds: string[] = existing ? JSON.parse(existing) : [];
+
+    if (!subscriptionIds.includes(subscriptionId)) {
+      subscriptionIds.push(subscriptionId);
+      await this.store.set(indexKey, JSON.stringify(subscriptionIds));
+    }
+  }
+
+  /**
+   * Load subscription data
+   */
+  private async loadSubscription(subscriptionId: string): Promise<StoredSubscription | null> {
+    const key = `subscription:${subscriptionId}`;
+    const data = await this.store.get(key);
+
+    if (!data) {
+      return null;
+    }
+
+    return JSON.parse(data);
+  }
+
+  /**
+   * Remove subscription data
+   */
+  private async removeSubscription(subscriptionId: string, userId: string): Promise<void> {
+    const key = `subscription:${subscriptionId}`;
+    await this.store.delete(key);
+
+    // Update user index
+    const indexKey = `user:${userId}:subscriptions`;
+    const existing = await this.store.get(indexKey);
+
+    if (existing) {
+      const subscriptionIds: string[] = JSON.parse(existing);
+      const filtered = subscriptionIds.filter((id) => id !== subscriptionId);
+      await this.store.set(indexKey, JSON.stringify(filtered));
+    }
+  }
+
+  /**
+   * Find resource definition for URI
+   */
+  private findResourceForUri(uri: string): ResourceDefinition | undefined {
+    return this.resources.find((resource) => {
+      // Convert URI template to regex pattern
+      // Step 1: Replace template variables with a placeholder
+      const withPlaceholders = resource.uri.replace(/\{[^}]+\}/g, '__PLACEHOLDER__');
+      
+      // Step 2: Escape special regex characters (but not our placeholders)
+      const escapedPattern = withPlaceholders.replace(/[-\\^$*+?.()|[\]{}]/g, '\\$&');
+      
+      // Step 3: Replace placeholders with capture groups
+      const patternString = escapedPattern.replace(/__PLACEHOLDER__/g, '([^/]+)');
+      
+      // Step 4: Create regex with anchors
+      const pattern = new RegExp('^' + patternString + '$');
+      
+      console.log('Pattern for resource', resource.name, ':', pattern);
+      console.log('Testing URI:', uri);
+      return pattern.test(uri);
+    });
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,341 @@
+import { Request, Response, NextFunction } from 'express';
+
+/**
+ * JSON Schema definition for input validation
+ */
+export interface JSONSchema {
+  type: string;
+  properties?: Record<string, any>;
+  required?: string[];
+  [key: string]: any;
+}
+
+/**
+ * Authentication context passed to handlers
+ */
+export interface AuthContext {
+  userId: string;
+  [key: string]: any;
+}
+
+/**
+ * Authentication handler function
+ */
+export type AuthenticateFunction = (req: Request) => Promise<AuthContext>;
+
+/**
+ * Logger interface
+ */
+export interface Logger {
+  debug(message: string, meta?: any): void;
+  info(message: string, meta?: any): void;
+  warn(message: string, meta?: any): void;
+  error(message: string, meta?: any): void;
+}
+
+/**
+ * Key-value store interface for persistence
+ */
+export interface KeyValueStore {
+  /**
+   * Get value by key
+   * @returns Value as string, or null if not found
+   */
+  get(key: string): Promise<string | null>;
+
+  /**
+   * Set value with optional TTL
+   * @param key - Key to set
+   * @param value - Value (will be JSON stringified)
+   * @param ttl - Time to live in seconds (optional)
+   */
+  set(key: string, value: string, ttl?: number): Promise<void>;
+
+  /**
+   * Delete key
+   */
+  delete(key: string): Promise<void>;
+
+  /**
+   * Scan keys by pattern (optional, for debugging)
+   * @param pattern - Glob pattern (e.g., "subscription:*")
+   */
+  scan?(pattern: string): Promise<string[]>;
+}
+
+/**
+ * Tool handler function
+ */
+export type ToolHandler<TInput = any, TOutput = any> = (
+  input: TInput,
+  context: AuthContext
+) => Promise<TOutput>;
+
+/**
+ * Tool definition
+ */
+export interface ToolDefinition<TInput = any, TOutput = any> {
+  name: string;
+  description: string;
+  inputSchema: JSONSchema;
+  handler: ToolHandler<TInput, TOutput>;
+}
+
+/**
+ * Resource list item
+ */
+export interface ResourceListItem {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+/**
+ * Resource read result
+ */
+export interface ResourceReadResult<TData = any> {
+  contents: TData;
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Resource read options
+ */
+export interface ResourceReadOptions {
+  pagination?: {
+    page?: number;
+    limit?: number;
+  };
+}
+
+/**
+ * Subscription metadata returned by onSubscribe
+ */
+export interface SubscriptionMetadata {
+  thirdPartyWebhookId: string;
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Webhook change information
+ */
+export interface WebhookChangeInfo {
+  resourceUri: string;
+  changeType: 'created' | 'updated' | 'deleted';
+  data?: any;
+}
+
+/**
+ * Resource subscription handlers
+ */
+export interface ResourceSubscription {
+  /**
+   * Called when a client subscribes to a resource
+   */
+  onSubscribe: (
+    uri: string,
+    subscriptionId: string,
+    thirdPartyWebhookUrl: string,
+    context: AuthContext
+  ) => Promise<SubscriptionMetadata>;
+
+  /**
+   * Called when a client unsubscribes
+   */
+  onUnsubscribe: (
+    uri: string,
+    subscriptionId: string,
+    storedData: SubscriptionMetadata,
+    context: AuthContext
+  ) => Promise<void>;
+
+  /**
+   * Called when third-party webhook is received
+   */
+  onWebhook: (
+    subscriptionId: string,
+    payload: any,
+    headers: Record<string, string>
+  ) => Promise<WebhookChangeInfo | null>;
+}
+
+/**
+ * Resource definition
+ */
+export interface ResourceDefinition<TData = any> {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType?: string;
+
+  read: (
+    uri: string,
+    context: AuthContext,
+    options?: ResourceReadOptions
+  ) => Promise<ResourceReadResult<TData>>;
+
+  list?: (context: AuthContext) => Promise<ResourceListItem[]>;
+
+  subscription?: ResourceSubscription;
+}
+
+/**
+ * Prompt definition
+ */
+export interface PromptDefinition {
+  name: string;
+  description: string;
+  arguments?: Array<{
+    name: string;
+    description: string;
+    required?: boolean;
+  }>;
+  handler: (args: Record<string, any>, context: AuthContext) => Promise<{
+    messages: Array<{
+      role: 'user' | 'assistant';
+      content: string;
+    }>;
+  }>;
+}
+
+/**
+ * Webhook configuration
+ */
+export interface WebhookConfig {
+  incomingPath?: string;
+  incomingSecret?: string;
+  verifyIncomingSignature?: (payload: any, signature: string, secret: string) => boolean;
+
+  outgoing?: {
+    timeout?: number;
+    retries?: number;
+    retryDelay?: number;
+    signPayload?: (payload: any, secret: string) => string;
+    onBeforeCall?: (url: string, payload: any) => void;
+    onAfterCall?: (url: string, response: any, error?: any) => void;
+  };
+}
+
+/**
+ * Metrics configuration
+ */
+export interface MetricsConfig {
+  enabled: boolean;
+  registry?: any; // prom-client Registry
+}
+
+/**
+ * Tracing configuration
+ */
+export interface TracingConfig {
+  enabled: boolean;
+  serviceName?: string;
+}
+
+/**
+ * Batch configuration
+ */
+export interface BatchConfig {
+  maxBatchSize?: number;
+  batchTimeout?: number;
+}
+
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+  enabled: boolean;
+  ttl?: number;
+  keyPrefix?: string;
+}
+
+/**
+ * Dead letter queue configuration
+ */
+export interface DeadLetterQueueConfig {
+  enabled: boolean;
+  store: KeyValueStore;
+  retention?: number;
+  maxRetries?: number;
+}
+
+/**
+ * Middleware function
+ */
+export type Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+
+/**
+ * MCP Server configuration
+ */
+export interface MCPServerConfig {
+  // Server Identity
+  name: string;
+  version: string;
+
+  // HTTP Server Configuration
+  port?: number;
+  host?: string;
+  basePath?: string;
+  publicUrl: string;
+
+  // Authentication
+  authenticate?: AuthenticateFunction;
+
+  // Core MCP Components
+  tools: ToolDefinition[];
+  resources: ResourceDefinition[];
+  prompts?: PromptDefinition[];
+
+  // Storage
+  store: KeyValueStore;
+
+  // Webhook Configuration
+  webhooks?: WebhookConfig;
+
+  // Advanced Features
+  batch?: BatchConfig;
+  cache?: CacheConfig;
+  metrics?: MetricsConfig;
+  tracing?: TracingConfig;
+  middleware?: Middleware[];
+
+  // Logging
+  logger?: Logger;
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+
+/**
+ * Stored subscription data
+ */
+export interface StoredSubscription {
+  uri: string;
+  resourceType: string;
+  clientCallbackUrl: string;
+  clientCallbackSecret?: string;
+  userId: string;
+  thirdPartyWebhookId: string;
+  metadata?: any;
+  createdAt: number;
+}
+
+/**
+ * MCP Error codes
+ */
+export enum MCPErrorCode {
+  AuthenticationError = -32001,
+  ValidationError = -32002,
+  ResourceNotFoundError = -32003,
+  ToolExecutionError = -32004,
+  WebhookError = -32005,
+  StorageError = -32006,
+}
+
+/**
+ * MCP Server instance
+ */
+export interface MCPServer {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  getApp(): any; // Express app
+}