mulmoterminal 0.1.0

package/server/mcp/broker.ts

@@ -0,0 +1,105 @@
+// GUI chat-protocol MCP server, built per session and served over HTTP from the
+// main mulmoterminal process (see the `/mcp/:sessionId` route in server/index.ts).
+// Registers one MCP tool per enabled plugin (from server/plugins-registry.js,
+// driven by plugins/plugins.json) and acts as a thin bridge to the host routes:
+//
+//   tool call  ->  POST /api/plugin/<toolName>         (the dispatch route)
+//              ->  envelope { data, message, instructions, title? }
+//              ->  POST /api/agent/toolResult           (store + publish; data gates it)
+//              ->  return message+instructions text to claude
+//
+// Tools are registered straight from gui-chat-protocol ToolDefinitions: the
+// JSON-schema `parameters` is passed through as the MCP inputSchema (no zod). This
+// is the same shape MulmoClaude's broker uses (server/agent/mcp-server.ts), and it
+// is why we drive the low-level Server API directly instead of McpServer.registerTool
+// (which expects a zod raw shape) — so a shared plugin package's JSON-schema
+// definition becomes an MCP tool without translation.
+//
+// The form round-trip is NOT a blocking call: the user's answer comes back by being
+// typed into the PTY (see the GUI panel / form view), so every tool returns at once.
+//
+// Previously this ran as a per-session stdio subprocess that claude spawned via
+// --mcp-config. It now lives in-process and is exposed over Streamable HTTP so the
+// agent can reach it from anywhere (host or, later, a Docker sandbox) without us
+// shipping the server code + tsx into the agent's environment. The session id and
+// the host base URL are passed in by the caller instead of via env.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { randomUUID } from "node:crypto";
+import { toolDefinitions } from "../plugins-registry.js";
+
+// Shape of the dispatch route's response (POST /api/plugin/<tool>). `data` gates
+// whether a toolResult is published to the GUI; the rest is narration/metadata.
+interface ToolEnvelope {
+  data?: unknown;
+  title?: unknown;
+  jsonData?: unknown;
+  message?: unknown;
+  instructions?: unknown;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null;
+
+async function postJson(url: string, body: unknown) {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(`${url} responded ${res.status}`);
+  return res;
+}
+
+// A ToolDefinition's optional `prompt` is host-injected usage guidance that isn't
+// part of the JSON-schema sent to the model; fold it into the description so claude
+// still sees it (MulmoClaude does the same).
+function describe(def: { description?: string; prompt?: string }) {
+  return [def.description, def.prompt].filter(Boolean).join("\n\n");
+}
+
+/**
+ * Build a fresh GUI MCP server bound to one chat session. Stateless: create one
+ * per request (Streamable HTTP in stateless mode forbids reusing a transport, and
+ * the server has no per-connection state beyond the captured `sessionId`).
+ *
+ * @param sessionId  the chat session whose GUI panel should render tool results
+ * @param baseUrl    the mulmoterminal host origin to POST plugin dispatch + results to
+ */
+export function buildGuiMcpServer(sessionId: string, baseUrl: string): Server {
+  const server = new Server({ name: "mulmoterminal-gui", version: "0.0.0" }, { capabilities: { tools: {} } });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: toolDefinitions.map((def) => ({
+      name: def.name,
+      description: describe(def),
+      inputSchema: def.parameters ?? { type: "object", properties: {} },
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    // 1. Dispatch to the plugin's server-side handler.
+    const parsed = await (await postJson(`${baseUrl}/api/plugin/${name}`, args ?? {})).json();
+    const envelope: ToolEnvelope = isRecord(parsed) ? parsed : {};
+
+    // 2. Publish a toolResult to the GUI — only when there is data to render.
+    if (envelope.data !== undefined) {
+      await postJson(`${baseUrl}/api/agent/toolResult`, {
+        sessionId,
+        toolName: name,
+        uuid: randomUUID(),
+        title: envelope.title,
+        data: envelope.data,
+        jsonData: envelope.jsonData ?? envelope.data,
+        message: envelope.message,
+      });
+    }
+
+    // 3. Return the narration to claude.
+    const parts = [envelope.message, envelope.instructions].filter(Boolean);
+    return { content: [{ type: "text", text: parts.length ? parts.join("\n") : "Done" }] };
+  });
+
+  return server;
+}

package/server/plugins-registry.ts

@@ -0,0 +1,110 @@
+// Server-side plugin registry. Loads two kinds of GUI-protocol plugins and
+// normalizes them into one shape the MCP broker and the dispatch route consume:
+//
+//   - packages: gui-chat-protocol plugin packages (e.g. @gui-chat-plugin/markdown).
+//       Their core entry exports a ToolPluginCore { toolDefinition, execute } plus
+//       TOOL_DEFINITION. These are shared VERBATIM with MulmoClaude — one source of
+//       truth, loaded as an npm dependency.
+//   - local:    in-tree plugins under plugins/<name>/ whose definition.js exports a
+//       gui-chat-protocol ToolDefinition and whose server.js exports execute(args).
+//       These are pre-extraction holdovers that migrate to packages over time.
+//
+// Both the main server (which mounts the dispatch route) and the MCP broker (which
+// registers the tools) import this, so the GUI tool set is driven entirely by
+// plugins.json.
+import fs from "fs";
+import path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+import type { Express } from "express";
+import { generateImage } from "./backends/image-gen.js";
+import { markdownHostApp } from "./backends/markdown.js";
+import { HOST_TOOL_DEFINITIONS } from "./host-tools.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PLUGINS_DIR = path.join(__dirname, "..", "plugins");
+
+const MCP_SERVER_NAME = "mulmoterminal-gui";
+
+// The gui-chat-protocol ToolContext.app — host-provided backends a plugin's
+// execute() may call (e.g. @mulmochat-plugin/generate-image calls
+// `context.app.generateImage(prompt)`). Plugins that don't need a backend simply
+// ignore it. Passed to every package's execute below.
+// Spread the markdown host app (loadDoc/saveDoc/saveNewDoc/marpThemes/exportPdf/
+// fillImages) alongside generateImage — context.app is a shared capability bag;
+// each plugin's execute uses only what it needs. The markdown backend is
+// initialised with the workspace + pubsub at boot (server/index.ts).
+const APP_CONTEXT = { generateImage, ...markdownHostApp };
+
+function loadConfig() {
+  const raw = fs.readFileSync(path.join(PLUGINS_DIR, "plugins.json"), "utf8");
+  const parsed = JSON.parse(raw);
+  return {
+    packages: Array.isArray(parsed.packages) ? parsed.packages : [],
+    local: Array.isArray(parsed.local) ? parsed.local : [],
+  };
+}
+
+// A gui-chat-protocol package. The core entry exposes TOOL_DEFINITION (a JSON-schema
+// ToolDefinition) and a ToolPluginCore whose execute(context, args) returns the
+// result envelope. We invoke it in-process when the broker dispatches, passing the
+// host backends as context.app (image generation, etc.).
+async function loadPackage(name: string) {
+  const mod = await import(name);
+  const definition = mod.TOOL_DEFINITION ?? mod.pluginCore?.toolDefinition;
+  const execute = mod.pluginCore?.execute ?? mod.execute;
+  if (!definition || typeof execute !== "function") {
+    throw new Error(`Package "${name}" is not a gui-chat-protocol plugin (missing TOOL_DEFINITION/execute).`);
+  }
+  return { toolName: definition.name, definition, execute: (args?: unknown) => execute({ app: APP_CONTEXT }, args ?? {}) };
+}
+
+// A local plugin: definition.js exports TOOL_DEFINITION (a gui-chat-protocol
+// ToolDefinition), server.js exports execute(args).
+async function loadLocal(name: string) {
+  const dir = path.join(PLUGINS_DIR, name);
+  const importJs = (file: string) => import(pathToFileURL(path.join(dir, file)).href);
+  const [{ TOOL_DEFINITION }, { execute }] = await Promise.all([importJs("definition.js"), importJs("server.js")]);
+  if (!TOOL_DEFINITION || typeof execute !== "function") {
+    throw new Error(`Local plugin "${name}" must export TOOL_DEFINITION and execute().`);
+  }
+  return { toolName: TOOL_DEFINITION.name, definition: TOOL_DEFINITION, execute: (args?: unknown) => execute(args ?? {}) };
+}
+
+const config = loadConfig();
+// Top-level await: the loaded set is ready by the time importers use it.
+export const plugins = [...(await Promise.all(config.packages.map(loadPackage))), ...(await Promise.all(config.local.map(loadLocal)))];
+
+const byName = Object.fromEntries(plugins.map((p) => [p.toolName, p]));
+
+// MCP tool definitions the broker registers — gui-chat-protocol ToolDefinitions
+// ({ name, description, prompt?, parameters }), one per enabled plugin plus the
+// built-in host tools (which the server dispatches itself; see host-tools.ts).
+export const toolDefinitions = [...plugins.map((p) => p.definition), ...HOST_TOOL_DEFINITIONS];
+
+// JSON-serializable summaries (no schema) for the GUI's tools pane.
+export const toolSummaries = toolDefinitions.map((d) => ({
+  toolName: d.name,
+  title: d.name,
+  description: d.description,
+}));
+
+// Mount the uniform dispatch route. The MCP broker POSTs a tool's args to
+// /api/plugin/<toolName>; the plugin's execute returns the result envelope
+// { data?, jsonData?, message?, instructions?, title? } the broker forwards.
+export function mountAllRoutes(app: Express) {
+  app.post("/api/plugin/:toolName", async (req, res) => {
+    const plugin = byName[req.params.toolName];
+    if (!plugin) return res.status(404).json({ error: `Unknown tool: ${req.params.toolName}` });
+    try {
+      res.json(await plugin.execute(req.body));
+    } catch (e) {
+      res.status(400).json({ error: e instanceof Error ? e.message : String(e) });
+    }
+  });
+}
+
+// Fully-qualified MCP tool names for claude's --allowedTools (auto-run, no prompt).
+// Includes host tools so they run without a permission prompt too.
+export function allowedToolNames() {
+  return toolDefinitions.map((d) => `mcp__${MCP_SERVER_NAME}__${d.name}`);
+}

package/server/pubsub.ts

@@ -0,0 +1,36 @@
+import { Server as IOServer } from "socket.io";
+import type { Server as HttpServer } from "node:http";
+
+// Minimal socket.io pub/sub, modeled on mulmoclaude's server/events/pub-sub.
+// Channel names are socket.io rooms — subscribe/unsubscribe map to
+// socket.join / socket.leave, and publish broadcasts to the room.
+// socket.io handles reconnect / heartbeat / transport for us.
+export function createPubSub(server: HttpServer, isAllowedOrigin: (origin?: string) => boolean = () => true) {
+  const io = new IOServer(server, {
+    path: "/ws/pubsub",
+    transports: ["websocket"],
+    // Reject cross-origin connections so an untrusted website can't subscribe to
+    // session activity. allowRequest covers the websocket handshake; cors covers
+    // any polling/preflight.
+    allowRequest: (req, cb) => cb(null, isAllowedOrigin(req.headers.origin)),
+    cors: {
+      origin: (origin, cb) => cb(null, isAllowedOrigin(origin)),
+      credentials: true,
+    },
+  });
+
+  io.on("connection", (socket) => {
+    socket.on("subscribe", (channel) => {
+      if (typeof channel === "string") socket.join(channel);
+    });
+    socket.on("unsubscribe", (channel) => {
+      if (typeof channel === "string") socket.leave(channel);
+    });
+  });
+
+  return {
+    publish(channel: string, data: unknown) {
+      io.to(channel).emit("data", { channel, data });
+    },
+  };
+}