@fitzzero/quickdraw-core 1.2.1 → 2.1.0

package/dist/server/index.js

@@ -2,6 +2,9 @@ import express from 'express';
 import { createServer } from 'http';
 import { Server } from 'socket.io';
 import * as jose from 'jose';
+import * as readline from 'readline';
+import * as fs from 'fs';
+import * as path from 'path';
 
 // src/shared/types.ts
 var consoleLogger = {
@@ -590,6 +593,35 @@ var BaseService = class {
   getPublicMethods() {
     return Array.from(this.publicMethods.values());
   }
+  /**
+   * Verify that all expected service methods have been defined via defineMethod().
+   * Call at the end of initMethods() to catch missing implementations at boot time.
+   *
+   * @param expectedMethods - Array of method names that should have been defined
+   * @throws Error if any expected methods are missing
+   *
+   * @example
+   * ```typescript
+   * private initMethods(): void {
+   *   this.defineMethod("createChat", "Read", ...);
+   *   this.defineMethod("deleteChat", "Admin", ...);
+   *   this.verifyAllMethods(["createChat", "deleteChat"]);
+   * }
+   * ```
+   */
+  verifyAllMethods(expectedMethods) {
+    const missing = [];
+    for (const method of expectedMethods) {
+      if (!this.publicMethods.has(method)) {
+        missing.push(method);
+      }
+    }
+    if (missing.length > 0) {
+      throw new Error(
+        `${this.serviceName}: Missing method implementations: ${missing.join(", ")}`
+      );
+    }
+  }
   // ===========================================================================
   // Admin Methods
   // ===========================================================================
@@ -1640,6 +1672,677 @@ function requireEnv(name, defaultValue) {
   return value;
 }
 
-export { BaseService, ServiceRegistry, applyRateLimitMiddleware, checkEnv, createJWT, createOAuthURL, createQuickdrawServer, createRateLimiter, createTieredRateLimiter, discordProvider, exchangeOAuthCode, getDefaultEntityFields, googleProvider, isRedisAdapterAvailable, mergeWithDefaultFields, requireEnv, setupRedisAdapter, validateEnv, verifyJWT, zodToAdminFields };
+// src/server/mcp/McpRegistry.ts
+var McpRegistry = class {
+  services = /* @__PURE__ */ new Map();
+  methodCache = /* @__PURE__ */ new Map();
+  hydrateUserContext;
+  logger;
+  customToolSpecs = null;
+  constructor(options) {
+    this.hydrateUserContext = options.hydrateUserContext;
+    this.logger = options.logger?.child({ service: "McpRegistry" }) ?? consoleLogger.child({ service: "McpRegistry" });
+  }
+  /**
+   * Optionally provide pre-generated tool specs for richer descriptions.
+   * If not set, tool definitions are built dynamically from registered services.
+   */
+  setToolSpecs(specs) {
+    this.customToolSpecs = specs;
+  }
+  registerService(serviceName, serviceInstance) {
+    this.services.set(serviceName, serviceInstance);
+    const methods = serviceInstance.getPublicMethods?.() ?? [];
+    const methodMap = /* @__PURE__ */ new Map();
+    for (const method of methods) {
+      methodMap.set(method.name, method);
+    }
+    this.methodCache.set(serviceName, methodMap);
+    this.logger.info(`Registered MCP service: ${serviceName}`, {
+      category: "startup",
+      methodCount: methods.length,
+      methods: methods.map((m) => m.name)
+    });
+  }
+  listTools(options) {
+    const hasDefaultUser = !!options?.defaultUserId;
+    if (this.customToolSpecs) {
+      return this.customToolSpecs.filter((s) => this.services.has(s.name)).map((svc) => this.buildToolDefinition(svc.name, svc.description, svc.methodNames, hasDefaultUser));
+    }
+    const tools = [];
+    for (const [serviceName] of this.services) {
+      const methodMap = this.methodCache.get(serviceName);
+      if (!methodMap) continue;
+      const methodNames = Array.from(methodMap.keys());
+      const description = this.buildDescription(serviceName, methodNames);
+      tools.push(this.buildToolDefinition(serviceName, description, methodNames, hasDefaultUser));
+    }
+    return tools;
+  }
+  async invoke(serviceName, methodName, payload, userId) {
+    const { instance, method } = this.resolveServiceMethod(serviceName, methodName);
+    const { serviceAccess } = await this.hydrateUserContext(userId);
+    const ctx = {
+      id: `mcp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      userId,
+      serviceAccess,
+      connected: true,
+      disconnected: false
+    };
+    const entryId = this.resolveEntryId(method, payload);
+    const logTag = `${serviceName}.${methodName}`;
+    this.logger.info(`MCP invoke start: ${logTag}`, {
+      category: "request_processing",
+      source: "mcp",
+      serviceName,
+      methodName,
+      userId,
+      entryId
+    });
+    const startTime = Date.now();
+    try {
+      const validatedPayload = this.validatePayload(method, payload);
+      if (instance.ensureAccessForMethod) {
+        await instance.ensureAccessForMethod(
+          method.access,
+          ctx,
+          entryId
+        );
+      }
+      const result = await method.handler(validatedPayload, {
+        userId,
+        socketId: ctx.id,
+        serviceAccess
+      });
+      this.logger.info(`MCP invoke success: ${logTag}`, {
+        category: "request_processing",
+        outcome: "success",
+        source: "mcp",
+        serviceName,
+        methodName,
+        userId,
+        durationMs: Date.now() - startTime
+      });
+      return result;
+    } catch (error) {
+      this.logger.error(`MCP invoke error: ${logTag}`, {
+        category: "error",
+        source: "mcp",
+        serviceName,
+        methodName,
+        userId,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
+  getServices() {
+    return Array.from(this.services.keys());
+  }
+  resolveServiceMethod(serviceName, methodName) {
+    const instance = this.services.get(serviceName);
+    if (!instance) {
+      throw new Error(
+        `Unknown service: ${serviceName}. Available: ${Array.from(this.services.keys()).join(", ")}`
+      );
+    }
+    const methodMap = this.methodCache.get(serviceName);
+    const method = methodMap?.get(methodName);
+    if (!method) {
+      throw new Error(
+        `Unknown method "${methodName}" on ${serviceName}. Available: ${Array.from(methodMap?.keys() ?? []).join(", ")}`
+      );
+    }
+    return { instance, method };
+  }
+  validatePayload(method, payload) {
+    if (method.schema) {
+      const result = method.schema.safeParse(payload);
+      if (!result.success) {
+        throw new Error(
+          `Validation error: ${result.error?.message ?? "invalid payload"}`
+        );
+      }
+      return result.data;
+    }
+    return payload;
+  }
+  resolveEntryId(method, payload) {
+    if (method.resolveEntryId) {
+      return method.resolveEntryId(payload) ?? void 0;
+    }
+    if (payload && typeof payload === "object" && "id" in payload) {
+      const v = payload.id;
+      return typeof v === "string" ? v : void 0;
+    }
+    return void 0;
+  }
+  buildToolDefinition(name, description, methodNames, hasDefaultUser) {
+    return {
+      name,
+      description,
+      inputSchema: {
+        type: "object",
+        properties: {
+          method: {
+            type: "string",
+            enum: methodNames,
+            description: "The service method to call"
+          },
+          payload: {
+            type: "object",
+            description: "Method-specific payload (see method listing in description for fields)"
+          },
+          userId: {
+            type: "string",
+            description: hasDefaultUser ? "User ID (optional - defaults to MCP_USER_ID env var)" : "The authenticated user ID (required for ACL checks)"
+          }
+        },
+        required: hasDefaultUser ? ["method"] : ["method", "userId"]
+      }
+    };
+  }
+  buildDescription(serviceName, methodNames) {
+    const displayName = serviceName.replace(/Service$/i, "").replace(/([a-z])([A-Z])/g, "$1 $2") + "Service";
+    const methodList = methodNames.map((m) => `- ${m}`).join("\n");
+    return `${displayName} service.
+
+Methods:
+${methodList}`;
+  }
+};
+function createMcpStdioServer(options) {
+  const { name, version, registry, defaultUserId } = options;
+  const serverInfo = { name, version };
+  const capabilities = { tools: {} };
+  function getToolDefinitions() {
+    return registry.listTools({
+      defaultUserId: defaultUserId ?? process.env.MCP_USER_ID
+    });
+  }
+  async function handleRequest(request) {
+    const { id, method, params } = request;
+    try {
+      switch (method) {
+        case "initialize":
+          return {
+            jsonrpc: "2.0",
+            id,
+            result: {
+              protocolVersion: "2024-11-05",
+              serverInfo,
+              capabilities
+            }
+          };
+        case "initialized":
+        case "notifications/initialized":
+          return null;
+        case "tools/list":
+          return {
+            jsonrpc: "2.0",
+            id,
+            result: { tools: getToolDefinitions() }
+          };
+        case "tools/call": {
+          const { name: serviceName, arguments: args } = params;
+          const methodName = args?.method;
+          if (!methodName) {
+            return {
+              jsonrpc: "2.0",
+              id,
+              error: {
+                code: -32602,
+                message: `Missing required argument "method" for service ${serviceName}`
+              }
+            };
+          }
+          const userId = args?.userId ?? defaultUserId ?? process.env.MCP_USER_ID ?? "mcp-anonymous";
+          const payload = args?.payload;
+          const result = await registry.invoke(
+            serviceName,
+            methodName,
+            payload,
+            userId
+          );
+          return {
+            jsonrpc: "2.0",
+            id,
+            result: {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(result, null, 2)
+                }
+              ]
+            }
+          };
+        }
+        case "ping":
+          return { jsonrpc: "2.0", id, result: {} };
+        default:
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32601, message: `Method not found: ${method}` }
+          };
+      }
+    } catch (error) {
+      return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+          code: -32e3,
+          message: error instanceof Error ? error.message : "Unknown error"
+        }
+      };
+    }
+  }
+  async function main() {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: false
+    });
+    function send(response) {
+      process.stdout.write(JSON.stringify(response) + "\n");
+    }
+    for await (const line of rl) {
+      if (!line.trim()) continue;
+      try {
+        const request = JSON.parse(line);
+        const response = await handleRequest(request);
+        if (response !== null) {
+          send(response);
+        }
+      } catch {
+        send({
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: -32700, message: "Parse error" }
+        });
+      }
+    }
+  }
+  main().catch((error) => {
+    process.stderr.write(`Fatal error: ${error}
+`);
+    process.exit(1);
+  });
+}
+
+// src/server/mcp/McpBootstrap.ts
+function bootstrapMcpServer(serverModulePath) {
+  process.env.MCP_MODE = "true";
+  process.env.LOG_LEVEL = process.env.LOG_LEVEL ?? "warn";
+  const stderrWrite = (data) => {
+    process.stderr.write(data + "\n");
+  };
+  console.log = (...args) => {
+    stderrWrite(args.map(String).join(" "));
+  };
+  console.info = (...args) => {
+    stderrWrite(args.map(String).join(" "));
+  };
+  console.warn = (...args) => {
+    stderrWrite(args.map(String).join(" "));
+  };
+  console.debug = (...args) => {
+    stderrWrite(args.map(String).join(" "));
+  };
+  import(serverModulePath).catch((error) => {
+    process.stderr.write(`Bootstrap error: ${error}
+`);
+    process.exit(1);
+  });
+}
+
+// src/server/mcp/McpHttpRoutes.ts
+function createMcpRoutes(router, options) {
+  const { registry, verifyToken } = options;
+  const logger = options.logger?.child({ service: "McpHttpRoutes" }) ?? consoleLogger.child({ service: "McpHttpRoutes" });
+  router.get("/mcp/tools", (_req, res) => {
+    const tools = registry.listTools();
+    res.json({ tools });
+  });
+  router.post("/mcp/invoke", async (req, res) => {
+    try {
+      const authHeader = req.headers.authorization;
+      if (!authHeader?.startsWith("Bearer ")) {
+        res.status(401).json({ error: "Missing or invalid Authorization header" });
+        return;
+      }
+      const token = authHeader.slice(7);
+      const tokenPayload = await verifyToken(token);
+      if (!tokenPayload?.userId) {
+        res.status(401).json({ error: "Invalid token" });
+        return;
+      }
+      const {
+        service,
+        method,
+        payload: toolPayload
+      } = req.body;
+      if (!service || !method) {
+        res.status(400).json({ error: "Missing service or method" });
+        return;
+      }
+      const result = await registry.invoke(
+        service,
+        method,
+        toolPayload,
+        tokenPayload.userId
+      );
+      res.json({ success: true, data: result });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Internal error";
+      logger.error("MCP HTTP invoke error", { error: message });
+      res.status(500).json({ error: message });
+    }
+  });
+  return router;
+}
+function extractFieldNames(schemaContent) {
+  const fields = [];
+  const lines = schemaContent.split("\n");
+  for (const line of lines) {
+    const fieldMatch = line.match(/^\s*(\w+)\s*:/);
+    if (fieldMatch?.[1]) {
+      const name = fieldMatch[1];
+      const isOptional2 = line.includes(".optional()") || line.includes(".nullable()");
+      fields.push(isOptional2 ? `${name}?` : name);
+    }
+  }
+  return fields;
+}
+function buildPayloadHint(fields) {
+  if (!fields || fields.length === 0) return "";
+  return `(${fields.join(", ")})`;
+}
+function parseServiceFile(filePath) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const classMatch = content.match(/export class (\w+Service)/);
+  if (!classMatch?.[1]) return null;
+  const className = classMatch[1];
+  const serviceName = className.charAt(0).toLowerCase() + className.slice(1);
+  const aclMatch = content.match(/hasEntryACL:\s*(true|false)/);
+  const hasEntryACL = aclMatch ? aclMatch[1] === "true" : false;
+  let aclPattern = "No ACL";
+  if (hasEntryACL) {
+    if (content.includes("override async checkEntryACL")) {
+      aclPattern = "Membership table";
+    } else {
+      aclPattern = "JSON ACL (default)";
+    }
+  }
+  if (content.includes("override checkAccess")) {
+    aclPattern = "Custom (self-access pattern)";
+  }
+  const schemas = /* @__PURE__ */ new Map();
+  const schemaRegex = /const (\w+Schema) = z\.object\(\{([\s\S]*?)\}\);/g;
+  let schemaMatch;
+  while ((schemaMatch = schemaRegex.exec(content)) !== null) {
+    if (!schemaMatch[1] || !schemaMatch[2]) continue;
+    const schemaContent = schemaMatch[2].split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n  ");
+    schemas.set(schemaMatch[1], schemaContent);
+  }
+  const methods = [];
+  const methodRegex = /this\.defineMethod\(\s*["'](\w+)["'],\s*["'](\w+)["']/g;
+  let methodMatch;
+  while ((methodMatch = methodRegex.exec(content)) !== null) {
+    const methodName = methodMatch[1] ?? "";
+    const accessLevel = methodMatch[2] ?? "Read";
+    const methodStart = methodMatch.index;
+    let parenDepth = 0;
+    let methodEnd = methodStart;
+    let foundStart = false;
+    for (let i = methodStart; i < content.length; i++) {
+      if (content[i] === "(") {
+        parenDepth++;
+        foundStart = true;
+      } else if (content[i] === ")") {
+        parenDepth--;
+        if (foundStart && parenDepth === 0) {
+          methodEnd = i;
+          break;
+        }
+      }
+    }
+    const methodBlock = content.substring(methodStart, methodEnd + 1);
+    const hasSchema = methodBlock.includes("schema:");
+    const schemaRef = methodBlock.match(/schema:\s*(\w+Schema)/);
+    const hasResolver = methodBlock.includes("resolveEntryId:");
+    let payloadFields;
+    if (schemaRef?.[1]) {
+      const schemaContent = schemas.get(schemaRef[1]);
+      if (schemaContent) {
+        payloadFields = extractFieldNames(schemaContent);
+      }
+    }
+    methods.push({
+      name: methodName,
+      accessLevel,
+      hasSchema,
+      schemaName: schemaRef?.[1],
+      hasResolver,
+      payloadFields
+    });
+  }
+  return {
+    name: serviceName,
+    className,
+    hasEntryACL,
+    aclPattern,
+    methods,
+    schemas
+  };
+}
+function findServiceDirs(dir, basePath = "") {
+  const results = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const fullPath = path.join(dir, entry.name);
+      const relativePath = basePath ? `${basePath}/${entry.name}` : entry.name;
+      if (fs.existsSync(path.join(fullPath, "index.ts"))) {
+        results.push(relativePath);
+      }
+      const nested = findServiceDirs(fullPath, relativePath);
+      results.push(...nested);
+    }
+  }
+  return results;
+}
+function generateToolsFileContent(services) {
+  let content = `/**
+ * MCP Tool Metadata
+ * 
+ * Auto-generated from service definitions.
+ * DO NOT EDIT - regenerate with: pnpm docs:generate
+ */
+
+export type MethodSpec = {
+  name: string;
+  access: "Public" | "Read" | "Moderate" | "Admin";
+  entryScoped: boolean;
+  payloadHint: string;
+};
+
+export type ServiceToolSpec = {
+  name: string;
+  description: string;
+  methods: MethodSpec[];
+  methodNames: string[];
+};
+
+`;
+  const serviceSpecs = [];
+  for (const service of services) {
+    const methodSpecs = service.methods.map((method) => {
+      const hint = buildPayloadHint(method.payloadFields);
+      return `    {
+      name: "${method.name}",
+      access: "${method.accessLevel}" as const,
+      entryScoped: ${method.hasResolver},
+      payloadHint: "${hint}",
+    }`;
+    });
+    const methodDescriptions = service.methods.map((method) => {
+      const hint = buildPayloadHint(method.payloadFields);
+      return `- ${method.name}${hint}`;
+    }).join("\\n");
+    const description = `${service.className} service.\\n\\nMethods:\\n${methodDescriptions}`;
+    serviceSpecs.push(`  {
+    name: "${service.name}",
+    description: "${description}",
+    methods: [
+${methodSpecs.join(",\n")}
+    ],
+    methodNames: [${service.methods.map((m) => `"${m.name}"`).join(", ")}],
+  }`);
+  }
+  content += `export const SERVICE_TOOLS: ServiceToolSpec[] = [
+${serviceSpecs.join(",\n")}
+];
+
+`;
+  content += `export const SERVICE_TOOLS_BY_NAME: Record<string, ServiceToolSpec> = Object.fromEntries(
+  SERVICE_TOOLS.map(s => [s.name, s])
+);
+
+`;
+  content += `export function getServiceNames(): string[] {
+  return SERVICE_TOOLS.map(s => s.name);
+}
+
+export function getServiceTool(serviceName: string): ServiceToolSpec | undefined {
+  return SERVICE_TOOLS_BY_NAME[serviceName];
+}
+
+export function methodExists(serviceName: string, methodName: string): boolean {
+  const service = SERVICE_TOOLS_BY_NAME[serviceName];
+  return !!service?.methodNames.includes(methodName);
+}
+
+export function getMethodSpec(serviceName: string, methodName: string): MethodSpec | undefined {
+  const service = SERVICE_TOOLS_BY_NAME[serviceName];
+  return service?.methods.find(m => m.name === methodName);
+}
+`;
+  return content;
+}
+function generateServiceDoc(service) {
+  let doc = `# ${service.className}
+
+`;
+  doc += `**Service Name:** \`${service.name}\`
+
+`;
+  doc += `**Access Control:** ${service.aclPattern}
+
+`;
+  if (service.hasEntryACL) {
+    doc += `**Entry-level ACL:** Enabled
+
+`;
+  }
+  doc += `---
+
+## Methods
+
+`;
+  for (const method of service.methods) {
+    doc += `### ${method.name}
+
+`;
+    doc += `- **Access Level:** \`${method.accessLevel}\`
+`;
+    doc += `- **Socket Event:** \`${service.name}:${method.name}\`
+`;
+    if (method.hasResolver) {
+      doc += `- **Entry-scoped:** Yes
+`;
+    }
+    if (method.hasSchema && method.schemaName) {
+      doc += `- **Validation:** Zod schema (\`${method.schemaName}\`)
+`;
+      const schemaContent = service.schemas.get(method.schemaName);
+      if (schemaContent) {
+        doc += `
+**Payload Schema:**
+
+\`\`\`typescript
+{
+  ${schemaContent}
+}
+\`\`\`
+`;
+      }
+    } else {
+      doc += `- **Validation:** None
+`;
+    }
+    doc += `
+`;
+  }
+  doc += `---
+
+*Generated by quickdraw-core*
+`;
+  return doc;
+}
+function generateToolMetadata(options) {
+  const { servicesDir, toolsOutputPath, docsOutputDir } = options;
+  const serviceDirs = findServiceDirs(servicesDir);
+  if (docsOutputDir && !fs.existsSync(docsOutputDir)) {
+    fs.mkdirSync(docsOutputDir, { recursive: true });
+  }
+  const toolsDir = path.dirname(toolsOutputPath);
+  if (!fs.existsSync(toolsDir)) {
+    fs.mkdirSync(toolsDir, { recursive: true });
+  }
+  const allServices = [];
+  for (const serviceDir of serviceDirs) {
+    const indexPath = path.join(servicesDir, serviceDir, "index.ts");
+    if (!fs.existsSync(indexPath)) continue;
+    const serviceInfo = parseServiceFile(indexPath);
+    if (!serviceInfo) continue;
+    allServices.push(serviceInfo);
+    if (docsOutputDir) {
+      const doc = generateServiceDoc(serviceInfo);
+      const outputPath = path.join(
+        docsOutputDir,
+        `${serviceInfo.className}.md`
+      );
+      fs.writeFileSync(outputPath, doc);
+    }
+  }
+  if (docsOutputDir) {
+    const indexContent = `# API Documentation
+
+Auto-generated documentation for all services.
+
+## Services
+
+` + allServices.map((s) => `- [${s.className}](./${s.className}.md)`).join("\n") + `
+
+---
+
+*Generated by quickdraw-core*
+`;
+    fs.writeFileSync(path.join(docsOutputDir, "README.md"), indexContent);
+  }
+  const toolsContent = generateToolsFileContent(allServices);
+  fs.writeFileSync(toolsOutputPath, toolsContent);
+  const totalMethods = allServices.reduce(
+    (sum, s) => sum + s.methods.length,
+    0
+  );
+  console.log(
+    `Generated ${allServices.length} service tools (${totalMethods} methods) -> ${toolsOutputPath}`
+  );
+}
+
+export { BaseService, McpRegistry, ServiceRegistry, applyRateLimitMiddleware, bootstrapMcpServer, checkEnv, createJWT, createMcpRoutes, createMcpStdioServer, createOAuthURL, createQuickdrawServer, createRateLimiter, createTieredRateLimiter, discordProvider, exchangeOAuthCode, generateToolMetadata, getDefaultEntityFields, googleProvider, isRedisAdapterAvailable, mergeWithDefaultFields, requireEnv, setupRedisAdapter, validateEnv, verifyJWT, zodToAdminFields };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map