mcp-http-webhook 1.0.0

package/src/server.ts

@@ -0,0 +1,595 @@
+import express, { Express, Request, Response, NextFunction } from 'express';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { z } from 'zod';
+import { MCPServerConfig, MCPServer, Logger, JSONSchema } from './types';
+import { SubscriptionManager } from './subscriptions/SubscriptionManager';
+import { WebhookManager } from './webhooks/WebhookManager';
+import { MCPError, AuthenticationError, ValidationError } from './errors';
+import { isValidUrl, isHttpsUrl } from './utils';
+import cors from 'cors';
+
+/**
+ * Default console logger
+ */
+const defaultLogger: Logger = {
+  debug: (msg, meta) => console.debug(msg, meta),
+  info: (msg, meta) => console.info(msg, meta),
+  warn: (msg, meta) => console.warn(msg, meta),
+  error: (msg, meta) => console.error(msg, meta),
+};
+
+/**
+ * Convert JSON Schema to Zod schema (simplified version)
+ * Handles basic types and nested objects
+ */
+function convertToZodSchema(jsonSchema: JSONSchema): Record<string, z.ZodTypeAny> {
+  const schema: Record<string, z.ZodTypeAny> = {};
+  
+  if (!jsonSchema || !jsonSchema.properties) {
+    return schema;
+  }
+  
+  const required = jsonSchema.required || [];
+  
+  for (const [key, value] of Object.entries(jsonSchema.properties)) {
+    let zodType: z.ZodTypeAny;
+    
+    if (value.type === 'string') {
+      zodType = z.string();
+    } else if (value.type === 'number' || value.type === 'integer') {
+      zodType = z.number();
+    } else if (value.type === 'boolean') {
+      zodType = z.boolean();
+    } else if (value.type === 'array') {
+      // Handle array items
+      if (value.items?.type === 'string') {
+        zodType = z.array(z.string());
+      } else if (value.items?.type === 'number') {
+        zodType = z.array(z.number());
+      } else if (value.items?.type === 'object') {
+        zodType = z.array(z.object(convertToZodSchema(value.items as JSONSchema)));
+      } else {
+        zodType = z.array(z.any());
+      }
+    } else if (value.type === 'object') {
+      zodType = z.object(convertToZodSchema(value as JSONSchema));
+    } else {
+      zodType = z.any();
+    }
+    
+    // Mark as optional if not in required array
+    if (!required.includes(key)) {
+      zodType = zodType.optional();
+    }
+    
+    schema[key] = zodType;
+  }
+  
+  return schema;
+}
+
+/**
+ * Create MCP HTTP Webhook Server using standard MCP SDK
+ */
+export function createMCPServer(config: MCPServerConfig): MCPServer {
+  const logger = config.logger || defaultLogger;
+  const basePath = config.basePath || '/mcp';
+  const port = config.port || 3000;
+  const host = config.host || '0.0.0.0';
+
+  // Validate configuration
+  validateConfig(config);
+
+  // Create Express app
+  const app: Express = express();
+
+  // Middleware
+  app.use(express.json());
+  // allow cors
+  app.use(cors());
+  // Custom middleware
+  if (config.middleware) {
+    config.middleware.forEach((mw) => app.use(mw));
+  }
+
+  // Create MCP SDK server
+  const sdkServer = new McpServer(
+    {
+      name: config.name,
+      version: config.version,
+    },
+    {
+      capabilities: {
+        resources: {
+          subscribe: true,
+          listChanged: true,
+        },
+        experimental: {
+          isConnector: true,
+        },
+      },
+    }
+  );
+
+  // Initialize managers for webhook subscriptions
+  const subscriptionManager = new SubscriptionManager(
+    config.store,
+    config.resources,
+    config.publicUrl,
+    logger
+  );
+
+  const webhookManager = new WebhookManager(config.webhooks, config.resources, logger);
+
+  // Register tools with MCP SDK
+  config.tools.forEach((toolDef) => {
+    sdkServer.registerTool(
+      toolDef.name,
+      {
+        title: toolDef.description,
+        description: toolDef.description,
+        inputSchema: convertToZodSchema(toolDef.inputSchema),
+      },
+      async (input) => {
+        // Get auth context from request metadata if available
+        const context = (sdkServer as any)._currentContext || { userId: 'anonymous' };
+        
+        const result = await toolDef.handler(input, context);
+        
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+          structuredContent: result,
+        };
+      }
+    );
+  });
+
+  // Register resources with MCP SDK
+  config.resources.forEach((resourceDef) => {
+    // Check if URI is a template (contains {})
+    const isTemplate = resourceDef.uri.includes('{') && resourceDef.uri.includes('}');
+    
+    if (isTemplate && resourceDef.list) {
+      // Use ResourceTemplate for templated URIs
+      const template = new ResourceTemplate(resourceDef.uri, {
+        list: async () => {
+          const context = (sdkServer as any)._currentContext || { userId: 'anonymous' };
+          const resources = await resourceDef.list!(context);
+          
+          // Map to MCP SDK Resource format with index signature
+          return {
+            resources: resources.map((r: any) => ({
+              uri: r.uri,
+              name: r.name,
+              description: r.description,
+              mimeType: resourceDef.mimeType,
+              ...r, // Spread to add index signature
+            })),
+          };
+        },
+      });
+      sdkServer.registerResource(
+        resourceDef.name,
+        template,
+        {
+          description: resourceDef.description,
+          mimeType: resourceDef.mimeType || 'application/json',
+        },
+        async (uri: any, _variables: any, _extra: any) => {
+          const context = (sdkServer as any)._currentContext || { userId: 'anonymous' };
+          const result = await resourceDef.read(uri.href, context);
+          
+          return {
+            contents: Array.isArray(result.contents)
+              ? result.contents.map((content: any) => ({
+                  uri: uri.href,
+                  text: typeof content === 'string' ? content : JSON.stringify(content),
+                  mimeType: resourceDef.mimeType || 'text/plain',
+                }))
+              : [{
+                  uri: uri.href,
+                  text: typeof result.contents === 'string' ? result.contents : JSON.stringify(result.contents),
+                  mimeType: resourceDef.mimeType || 'text/plain',
+                }],
+          };
+        }
+      );
+    } else {
+      // Static resource - simple URI
+      sdkServer.registerResource(
+        resourceDef.name,
+        resourceDef.uri,
+        {
+          description: resourceDef.description,
+          mimeType: resourceDef.mimeType || 'application/json',
+        },
+        async (uri: any, _extra: any) => {
+          const context = (sdkServer as any)._currentContext || { userId: 'anonymous' };
+          const result = await resourceDef.read(uri.href, context);
+          
+          return {
+            contents: Array.isArray(result.contents)
+              ? result.contents.map((content: any) => ({
+                  uri: uri.href,
+                  text: typeof content === 'string' ? content : JSON.stringify(content),
+                  mimeType: resourceDef.mimeType || 'application/json',
+                }))
+              : [{
+                  uri: uri.href,
+                  text: typeof result.contents === 'string' ? result.contents : JSON.stringify(result.contents),
+                  mimeType: resourceDef.mimeType || 'application/json',
+                }],
+          };
+        }
+      );
+    }
+
+  });
+
+  // Register prompts with MCP SDK
+  if (config.prompts) {
+    config.prompts.forEach((promptDef) => {
+      sdkServer.registerPrompt(
+        promptDef.name,
+        {
+          title: promptDef.name,
+          description: promptDef.description,
+          argsSchema: promptDef.arguments?.reduce(
+            (schema, arg) => {
+              schema[arg.name] = z.string();
+              return schema;
+            },
+            {} as Record<string, any>
+          ) || {},
+        },
+        async (args: any) => {
+          const context = (sdkServer as any)._currentContext || { userId: 'anonymous' };
+          const result = await promptDef.handler(args, context);
+          
+          // Convert to MCP SDK message format
+          return {
+            messages: result.messages.map((msg: any) => ({
+              role: msg.role,
+              content: {
+                type: 'text',
+                text: msg.content,
+              },
+            })),
+          };
+        }
+      );
+    });
+  }
+
+  // Health check endpoints
+  app.get('/health', (_req: any, res: any) => {
+    res.json({ status: 'ok' });
+  });
+
+  app.get('/ready', async (_req: any, res: any) => {
+    try {
+      // Test store connectivity
+      await config.store.set('health-check', 'ok', 10);
+      await config.store.delete('health-check');
+      res.json({ status: 'ready' });
+    } catch (error) {
+      res.status(503).json({ status: 'not ready', error: String(error) });
+    }
+  });
+
+  // Standard MCP endpoint with StreamableHTTPServerTransport
+  app.post(basePath, asyncHandler(async (req, res) => {
+    // Authenticate and store context
+    const context = await authenticate(req, config);
+    (sdkServer as any)._currentContext = context;
+
+    // Intercept resources/subscribe to support webhook callbacks
+    if (req.body.method === 'resources/subscribe') {
+      const { uri } = req.body.params || {};
+      const webhookUrl = req.body.params?._meta?.webhookUrl || req.body.params?.webhookUrl;
+      const webhookSecret = req.body.params?._meta?.webhookSecret || req.body.params?.webhookSecret;
+
+      if (webhookUrl) {
+        // Handle webhook-based subscription
+        logger.info('Standard MCP subscribe with webhook support', { uri, webhookUrl });
+
+        if (!isValidUrl(webhookUrl)) {
+          return res.json({
+            jsonrpc: '2.0',
+            id: req.body.id,
+            error: {
+              code: -32602,
+              message: 'Invalid webhookUrl in _meta'
+            }
+          });
+        }
+
+        try {
+          await subscriptionManager.createSubscription({
+            uri,
+            clientCallbackUrl: webhookUrl,
+            clientCallbackSecret: webhookSecret,
+            context,
+          });
+
+          // Return standard MCP response
+          return res.json({
+            jsonrpc: '2.0',
+            id: req.body.id,
+            method: 'notifications/resources/updated',
+            params: {
+              uri: uri,
+            }
+          });
+        } catch (error: any) {
+          return res.json({
+            jsonrpc: '2.0',
+            id: req.body.id,
+            error: {
+              code: -32603,
+              message: error.message || 'Failed to create subscription'
+            }
+          });
+        }
+      } else {
+        // No webhookUrl - throw error
+        return res.json({
+          jsonrpc: '2.0',
+          id: req.body.id,
+            error: {
+                code: -32602,
+                message: 'Invalid webhookUrl in _meta'
+            }
+        });
+      }
+    }
+
+    // Intercept resources/unsubscribe to support webhook cleanup
+    if (req.body.method === 'resources/unsubscribe') {
+      const subscriptionId = req.body.params?._meta?.subscriptionId || req.body.params?.subscriptionId;
+
+      if (subscriptionId) {
+        logger.info('Standard MCP unsubscribe with webhook cleanup', { subscriptionId });
+
+        try {
+          await subscriptionManager.deleteSubscription(subscriptionId, context);
+
+          return res.json({
+            jsonrpc: '2.0',
+            id: req.body.id,
+            result: {
+              success: true,
+              _meta: {
+                webhookEnabled: true
+              }
+            }
+          });
+        } catch (error: any) {
+          return res.json({
+            jsonrpc: '2.0',
+            id: req.body.id,
+            error: {
+              code: -32603,
+              message: error.message || 'Failed to unsubscribe'
+            }
+          });
+        }
+      }
+    }
+
+    // Standard MCP request handling
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+      enableJsonResponse: true,
+    });
+
+    res.on('close', () => {
+      transport.close();
+      delete (sdkServer as any)._currentContext;
+    });
+
+    await sdkServer.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  }));
+
+  // Additional webhook subscription endpoints (extensions to MCP)
+  app.post(`${basePath}/resources/subscribe`, asyncHandler(async (req, res) => {
+    const context = await authenticate(req, config);
+    const { uri, callbackUrl, callbackSecret } = req.body.params || req.body;
+
+    if (!uri || !callbackUrl) {
+      throw new ValidationError('uri and callbackUrl are required');
+    }
+
+    if (!isValidUrl(callbackUrl)) {
+      throw new ValidationError('Invalid callbackUrl');
+    }
+
+    const result = await subscriptionManager.createSubscription({
+      uri,
+      clientCallbackUrl: callbackUrl,
+      clientCallbackSecret: callbackSecret,
+      context,
+    });
+
+    res.json(result);
+  }));
+
+  app.post(`${basePath}/resources/unsubscribe`, asyncHandler(async (req, res) => {
+    const context = await authenticate(req, config);
+    const { subscriptionId } = req.body.params || req.body;
+
+    if (!subscriptionId) {
+      throw new ValidationError('subscriptionId is required');
+    }
+
+    await subscriptionManager.deleteSubscription(subscriptionId, context);
+
+    res.json({ status: 'unsubscribed' });
+  }));
+
+  // Webhook endpoints
+  const webhookPath = config.webhooks?.incomingPath || '/webhooks/incoming';
+
+  app.post(`${webhookPath}/:subscriptionId`, asyncHandler(async (req, res) => {
+    const { subscriptionId } = req.params;
+    const payload = req.body;
+    const headers = req.headers as Record<string, string>;
+
+    logger.debug('Received webhook', { subscriptionId });
+
+    // Load subscription
+    const subscription = await subscriptionManager.getSubscription(subscriptionId);
+    if (!subscription) {
+      logger.warn('Subscription not found', { subscriptionId });
+      return res.status(404).json({ error: 'Subscription not found' });
+    }
+
+    // Process webhook
+    const changeInfo = await webhookManager.processIncomingWebhook(
+      subscriptionId,
+      payload,
+      headers,
+      subscription
+    );
+
+    if (changeInfo) {
+      // Notify client (async, don't wait)
+      webhookManager.notifyClient(subscription, changeInfo).catch((error) => {
+        logger.error('Failed to notify client', {
+          subscriptionId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      });
+    }
+
+    res.json({ received: true });
+  }));
+
+  // Error handler
+  app.use((err: Error, _req: Request, res: Response, _next: NextFunction) => {
+    if (err instanceof MCPError) {
+      logger.warn('MCP Error', { code: err.code, message: err.message });
+      return res.status(400).json(err.toJSON());
+    }
+
+    logger.error('Unexpected error', {
+      error: err.message,
+      stack: err.stack,
+    });
+
+    res.status(500).json({
+      error: {
+        code: -1,
+        message: 'Internal server error',
+      },
+    });
+  });
+
+  // Server instance
+  let server: any;
+
+  const mcpServer: MCPServer = {
+    async start() {
+      return new Promise((resolve) => {
+        server = app.listen(port, host, () => {
+          logger.info(`MCP Server started`, {
+            name: config.name,
+            version: config.version,
+            host,
+            port,
+            publicUrl: config.publicUrl,
+          });
+          resolve();
+        });
+      });
+    },
+
+    async stop() {
+      if (server) {
+        return new Promise((resolve) => {
+          server.close(() => {
+            logger.info('MCP Server stopped');
+            resolve();
+          });
+        });
+      }
+    },
+
+    getApp() {
+      return app;
+    },
+  };
+
+  return mcpServer;
+}
+
+/**
+ * Validate server configuration
+ */
+function validateConfig(config: MCPServerConfig): void {
+  if (!config.name) {
+    throw new Error('Server name is required');
+  }
+
+  if (!config.version) {
+    throw new Error('Server version is required');
+  }
+
+  if (!config.publicUrl) {
+    throw new Error('publicUrl is required');
+  }
+
+  if (!isValidUrl(config.publicUrl)) {
+    throw new Error('Invalid publicUrl');
+  }
+
+  if (process.env.NODE_ENV === 'production' && !isHttpsUrl(config.publicUrl)) {
+    throw new Error('publicUrl must use HTTPS in production');
+  }
+
+  if (!config.store) {
+    throw new Error('Store is required');
+  }
+
+  if (!Array.isArray(config.tools)) {
+    throw new Error('tools must be an array');
+  }
+
+  if (!Array.isArray(config.resources)) {
+    throw new Error('resources must be an array');
+  }
+}
+
+/**
+ * Authenticate request
+ */
+async function authenticate(req: Request, config: MCPServerConfig) {
+  if (!config.authenticate) {
+    // No authentication configured - return default context
+    return { userId: 'anonymous' };
+  }
+
+  try {
+    return await config.authenticate(req);
+  } catch (error) {
+    throw new AuthenticationError(
+      error instanceof Error ? error.message : 'Authentication failed'
+    );
+  }
+}
+
+/**
+ * Async handler wrapper
+ */
+function asyncHandler(fn: (req: Request, res: Response) => Promise<any>) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    Promise.resolve(fn(req, res)).catch(next);
+  };
+}

package/src/stores/InMemoryStore.ts

@@ -0,0 +1,87 @@
+import { KeyValueStore } from '../types';
+
+/**
+ * In-memory store implementation (for development/testing only)
+ * DO NOT USE IN PRODUCTION
+ */
+export class InMemoryStore implements KeyValueStore {
+  private data: Map<string, { value: string; expiresAt?: number }> = new Map();
+  private cleanupInterval: NodeJS.Timeout;
+
+  constructor() {
+    // Cleanup expired keys every minute
+    this.cleanupInterval = setInterval(() => this.cleanup(), 60000);
+  }
+
+  async get(key: string): Promise<string | null> {
+    const item = this.data.get(key);
+
+    if (!item) {
+      return null;
+    }
+
+    // Check expiration
+    if (item.expiresAt && item.expiresAt < Date.now()) {
+      this.data.delete(key);
+      return null;
+    }
+
+    return item.value;
+  }
+
+  async set(key: string, value: string, ttl?: number): Promise<void> {
+    const item: { value: string; expiresAt?: number } = { value };
+
+    if (ttl) {
+      item.expiresAt = Date.now() + ttl * 1000;
+    }
+
+    this.data.set(key, item);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.data.delete(key);
+  }
+
+  async scan(pattern: string): Promise<string[]> {
+    // Simple glob pattern matching
+    const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+    const keys: string[] = [];
+
+    for (const key of this.data.keys()) {
+      if (regex.test(key)) {
+        keys.push(key);
+      }
+    }
+
+    return keys;
+  }
+
+  /**
+   * Cleanup expired keys
+   */
+  private cleanup(): void {
+    const now = Date.now();
+
+    for (const [key, item] of this.data.entries()) {
+      if (item.expiresAt && item.expiresAt < now) {
+        this.data.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Clear all data
+   */
+  clear(): void {
+    this.data.clear();
+  }
+
+  /**
+   * Destroy store and cleanup interval
+   */
+  destroy(): void {
+    clearInterval(this.cleanupInterval);
+    this.clear();
+  }
+}