mojulo 0.0.0 → 0.1.1

package/lib/mcp/jobs.js

@@ -0,0 +1,64 @@
+/**
+ * In-process job runner for long-running MCP tool calls.
+ *
+ * MCP clients don't all implement progress notifications, and many tool
+ * libraries enforce a "tools must return in N seconds" pattern. We wrap
+ * anything >2s as a job: returns { jobId } immediately, the model polls
+ * with `poll_job`.
+ *
+ * Storage: `mcp_jobs` table (see lib/db/index.js). On control-plane restart,
+ * pending / running jobs are reaped to `error` state — that's all the
+ * recovery the single-user posture needs.
+ */
+
+import { McpJobRepository, JOB_STATUS } from '@/lib/db/repositories/mcpJobs';
+
+/**
+ * Start a job. Returns immediately with { jobId, status: 'pending' }.
+ * The provided `task(jobId)` runs in the background; its return value becomes
+ * the job result, its thrown error becomes the job error.
+ *
+ * `task` can optionally call McpJobRepository.setProgress(jobId, pct) to
+ * report progress for clients that poll.
+ */
+export async function startJob({
+  tool,
+  mcpSessionId = null,
+  builderSessionId = null,
+  task,
+}) {
+  if (typeof task !== 'function') {
+    throw new Error('startJob requires a task function');
+  }
+
+  const job = await McpJobRepository.create({ tool, mcpSessionId, builderSessionId });
+
+  // Don't await — fire and forget; the caller returns the jobId to the client.
+  runJobInBackground(job.id, task);
+
+  return { jobId: job.id, status: job.status };
+}
+
+function runJobInBackground(jobId, task) {
+  // setImmediate so the create() write commits and the HTTP response goes out
+  // before we start the heavy work. queueMicrotask wouldn't be enough — the
+  // task can be CPU-bound on the embedder.
+  setImmediate(async () => {
+    try {
+      await McpJobRepository.setRunning(jobId);
+      const result = await task(jobId);
+      await McpJobRepository.setDone(jobId, result);
+    } catch (err) {
+      console.error(`[mcp:job ${jobId}] failed:`, err);
+      await McpJobRepository.setError(jobId, err).catch((dbErr) => {
+        console.error(`[mcp:job ${jobId}] failed to persist error:`, dbErr);
+      });
+    }
+  });
+}
+
+export async function getJob(jobId) {
+  return McpJobRepository.findById(jobId);
+}
+
+export { JOB_STATUS };

package/lib/mcp/server.js

@@ -0,0 +1,184 @@
+/**
+ * MCP server core — protocol dispatch and tool registry.
+ *
+ * The Next.js route ([api/mcp/route.js]) handles HTTP + bearer auth and
+ * forwards parsed JSON-RPC messages here. This module owns the MCP
+ * protocol semantics: initialize / tools/list / tools/call.
+ *
+ * Tools are registered in rings (see [tools/build.js], [tools/operate.js]).
+ * Each registered tool has:
+ *   - name, description, inputSchema (JSON Schema)
+ *   - handler(input, context) → result | Promise<result>
+ *
+ * Execution context carries:
+ *   - mcpSessionId — used by session-binding.js to attach a BuilderSession
+ *   - userId — always 'local' (single-user posture, see auth/service.js)
+ */
+
+const PROTOCOL_VERSION = '2024-11-05';
+const SERVER_NAME = 'mojulo-control-plane';
+const SERVER_VERSION = '0.1.0';
+
+// Surfaced to the connecting model on `initialize`. Most MCP clients hand this
+// to the agent as a system-prompt-style preamble — it has to fit and stick
+// even on clients that truncate aggressively. We keep it deliberately short
+// and noun-free: one framing sentence + one explicit pointer to load the full
+// briefing on demand. The heavy lifting (glossary, capability model,
+// lifecycle, tool index) lives in the `forward_context` tool's response so
+// the agent only pays the context cost when the user actually needs it.
+const SERVER_INSTRUCTIONS = `Mojulo is a control plane for **chatbot-based solutions** — chatbots that talk to your users, capture what they say, and turn those conversations into real outcomes in the tools the user already runs (CRM, calendar, ticketing, drive, warehouse).
+
+**When the user asks what mojulo is, how it works, or which tools to pick — call \`forward_context\` first.** It returns the concept glossary, the bot capability model, the deploy/connect lifecycle, and a one-line description of every tool, so you can orient before acting.`;
+
+const registeredTools = new Map();
+
+export function registerTool(tool) {
+  if (!tool || !tool.name || typeof tool.handler !== 'function') {
+    throw new Error('registerTool requires { name, handler }');
+  }
+  registeredTools.set(tool.name, tool);
+}
+
+export function listTools() {
+  return Array.from(registeredTools.values()).map((t) => ({
+    name: t.name,
+    description: t.description || '',
+    inputSchema: t.inputSchema || { type: 'object', properties: {} },
+  }));
+}
+
+function jsonRpcResult(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+
+function jsonRpcError(id, code, message, data) {
+  const err = { code, message };
+  if (data !== undefined) err.data = data;
+  return { jsonrpc: '2.0', id, error: err };
+}
+
+const ErrorCodes = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+};
+
+export async function dispatchMcpRequest(message, context) {
+  if (!message || message.jsonrpc !== '2.0') {
+    return jsonRpcError(message?.id ?? null, ErrorCodes.INVALID_REQUEST, 'Invalid JSON-RPC request');
+  }
+
+  // Notifications (no id) — we accept and return nothing.
+  const isNotification = message.id === undefined || message.id === null;
+
+  try {
+    switch (message.method) {
+      case 'initialize':
+        return isNotification
+          ? null
+          : jsonRpcResult(message.id, {
+              protocolVersion: PROTOCOL_VERSION,
+              capabilities: {
+                tools: { listChanged: false },
+              },
+              serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+              instructions: SERVER_INSTRUCTIONS,
+            });
+
+      case 'notifications/initialized':
+      case 'initialized':
+        return null;
+
+      case 'ping':
+        return isNotification ? null : jsonRpcResult(message.id, {});
+
+      case 'tools/list':
+        return jsonRpcResult(message.id, { tools: listTools() });
+
+      case 'tools/call':
+        return await handleToolCall(message, context);
+
+      default:
+        if (isNotification) return null;
+        return jsonRpcError(
+          message.id,
+          ErrorCodes.METHOD_NOT_FOUND,
+          `Method not found: ${message.method}`
+        );
+    }
+  } catch (err) {
+    console.error('[mcp] dispatch error:', err);
+    if (isNotification) return null;
+    return jsonRpcError(
+      message.id,
+      ErrorCodes.INTERNAL_ERROR,
+      err.message || 'Internal error'
+    );
+  }
+}
+
+async function handleToolCall(message, context) {
+  const params = message.params || {};
+  const toolName = params.name;
+  const toolInput = params.arguments || {};
+
+  const tool = registeredTools.get(toolName);
+  if (!tool) {
+    return jsonRpcError(
+      message.id,
+      ErrorCodes.METHOD_NOT_FOUND,
+      `Unknown tool: ${toolName}`
+    );
+  }
+
+  try {
+    const result = await tool.handler(toolInput, context);
+    return jsonRpcResult(message.id, toMcpToolResult(result));
+  } catch (err) {
+    // Per MCP spec, tool execution failures are returned as a tool_result
+    // with isError: true rather than a JSON-RPC error — so the client model
+    // can see the failure and react.
+    return jsonRpcResult(message.id, {
+      content: [{ type: 'text', text: err.message || 'Tool execution failed' }],
+      isError: true,
+    });
+  }
+}
+
+function toMcpToolResult(result) {
+  if (result && typeof result === 'object' && Array.isArray(result.content)) {
+    // Tool already returned MCP-shaped content; trust it.
+    return result;
+  }
+  const text =
+    typeof result === 'string' ? result : JSON.stringify(result ?? {}, null, 2);
+  return { content: [{ type: 'text', text }] };
+}
+
+// Tool registrations run on first request rather than at module load. We use
+// dynamic import to avoid a circular dependency: tool modules import
+// `registerTool` from this file.
+let _registered = false;
+export async function ensureToolsRegistered() {
+  if (_registered) return;
+  _registered = true;
+  const { registerContextTools } = await import('@/lib/mcp/tools/context');
+  const { registerBuildTools } = await import('@/lib/mcp/tools/build');
+  const { registerJobsTools } = await import('@/lib/mcp/tools/jobs-tools');
+  const { registerOperateTools } = await import('@/lib/mcp/tools/operate');
+  const { registerFleetTools } = await import('@/lib/mcp/tools/fleet');
+  const { registerCatalystTools } = await import('@/lib/mcp/tools/catalysts');
+  // Order matters only for tools/list output (insertion order). Putting
+  // forward_context first means clients that surface the tool list to the
+  // model see the orientation tool at the top. Fleet tools sit between
+  // per-bot operate and catalysts so the natural reading order is
+  // per-bot → fleet → outcome.
+  registerContextTools();
+  registerBuildTools();
+  registerJobsTools();
+  registerOperateTools();
+  registerFleetTools();
+  registerCatalystTools();
+}

package/lib/mcp/session-binding.js

@@ -0,0 +1,130 @@
+/**
+ * Lazy BuilderSession binding for MCP connections.
+ *
+ * The web chat-builder threads a `session_id` through every tool call;
+ * MCP doesn't have an analogous primitive that's load-bearing for our flow.
+ * Instead, we bind one BuilderSession per `mcp-session-id` header value,
+ * creating it on first build-tool invocation and reusing across calls.
+ *
+ * On reconnect / restart, in-memory map is lost; the user's Claude effectively
+ * starts a new bot. Mirrors the web flow's "tab closed = session orphaned"
+ * behavior. See plan section 9 for the upgrade path (persist + resume).
+ */
+
+import { BuilderSessionRepository } from '@/lib/db/repositories/builderSessions';
+import { DocumentRepository } from '@/lib/db/repositories/documents';
+import { DeploymentRepository } from '@/lib/db/repositories/deployments';
+import { ApiKeyRepository } from '@/lib/db/repositories/apiKeys';
+import { getDefaultModelForTask } from '@/lib/llm-providers';
+
+const ANTHROPIC_DEFAULT_MODEL = 'claude-sonnet-4-6';
+
+// The api_keys table mixes LLM provider keys with cloud-deploy provider keys
+// (Fly.io's API token lives under provider='fly'; see lib/deployers/cloud-deploy.js).
+// When picking a *default LLM* we must filter to providers the chat / builder
+// LLM call sites actually handle — otherwise generate_form_schema and friends
+// throw "Unsupported provider: fly".
+const LLM_PROVIDERS = new Set(['anthropic', 'openai', 'ollama']);
+
+// mcpSessionId → BuilderSession.id
+const bindings = new Map();
+
+/**
+ * Mirror of the web flow's buildPreloadedContext (api/builder/stream/route.js).
+ * Loaded onto every fresh BuilderSession so tool executors can read the
+ * default provider, API key, and workspace docs.
+ */
+async function buildPreloadedContext(userId) {
+  const [documents, apiKeys] = await Promise.all([
+    DocumentRepository.findByBotSpaceId(null),
+    ApiKeyRepository.findByUserId(userId),
+  ]);
+
+  const existingBots = await DeploymentRepository.list();
+
+  const llmKeys = apiKeys.filter((k) => LLM_PROVIDERS.has(k.provider));
+
+  let defaultProvider;
+  let defaultModel;
+  let defaultApiKeyId;
+  const defaultKey = llmKeys.find((k) => k.isDefault) || llmKeys[0];
+  if (defaultKey) {
+    defaultProvider = defaultKey.provider;
+    defaultModel = getDefaultModelForTask(defaultKey.provider, 'reasoning');
+    defaultApiKeyId = defaultKey.id;
+  } else {
+    defaultProvider = 'anthropic';
+    defaultModel = ANTHROPIC_DEFAULT_MODEL;
+  }
+
+  return {
+    organizationName: 'Local',
+    workspaceName: 'Mojulo-Lite',
+    workspaceDocuments: documents.map((d) => ({
+      id: d.id,
+      name: d.originalName,
+      mimeType: d.mimeType,
+    })),
+    existingBots: existingBots
+      .filter((d) => d.status === 'ready' && d.url)
+      .map((d) => ({
+        botName: d.botName,
+        id: d.id,
+        url: d.url,
+        botSummary: d.config?.botSummary || null,
+      })),
+    defaultProvider,
+    defaultModel,
+    defaultApiKeyId,
+    apiKeys: apiKeys.map((k) => ({
+      id: k.id,
+      name: k.name,
+      provider: k.provider,
+    })),
+    disableModuloAnimation: true,
+  };
+}
+
+/**
+ * Get or create the BuilderSession for this MCP connection. Always refreshes
+ * the session row from SQLite so tool handlers see writes from prior tool
+ * calls in the same connection.
+ */
+export async function getOrCreateBuilderSession(mcpSessionId, userId) {
+  const existingId = bindings.get(mcpSessionId);
+  if (existingId) {
+    const session = await BuilderSessionRepository.findById(existingId);
+    if (session) return session;
+    bindings.delete(mcpSessionId);
+  }
+
+  const apiKeys = await ApiKeyRepository.findByUserId(userId);
+  const hasLlmKey = apiKeys.some((k) => LLM_PROVIDERS.has(k.provider));
+  if (!hasLlmKey) {
+    throw new Error(
+      'No LLM provider key configured on the control plane. Add an Anthropic / OpenAI / Ollama key at /settings before using the MCP build tools. (Cloud-deploy tokens like Fly do not count.)'
+    );
+  }
+
+  const preloadedContext = await buildPreloadedContext(userId);
+  const session = await BuilderSessionRepository.createWithContext({
+    userId,
+    botSpaceId: null,
+    preloadedContext,
+  });
+  bindings.set(mcpSessionId, session.id);
+  return session;
+}
+
+/**
+ * Force a new BuilderSession on the next build-tool call. Used by the
+ * `start_new_bot` MCP tool so the user's Claude can build a second bot in
+ * the same MCP connection without restarting the client.
+ */
+export function resetBuilderSession(mcpSessionId) {
+  bindings.delete(mcpSessionId);
+}
+
+export function getBoundSessionId(mcpSessionId) {
+  return bindings.get(mcpSessionId) || null;
+}

package/lib/mcp/tools/build.js

@@ -0,0 +1,123 @@
+/**
+ * MCP Ring 1 — build tools.
+ *
+ * Each tool here is a thin wrapper around a handler in
+ * [@/lib/builder/tool-executors](control/lib/builder/tool-executors.js).
+ * The wrapper:
+ *   1. Lazily binds a BuilderSession to the MCP connection (first call).
+ *   2. Refreshes the session row so writes from prior tool calls are visible.
+ *   3. Delegates to executeBuilderTool, surfaces success / error to MCP.
+ *
+ * Tool schemas are derived from BUILDER_TOOLS — single source of truth lives
+ * in [@/lib/builder/tools](control/lib/builder/tools.js). The MCP `inputSchema`
+ * is the same JSON Schema the web chat builder gives Claude, so the user's
+ * Claude sees an identical tool surface.
+ *
+ * Phase 1 registers synchronous tools only. `process_documents` and
+ * `save_modular_bot` are deferred to Phase 2 (job-based) because they can run
+ * >2s and need a poll interface.
+ */
+
+import { BUILDER_TOOLS } from '@/lib/builder/tools';
+import { executeBuilderTool } from '@/lib/builder/tool-executors';
+import { BuilderSessionRepository } from '@/lib/db/repositories/builderSessions';
+import {
+  getOrCreateBuilderSession,
+  resetBuilderSession,
+} from '@/lib/mcp/session-binding';
+import { registerTool } from '@/lib/mcp/server';
+
+const SYNC_TOOL_NAMES = new Set([
+  'infer_intent',
+  'recommend_protocols',
+  'generate_form_schema',
+  'generate_appointment_config',
+  'generate_triage_config',
+  'generate_optical_read_config',
+  'compose_identity',
+  'set_suggested_prompts',
+  'generate_bot_summary',
+]);
+
+function findBuilderToolSchema(name) {
+  const tool = BUILDER_TOOLS.find((t) => t.name === name);
+  if (!tool) throw new Error(`BUILDER_TOOLS is missing ${name}`);
+  return tool;
+}
+
+/**
+ * Build a context the existing tool executors expect: { session, userId }.
+ * The session is re-fetched on every call to pick up writes from prior tool
+ * invocations in the same MCP connection (each call mutates SQLite, but the
+ * in-memory object would be stale otherwise).
+ */
+async function buildExecutorContext(mcpContext) {
+  const session = await getOrCreateBuilderSession(
+    mcpContext.mcpSessionId,
+    mcpContext.userId
+  );
+  return { session, userId: mcpContext.userId };
+}
+
+function makeHandler(toolName) {
+  return async function handle(input, mcpContext) {
+    const ctx = await buildExecutorContext(mcpContext);
+    const result = await executeBuilderTool(toolName, input, ctx);
+    if (!result.success) {
+      throw new Error(result.error || `${toolName} failed`);
+    }
+    return result.result;
+  };
+}
+
+export function registerBuildTools() {
+  for (const name of SYNC_TOOL_NAMES) {
+    const schema = findBuilderToolSchema(name);
+    registerTool({
+      name: schema.name,
+      description: schema.description,
+      inputSchema: schema.input_schema,
+      handler: makeHandler(name),
+    });
+  }
+
+  // Ergonomic extra not in BUILDER_TOOLS — lets the user's Claude start over
+  // without dropping the MCP connection. Mirrors closing/reopening the web
+  // chat-builder tab.
+  registerTool({
+    name: 'start_new_bot',
+    description:
+      'Reset the builder session for this MCP connection so the next build tool call starts a fresh bot from scratch. Use when the user wants to build a second bot in the same session, or to discard in-progress configuration.',
+    inputSchema: { type: 'object', properties: {} },
+    handler: async (_input, mcpContext) => {
+      resetBuilderSession(mcpContext.mcpSessionId);
+      return { message: 'Builder session reset. The next build tool call will start a new bot.' };
+    },
+  });
+
+  // Lets the user's Claude inspect the in-progress configuration without
+  // peeking at the SQLite row directly. Read-only, no session mutation.
+  registerTool({
+    name: 'get_builder_session',
+    description:
+      'Return the current builder session state for this MCP connection — inferred intent, recommended protocols, identity, generated configs. Useful for the model to see what it has built so far before composing the final save.',
+    inputSchema: { type: 'object', properties: {} },
+    handler: async (_input, mcpContext) => {
+      const session = await getOrCreateBuilderSession(
+        mcpContext.mcpSessionId,
+        mcpContext.userId
+      );
+      const fresh = await BuilderSessionRepository.findById(session.id);
+      return {
+        sessionId: fresh.id,
+        status: fresh.status,
+        inferredIntent: fresh.inferredIntent,
+        intentConfidence: fresh.intentConfidence,
+        recommendedProtocols: fresh.recommendedProtocols,
+        enabledProtocols: fresh.enabledProtocols,
+        generatedConfigs: fresh.generatedConfigs,
+        deploymentId: fresh.deploymentId,
+      };
+    },
+  });
+}