webspresso 0.0.91 → 0.0.93

package/plugins/mcp/discovery.js

@@ -0,0 +1,88 @@
+/**
+ * Webspresso MCP File-Based Auto-Discovery
+ * Discovers custom MCP tools, resources, and prompts from project `mcp/` directory
+ * @module plugins/mcp/discovery
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Scan a directory for JS files and require them
+ * @param {string} dirPath
+ * @returns {Array<Object>}
+ */
+function scanModuleDir(dirPath) {
+  if (!fs.existsSync(dirPath)) return [];
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  const items = [];
+
+  for (const entry of entries) {
+    if (entry.isFile() && (entry.name.endsWith('.js') || entry.name.endsWith('.cjs'))) {
+      if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
+      const fullPath = path.join(dirPath, entry.name);
+      try {
+        const mod = require(fullPath);
+        if (mod && typeof mod === 'object') {
+          // If mod doesn't have a name, default to filename without extension
+          if (!mod.name && !mod.uri) {
+            const baseName = path.basename(entry.name, path.extname(entry.name));
+            mod.name = baseName;
+          }
+          items.push(mod);
+        }
+      } catch (err) {
+        console.warn(`[mcp-discovery] Failed to load module at ${fullPath}:`, err.message);
+      }
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Discovers custom MCP components from the filesystem and registers them to the server
+ * @param {import('./server').McpServer} server
+ * @param {string} [rootDir=process.cwd()]
+ * @param {string} [mcpDirName='mcp']
+ */
+function discoverMcpDirectory(server, rootDir = process.cwd(), mcpDirName = 'mcp') {
+  const mcpRoot = path.resolve(rootDir, mcpDirName);
+  if (!fs.existsSync(mcpRoot)) return;
+
+  // 1. Discover custom tools: mcp/tools/
+  const toolsDir = path.join(mcpRoot, 'tools');
+  const customTools = scanModuleDir(toolsDir);
+  for (const tool of customTools) {
+    if (typeof tool.handler === 'function') {
+      server.registerTool(tool);
+    }
+  }
+
+  // 2. Discover custom resources: mcp/resources/
+  const resourcesDir = path.join(mcpRoot, 'resources');
+  const customResources = scanModuleDir(resourcesDir);
+  for (const res of customResources) {
+    if (typeof res.handler === 'function') {
+      if (res.uriTemplate) {
+        server.registerResourceTemplate(res);
+      } else if (res.uri) {
+        server.registerResource(res);
+      }
+    }
+  }
+
+  // 3. Discover custom prompts: mcp/prompts/
+  const promptsDir = path.join(mcpRoot, 'prompts');
+  const customPrompts = scanModuleDir(promptsDir);
+  for (const prompt of customPrompts) {
+    if (typeof prompt.handler === 'function') {
+      server.registerPrompt(prompt);
+    }
+  }
+}
+
+module.exports = {
+  discoverMcpDirectory,
+  scanModuleDir,
+};

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