webspresso 0.0.91 → 0.0.93

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,
+};

package/plugins/mcp/providers/services.js

@@ -0,0 +1,190 @@
+/**
+ * Webspresso MCP Services Provider
+ * Bridges Webspresso ServiceRegistry to MCP Tools with automatic Zod -> JSON Schema conversion.
+ * @module plugins/mcp/providers/services
+ */
+
+const { zodToJsonSchema } = require('zod-to-json-schema');
+
+/**
+ * Normalizes a dot-separated service name to an MCP-safe tool name
+ * e.g. "user.create" -> "service__user__create"
+ * @param {string} serviceName
+ * @returns {string}
+ */
+function serviceNameToToolName(serviceName) {
+  return `service__${serviceName.replace(/\./g, '__').replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+}
+
+/**
+ * Reconstructs original service name from tool name
+ * @param {string} toolName
+ * @returns {string|null}
+ */
+function toolNameToServiceName(toolName) {
+  if (!toolName.startsWith('service__')) return null;
+  return toolName.slice('service__'.length).replace(/__/g, '.');
+}
+
+/**
+ * Check if a service name matches any pattern in a list (e.g. ['user.*', 'order.get'])
+ * @param {string} name
+ * @param {Array<string>} patterns
+ * @returns {boolean}
+ */
+function matchesPattern(name, patterns) {
+  if (!patterns || patterns.length === 0) return true;
+  return patterns.some((pattern) => {
+    if (pattern === '*' || pattern === name) return true;
+    if (pattern.endsWith('*')) {
+      const prefix = pattern.slice(0, -1);
+      return name.startsWith(prefix);
+    }
+    return false;
+  });
+}
+
+/**
+ * Checks if a service is likely a mutation (create, update, delete, remove, post, send, prune, etc.)
+ * @param {string} serviceName
+ * @param {Object} [serviceDef]
+ * @returns {boolean}
+ */
+function isMutationService(serviceName, serviceDef) {
+  if (serviceDef?.mutation !== undefined) {
+    return Boolean(serviceDef.mutation);
+  }
+  const parts = serviceName.toLowerCase().split('.');
+  const lastPart = parts[parts.length - 1];
+  const mutationKeywords = [
+    'create',
+    'add',
+    'insert',
+    'update',
+    'patch',
+    'edit',
+    'delete',
+    'remove',
+    'destroy',
+    'prune',
+    'reset',
+    'send',
+    'dispatch',
+    'cancel',
+    'pay',
+    'checkout',
+    'execute',
+    'import',
+    'clear',
+    'flush',
+    'purge',
+    'drop',
+    'truncate',
+  ];
+  return mutationKeywords.some((kw) => lastPart.includes(kw));
+}
+
+/**
+ * Converts a Webspresso Zod schema to a clean MCP inputSchema
+ * @param {import('zod').ZodTypeAny} schema
+ * @returns {Object}
+ */
+function convertZodToInputSchema(schema) {
+  if (!schema) {
+    return {
+      type: 'object',
+      properties: {},
+      additionalProperties: true,
+    };
+  }
+
+  try {
+    const rawSchema = zodToJsonSchema(schema, {
+      $refStrategy: 'none',
+      removeAdditionalStrategy: 'strict',
+    });
+
+    // Clean up definition wrapper if present
+    if (rawSchema && typeof rawSchema === 'object') {
+      const { $schema, ...clean } = rawSchema;
+      if (!clean.type) {
+        clean.type = 'object';
+      }
+      return clean;
+    }
+    return { type: 'object', properties: {} };
+  } catch (err) {
+    return {
+      type: 'object',
+      properties: {},
+      description: `Input schema auto-conversion error: ${err.message}`,
+    };
+  }
+}
+
+/**
+ * Generates MCP tool definitions from a Webspresso ServiceRegistry
+ * @param {Object} options
+ * @param {import('../../src/services').ServiceRegistry} options.registry
+ * @param {Array<string>} [options.include] - Whitelist of service patterns
+ * @param {Array<string>} [options.exclude] - Blacklist of service patterns
+ * @param {boolean} [options.readOnly=false] - When true, filters out mutation services
+ * @param {string|Array<string>} [options.role] - Simulated user role for auth
+ * @returns {Array<Object>}
+ */
+function createServiceTools(options = {}) {
+  const { registry, include, exclude, readOnly = false, role = 'admin' } = options;
+  if (!registry) return [];
+
+  const tools = [];
+  const serviceNames = registry.list();
+
+  for (const name of serviceNames) {
+    // Check include / exclude patterns
+    if (include && !matchesPattern(name, include)) continue;
+    if (exclude && matchesPattern(name, exclude)) continue;
+
+    const def = registry.get(name);
+    if (!def) continue;
+
+    const isMutation = isMutationService(name, def);
+    if (readOnly && isMutation) {
+      continue;
+    }
+
+    const toolName = serviceNameToToolName(name);
+    const inputSchema = convertZodToInputSchema(def.schema);
+
+    const description =
+      def.description ||
+      def.metadata?.description ||
+      `Executes Webspresso service '${name}'.${isMutation ? ' (Mutation)' : ' (Query)'}`;
+
+    tools.push({
+      name: toolName,
+      description,
+      inputSchema,
+      handler: async (args, ctx) => {
+        // Execute service via registry
+        const execCtx = {
+          ...ctx,
+          user: ctx.user || (role ? { id: 'mcp-agent', role } : null),
+        };
+
+        const result = await registry.execute(name, args, execCtx);
+        return result;
+      },
+    });
+  }
+
+  return tools;
+}
+
+module.exports = {
+  createServiceTools,
+  serviceNameToToolName,
+  toolNameToServiceName,
+  convertZodToInputSchema,
+  isMutationService,
+  matchesPattern,
+};

package/plugins/mcp/providers/system.js

@@ -0,0 +1,87 @@
+/**
+ * Webspresso MCP System Provider
+ * Exposes application routes, services index, and health info as MCP Resources
+ * @module plugins/mcp/providers/system
+ */
+
+/**
+ * Creates system MCP resources
+ * @param {Object} options
+ * @param {Object} [options.appContext]
+ * @param {Object} [options.serviceRegistry]
+ * @param {Object} [options.routes]
+ * @param {Object} [options.db]
+ * @returns {Array<Object>}
+ */
+function createSystemResources(options = {}) {
+  const { appContext, serviceRegistry, routes, db } = options;
+
+  return [
+    {
+      uri: 'webspresso://routes',
+      name: 'Application Routes',
+      description: 'List of all file-based SSR and API routes mounted in the Webspresso application.',
+      mimeType: 'application/json',
+      handler: async () => {
+        const rawRoutes = routes || appContext?.routes || [];
+        if (Array.isArray(rawRoutes)) {
+          return rawRoutes.map((r) => ({
+            path: r.path || r.route,
+            method: r.method ? r.method.toUpperCase() : 'GET',
+            isApi: Boolean(r.isApi || r.path?.startsWith('/api/')),
+            middleware: r.middleware || [],
+            sourceFile: r.filePath || r.file,
+          }));
+        }
+        return rawRoutes;
+      },
+    },
+    {
+      uri: 'webspresso://services',
+      name: 'Services Directory',
+      description: 'List of all business logic services discovered and registered in the application.',
+      mimeType: 'application/json',
+      handler: async () => {
+        if (!serviceRegistry) return [];
+        const names = serviceRegistry.list();
+        return names.map((name) => {
+          const def = serviceRegistry.get(name);
+          return {
+            name,
+            description: def?.description || '',
+            hasSchema: Boolean(def?.schema),
+            hasAuth: Boolean(def?.auth),
+            timeout: def?.timeout || null,
+            transaction: Boolean(def?.transaction),
+          };
+        });
+      },
+    },
+    {
+      uri: 'webspresso://health',
+      name: 'System Health & Metrics',
+      description: 'Framework runtime information, node version, memory usage, and uptime.',
+      mimeType: 'application/json',
+      handler: async () => {
+        const memory = process.memoryUsage();
+        return {
+          status: 'ok',
+          uptimeSeconds: Math.floor(process.uptime()),
+          nodeVersion: process.version,
+          platform: process.platform,
+          memory: {
+            heapUsedMB: Math.round(memory.heapUsed / 1024 / 1024),
+            heapTotalMB: Math.round(memory.heapTotal / 1024 / 1024),
+            rssMB: Math.round(memory.rss / 1024 / 1024),
+          },
+          databaseConnected: Boolean(db),
+          timestamp: new Date().toISOString(),
+        };
+      },
+    },
+  ];
+}
+
+module.exports = {
+  createSystemResources,
+};