webspresso 0.0.91 → 0.0.94

package/plugins/mcp/index.js

@@ -0,0 +1,208 @@
+/**
+ * Webspresso Model Context Protocol (MCP) Plugin
+ * Connects Webspresso applications to AI agents, IDEs, and LLM tools.
+ * @module plugins/mcp
+ */
+
+const { McpServer } = require('./server');
+const { createServiceTools } = require('./providers/services');
+const { createOrmTools, createOrmResources } = require('./providers/orm');
+const { createSystemResources } = require('./providers/system');
+const { createBuiltinPrompts } = require('./prompts');
+const { createMcpAuthMiddleware } = require('./auth');
+const { mountSseTransport } = require('./transports/sse');
+const { startStdioTransport, redirectConsoleToStderr, restoreConsole } = require('./transports/stdio');
+const { discoverMcpDirectory } = require('./discovery');
+
+const { getServiceRegistry, hasServiceRegistry } = require('../../src/app-context');
+
+/**
+ * MCP Plugin Factory
+ * @param {Object} [options={}]
+ * @param {string} [options.path='/_mcp'] - Route path for HTTP & SSE endpoints
+ * @param {boolean} [options.enabled=true] - Whether the plugin is active
+ * @param {Object} [options.auth] - Authentication options { token, localhostOnly, verify }
+ * @param {Object|boolean} [options.services] - Services auto-bridge config
+ * @param {Object|boolean} [options.orm] - ORM auto-bridge config
+ * @param {Object|boolean} [options.system] - System resources config
+ * @param {Array<Object>} [options.tools] - Additional custom tools
+ * @param {Array<Object>} [options.resources] - Additional custom resources
+ * @param {Array<Object>} [options.prompts] - Additional custom prompts
+ * @param {boolean} [options.discovery=true] - Auto-discover mcp/ folder
+ * @param {string} [options.name='webspresso-mcp'] - Server name
+ * @param {string} [options.version='1.0.0'] - Server version
+ * @param {string} [options.instructions] - Instructions for the LLM
+ * @returns {Object} Webspresso plugin definition
+ */
+function mcpPlugin(options = {}) {
+  const {
+    path = '/_mcp',
+    enabled = true,
+    auth = {},
+    services: servicesOption = true,
+    orm: ormOption = true,
+    system: systemOption = true,
+    tools: extraTools = [],
+    resources: extraResources = [],
+    prompts: extraPrompts = [],
+    discovery = true,
+    name = 'webspresso-mcp',
+    version = '1.0.0',
+    instructions,
+  } = options;
+
+  let serverInstance = null;
+
+  return {
+    name: 'mcp',
+    version: '1.0.0',
+    dependencies: [],
+
+    api: {
+      getServer: () => serverInstance,
+      registerTool: (tool) => serverInstance && serverInstance.registerTool(tool),
+      registerResource: (res) => serverInstance && serverInstance.registerResource(res),
+      registerPrompt: (prompt) => serverInstance && serverInstance.registerPrompt(prompt),
+    },
+
+    register(ctx) {
+      if (!enabled) return;
+
+      serverInstance = new McpServer({
+        name,
+        version,
+        instructions,
+        context: {
+          app: ctx.app,
+        },
+      });
+
+      // Register initial custom tools, resources, prompts
+      if (Array.isArray(extraTools)) {
+        serverInstance.registerTools(extraTools);
+      }
+      if (Array.isArray(extraResources)) {
+        for (const res of extraResources) {
+          if (res.uriTemplate) {
+            serverInstance.registerResourceTemplate(res);
+          } else {
+            serverInstance.registerResource(res);
+          }
+        }
+      }
+      if (Array.isArray(extraPrompts)) {
+        for (const prompt of extraPrompts) {
+          serverInstance.registerPrompt(prompt);
+        }
+      }
+
+      // Register built-in prompts
+      const builtinPrompts = createBuiltinPrompts();
+      for (const p of builtinPrompts) {
+        serverInstance.registerPrompt(p);
+      }
+
+      // Expose to ctx
+      ctx.mcp = {
+        server: serverInstance,
+        registerTool: (t) => serverInstance.registerTool(t),
+        registerResource: (r) => serverInstance.registerResource(r),
+        registerPrompt: (p) => serverInstance.registerPrompt(p),
+      };
+    },
+
+    onRoutesReady(ctx) {
+      if (!enabled || !serverInstance) return;
+
+      const { app, db, routes } = ctx;
+      serverInstance.context.db = db;
+
+      // 1. Resolve ServiceRegistry
+      let registry = null;
+      if (ctx.options?.serviceRegistry) {
+        registry = ctx.options.serviceRegistry;
+      } else if (hasServiceRegistry()) {
+        registry = getServiceRegistry();
+      }
+      serverInstance.context.serviceRegistry = registry;
+
+      // 2. Auto-bridge Services to MCP Tools
+      if (servicesOption && registry) {
+        const sOpts = typeof servicesOption === 'object' ? servicesOption : {};
+        const serviceTools = createServiceTools({
+          registry,
+          include: sOpts.include,
+          exclude: sOpts.exclude,
+          readOnly: Boolean(sOpts.readOnly),
+          role: sOpts.role || 'admin',
+        });
+        serverInstance.registerTools(serviceTools);
+      }
+
+      // 3. Auto-bridge ORM Models to MCP Tools and Resources
+      if (ormOption && db) {
+        const oOpts = typeof ormOption === 'object' ? ormOption : {};
+        const ormTools = createOrmTools({
+          db,
+          readOnly: Boolean(oOpts.readOnly),
+          models: oOpts.models,
+        });
+        serverInstance.registerTools(ormTools);
+
+        const { resources, templates } = createOrmResources({ db });
+        for (const r of resources) {
+          serverInstance.registerResource(r);
+        }
+        for (const t of templates) {
+          serverInstance.registerResourceTemplate(t);
+        }
+      }
+
+      // 4. Auto-bridge System Resources
+      if (systemOption) {
+        const sysResources = createSystemResources({
+          appContext: ctx,
+          serviceRegistry: registry,
+          routes,
+          db,
+        });
+        for (const r of sysResources) {
+          serverInstance.registerResource(r);
+        }
+      }
+
+      // 5. Auto-discover custom items from mcp/ directory
+      if (discovery) {
+        discoverMcpDirectory(serverInstance, process.cwd());
+      }
+
+      // 6. Mount HTTP & SSE Transport on Express
+      const authMiddleware =
+        auth.token || auth.localhostOnly || auth.verify ? createMcpAuthMiddleware(auth) : null;
+
+      mountSseTransport({
+        app,
+        server: serverInstance,
+        path,
+        authMiddleware,
+      });
+    },
+  };
+}
+
+module.exports = {
+  mcpPlugin,
+  McpServer,
+  createMcpServer: (opts) => new McpServer(opts),
+  startStdioTransport,
+  mountSseTransport,
+  createMcpAuthMiddleware,
+  createServiceTools,
+  createOrmTools,
+  createOrmResources,
+  createSystemResources,
+  createBuiltinPrompts,
+  discoverMcpDirectory,
+  redirectConsoleToStderr,
+  restoreConsole,
+};

package/plugins/mcp/prompts.js

@@ -0,0 +1,149 @@
+/**
+ * Webspresso MCP Built-in Prompt Templates
+ * Provides standard LLM prompt templates following Webspresso architectural guidelines.
+ * @module plugins/mcp/prompts
+ */
+
+/**
+ * Generates built-in prompt definitions
+ * @returns {Array<Object>}
+ */
+function createBuiltinPrompts() {
+  return [
+    {
+      name: 'scaffold_service',
+      description: 'Generates a Webspresso service file adhering to strict architecture guidelines.',
+      arguments: [
+        {
+          name: 'serviceName',
+          description: 'Dot-notation service name (e.g. "order.cancel" or "user.invite")',
+          required: true,
+        },
+        {
+          name: 'description',
+          description: 'Brief description of what the service does',
+          required: false,
+        },
+      ],
+      handler: async ({ serviceName, description = '' }) => {
+        const parts = serviceName.split('.');
+        const domain = parts.slice(0, -1).join('/');
+        const action = parts[parts.length - 1];
+        const filePath = `services/${domain ? `${domain}/` : ''}${action}.js`;
+
+        return {
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `Please generate a Webspresso service file for "${serviceName}" at path "${filePath}".
+Description: ${description || 'N/A'}
+
+Follow Webspresso rules:
+- Export an object with { schema, auth, timeout, transaction, handler }.
+- Use Zod (const { z } = require('zod');) for schema validation.
+- Set transaction: true if multi-step mutation.
+- Use req.db / ctx.db.getRepository('ModelName') to access data. NEVER write raw knex table queries.
+- Throw semantic errors: NotFoundError, ValidationError, UnauthorizedError, ForbiddenError.
+- Do NOT use controllers.`,
+              },
+            },
+          ],
+        };
+      },
+    },
+    {
+      name: 'scaffold_model',
+      description: 'Generates an ORM model file using defineModel and zdb schema builder.',
+      arguments: [
+        {
+          name: 'modelName',
+          description: 'PascalCase model name (e.g. "Product", "Invoice")',
+          required: true,
+        },
+        {
+          name: 'tableName',
+          description: 'Database table name (e.g. "products", "invoices")',
+          required: false,
+        },
+      ],
+      handler: async ({ modelName, tableName }) => {
+        const table = tableName || `${modelName.toLowerCase()}s`;
+        const filePath = `models/${modelName.toLowerCase()}.js`;
+
+        return {
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `Please generate a Webspresso ORM model for "${modelName}" (table: "${table}") at path "${filePath}".
+
+Follow Webspresso rules:
+- Use const { defineModel, zdb } = require('webspresso');
+- Use defineModel({ name, table, schema, relations, scopes, hidden, admin }).
+- Build schema with zdb: zdb.id(), zdb.string(), zdb.integer(), zdb.boolean(), zdb.json(), zdb.dateTime().
+- Define relations if relevant (hasMany, belongsTo).
+- Enable admin: { enabled: true, icon: '...' } if appropriate.`,
+              },
+            },
+          ],
+        };
+      },
+    },
+    {
+      name: 'scaffold_api',
+      description: 'Generates a file-based API route module inside pages/api/...',
+      arguments: [
+        {
+          name: 'endpoint',
+          description: 'API endpoint route (e.g. "/api/notes" or "/api/notes/[id]")',
+          required: true,
+        },
+        {
+          name: 'method',
+          description: 'HTTP method (GET, POST, PUT, PATCH, DELETE)',
+          required: true,
+        },
+      ],
+      handler: async ({ endpoint, method }) => {
+        const m = method.toLowerCase();
+        let relativePath = endpoint.replace(/^\/api\//, '');
+        const filePath = `pages/api/${relativePath}.${m}.js`;
+
+        return {
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `Please generate a Webspresso API route file at "${filePath}".
+Endpoint: ${method.toUpperCase()} ${endpoint}
+
+Follow Webspresso rules:
+- 100% File-Based Routing: NEVER create a routes/ folder or use express.Router().
+- Standard API Route Module Contract:
+  module.exports = {
+    schema: ({ z }) => ({
+      body: z.object({...}),
+      params: z.object({...}),
+    }),
+    middleware: [],
+    handler: async (req, res) => {
+      // req.db and req.service are injected
+      // req.input contains validated { body, query, params }
+    }
+  };`,
+              },
+            },
+          ],
+        };
+      },
+    },
+  ];
+}
+
+module.exports = {
+  createBuiltinPrompts,
+};

package/plugins/mcp/providers/orm.js

@@ -0,0 +1,325 @@
+/**
+ * Webspresso MCP ORM Provider
+ * Bridges Webspresso ORM models to MCP Tools and Resources
+ * @module plugins/mcp/providers/orm
+ */
+
+const { getAllModels } = require('../../../core/orm/model');
+const { convertZodToInputSchema } = require('./services');
+
+/**
+ * Describe a model's schema, columns, and relations
+ * @param {import('../../../core/orm/types').ModelDefinition} model
+ * @returns {Object}
+ */
+function describeModel(model) {
+  if (!model) return null;
+
+  const columns = {};
+  if (model.columns instanceof Map) {
+    for (const [colName, colMeta] of model.columns.entries()) {
+      columns[colName] = {
+        type: colMeta.type || 'unknown',
+        nullable: Boolean(colMeta.nullable),
+        primaryKey: Boolean(colMeta.primaryKey),
+        unique: Boolean(colMeta.unique),
+        default: colMeta.default,
+      };
+    }
+  }
+
+  // Also extract fields from schema shape if available
+  if (model.schema && model.schema.shape) {
+    for (const [key, val] of Object.entries(model.schema.shape)) {
+      if (!columns[key]) {
+        columns[key] = {
+          type: val._def?.typeName?.replace(/^Zod/, '').toLowerCase() || 'unknown',
+          nullable: val.isNullable ? val.isNullable() : false,
+          optional: val.isOptional ? val.isOptional() : false,
+        };
+      }
+    }
+  }
+
+  const relations = {};
+  if (model.relations) {
+    for (const [relName, relMeta] of Object.entries(model.relations)) {
+      let targetName = relMeta.targetModel;
+      if (!targetName && typeof relMeta.model === 'function') {
+        try {
+          const res = relMeta.model();
+          targetName = typeof res === 'string' ? res : res?.name;
+        } catch (e) {}
+      }
+      relations[relName] = {
+        type: relMeta.type,
+        targetModel: targetName,
+        foreignKey: relMeta.foreignKey,
+      };
+    }
+  }
+
+  return {
+    name: model.name,
+    table: model.table,
+    primaryKey: model.primaryKey || 'id',
+    columns,
+    relations,
+    hidden: model.hidden || [],
+    softDelete: Boolean(model.softDelete),
+    admin: model.admin || null,
+  };
+}
+
+/**
+ * Creates ORM-related MCP tools
+ * @param {Object} options
+ * @param {Object} options.db - Webspresso database instance
+ * @param {boolean} [options.readOnly=false]
+ * @param {Array<string>} [options.models] - Whitelist of model names
+ * @returns {Array<Object>}
+ */
+function createOrmTools(options = {}) {
+  const { db, readOnly = false, models: modelWhitelist } = options;
+  if (!db) return [];
+
+  const tools = [
+    {
+      name: 'orm_describe_model',
+      description: 'Get detailed metadata, columns, types, relations, and settings for a given ORM model.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          model: {
+            type: 'string',
+            description: 'Name of the model (e.g. "User", "Product")',
+          },
+        },
+        required: ['model'],
+      },
+      handler: async ({ model }) => {
+        const modelDef = db.getModel ? db.getModel(model) : null;
+        if (!modelDef) {
+          throw new Error(`Model "${model}" not found in registered database models.`);
+        }
+        return describeModel(modelDef);
+      },
+    },
+    {
+      name: 'orm_find',
+      description: 'Query records from an ORM model using where filters, pagination, and sorting.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          model: { type: 'string', description: 'Model name' },
+          where: { type: 'object', description: 'Filter key-value pairs (e.g. {"status": "active"})' },
+          limit: { type: 'number', description: 'Maximum number of records (default: 20, max: 100)' },
+          page: { type: 'number', description: 'Page number (default: 1)' },
+          sort: { type: 'string', description: 'Column to sort by' },
+          order: { type: 'string', enum: ['asc', 'desc'], description: 'Sort order' },
+        },
+        required: ['model'],
+      },
+      handler: async ({ model, where = {}, limit = 20, page = 1, sort, order = 'asc' }) => {
+        const repo = db.getRepository(model);
+        if (!repo) {
+          throw new Error(`Repository for model "${model}" not found.`);
+        }
+
+        const safeLimit = Math.min(Math.max(1, Number(limit) || 20), 100);
+        const safePage = Math.max(1, Number(page) || 1);
+
+        let query = repo.query();
+        if (where && typeof where === 'object') {
+          for (const [k, v] of Object.entries(where)) {
+            if (v !== undefined) {
+              query = query.where(k, v);
+            }
+          }
+        }
+
+        if (sort) {
+          query = query.orderBy(sort, order);
+        }
+
+        const result = await query.paginate({ page: safePage, limit: safeLimit });
+        return result;
+      },
+    },
+    {
+      name: 'orm_findById',
+      description: 'Fetch a single record by primary key ID from an ORM model.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          model: { type: 'string', description: 'Model name' },
+          id: { description: 'Record primary key ID' },
+        },
+        required: ['model', 'id'],
+      },
+      handler: async ({ model, id }) => {
+        const repo = db.getRepository(model);
+        if (!repo) {
+          throw new Error(`Repository for model "${model}" not found.`);
+        }
+        const record = await repo.findById(id);
+        if (!record) {
+          return { found: false, record: null };
+        }
+        return { found: true, record };
+      },
+    },
+  ];
+
+  // If not readOnly, add mutation tools
+  if (!readOnly) {
+    tools.push(
+      {
+        name: 'orm_create',
+        description: 'Create a new record for a given ORM model with schema validation and lifecycle hooks.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            model: { type: 'string', description: 'Model name' },
+            data: { type: 'object', description: 'Record fields to insert' },
+          },
+          required: ['model', 'data'],
+        },
+        handler: async ({ model, data }) => {
+          const repo = db.getRepository(model);
+          if (!repo) {
+            throw new Error(`Repository for model "${model}" not found.`);
+          }
+          const created = await repo.create(data);
+          return { success: true, record: created };
+        },
+      },
+      {
+        name: 'orm_update',
+        description: 'Update an existing record by ID in an ORM model.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            model: { type: 'string', description: 'Model name' },
+            id: { description: 'Record ID to update' },
+            data: { type: 'object', description: 'Fields to update' },
+          },
+          required: ['model', 'id', 'data'],
+        },
+        handler: async ({ model, id, data }) => {
+          const repo = db.getRepository(model);
+          if (!repo) {
+            throw new Error(`Repository for model "${model}" not found.`);
+          }
+          const updated = await repo.update(id, data);
+          return { success: Boolean(updated), record: updated };
+        },
+      },
+      {
+        name: 'orm_delete',
+        description: 'Delete a record by ID from an ORM model (respects soft deletes if configured).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            model: { type: 'string', description: 'Model name' },
+            id: { description: 'Record ID to delete' },
+          },
+          required: ['model', 'id'],
+        },
+        handler: async ({ model, id }) => {
+          const repo = db.getRepository(model);
+          if (!repo) {
+            throw new Error(`Repository for model "${model}" not found.`);
+          }
+          const ok = await repo.delete(id);
+          return { success: Boolean(ok) };
+        },
+      }
+    );
+  }
+
+  // Whitelist filtering if specified
+  if (modelWhitelist && modelWhitelist.length > 0) {
+    const allowed = new Set(modelWhitelist);
+    return tools.map((t) => ({
+      ...t,
+      handler: async (args, ctx) => {
+        if (args.model && !allowed.has(args.model)) {
+          throw new Error(`Access to model "${args.model}" is not permitted.`);
+        }
+        return t.handler(args, ctx);
+      },
+    }));
+  }
+
+  return tools;
+}
+
+/**
+ * Creates ORM-related MCP resources and templates
+ * @param {Object} options
+ * @param {Object} options.db
+ * @returns {{ resources: Array<Object>, templates: Array<Object> }}
+ */
+function createOrmResources(options = {}) {
+  const { db } = options;
+  if (!db) return { resources: [], templates: [] };
+
+  const resources = [
+    {
+      uri: 'webspresso://models',
+      name: 'Registered ORM Models',
+      description: 'List of all database models registered in Webspresso.',
+      mimeType: 'application/json',
+      handler: async () => {
+        const models = getAllModels ? getAllModels() : [];
+        const modelList = models instanceof Map ? Array.from(models.values()) : (Array.isArray(models) ? models : Object.values(models));
+        return modelList.map((m) => ({
+          name: m.name,
+          table: m.table,
+          softDelete: Boolean(m.softDelete),
+          primaryKey: m.primaryKey || 'id',
+        }));
+      },
+    },
+    {
+      uri: 'webspresso://schema',
+      name: 'Database Schema Overview',
+      description: 'Complete database models schema structure with columns, types, and relations.',
+      mimeType: 'application/json',
+      handler: async () => {
+        const models = getAllModels ? getAllModels() : [];
+        const modelList = models instanceof Map ? Array.from(models.values()) : (Array.isArray(models) ? models : Object.values(models));
+        const result = {};
+        for (const model of modelList) {
+          result[model.name] = describeModel(model);
+        }
+        return result;
+      },
+    },
+  ];
+
+  const templates = [
+    {
+      uriTemplate: 'webspresso://models/{model}',
+      name: 'ORM Model Metadata',
+      description: 'Get full schema and relationship definition for a specific model.',
+      mimeType: 'application/json',
+      handler: async (uri, params) => {
+        const modelDef = db.getModel ? db.getModel(params.model) : null;
+        if (!modelDef) {
+          throw new Error(`Model "${params.model}" not found.`);
+        }
+        return describeModel(modelDef);
+      },
+    },
+  ];
+
+  return { resources, templates };
+}
+
+module.exports = {
+  createOrmTools,
+  createOrmResources,
+  describeModel,
+};