mulmoclaude 0.1.0

package/server/agent/mcp-server.ts

@@ -0,0 +1,412 @@
+/**
+ * Standalone MCP stdio server — spawned by the Claude CLI via --mcp-config.
+ * Bridges Claude's tool calls to our server endpoints and pushes ToolResults
+ * back to the active frontend SSE stream via the session registry.
+ */
+
+import type { ToolDefinition } from "gui-chat-protocol";
+import { mcpTools, isMcpToolEnabled } from "./mcp-tools/index.js";
+import { TOOL_ENDPOINTS, PLUGIN_DEFS } from "./plugin-names.js";
+import { errorMessage } from "../utils/errors.js";
+import { isNonEmptyString, isRecord } from "../utils/types.js";
+import { API_ROUTES } from "../../src/config/apiRoutes.js";
+import { env } from "../system/env.js";
+import { extractFetchError } from "../utils/fetch.js";
+import { safeResponseText } from "../utils/http.js";
+import { readTextSafeSync } from "../utils/files/safe.js";
+import { WORKSPACE_PATHS } from "../workspace/paths.js";
+
+type JsonRpcId = string | number | null;
+
+interface ToolCallParams {
+  name: string;
+  arguments?: Record<string, unknown>;
+}
+
+interface JsonRpcMessage {
+  jsonrpc: string;
+  id?: JsonRpcId;
+  method: string;
+  params?: ToolCallParams;
+}
+
+const isJsonRpcMessage = (v: unknown): v is JsonRpcMessage => isRecord(v) && "method" in v;
+
+const SESSION_ID = env.mcpSessionId;
+const PORT = env.port;
+const PLUGIN_NAMES = env.mcpPluginNames;
+const ROLE_IDS = env.mcpRoleIds;
+const MCP_HOST = env.mcpHost;
+const BASE_URL = `http://${MCP_HOST}:${PORT}`;
+
+// Bearer token for /api/* calls back to the parent server (#272).
+// The parent writes it to <workspace>/.session-token at startup; we
+// read once at module load — the token is immutable for the server's
+// lifetime. Same resolution order as bridges/cli/token.ts.
+function readSessionToken(): string {
+  const fromEnv = process.env.MULMOCLAUDE_AUTH_TOKEN;
+  if (isNonEmptyString(fromEnv)) return fromEnv;
+  return readTextSafeSync(WORKSPACE_PATHS.sessionToken)?.trim() ?? "";
+}
+const SESSION_TOKEN = readSessionToken();
+const AUTH_HEADER: Record<string, string> = SESSION_TOKEN ? { Authorization: `Bearer ${SESSION_TOKEN}` } : {};
+
+interface ToolDef {
+  name: string;
+  description: string;
+  inputSchema: object;
+  endpoint?: string; // absent for tools handled specially (e.g. switchRole)
+}
+
+// Combine `description` (one-liner) and `prompt` (detailed usage
+// instructions) into the MCP tool description so Claude CLI sees
+// both. The MCP protocol only has `description` — there's no
+// `prompt` field — so the prompt content must ride along in the
+// description string. The gui-chat-protocol ToolDefinition carries
+// `prompt` separately because the Vue client uses it for different
+// purposes, but the CLI needs it in-band.
+function fromPackage(def: ToolDefinition, endpoint: string): ToolDef {
+  const parts = [def.description];
+  if (typeof def.prompt === "string" && def.prompt.length > 0) {
+    parts.push(def.prompt);
+  }
+  return {
+    name: def.name,
+    description: parts.join("\n\n"),
+    inputSchema: def.parameters ?? {},
+    endpoint,
+  };
+}
+
+// Pure MCP tools (no GUI) — auto-registered from server/mcp-tools/
+const mcpToolDefs: Record<string, ToolDef> = Object.fromEntries(
+  mcpTools.filter(isMcpToolEnabled).map((t) => [
+    t.definition.name,
+    {
+      name: t.definition.name,
+      description: t.definition.description,
+      inputSchema: t.definition.inputSchema,
+    },
+  ]),
+);
+
+const ALL_TOOLS: Record<string, ToolDef> = {
+  ...mcpToolDefs,
+  ...Object.fromEntries(PLUGIN_DEFS.map((def) => [def.name, fromPackage(def, TOOL_ENDPOINTS[def.name])])),
+  switchRole: {
+    name: "switchRole",
+    description: "Switch to a different AI role, resetting the conversation context. Use when the user's request is better served by another role.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        roleId: {
+          type: "string",
+          enum: ROLE_IDS,
+          description: "The ID of the role to switch to.",
+        },
+      },
+      required: ["roleId"],
+    },
+  },
+};
+
+const tools = PLUGIN_NAMES.map((name) => ALL_TOOLS[name]).filter(Boolean);
+
+function respond(msg: unknown): void {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+// All bridge calls go to the same backend on the same session, so
+// every fetch was duplicating the same headers, method, and
+// stringify boilerplate. `postJson` captures BASE_URL + SESSION_ID
+// once and lets handleToolCall focus on what it's calling, not how.
+//
+// `path` is the absolute server path (e.g. /api/internal/tool-result)
+// — the session query string is appended automatically.
+//
+// Both network errors and HTTP failures (4xx/5xx) are converted into
+// a descriptive Error by default, so the outer catch in handleToolCall
+// reports them as the failed tool call instead of a silent success.
+// Pass `allowHttpError: true` for callers that want to inspect the
+// response themselves (e.g. /api/mcp-tools/* which has its own
+// status-aware result handling).
+interface PostJsonOpts {
+  allowHttpError?: boolean;
+}
+
+async function postJson(path: string, body: unknown, opts: PostJsonOpts = {}): Promise<Response> {
+  // SESSION_ID comes from the parent process env so it's effectively
+  // trusted, but encode it anyway — defense in depth against future
+  // callers passing unexpected characters (`&`, `#`, newlines, etc.).
+  // The path arg is used as-is because all current call sites pass
+  // hardcoded literals.
+  let res: Response;
+  try {
+    res = await fetch(`${BASE_URL}${path}?session=${encodeURIComponent(SESSION_ID)}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...AUTH_HEADER },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    throw new Error(`Network error calling ${path}: ${errorMessage(err)}`);
+  }
+  if (!opts.allowHttpError && !res.ok) {
+    const errBody = await safeResponseText(res, 500);
+    const detail = errBody ? `: ${errBody}` : "";
+    throw new Error(`HTTP ${res.status} calling ${path}${detail}`);
+  }
+  return res;
+}
+
+// Bridge for the manageSkills tool. Routes by `action`:
+//   - "list" (default): GET /api/skills, push the list as a ToolResult
+//   - "save"          : POST /api/skills with { name, description, body }
+//   - "delete"        : DELETE /api/skills/:name
+// In every case, after a successful mutation we re-fetch the list and
+// push it so the canvas reflects the new state immediately.
+async function handleManageSkills(args: Record<string, unknown>): Promise<string> {
+  const action = typeof args.action === "string" ? args.action : "list";
+  if (action === "save") return handleManageSkillsSave(args);
+  if (action === "update") return handleManageSkillsUpdate(args);
+  if (action === "delete") return handleManageSkillsDelete(args);
+  return handleManageSkillsList();
+}
+
+async function fetchSkillsList(): Promise<{ name: string }[]> {
+  const url = `${BASE_URL}/api/skills?session=${encodeURIComponent(SESSION_ID)}`;
+  let res: Response;
+  try {
+    res = await fetch(url, { headers: AUTH_HEADER });
+  } catch (err) {
+    throw new Error(`Network error calling /api/skills: ${errorMessage(err)}`);
+  }
+  if (!res.ok) {
+    const body = await safeResponseText(res);
+    throw new Error(`HTTP ${res.status} calling /api/skills: ${body}`);
+  }
+  const body: { skills: { name: string }[] } = await res.json();
+  return body.skills;
+}
+
+async function pushSkillsListResult(message: string): Promise<void> {
+  const skills = await fetchSkillsList();
+  await postJson(API_ROUTES.agent.internal.toolResult, {
+    toolName: "manageSkills",
+    uuid: crypto.randomUUID(),
+    title: "Skills",
+    message,
+    data: { skills },
+  });
+}
+
+async function handleManageSkillsList(): Promise<string> {
+  const skills = await fetchSkillsList();
+  const suffix = skills.length === 1 ? "" : "s";
+  await postJson(API_ROUTES.agent.internal.toolResult, {
+    toolName: "manageSkills",
+    uuid: crypto.randomUUID(),
+    title: "Skills",
+    message: `Found ${skills.length} skill${suffix}.`,
+    data: { skills },
+  });
+  return `Listed ${skills.length} skill${suffix}`;
+}
+
+async function handleManageSkillsSave(args: Record<string, unknown>): Promise<string> {
+  // Normalize name once up front so log / result messages below never
+  // interpolate an accidental object / number into `/${name}`.
+  const name = String(args.name ?? "");
+  const res = await postJson(
+    API_ROUTES.skills.create,
+    {
+      name,
+      description: args.description,
+      body: args.body,
+    },
+    { allowHttpError: true },
+  );
+  if (!res.ok) {
+    return "Error: " + (await extractFetchError(res));
+  }
+  await pushSkillsListResult(`Saved skill "${name}".`);
+  return `Saved skill ${name}. Run with /${name}.`;
+}
+
+async function handleManageSkillsUpdate(args: Record<string, unknown>): Promise<string> {
+  const name = String(args.name ?? "");
+  const url = `${BASE_URL}/api/skills/${encodeURIComponent(name)}?session=${encodeURIComponent(SESSION_ID)}`;
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: "PUT",
+      headers: { ...AUTH_HEADER, "Content-Type": "application/json" },
+      body: JSON.stringify({
+        description: args.description,
+        body: args.body,
+      }),
+    });
+  } catch (err) {
+    throw new Error(`Network error calling PUT /api/skills/${name}: ${errorMessage(err)}`);
+  }
+  if (!res.ok) {
+    return "Error: " + (await extractFetchError(res));
+  }
+  await pushSkillsListResult(`Updated skill "${name}".`);
+  return `Updated skill ${name}. The changes take effect in new sessions.`;
+}
+
+async function handleManageSkillsDelete(args: Record<string, unknown>): Promise<string> {
+  const name = String(args.name ?? "");
+  const url = `/api/skills/${encodeURIComponent(name)}?session=${encodeURIComponent(SESSION_ID)}`;
+  let res: Response;
+  try {
+    res = await fetch(`${BASE_URL}${url}`, {
+      method: "DELETE",
+      headers: AUTH_HEADER,
+    });
+  } catch (err) {
+    throw new Error(`Network error calling DELETE ${url}: ${errorMessage(err)}`);
+  }
+  if (!res.ok) {
+    return "Error: " + (await extractFetchError(res));
+  }
+  await pushSkillsListResult(`Deleted skill "${name}".`);
+  return `Deleted skill ${name}.`;
+}
+
+async function handleToolCall(name: string, args: Record<string, unknown>): Promise<string> {
+  if (name === "switchRole") {
+    await postJson(API_ROUTES.agent.internal.switchRole, {
+      roleId: args.roleId,
+    });
+    return `Switching to ${args.roleId} role`;
+  }
+
+  if (name === "manageRoles") {
+    const res = await postJson(API_ROUTES.roles.manage, args);
+    const result = await res.json();
+
+    // For the list action, push a visual canvas result so the viewer renders
+    if (args.action === "list" && result.success) {
+      await postJson(API_ROUTES.agent.internal.toolResult, {
+        toolName: "manageRoles",
+        uuid: crypto.randomUUID(),
+        ...result,
+      });
+    }
+
+    return result.message ?? (result.error ? `Error: ${result.error}` : "Done");
+  }
+
+  if (name === "manageSkills") return handleManageSkills(args);
+
+  // Pure MCP tools — call via /api/mcp-tools/:tool, return text directly
+  // (no frontend push). Opt out of postJson's HTTP error throw because
+  // we want to surface the JSON error body to the caller as a string.
+  const mcpTool = mcpTools.find((t) => t.definition.name === name);
+  if (mcpTool) {
+    const res = await postJson(`/api/mcp-tools/${name}`, args, {
+      allowHttpError: true,
+    });
+    const json = await res.json();
+    if (!res.ok) return `Error: ${json.error ?? res.status}`;
+    return typeof json.result === "string" ? json.result : JSON.stringify(json.result);
+  }
+
+  const tool = tools.find((t) => t.name === name);
+  if (!tool) throw new Error(`Unknown tool: ${name}`);
+
+  const res = await postJson(tool.endpoint!, args);
+  const result = await res.json();
+
+  // Push visual ToolResult to the frontend via the session
+  await postJson(API_ROUTES.agent.internal.toolResult, {
+    toolName: name,
+    uuid: crypto.randomUUID(),
+    ...result,
+  });
+
+  const parts = [result.message, result.instructions].filter(Boolean);
+  return parts.length > 0 ? parts.join("\n") : "Done";
+}
+
+let buffer = "";
+
+process.stdin.on("data", (chunk: Buffer) => {
+  buffer += chunk.toString();
+  const lines = buffer.split("\n");
+  buffer = lines.pop() ?? "";
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let msg: unknown;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isJsonRpcMessage(msg)) continue;
+
+    const { id, method, params } = msg;
+
+    if (method === "initialize") {
+      respond({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: "2024-11-05",
+          capabilities: { tools: {} },
+          serverInfo: { name: "mulmoclaude", version: "1.0.0" },
+        },
+      });
+    } else if (method === "tools/list") {
+      respond({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          tools: tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+          })),
+        },
+      });
+    } else if (method === "tools/call") {
+      if (!params?.name) {
+        respond({
+          jsonrpc: "2.0",
+          id,
+          error: {
+            code: -32602,
+            message: "Invalid params: tools/call requires params.name",
+          },
+        });
+        continue;
+      }
+      const toolArgs = params.arguments ?? {};
+      handleToolCall(params.name, toolArgs)
+        .then((text) => {
+          respond({
+            jsonrpc: "2.0",
+            id,
+            result: { content: [{ type: "text", text }] },
+          });
+        })
+        .catch((err: unknown) => {
+          respond({
+            jsonrpc: "2.0",
+            id,
+            result: {
+              content: [{ type: "text", text: String(err) }],
+              isError: true,
+            },
+          });
+        });
+    } else if (method === "ping") {
+      respond({ jsonrpc: "2.0", id, result: {} });
+    }
+    // notifications/initialized and other notifications: no response needed
+  }
+});
+
+process.stdin.on("end", () => process.exit(0));

package/server/agent/mcp-tools/index.ts

@@ -0,0 +1,63 @@
+import { Router, Request, Response } from "express";
+import { readXPost, searchX } from "./x.js";
+import { errorMessage } from "../../utils/errors.js";
+import { notFound, sendError, serverError } from "../../utils/httpError.js";
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+
+export interface McpTool {
+  definition: {
+    name: string;
+    description: string;
+    inputSchema: object;
+  };
+  requiredEnv?: string[];
+  prompt?: string;
+  handler: (args: Record<string, unknown>) => Promise<string>;
+}
+
+export const mcpTools: McpTool[] = [readXPost, searchX];
+
+const toolMap = new Map(mcpTools.map((t) => [t.definition.name, t]));
+
+export function isMcpToolEnabled(tool: McpTool): boolean {
+  return (tool.requiredEnv ?? []).every((key) => !!process.env[key]);
+}
+
+// Express router ──────────────────────────────────────────────────────────────
+
+export const mcpToolsRouter = Router();
+
+interface McpToolParams {
+  tool: string;
+}
+
+// GET /api/mcp-tools — returns { name, enabled, requiredEnv } for each tool (used by the role builder UI)
+mcpToolsRouter.get(API_ROUTES.mcpTools.list, (_req: Request, res: Response) => {
+  res.json(
+    mcpTools.map((t) => ({
+      name: t.definition.name,
+      enabled: isMcpToolEnabled(t),
+      requiredEnv: t.requiredEnv ?? [],
+      prompt: t.prompt,
+    })),
+  );
+});
+
+// POST /api/mcp-tools/:tool — dispatches to the right handler
+mcpToolsRouter.post(API_ROUTES.mcpTools.invoke, async (req: Request<McpToolParams, unknown, Record<string, unknown>>, res: Response) => {
+  const tool = toolMap.get(req.params.tool);
+  if (!tool) {
+    notFound(res, `Unknown MCP tool: ${req.params.tool}`);
+    return;
+  }
+  if (!isMcpToolEnabled(tool)) {
+    sendError(res, 503, `Tool ${req.params.tool} is not configured.`);
+    return;
+  }
+  try {
+    const result = await tool.handler(req.body);
+    res.json({ result });
+  } catch (err) {
+    serverError(res, errorMessage(err));
+  }
+});

package/server/agent/mcp-tools/x.ts

@@ -0,0 +1,188 @@
+import { errorMessage } from "../../utils/errors.js";
+import { safeResponseText } from "../../utils/http.js";
+import { env } from "../../system/env.js";
+
+const X_API_BASE = "https://api.twitter.com/2";
+const TWEET_FIELDS = "tweet.fields=created_at,author_id,public_metrics,entities";
+const EXPANSIONS = "expansions=author_id";
+const USER_FIELDS = "user.fields=name,username";
+
+interface XUser {
+  id: string;
+  name: string;
+  username: string;
+}
+
+interface XTweet {
+  id: string;
+  text: string;
+  author_id?: string;
+  created_at?: string;
+  public_metrics?: {
+    like_count: number;
+    retweet_count: number;
+    reply_count: number;
+  };
+}
+
+interface XApiResponse {
+  data?: XTweet | XTweet[];
+  includes?: { users?: XUser[] };
+  errors?: { detail: string }[];
+  meta?: { result_count: number };
+}
+
+async function fetchX(path: string): Promise<XApiResponse> {
+  const token = env.xBearerToken;
+  if (!token) throw new Error("X_BEARER_TOKEN is not configured in .env");
+
+  let response: Response;
+  try {
+    response = await fetch(`${X_API_BASE}${path}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+  } catch (err) {
+    throw new Error(`Network error calling X API: ${errorMessage(err)}`);
+  }
+
+  if (response.status === 401) throw new Error("X API error 401: Invalid or expired Bearer Token.");
+  if (response.status === 429) throw new Error("X API error 429: Rate limit exceeded. Please wait before retrying.");
+  if (!response.ok) {
+    const body = await safeResponseText(response);
+    throw new Error(`X API error ${response.status}: ${body}`);
+  }
+
+  return response.json() as Promise<XApiResponse>;
+}
+
+function formatTweet(tweet: XTweet, author?: XUser, url?: string): string {
+  const date = tweet.created_at ? new Date(tweet.created_at).toISOString().split("T")[0] : "";
+  const dateSuffix = date ? ` · ${date}` : "";
+  const byline = author ? `@${author.username} (${author.name})${dateSuffix}` : date;
+  const metrics = tweet.public_metrics
+    ? `Likes: ${tweet.public_metrics.like_count} | Retweets: ${tweet.public_metrics.retweet_count} | Replies: ${tweet.public_metrics.reply_count}`
+    : "";
+  const link = url ?? "";
+  return [byline, "", tweet.text, "", metrics, link]
+    .filter((l) => l !== undefined)
+    .join("\n")
+    .trimEnd();
+}
+
+// ── readXPost ──────────────────────────────────────────────────────────────────
+
+export const readXPost = {
+  definition: {
+    name: "readXPost",
+    description: "Fetch the content of a single X (Twitter) post by URL or tweet ID. Returns the author, text, and engagement metrics.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description: "Full X post URL (https://x.com/user/status/ID) or bare tweet ID.",
+        },
+      },
+      required: ["url"],
+    },
+  },
+
+  requiredEnv: ["X_BEARER_TOKEN"],
+
+  prompt: "Use the readXPost tool whenever the user shares a URL from x.com or twitter.com.",
+
+  async handler(args: Record<string, unknown>): Promise<string> {
+    const url = String(args.url ?? "");
+    const match = url.match(/status\/(\d+)/);
+    const tweetId = match ? match[1] : /^\d+$/.test(url) ? url : null;
+    if (!tweetId) return `Could not extract a tweet ID from: ${url}. Provide a full x.com URL or a numeric tweet ID.`;
+
+    let data: XApiResponse;
+    try {
+      data = await fetchX(`/tweets/${tweetId}?${TWEET_FIELDS}&${EXPANSIONS}&${USER_FIELDS}`);
+    } catch (err) {
+      return errorMessage(err);
+    }
+
+    if (data.errors?.length) return `X API error: ${data.errors.map((e) => e.detail).join("; ")}`;
+
+    const tweet = data.data as XTweet | undefined;
+    if (!tweet) return "Tweet not found.";
+
+    const author = data.includes?.users?.find((u) => u.id === tweet.author_id);
+    const canonicalUrl = author ? `https://x.com/${author.username}/status/${tweet.id}` : undefined;
+    return formatTweet(tweet, author, canonicalUrl);
+  },
+};
+
+// ── searchX ───────────────────────────────────────────────────────────────────
+
+export const searchX = {
+  definition: {
+    name: "searchX",
+    description: "Search recent X (Twitter) posts by keyword or query. Returns up to max_results posts (default 10, max 100).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "X search query. Supports operators like from:user, #hashtag, -excludeword.",
+        },
+        max_results: {
+          type: "number",
+          description: "Number of results to return (10–100). Defaults to 10.",
+        },
+        sort_order: {
+          type: "string",
+          enum: ["recency", "relevancy"],
+          description: "'recency' = latest tweets first (default). 'relevancy' = most relevant (Top) first.",
+        },
+      },
+      required: ["query"],
+    },
+  },
+
+  requiredEnv: ["X_BEARER_TOKEN"],
+
+  prompt: "Use the searchX tool to find recent posts on X by keyword or topic.",
+
+  async handler(args: Record<string, unknown>): Promise<string> {
+    const query = String(args.query ?? "").trim();
+    if (!query) return "A search query is required.";
+
+    const maxResults = Math.min(100, Math.max(10, Number(args.max_results ?? 10)));
+
+    let data: XApiResponse;
+    try {
+      const sortOrder = args.sort_order === "relevancy" ? "relevancy" : "recency";
+      const params = new URLSearchParams({
+        query,
+        max_results: String(maxResults),
+        sort_order: sortOrder,
+      });
+      params.append("tweet.fields", "created_at,author_id,public_metrics");
+      params.append("expansions", "author_id");
+      params.append("user.fields", "name,username");
+      data = await fetchX(`/tweets/search/recent?${params.toString()}`);
+    } catch (err) {
+      return errorMessage(err);
+    }
+
+    if (data.errors?.length) return `X API error: ${data.errors.map((e) => e.detail).join("; ")}`;
+
+    const tweets = Array.isArray(data.data) ? data.data : [];
+    if (tweets.length === 0) return `No recent posts found for: "${query}"`;
+
+    const users = data.includes?.users ?? [];
+    const userMap = new Map(users.map((u) => [u.id, u]));
+
+    const lines: string[] = [`Search: "${query}" — ${tweets.length} result${tweets.length !== 1 ? "s" : ""}`, ""];
+    tweets.forEach((tweet, i) => {
+      const author = tweet.author_id ? userMap.get(tweet.author_id) : undefined;
+      lines.push(`${i + 1}. ${formatTweet(tweet, author)}`);
+      lines.push("");
+    });
+
+    return lines.join("\n").trimEnd();
+  },
+};