mergestorm-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Margin Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# mergestorm-mcp
+
+Stdio MCP server for Mergestorm. Tools: `whoami`, `credits`, `review_list`, `review_get`, `review_submit`, `review_wait`.
+
+Auth is `MERGESTORM_API_KEY`, then `~/.mergestorm/config.json` (same as `mg`).
+
+`context_files` passed to `review_submit` may only read files under the host-configured sandbox root (`MERGESTORM_SANDBOX_ROOT`, default: the MCP server's working directory), so a prompt-injected agent cannot use them to exfiltrate files outside it.
+
+```bash
+claude mcp add mergestorm -- npx -y mergestorm-mcp
+```
+
+Then call `whoami`. It should return the key prefix.
+
+Requires Node.js 22+ and a Mergestorm API key (`mg login` or `MERGESTORM_API_KEY`).

package/dist/index.js

@@ -0,0 +1,474 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CommandError as CommandError6 } from "mergestorm/client";
+
+// src/tools/credits.ts
+import { CommandError, getMe, loadConfig } from "mergestorm/client";
+async function credits(cfg) {
+  const resolved = cfg ?? await loadConfig();
+  const me = await getMe(resolved);
+  if (!me) {
+    throw new CommandError(
+      "Credits are not available right now (Mergestorm API is offline, unreachable, or too old)."
+    );
+  }
+  if (!me.usage) {
+    throw new CommandError(
+      "Credits are not available on this server yet. Update the API or use the dashboard."
+    );
+  }
+  const standard = me.usage.standard;
+  const remaining = standard.remaining ?? (standard.limit != null ? Math.max(0, standard.limit - standard.used) : null);
+  return {
+    summary: remaining == null ? `${standard.used} used \xB7 unlimited` : `${standard.used} used \xB7 ${remaining} remaining`,
+    data: {
+      usage: me.usage,
+      resets_at: me.resets_at ?? null
+    }
+  };
+}
+
+// src/tools/review-get.ts
+import {
+  CommandError as CommandError2,
+  getReview,
+  toReviewJobEnvelope as toReviewJobEnvelope2
+} from "mergestorm/client";
+
+// src/tools/envelope.ts
+import {
+  isCommandErrorCode,
+  toReviewJobEnvelope
+} from "mergestorm/client";
+function payloadFromRow(row, fallback = {}) {
+  const envelope = toReviewJobEnvelope(row, fallback);
+  const bits = [envelope.status];
+  if (envelope.verdict) bits.push(envelope.verdict);
+  return {
+    summary: `${envelope.job_id ?? fallback.jobId ?? "review"} \xB7 ${bits.join(" \xB7 ")}`,
+    data: envelope
+  };
+}
+function payloadFromRateLimit(err, jobId) {
+  if (!isCommandErrorCode(err, "rate_limited")) return null;
+  return payloadFromRow(null, {
+    jobId,
+    status: "rate_limited",
+    error: err.message,
+    retryAfterSeconds: err.retryAfterSeconds
+  });
+}
+
+// src/tools/review-get.ts
+async function reviewGet(jobId, cfg) {
+  let row;
+  try {
+    row = await getReview(jobId, cfg);
+  } catch (err) {
+    const rateLimited = payloadFromRateLimit(err, jobId);
+    if (rateLimited) return rateLimited;
+    throw err;
+  }
+  if (!row || typeof row !== "object" || typeof row.status !== "string") {
+    throw new CommandError2(`Unexpected response for review ${jobId}.`);
+  }
+  const envelope = toReviewJobEnvelope2(row, { jobId });
+  const bits = [envelope.status];
+  if (envelope.verdict) bits.push(envelope.verdict);
+  return {
+    summary: `${envelope.job_id ?? jobId} \xB7 ${bits.join(" \xB7 ")}`,
+    data: envelope
+  };
+}
+
+// src/tools/review-list.ts
+import { listJobs, toReviewJobEnvelope as toReviewJobEnvelope3 } from "mergestorm/client";
+async function reviewList(limit = 10, cfg) {
+  const items = await listJobs(limit, cfg);
+  const envelopes = items.map((row) => toReviewJobEnvelope3(row));
+  const n = envelopes.length;
+  return {
+    summary: n === 0 ? "No review jobs" : `${n} review job${n === 1 ? "" : "s"}`,
+    data: { items: envelopes }
+  };
+}
+
+// src/tools/review-submit.ts
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { relative, resolve, sep } from "node:path";
+import {
+  CommandError as CommandError3,
+  REVIEW_THREAD_SLUG_RE,
+  ReviewPollTimeoutError,
+  collectReviewInput,
+  loadConfig as loadConfig2,
+  loadReviewContext,
+  pollReview,
+  rateLimitedMessage,
+  submitReview
+} from "mergestorm/client";
+var MCP_WAIT_CEILING_S = 300;
+function mcpSandboxRoot() {
+  return process.env.MERGESTORM_SANDBOX_ROOT?.trim() || process.cwd();
+}
+function waitTimeoutMs(timeout_s) {
+  const seconds = timeout_s ?? MCP_WAIT_CEILING_S;
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    throw new CommandError3("timeout_s must be a positive number of seconds", 2, "usage");
+  }
+  return Math.max(1, Math.round(Math.min(seconds, MCP_WAIT_CEILING_S) * 1e3));
+}
+async function resolveInput(input) {
+  const cwd = input.cwd ?? process.cwd();
+  const head = input.head?.trim() || "HEAD";
+  if (input.diff?.trim()) {
+    const branch = "local";
+    const thread = input.thread?.trim() || `local/diff-${createHash("sha256").update(input.diff).digest("hex").slice(0, 12)}`;
+    return {
+      thread,
+      branch,
+      baseLabel: input.base?.trim() || "main",
+      headLabel: head,
+      diff: input.diff,
+      files: []
+    };
+  }
+  const bases = input.base?.trim() ? [input.base.trim()] : ["main", "master"];
+  const sandboxRoot = mcpSandboxRoot();
+  try {
+    const [sandboxReal, cwdReal] = await Promise.all([
+      realpath(resolve(sandboxRoot)),
+      realpath(resolve(cwd))
+    ]);
+    const relToSandbox = relative(sandboxReal, cwdReal);
+    if (relToSandbox === ".." || relToSandbox.startsWith(`..${sep}`)) {
+      throw new CommandError3("cwd must be inside the configured sandbox root", 2, "usage");
+    }
+  } catch (err) {
+    if (err instanceof CommandError3) throw err;
+    throw new CommandError3("cwd must be inside the configured sandbox root", 2, "usage");
+  }
+  let lastErr;
+  let collected = null;
+  let yielded = false;
+  for (const base of bases) {
+    try {
+      const candidate = await collectReviewInput(base, head, cwd, sandboxRoot);
+      yielded = true;
+      if (!collected) collected = candidate;
+    } catch (err) {
+      if (yielded) continue;
+      lastErr = err;
+      if (input.base?.trim()) throw err;
+    }
+  }
+  if (yielded) return collected;
+  if (lastErr) throw lastErr;
+  return null;
+}
+async function reviewSubmit(input, cfg, opts = {}) {
+  const resolved = cfg ?? await loadConfig2();
+  const wait = input.wait !== false;
+  const timeoutMs = waitTimeoutMs(input.timeout_s);
+  if (input.thread && !REVIEW_THREAD_SLUG_RE.test(input.thread)) {
+    throw new CommandError3("thread must be 1\u2013120 chars [A-Za-z0-9._/-]", 2, "usage");
+  }
+  if (input.context === "-") {
+    throw new CommandError3(
+      'context "-" (stdin) is not available over MCP; pass the text directly',
+      2,
+      "usage"
+    );
+  }
+  const collected = await resolveInput(input);
+  if (!collected) {
+    return payloadFromRow(null, { status: "no_changes" });
+  }
+  if (input.thread) collected.thread = input.thread;
+  const extras = await loadReviewContext({
+    context: input.context,
+    contextFiles: input.context_files ?? [],
+    cwd: input.cwd ?? process.cwd(),
+    sandboxCwd: mcpSandboxRoot()
+  });
+  const submitted = await submitReview(resolved, collected, {
+    routerMode: input.router,
+    specialists: input.specialists,
+    context: extras.context,
+    contextFiles: extras.contextFiles,
+    idempotencyKey: input.idempotency_key
+  });
+  const jobId = submitted.row.job_id ?? submitted.row.id ?? null;
+  if (submitted.status === 402) {
+    return payloadFromRow(submitted.row, {
+      jobId,
+      status: "quota_exceeded",
+      error: "Review limit reached for this period."
+    });
+  }
+  if (submitted.status === 429) {
+    return payloadFromRow(submitted.row, {
+      jobId,
+      status: "rate_limited",
+      error: rateLimitedMessage(submitted.retryAfterSeconds),
+      retryAfterSeconds: submitted.retryAfterSeconds
+    });
+  }
+  if (submitted.status !== 202 && submitted.status !== 200) {
+    throw new CommandError3(JSON.stringify(submitted.row));
+  }
+  if (!jobId) {
+    throw new CommandError3("Review API returned no job_id");
+  }
+  if (!wait) {
+    return payloadFromRow(submitted.row, { jobId, status: submitted.row.status ?? "queued" });
+  }
+  let row;
+  try {
+    row = await pollReview(resolved, jobId, {
+      timeoutMs,
+      intervalMs: opts.pollIntervalMs
+    });
+  } catch (err) {
+    if (err instanceof ReviewPollTimeoutError) {
+      return payloadFromRow(err.lastRow, {
+        jobId,
+        status: err.lastRow.status ?? "in_progress",
+        error: "Timed out waiting for review."
+      });
+    }
+    const rateLimited = payloadFromRateLimit(err, jobId);
+    if (rateLimited) return rateLimited;
+    throw err;
+  }
+  return payloadFromRow(row, { jobId });
+}
+
+// src/tools/review-wait.ts
+import {
+  CommandError as CommandError4,
+  ReviewPollTimeoutError as ReviewPollTimeoutError2,
+  loadConfig as loadConfig3,
+  pollReview as pollReview2
+} from "mergestorm/client";
+async function reviewWait(jobId, timeout_s, cfg, opts = {}) {
+  const resolved = cfg ?? await loadConfig3();
+  const id = jobId.trim();
+  if (!id) {
+    throw new CommandError4("job_id is required", 2, "usage");
+  }
+  try {
+    const row = await pollReview2(resolved, id, {
+      timeoutMs: waitTimeoutMs(timeout_s),
+      intervalMs: opts.pollIntervalMs
+    });
+    return payloadFromRow(row, { jobId: id });
+  } catch (err) {
+    if (err instanceof ReviewPollTimeoutError2) {
+      return payloadFromRow(err.lastRow, {
+        jobId: id,
+        status: err.lastRow.status ?? "in_progress",
+        error: "Timed out waiting for review."
+      });
+    }
+    const rateLimited = payloadFromRateLimit(err, id);
+    if (rateLimited) return rateLimited;
+    throw err;
+  }
+}
+
+// src/tools/whoami.ts
+import {
+  CommandError as CommandError5,
+  apiBase,
+  configPath,
+  getMe as getMe2,
+  keyDisplay,
+  loadConfig as loadConfig4,
+  resolveApiKey
+} from "mergestorm/client";
+async function whoami(cfg) {
+  const resolved = cfg ?? await loadConfig4();
+  const key = resolveApiKey(resolved);
+  if (!key) {
+    throw new CommandError5(
+      "No API key. Run `mergestorm login` or set MERGESTORM_API_KEY.",
+      1,
+      "missing_api_key"
+    );
+  }
+  const me = await getMe2(resolved);
+  const data = {
+    key_prefix: me?.key.prefix ?? keyDisplay(key),
+    key_name: me?.key.name ?? null,
+    plan_key: me?.plan_key ?? null,
+    plan_label_key: me?.plan_label_key ?? null,
+    api_base: apiBase(resolved),
+    config_path: configPath(),
+    usage: me?.usage ?? null
+  };
+  const plan = data.plan_label_key ?? data.plan_key ?? "unknown plan";
+  return {
+    summary: `${data.key_prefix} \xB7 ${plan}`,
+    data
+  };
+}
+
+// src/server.ts
+var MCP_SERVER_NAME = "mergestorm";
+var MCP_SERVER_VERSION = "0.1.0";
+function stripNulls(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => stripNulls(item));
+  }
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+      if (val !== null && val !== void 0) out[key] = stripNulls(val);
+    }
+    return out;
+  }
+  return value;
+}
+function ok(payload) {
+  return {
+    content: [{ type: "text", text: payload.summary }],
+    structuredContent: stripNulls(payload.data)
+  };
+}
+function fail(err) {
+  const message = err instanceof CommandError6 ? err.code ? `Mergestorm request failed (${err.code}): ${err.message}.` : err.message : err instanceof Error ? err.message : String(err);
+  return {
+    isError: true,
+    content: [{ type: "text", text: message }]
+  };
+}
+function createMergestormMcpServer() {
+  const server2 = new McpServer({
+    name: MCP_SERVER_NAME,
+    version: MCP_SERVER_VERSION
+  });
+  const addTool = server2.registerTool.bind(server2);
+  addTool(
+    "whoami",
+    {
+      title: "Who am I",
+      description: "Current Mergestorm API key prefix, plan, and API base."
+    },
+    async () => {
+      try {
+        return ok(await whoami());
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
+  addTool(
+    "credits",
+    {
+      title: "Credits",
+      description: "Current standard-credit usage and reset time."
+    },
+    async () => {
+      try {
+        return ok(await credits());
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
+  addTool(
+    "review_list",
+    {
+      title: "List reviews",
+      description: "List recent Mergestorm review jobs as job envelopes.",
+      inputSchema: {
+        limit: z.number().int().min(1).max(50).optional()
+      }
+    },
+    async ({ limit }) => {
+      try {
+        return ok(await reviewList(limit));
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
+  addTool(
+    "review_get",
+    {
+      title: "Get review",
+      description: "Fetch one Mergestorm review job as a job envelope. On rate_limited, wait retry_after_seconds before trying again.",
+      inputSchema: {
+        job_id: z.string().min(1)
+      }
+    },
+    async ({ job_id }) => {
+      try {
+        return ok(await reviewGet(job_id));
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
+  addTool(
+    "review_submit",
+    {
+      title: "Submit review",
+      description: "Submit a local git diff (or an explicit diff) as a Mergestorm review job. Default waits up to 300s. On rate_limited, wait retry_after_seconds and inspect or wait for an in-flight review before resubmitting.",
+      inputSchema: {
+        cwd: z.string().optional(),
+        base: z.string().optional(),
+        head: z.string().optional(),
+        diff: z.string().optional(),
+        router: z.enum(["off", "standard", "max", "manual"]).optional(),
+        specialists: z.array(z.string().min(1)).max(5).optional(),
+        context: z.string().optional(),
+        context_files: z.array(z.string().min(1)).max(10).optional(),
+        thread: z.string().min(1).max(120).optional(),
+        idempotency_key: z.string().min(1).max(128).optional(),
+        wait: z.boolean().optional(),
+        timeout_s: z.number().positive().max(300).optional()
+      }
+    },
+    async (args) => {
+      try {
+        return ok(await reviewSubmit(args));
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
+  addTool(
+    "review_wait",
+    {
+      title: "Wait for review",
+      description: "Poll one Mergestorm review job until it finishes, return in_progress after 300s, or return rate_limited with retry_after_seconds.",
+      inputSchema: {
+        job_id: z.string().min(1),
+        timeout_s: z.number().positive().max(300).optional()
+      }
+    },
+    async ({ job_id, timeout_s }) => {
+      try {
+        return ok(await reviewWait(job_id, timeout_s));
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
+  return server2;
+}
+
+// src/index.ts
+var server = createMergestormMcpServer();
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "mergestorm-mcp",
+  "version": "0.1.0",
+  "description": "Mergestorm MCP server — whoami, credits, and review read tools over stdio",
+  "license": "MIT",
+  "type": "module",
+  "author": "Margin Systems <hello@mergestorm.ai>",
+  "keywords": [
+    "mergestorm",
+    "mcp",
+    "code-review"
+  ],
+  "bin": {
+    "mergestorm-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external --banner:js=\"#!/usr/bin/env node\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test src/*.test.ts src/**/*.test.ts",
+    "start": "node dist/index.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "mergestorm": "^0.3.13",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "esbuild": "^0.25.9",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marginsystems/mergestorm-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/marginsystems/mergestorm-mcp/issues"
+  },
+  "homepage": "https://github.com/marginsystems/mergestorm-mcp"
+}