webspresso 0.0.91 → 0.0.93

package/plugins/mcp/server.js

@@ -0,0 +1,472 @@
+/**
+ * Webspresso MCP Server Engine
+ * Implements Model Context Protocol (MCP) specification version 2024-11-05
+ * Pure Node.js JSON-RPC 2.0 router with tools, resources, and prompts registry.
+ * @module plugins/mcp/server
+ */
+
+const EventEmitter = require('events');
+
+const PROTOCOL_VERSION = '2024-11-05';
+
+// Standard JSON-RPC 2.0 error codes
+const ERROR_CODES = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+};
+
+/**
+ * Creates a standard JSON-RPC 2.0 success response
+ * @param {string|number|null} id
+ * @param {*} result
+ * @returns {Object}
+ */
+function createJsonRpcResponse(id, result) {
+  return {
+    jsonrpc: '2.0',
+    id: id !== undefined ? id : null,
+    result,
+  };
+}
+
+/**
+ * Creates a standard JSON-RPC 2.0 error response
+ * @param {string|number|null} id
+ * @param {number} code
+ * @param {string} message
+ * @param {*} [data]
+ * @returns {Object}
+ */
+function createJsonRpcError(id, code, message, data) {
+  const errorObj = { code, message };
+  if (data !== undefined) {
+    errorObj.data = data;
+  }
+  return {
+    jsonrpc: '2.0',
+    id: id !== undefined ? id : null,
+    error: errorObj,
+  };
+}
+
+class McpServer extends EventEmitter {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.name='webspresso-mcp']
+   * @param {string} [options.version='1.0.0']
+   * @param {string} [options.instructions]
+   * @param {Object} [options.context]
+   */
+  constructor(options = {}) {
+    super();
+    this.name = options.name || 'webspresso-mcp';
+    this.version = options.version || '1.0.0';
+    this.instructions =
+      options.instructions ||
+      'Webspresso Model Context Protocol server exposing services, ORM models, and system capabilities.';
+    this.context = options.context || {};
+
+    // Registries
+    this.tools = new Map();
+    this.resources = new Map();
+    this.resourceTemplates = [];
+    this.prompts = new Map();
+
+    // Client session info after initialize
+    this.clientInfo = null;
+    this.isInitialized = false;
+  }
+
+  /**
+   * Register an MCP tool
+   * @param {Object} toolDef
+   * @param {string} toolDef.name
+   * @param {string} [toolDef.description]
+   * @param {Object} [toolDef.inputSchema] - JSON Schema object
+   * @param {function(Object, Object): Promise<*>|*} toolDef.handler
+   * @returns {this}
+   */
+  registerTool(toolDef) {
+    if (!toolDef || !toolDef.name) {
+      throw new Error('Tool must have a name');
+    }
+    if (typeof toolDef.handler !== 'function') {
+      throw new Error(`Tool "${toolDef.name}" must have a handler function`);
+    }
+
+    this.tools.set(toolDef.name, {
+      name: toolDef.name,
+      description: toolDef.description || '',
+      inputSchema: toolDef.inputSchema || {
+        type: 'object',
+        properties: {},
+        additionalProperties: true,
+      },
+      handler: toolDef.handler,
+    });
+    return this;
+  }
+
+  /**
+   * Register multiple tools
+   * @param {Array<Object>} toolDefs
+   * @returns {this}
+   */
+  registerTools(toolDefs = []) {
+    for (const tool of toolDefs) {
+      this.registerTool(tool);
+    }
+    return this;
+  }
+
+  /**
+   * Remove a registered tool
+   * @param {string} name
+   * @returns {boolean}
+   */
+  unregisterTool(name) {
+    return this.tools.delete(name);
+  }
+
+  /**
+   * Register an MCP resource
+   * @param {Object} resourceDef
+   * @param {string} resourceDef.uri
+   * @param {string} [resourceDef.name]
+   * @param {string} [resourceDef.description]
+   * @param {string} [resourceDef.mimeType='application/json']
+   * @param {function(string, Object): Promise<*>|*} resourceDef.handler
+   * @returns {this}
+   */
+  registerResource(resourceDef) {
+    if (!resourceDef || !resourceDef.uri) {
+      throw new Error('Resource must have a uri');
+    }
+    if (typeof resourceDef.handler !== 'function') {
+      throw new Error(`Resource "${resourceDef.uri}" must have a handler function`);
+    }
+
+    this.resources.set(resourceDef.uri, {
+      uri: resourceDef.uri,
+      name: resourceDef.name || resourceDef.uri,
+      description: resourceDef.description || '',
+      mimeType: resourceDef.mimeType || 'application/json',
+      handler: resourceDef.handler,
+    });
+    return this;
+  }
+
+  /**
+   * Register a parameterized resource template
+   * @param {Object} templateDef
+   * @param {string} templateDef.uriTemplate - e.g. "webspresso://models/{model}"
+   * @param {string} [templateDef.name]
+   * @param {string} [templateDef.description]
+   * @param {string} [templateDef.mimeType='application/json']
+   * @param {function(string, Object, Object): Promise<*>|*} templateDef.handler - (uri, params, ctx)
+   * @returns {this}
+   */
+  registerResourceTemplate(templateDef) {
+    if (!templateDef || !templateDef.uriTemplate) {
+      throw new Error('Resource template must have a uriTemplate');
+    }
+    if (typeof templateDef.handler !== 'function') {
+      throw new Error(`Resource template "${templateDef.uriTemplate}" must have a handler function`);
+    }
+
+    // Convert uriTemplate to regex for matching
+    const paramNames = [];
+    const patternStr = templateDef.uriTemplate.replace(/\{([a-zA-Z0-9_]+)\}/g, (_, name) => {
+      paramNames.push(name);
+      return '([^/]+)';
+    });
+    const regex = new RegExp(`^${patternStr}$`);
+
+    this.resourceTemplates.push({
+      uriTemplate: templateDef.uriTemplate,
+      name: templateDef.name || templateDef.uriTemplate,
+      description: templateDef.description || '',
+      mimeType: templateDef.mimeType || 'application/json',
+      handler: templateDef.handler,
+      regex,
+      paramNames,
+    });
+    return this;
+  }
+
+  /**
+   * Register an MCP prompt template
+   * @param {Object} promptDef
+   * @param {string} promptDef.name
+   * @param {string} [promptDef.description]
+   * @param {Array<Object>} [promptDef.arguments]
+   * @param {function(Object, Object): Promise<*>|*} promptDef.handler
+   * @returns {this}
+   */
+  registerPrompt(promptDef) {
+    if (!promptDef || !promptDef.name) {
+      throw new Error('Prompt must have a name');
+    }
+    if (typeof promptDef.handler !== 'function') {
+      throw new Error(`Prompt "${promptDef.name}" must have a handler function`);
+    }
+
+    this.prompts.set(promptDef.name, {
+      name: promptDef.name,
+      description: promptDef.description || '',
+      arguments: promptDef.arguments || [],
+      handler: promptDef.handler,
+    });
+    return this;
+  }
+
+  /**
+   * Handle incoming JSON-RPC 2.0 message
+   * @param {Object} message - Parsed JSON-RPC message object
+   * @param {Object} [callContext={}] - Extra context per call (e.g. req, db)
+   * @returns {Promise<Object|null>} Response object or null if notification
+   */
+  async handleMessage(message, callContext = {}) {
+    if (!message || typeof message !== 'object') {
+      return createJsonRpcError(null, ERROR_CODES.INVALID_REQUEST, 'Invalid Request: Message must be an object');
+    }
+
+    const { id, method, params } = message;
+    const isNotification = id === undefined || id === null;
+
+    // Notifications without response
+    if (method === 'notifications/initialized') {
+      this.isInitialized = true;
+      this.emit('initialized', params);
+      return null;
+    }
+
+    if (method === 'notifications/cancelled') {
+      this.emit('cancelled', params);
+      return null;
+    }
+
+    // Request handlers
+    try {
+      switch (method) {
+        case 'initialize': {
+          this.clientInfo = params?.clientInfo || null;
+          return createJsonRpcResponse(id, {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {
+              tools: { listChanged: true },
+              resources: { subscribe: false, listChanged: true },
+              prompts: { listChanged: true },
+              logging: {},
+            },
+            serverInfo: {
+              name: this.name,
+              version: this.version,
+            },
+            instructions: this.instructions,
+          });
+        }
+
+        case 'ping': {
+          return createJsonRpcResponse(id, {});
+        }
+
+        case 'tools/list': {
+          const toolsList = [];
+          for (const tool of this.tools.values()) {
+            toolsList.push({
+              name: tool.name,
+              description: tool.description,
+              inputSchema: tool.inputSchema,
+            });
+          }
+          return createJsonRpcResponse(id, { tools: toolsList });
+        }
+
+        case 'tools/call': {
+          if (!params || !params.name) {
+            return createJsonRpcError(id, ERROR_CODES.INVALID_PARAMS, 'Missing tool name in params');
+          }
+
+          const tool = this.tools.get(params.name);
+          if (!tool) {
+            return createJsonRpcResponse(id, {
+              content: [
+                {
+                  type: 'text',
+                  text: `Error: Tool "${params.name}" not found.`,
+                },
+              ],
+              isError: true,
+            });
+          }
+
+          try {
+            const mergedCtx = { ...this.context, ...callContext };
+            const args = params.arguments || {};
+            const result = await tool.handler(args, mergedCtx);
+
+            // Format result according to MCP specs
+            let content;
+            if (result && Array.isArray(result.content)) {
+              content = result.content;
+            } else if (typeof result === 'string') {
+              content = [{ type: 'text', text: result }];
+            } else {
+              content = [{ type: 'text', text: JSON.stringify(result, null, 2) }];
+            }
+
+            return createJsonRpcResponse(id, {
+              content,
+              isError: Boolean(result?.isError),
+            });
+          } catch (err) {
+            return createJsonRpcResponse(id, {
+              content: [
+                {
+                  type: 'text',
+                  text: `Tool execution failed: ${err.message}`,
+                },
+              ],
+              isError: true,
+            });
+          }
+        }
+
+        case 'resources/list': {
+          const resourceList = [];
+          for (const res of this.resources.values()) {
+            resourceList.push({
+              uri: res.uri,
+              name: res.name,
+              description: res.description,
+              mimeType: res.mimeType,
+            });
+          }
+          return createJsonRpcResponse(id, { resources: resourceList });
+        }
+
+        case 'resources/templates/list': {
+          const templateList = this.resourceTemplates.map((t) => ({
+            uriTemplate: t.uriTemplate,
+            name: t.name,
+            description: t.description,
+            mimeType: t.mimeType,
+          }));
+          return createJsonRpcResponse(id, { resourceTemplates: templateList });
+        }
+
+        case 'resources/read': {
+          if (!params || !params.uri) {
+            return createJsonRpcError(id, ERROR_CODES.INVALID_PARAMS, 'Missing uri in params');
+          }
+
+          const uri = params.uri;
+          const mergedCtx = { ...this.context, ...callContext };
+
+          // Direct resource match
+          if (this.resources.has(uri)) {
+            const res = this.resources.get(uri);
+            const data = await res.handler(uri, mergedCtx);
+            const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+            return createJsonRpcResponse(id, {
+              contents: [
+                {
+                  uri,
+                  mimeType: res.mimeType,
+                  text,
+                },
+              ],
+            });
+          }
+
+          // Template matching
+          for (const tmpl of this.resourceTemplates) {
+            const match = uri.match(tmpl.regex);
+            if (match) {
+              const matchedParams = {};
+              tmpl.paramNames.forEach((name, idx) => {
+                matchedParams[name] = match[idx + 1];
+              });
+
+              const data = await tmpl.handler(uri, matchedParams, mergedCtx);
+              const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+              return createJsonRpcResponse(id, {
+                contents: [
+                  {
+                    uri,
+                    mimeType: tmpl.mimeType,
+                    text,
+                  },
+                ],
+              });
+            }
+          }
+
+          return createJsonRpcError(id, ERROR_CODES.INVALID_PARAMS, `Resource not found: ${uri}`);
+        }
+
+        case 'prompts/list': {
+          const promptsList = [];
+          for (const prompt of this.prompts.values()) {
+            promptsList.push({
+              name: prompt.name,
+              description: prompt.description,
+              arguments: prompt.arguments,
+            });
+          }
+          return createJsonRpcResponse(id, { prompts: promptsList });
+        }
+
+        case 'prompts/get': {
+          if (!params || !params.name) {
+            return createJsonRpcError(id, ERROR_CODES.INVALID_PARAMS, 'Missing prompt name in params');
+          }
+
+          const prompt = this.prompts.get(params.name);
+          if (!prompt) {
+            return createJsonRpcError(id, ERROR_CODES.INVALID_PARAMS, `Prompt "${params.name}" not found`);
+          }
+
+          const mergedCtx = { ...this.context, ...callContext };
+          const args = params.arguments || {};
+          const result = await prompt.handler(args, mergedCtx);
+
+          return createJsonRpcResponse(id, {
+            description: prompt.description,
+            messages: Array.isArray(result?.messages)
+              ? result.messages
+              : [
+                  {
+                    role: 'user',
+                    content: {
+                      type: 'text',
+                      text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                    },
+                  },
+                ],
+          });
+        }
+
+        default: {
+          if (isNotification) return null;
+          return createJsonRpcError(id, ERROR_CODES.METHOD_NOT_FOUND, `Method "${method}" not found`);
+        }
+      }
+    } catch (err) {
+      if (isNotification) return null;
+      return createJsonRpcError(id, ERROR_CODES.INTERNAL_ERROR, err.message);
+    }
+  }
+}
+
+module.exports = {
+  McpServer,
+  PROTOCOL_VERSION,
+  ERROR_CODES,
+  createJsonRpcResponse,
+  createJsonRpcError,
+};

package/plugins/mcp/transports/sse.js

@@ -0,0 +1,139 @@
+/**
+ * Webspresso MCP HTTP & SSE Transport
+ * Implements MCP HTTP endpoints (Server-Sent Events + HTTP POST message endpoint)
+ * @module plugins/mcp/transports/sse
+ */
+
+const crypto = require('crypto');
+const { createJsonRpcError, ERROR_CODES } = require('../server');
+
+/**
+ * Mounts MCP SSE and HTTP POST routes onto Express app
+ * @param {Object} options
+ * @param {import('express').Express} options.app
+ * @param {import('../server').McpServer} options.server
+ * @param {string} [options.path='/_mcp']
+ * @param {import('express').RequestHandler} [options.authMiddleware]
+ * @returns {{ sessions: Map<string, Object> }}
+ */
+function mountSseTransport(options) {
+  const { app, server, path: basePath = '/_mcp', authMiddleware } = options;
+
+  const normalizedBase = basePath.replace(/\/+$/, '');
+  const sessions = new Map();
+
+  const middlewareChain = authMiddleware ? [authMiddleware] : [];
+
+  // 1. GET /_mcp/sse - Server-Sent Events initiation
+  app.get(`${normalizedBase}/sse`, ...middlewareChain, (req, res) => {
+    // Check if compression is enabled on res, opt-out for SSE
+    if (typeof res.compress === 'function') {
+      res.compress(false);
+    }
+
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache, no-transform',
+      'Connection': 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    });
+    if (typeof res.flushHeaders === 'function') {
+      res.flushHeaders();
+    }
+
+    const sessionId = crypto.randomUUID ? crypto.randomUUID() : crypto.randomBytes(16).toString('hex');
+    const endpointUri = `${normalizedBase}/messages?sessionId=${sessionId}`;
+
+    const sessionObj = {
+      id: sessionId,
+      req,
+      res,
+      send: (data) => {
+        try {
+          res.write(`event: message\ndata: ${JSON.stringify(data)}\n\n`);
+          if (typeof res.flush === 'function') res.flush();
+        } catch (err) {
+          console.warn(`[mcp-sse] Failed to write to session ${sessionId}:`, err.message);
+        }
+      },
+    };
+
+    sessions.set(sessionId, sessionObj);
+
+    // Send initial endpoint event per MCP spec
+    res.write(`event: endpoint\ndata: ${endpointUri}\n\n`);
+    if (typeof res.flush === 'function') {
+      res.flush();
+    }
+
+    // Ping interval to keep connection alive through proxies
+    const keepAlive = setInterval(() => {
+      try {
+        res.write(': ping\n\n');
+      } catch (e) {
+        clearInterval(keepAlive);
+      }
+    }, 15000);
+
+    req.on('close', () => {
+      clearInterval(keepAlive);
+      sessions.delete(sessionId);
+    });
+  });
+
+  // 2. POST /_mcp/messages - MCP message ingestion for an active SSE session
+  app.post(`${normalizedBase}/messages`, ...middlewareChain, async (req, res) => {
+    const sessionId = req.query?.sessionId;
+    if (!sessionId) {
+      return res.status(400).json(createJsonRpcError(null, ERROR_CODES.INVALID_PARAMS, 'Missing sessionId query parameter'));
+    }
+
+    const session = sessions.get(sessionId);
+    if (!session) {
+      return res.status(404).json(createJsonRpcError(null, ERROR_CODES.INVALID_PARAMS, `Active SSE session "${sessionId}" not found`));
+    }
+
+    const message = req.body;
+    if (!message || typeof message !== 'object') {
+      return res.status(400).json(createJsonRpcError(null, ERROR_CODES.PARSE_ERROR, 'Invalid JSON body'));
+    }
+
+    try {
+      const callCtx = { req, res, db: req.db, service: req.service };
+      const response = await server.handleMessage(message, callCtx);
+
+      if (response) {
+        session.send(response);
+      }
+
+      return res.status(202).send('Accepted');
+    } catch (err) {
+      return res.status(500).json(createJsonRpcError(message?.id || null, ERROR_CODES.INTERNAL_ERROR, err.message));
+    }
+  });
+
+  // 3. POST /_mcp - Direct Streamable HTTP endpoint for single-turn JSON-RPC execution
+  app.post(`${normalizedBase}`, ...middlewareChain, async (req, res) => {
+    const message = req.body;
+    if (!message || typeof message !== 'object') {
+      return res.status(400).json(createJsonRpcError(null, ERROR_CODES.PARSE_ERROR, 'Invalid JSON body'));
+    }
+
+    try {
+      const callCtx = { req, res, db: req.db, service: req.service };
+      const response = await server.handleMessage(message, callCtx);
+      if (!response) {
+        return res.status(204).end();
+      }
+      return res.json(response);
+    } catch (err) {
+      return res.status(500).json(createJsonRpcError(message?.id || null, ERROR_CODES.INTERNAL_ERROR, err.message));
+    }
+  });
+
+  return { sessions };
+}
+
+module.exports = {
+  mountSseTransport,
+};

package/plugins/mcp/transports/stdio.js

@@ -0,0 +1,108 @@
+/**
+ * Webspresso MCP Stdio Transport
+ * Runs MCP server over standard input and standard output (JSON-RPC 2.0 lines).
+ * Redirects console.log to process.stderr to prevent JSON-RPC stream corruption.
+ * @module plugins/mcp/transports/stdio
+ */
+
+const readline = require('readline');
+const { ERROR_CODES, createJsonRpcError } = require('../server');
+
+let originalConsoleLog = null;
+let originalConsoleInfo = null;
+
+/**
+ * Redirects standard console logs to stderr
+ */
+function redirectConsoleToStderr() {
+  if (originalConsoleLog) return;
+  originalConsoleLog = console.log;
+  originalConsoleInfo = console.info;
+
+  console.log = (...args) => {
+    process.stderr.write(`${args.map((a) => (typeof a === 'object' ? JSON.stringify(a) : a)).join(' ')}\n`);
+  };
+  console.info = (...args) => {
+    process.stderr.write(`${args.map((a) => (typeof a === 'object' ? JSON.stringify(a) : a)).join(' ')}\n`);
+  };
+}
+
+/**
+ * Restores original console log functions
+ */
+function restoreConsole() {
+  if (originalConsoleLog) {
+    console.log = originalConsoleLog;
+    originalConsoleLog = null;
+  }
+  if (originalConsoleInfo) {
+    console.info = originalConsoleInfo;
+    originalConsoleInfo = null;
+  }
+}
+
+/**
+ * Starts Stdio transport for an MCP Server
+ * @param {import('../server').McpServer} server
+ * @param {Object} [options]
+ * @param {ReadableStream} [options.input=process.stdin]
+ * @param {WritableStream} [options.output=process.stdout]
+ * @param {boolean} [options.redirectStderr=true]
+ * @returns {{ close: Function, rl: readline.Interface }}
+ */
+function startStdioTransport(server, options = {}) {
+  const input = options.input || process.stdin;
+  const output = options.output || process.stdout;
+  const shouldRedirect = options.redirectStderr !== false;
+
+  if (shouldRedirect) {
+    redirectConsoleToStderr();
+  }
+
+  const rl = readline.createInterface({
+    input,
+    output: null,
+    terminal: false,
+  });
+
+  const sendResponse = (msg) => {
+    if (msg) {
+      output.write(`${JSON.stringify(msg)}\n`);
+    }
+  };
+
+  rl.on('line', async (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (err) {
+      sendResponse(createJsonRpcError(null, ERROR_CODES.PARSE_ERROR, `Parse error: ${err.message}`));
+      return;
+    }
+
+    try {
+      const response = await server.handleMessage(parsed);
+      sendResponse(response);
+    } catch (err) {
+      sendResponse(createJsonRpcError(parsed?.id || null, ERROR_CODES.INTERNAL_ERROR, err.message));
+    }
+  });
+
+  const close = () => {
+    rl.close();
+    if (shouldRedirect) {
+      restoreConsole();
+    }
+  };
+
+  return { close, rl };
+}
+
+module.exports = {
+  startStdioTransport,
+  redirectConsoleToStderr,
+  restoreConsole,
+};