Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

feat(mcp): add an Orca board bridge over MCP stdio

Abdurrahman Fakhrula939dc16ae91
diff --git a/bin/orca-mcp-tools.mjs b/bin/orca-mcp-tools.mjs
new file mode 100644
index 00000000..8cee8a3f
--- /dev/null
+++ b/bin/orca-mcp-tools.mjs
@@ -0,0 +1,206 @@
+// Tool table for the Orca MCP bridge. Declarative: each entry names the orca
+// subcommand and how arguments map onto flags, so there is one generic argv
+// builder instead of a dozen hand-written ones.
+
+const WORKTREE = { type: "string", description: "Worktree selector: active, current, name:<n>, branch:<b>, path:<p>, id:<repo>::<path>, issue:<n>" };
+const TERMINAL = { type: "string", description: "Runtime terminal handle from orca_terminal_list (e.g. term_123). Omit to target the current terminal." };
+const LIMIT = { type: "number", description: "Max rows to return" };
+// Which Orca host to act on. Omitted = this laptop. "antinrml" is the VPS runtime.
+// Worktrees/terminals belong to the runtime that owns them: a handle from the VPS
+// is invalid locally, so every call must carry the same host as its target.
+const HOST = { type: "string", description: "Orca host selector. Omit for this laptop. Use \"antinrml\" (VPS runtime) or --host ssh:... for remote. Required when acting on a handle issued by another host." };
+const obj = (properties, required) => ({ type: "object", properties, ...(required ? { required } : {}) });
+
+// values: string/number flags. switches: present-when-true booleans.
+export const TOOLS = {
+ orca_status: {
+ description: "Check whether the Orca runtime (and its desktop window) is reachable. Run first: every other orca_* tool fails while runtime.state is not_running.",
+ inputSchema: obj({ host: HOST }),
+ argv: ["status"],
+ },
+ orca_host_list: {
+ description: "List every Orca host this laptop can target: local, SSH targets, and paired runtimes (e.g. the \"antinrml\" VPS). Use it to learn the host label before acting on a remote board.",
+ inputSchema: obj({}),
+ argv: ["host", "list"],
+ },
+ orca_worktree_list: {
+ description: "List Orca-managed worktrees — the units on the Orca board. Find a worktree selector here before creating terminals or launching agents. Pass host=\"antinrml\" for the VPS board; omitting host shows only this laptop.",
+ inputSchema: obj({ host: HOST, repo: { type: "string", description: "Repo selector: id:<id>, name:<name>, path:<path>" }, limit: LIMIT }),
+ argv: ["worktree", "list"],
+ values: { repo: "--repo", limit: "--limit" },
+ },
+ orca_worktree_ps: {
+ description: "Compact orchestration summary across worktrees: what each agent/terminal is doing now. Cheapest read of board state. Pass host=\"antinrml\" to read the VPS board.",
+ inputSchema: obj({ host: HOST, limit: LIMIT }),
+ argv: ["worktree", "ps"],
+ values: { limit: "--limit" },
+ },
+ orca_worktree_create: {
+ description: "Create an Orca-managed worktree (new git checkout shown on the board). Optionally launch an agent inside it with a prompt.",
+ inputSchema: obj({
+ host: HOST,
+ name: { type: "string", description: "Required worktree display name" },
+ repo: { type: "string", description: "Repo selector: id:<id>, name:<name>, path:<path>. Required unless run from inside a managed worktree." },
+ agent: { type: "string", description: "Agent id to launch, e.g. codex, claude, opencode. Omit to create the checkout only." },
+ prompt: { type: "string", description: "Initial prompt for the launched agent" },
+ model: { type: "string", description: "Model id for the agent launch" },
+ effort: { type: "string", description: "Reasoning effort level for the agent launch" },
+ base_branch: { type: "string", description: "Base ref for the new branch" },
+ setup: { type: "string", enum: ["run", "skip", "inherit"], description: "Whether to run project setup hooks" },
+ }, ["name"]),
+ argv: ["worktree", "create"],
+ values: { name: "--name", repo: "--repo", agent: "--agent", prompt: "--prompt", model: "--model", effort: "--effort", base_branch: "--base-branch", setup: "--setup" },
+ switches: { activate: "--activate" },
+ },
+ orca_worktree_set: {
+ description: "Update board metadata for one worktree: comment, workspace status column, display name. Keeps the board honest about what an agent is doing.",
+ inputSchema: obj({
+ host: HOST,
+ worktree: WORKTREE,
+ comment: { type: "string", description: "Free-text note shown on the board" },
+ workspace_status: { type: "string", description: "Board status/column id" },
+ display_name: { type: "string", description: "New display name" },
+ }, ["worktree"]),
+ argv: ["worktree", "set"],
+ values: { worktree: "--worktree", comment: "--comment", workspace_status: "--workspace-status", display_name: "--display-name" },
+ },
+ orca_terminal_list: {
+ description: "List live Orca-managed terminals with runtime handles. Handles are required by orca_terminal_send/read/wait/close.",
+ inputSchema: obj({ host: HOST, worktree: WORKTREE, limit: LIMIT, include_visual_layouts: { type: "boolean", description: "Include tab and pane topology" } }),
+ argv: ["terminal", "list"],
+ values: { worktree: "--worktree", limit: "--limit" },
+ switches: { include_visual_layouts: "--include-visual-layouts" },
+ },
+ orca_terminal_create: {
+ description: "Spawn a terminal session in a worktree. How you start a long-running interactive process (agent CLI, dev server) that appears on the Orca board.",
+ inputSchema: obj({
+ host: HOST,
+ worktree: WORKTREE,
+ title: { type: "string", description: "Terminal tab title" },
+ command: { type: "string", description: "Command to run, e.g. \"codex\" or \"bun run dev\"" },
+ shell: { type: "string", description: "Shell to use" },
+ focus: { type: "boolean", description: "Bring the terminal to the foreground" },
+ }),
+ argv: ["terminal", "create"],
+ values: { worktree: "--worktree", title: "--title", command: "--command", shell: "--shell" },
+ switches: { focus: "--focus" },
+ },
+ orca_terminal_send: {
+ description: "Send text to a live terminal; enter=true submits it. Interactive agent TUI input, not a shell one-shot.",
+ inputSchema: obj({
+ host: HOST,
+ terminal: TERMINAL,
+ text: { type: "string", description: "Text to send" },
+ enter: { type: "boolean", description: "Append Enter to submit" },
+ interrupt: { type: "boolean", description: "Send as interrupt-style input" },
+ wait_submit: { type: "number", description: "Seconds to observe the accepted prompt without resending" },
+ }, ["text"]),
+ argv: ["terminal", "send"],
+ values: { terminal: "--terminal", text: "--text", wait_submit: "--wait-submit" },
+ switches: { enter: "--enter", interrupt: "--interrupt" },
+ },
+ orca_terminal_read: {
+ description: "Read bounded terminal output. Pass cursor from a previous read to continue incrementally.",
+ inputSchema: obj({ host: HOST, terminal: TERMINAL, cursor: { type: "number", description: "Resume cursor from a previous read" }, limit: LIMIT }),
+ argv: ["terminal", "read"],
+ values: { terminal: "--terminal", cursor: "--cursor", limit: "--limit" },
+ },
+ orca_terminal_wait: {
+ description: "Block until a terminal exits or its TUI goes idle. Use after sending a prompt instead of polling.",
+ inputSchema: obj({
+ host: HOST,
+ terminal: TERMINAL,
+ for: { type: "string", enum: ["exit", "tui-idle"], description: "Condition to wait for" },
+ timeout_ms: { type: "number", description: "Max wait in milliseconds" },
+ }, ["for"]),
+ argv: ["terminal", "wait"],
+ values: { terminal: "--terminal", for: "--for", timeout_ms: "--timeout-ms" },
+ },
+ orca_terminal_close: {
+ description: "Close one terminal, its whole tab (tab=true), or every terminal in a worktree (all=true with worktree).",
+ inputSchema: obj({
+ host: HOST,
+ terminal: TERMINAL,
+ tab: { type: "boolean", description: "Close the whole tab containing the terminal" },
+ worktree: WORKTREE,
+ all: { type: "boolean", description: "Close every terminal in the worktree" },
+ }),
+ argv: ["terminal", "close"],
+ values: { terminal: "--terminal", worktree: "--worktree" },
+ switches: { tab: "--tab", all: "--all" },
+ requireOneOf: [["terminal", "all"]],
+ },
+ orca_agent_launch: {
+ description: "Launch a coding agent (chat or terminal, per Orca settings) in an existing worktree. Prefer over orca_terminal_create when you want a tracked agent rather than a raw shell.",
+ inputSchema: obj({
+ host: HOST,
+ agent: { type: "string", description: "Agent id, e.g. codex, claude, opencode" },
+ worktree: WORKTREE,
+ prompt: { type: "string", description: "Initial prompt" },
+ model: { type: "string", description: "Model id" },
+ effort: { type: "string", description: "Reasoning effort level" },
+ focus: { type: "boolean", description: "Bring the agent to the foreground" },
+ }, ["agent"]),
+ argv: ["agent", "launch"],
+ values: { agent: "--agent", worktree: "--worktree", prompt: "--prompt", model: "--model", effort: "--effort" },
+ switches: { focus: "--focus" },
+ },
+};
+
+const READ_ONLY = new Set(["orca_status", "orca_host_list", "orca_worktree_list", "orca_worktree_ps", "orca_terminal_list", "orca_terminal_read"]);
+
+// `orca` spells remote targeting two ways: --environment <name|id> for every
+// routed command, and --host runtime:<env-id> for worktree create only. Normalise
+// one `host` argument onto whichever the subcommand accepts.
+function hostFlags(name, args) {
+ const host = typeof args.host === "string" ? args.host.trim() : "";
+ if (!host || host === "local") return [];
+ if (name === "orca_host_list") return []; // rejects --environment by design
+ if (name === "orca_worktree_create" && (host.startsWith("runtime:") || host.startsWith("ssh:"))) return ["--host", host];
+ // A bare name is a paired-runtime name; --environment takes a name or an id.
+ return ["--environment", host.replace(/^runtime:/, "")];
+}
+
+/** True when a bare paired-runtime name must be resolved to its id before `--host runtime:<id>` works. */
+export function needsEnvironmentId(name, args) {
+ const host = typeof args.host === "string" ? args.host.trim() : "";
+ return name === "orca_worktree_create" && host !== "" && host !== "local" && !host.includes(":");
+}
+
+export function toolDescriptors() {
+ return Object.entries(TOOLS).map(([name, tool]) => ({
+ name,
+ description: tool.description,
+ inputSchema: tool.inputSchema,
+ annotations: {
+ readOnlyHint: READ_ONLY.has(name),
+ destructiveHint: name === "orca_terminal_close",
+ openWorldHint: false,
+ },
+ }));
+}
+
+/** Map snake_case args onto orca flags. Returns argv, or null when a required arg is missing. */
+export function buildArgv(name, args) {
+ const tool = TOOLS[name];
+ if (!tool) return null;
+ const argv = [...tool.argv, ...hostFlags(name, args)];
+ for (const [arg, flag] of Object.entries(tool.values ?? {})) {
+ const value = args[arg];
+ if (value === undefined || value === null || value === "") continue;
+ argv.push(flag, String(value));
+ }
+ for (const [arg, flag] of Object.entries(tool.switches ?? {})) {
+ if (args[arg] === true) argv.push(flag);
+ }
+ for (const group of tool.requireOneOf ?? []) {
+ const present = (arg) => args[arg] !== undefined && args[arg] !== null && args[arg] !== "" && args[arg] !== false;
+ // Each entry is an alternative: at least one argument must be supplied.
+ if (!group.some(present)) return null;
+ }
+ const required = tool.inputSchema.required ?? [];
+ if (required.some((arg) => args[arg] === undefined || args[arg] === null || args[arg] === "")) return null;
+ // --all needs a worktree scope; default to the active one.
+ if (name === "orca_terminal_close" && args.all === true && !args.worktree) argv.push("--worktree", "active");
+ return argv;
+}
diff --git a/bin/orca-mcp.mjs b/bin/orca-mcp.mjs
new file mode 100644
index 00000000..7b78f841
--- /dev/null
+++ b/bin/orca-mcp.mjs
@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// MSO <-> Orca bridge over MCP stdio.
+//
+// WHY stdio and not an MSO HTTP tool: the MSO MCP server runs on the VPS, the
+// Orca runtime is a Windows desktop app on the laptop. A VPS-side tool cannot
+// reach it. This server is spawned locally by the MCP client (OpenCode/Hermes),
+// so it inherits the laptop's WSL interop and the `orca` CLI shim.
+//
+// Every tool is a thin argv mapping onto `orca <cmd> --json`. No shell is
+// involved (spawn with an argv array), so no quoting/injection surface.
+//
+// Override the CLI with ORCA_BIN. Default: `orca` on PATH, then the WSL launcher.
+
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { buildArgv, needsEnvironmentId, TOOLS, toolDescriptors } from "./orca-mcp-tools.mjs";
+
+const CANDIDATES = [process.env.ORCA_BIN, join(homedir(), ".local/bin/orca-ide"), "/opt/Orca/resources/bin/orca-ide"].filter(Boolean);
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+const str = (a, k) => (typeof a?.[k] === "string" && a[k].trim() ? a[k] : undefined);
+const num = (a, k) => (Number.isFinite(a?.[k]) ? Number(a[k]) : undefined);
+
+/** Run the Orca CLI and return parsed JSON (or raw text when it is not JSON). */
+export function orca(bin, argv, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+ return new Promise((resolve) => {
+ let child;
+ try {
+ child = spawn(bin, [...argv, "--json"], { stdio: ["ignore", "pipe", "pipe"] });
+ } catch (error) {
+ resolve({ ok: false, error: `cannot spawn ${bin}: ${error.message}` });
+ return;
+ }
+ let out = "", err = "", done = false;
+ const finish = (result) => { if (!done) { done = true; clearTimeout(timer); resolve(result); } };
+ const timer = setTimeout(() => {
+ child.kill("SIGKILL");
+ finish({ ok: false, error: `orca ${argv.join(" ")} timed out after ${timeoutMs}ms` });
+ }, timeoutMs);
+ child.stdout.setEncoding("utf8").on("data", (c) => { out += c; });
+ child.stderr.setEncoding("utf8").on("data", (c) => { err += c; });
+ child.on("error", (error) => finish({ ok: false, error: `orca failed to start: ${error.message}` }));
+ child.on("close", (code) => {
+ const text = out.trim();
+ if (code !== 0) {
+ finish({ ok: false, error: (err || text || `orca exited with code ${code}`).trim().slice(0, 4000) });
+ return;
+ }
+ if (!text) { finish({ ok: true, value: null }); return; }
+ try { finish({ ok: true, value: JSON.parse(text) }); }
+ catch { finish({ ok: true, value: text.slice(0, 20_000) }); }
+ });
+ });
+}
+export { toolDescriptors, TOOLS };
+
+function text(value) { return [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }]; }
+
+async function callTool(bin, name, args) {
+ if (!TOOLS[name]) return { content: text(`unknown tool: ${name}`), isError: true };
+ const argv = buildArgv(name, args ?? {});
+ if (!argv) return { content: text(`${name}: missing required argument`), isError: true };
+ // worktree create only targets a remote board via --host runtime:<environment-id>,
+ // so a friendly environment name has to be resolved to its id first.
+ if (needsEnvironmentId(name, args ?? {})) {
+ const listed = await orca(bin, ["environment", "list"]);
+ const envs = listed.ok ? (listed.value?.result?.environments ?? []) : [];
+ const wanted = String(args.host).trim();
+ const match = envs.find((e) => e.name === wanted) ?? envs.find((e) => e.id === wanted);
+ if (!match) return { content: text(`unknown Orca environment: ${wanted}. Run orca_host_list to see paired runtimes.`), isError: true };
+ const index = argv.findIndex((v) => v === "--environment");
+ if (index >= 0) argv.splice(index, 2);
+ argv.push("--host", `runtime:${match.id}`);
+ }
+ const result = await orca(bin, argv, { timeoutMs: num(args, "timeout_ms") ?? DEFAULT_TIMEOUT_MS });
+ if (!result.ok) return { content: text(`orca ${argv.join(" ")}\n${result.error}`), isError: true };
+ return { content: text(labelHost(result.value ?? { ok: true }, args)) };
+}
+
+// Every board row must say which machine it lives on. Orca's own rows carry
+// hostId only for git worktrees and omit it for folder workspaces, so stamp the
+// host this call was routed to. Handles from another host are unusable here.
+function labelHost(value, args) {
+ const host = typeof args?.host === "string" && args.host.trim() ? args.host.trim() : "local";
+ const worktrees = value?.result?.worktrees;
+ if (!Array.isArray(worktrees)) return value;
+ return { ...value, result: { ...value.result, worktrees: worktrees.map((row) => ({ host, ...row })) } };
+}
+
+export function createServer(bin) {
+ /** @param {any} msg @returns {Promise<any>} */
+ const handle = async (msg) => {
+ const id = msg.id;
+ const reply = (result) => ({ jsonrpc: "2.0", id, result });
+ const fail = (code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
+ switch (msg.method) {
+ case "initialize":
+ return reply({
+ protocolVersion: msg.params?.protocolVersion ?? "2025-06-18",
+ capabilities: { tools: { listChanged: false } },
+ serverInfo: { name: "mso-orca", version: "0.1.0" },
+ });
+ case "tools/list":
+ return reply({ tools: toolDescriptors() });
+ case "tools/call":
+ try {
+ return reply(await callTool(bin, msg.params?.name, msg.params?.arguments));
+ } catch (error) {
+ return reply({ content: text(String(error?.message ?? error)), isError: true });
+ }
+ case "ping":
+ return reply({});
+ default:
+ if (msg.id === undefined) return null; // notification (initialized, cancelled)
+ return fail(-32601, `method not found: ${msg.method}`);
+ }
+ };
+ return { handle };
+}
+
+function main() {
+ const bin = CANDIDATES.find((candidate) => existsSync(candidate)) ?? CANDIDATES[0];
+ const { handle } = createServer(bin);
+ const write = (msg) => { if (msg) process.stdout.write(`${JSON.stringify(msg)}\n`); };
+ const rl = createInterface({ input: process.stdin, terminal: false });
+ let queue = Promise.resolve();
+ rl.on("line", (line) => {
+ const trimmed = line.trim();
+ if (!trimmed) return;
+ let msg;
+ try { msg = JSON.parse(trimmed); } catch { write({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } }); return; }
+ // Serialize tool calls: Orca CLI invocations are cheap but not concurrent-safe on one worktree.
+ queue = queue.then(() => handle(msg)).then(write, (error) => write({ jsonrpc: "2.0", id: msg?.id ?? null, error: { code: -32603, message: String(error?.message ?? error) } }));
+ });
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();
diff --git a/bin/orca-mcp.test.ts b/bin/orca-mcp.test.ts
new file mode 100644
index 00000000..20c4874f
--- /dev/null
+++ b/bin/orca-mcp.test.ts
@@ -0,0 +1,134 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { createServer, orca, toolDescriptors, TOOLS } from "./orca-mcp.mjs";
+import { buildArgv, needsEnvironmentId } from "./orca-mcp-tools.mjs";
+
+// Fake orca CLI: echoes its argv as JSON.
+function fakeBin(body = `process.stdout.write(JSON.stringify({ argv: process.argv.slice(2) }));`): string {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "orca-mcp-"));
+ const file = path.join(dir, "orca");
+ fs.writeFileSync(file, `#!/usr/bin/env node\n${body}\n`, { mode: 0o755 });
+ return file;
+}
+
+const call = (bin: string, name: string, args: unknown) =>
+ createServer(bin).handle({ id: 1, method: "tools/call", params: { name, arguments: args } });
+
+describe("orca-mcp tool table", () => {
+ it("describes every tool with an object schema and annotations", () => {
+ const tools = toolDescriptors();
+ expect(tools.length).toBe(Object.keys(TOOLS).length);
+ for (const tool of tools) {
+ expect(tool.inputSchema.type).toBe("object");
+ expect(tool.description.length).toBeGreaterThan(20);
+ }
+ expect(tools.find((t) => t.name === "orca_terminal_close")?.annotations.destructiveHint).toBe(true);
+ expect(tools.find((t) => t.name === "orca_status")?.annotations.readOnlyHint).toBe(true);
+ expect(tools.find((t) => t.name === "orca_terminal_read")?.annotations.readOnlyHint).toBe(true);
+ });
+
+ it("maps snake_case args onto orca flags in declaration order", () => {
+ expect(buildArgv("orca_terminal_create", { worktree: "active", title: "agent", command: "codex", focus: true }))
+ .toEqual(["terminal", "create", "--worktree", "active", "--title", "agent", "--command", "codex", "--focus"]);
+ });
+
+ it("omits absent optional args and false switches", () => {
+ expect(buildArgv("orca_terminal_read", { terminal: "term_1" })).toEqual(["terminal", "read", "--terminal", "term_1"]);
+ expect(buildArgv("orca_terminal_list", { focus: false, limit: 3 })).toEqual(["terminal", "list", "--limit", "3"]);
+ });
+
+ it("converts numbers to strings for flag values", () => {
+ expect(buildArgv("orca_terminal_wait", { terminal: "t", for: "exit", timeout_ms: 5000 }))
+ .toEqual(["terminal", "wait", "--terminal", "t", "--for", "exit", "--timeout-ms", "5000"]);
+ });
+
+ it("returns null for a missing required arg or an unknown tool", () => {
+ expect(buildArgv("orca_worktree_create", {})).toBeNull();
+ expect(buildArgv("orca_terminal_send", { terminal: "t" })).toBeNull();
+ expect(buildArgv("orca_nope", {})).toBeNull();
+ });
+
+ it("requires a close target and defaults --all to the active worktree", () => {
+ expect(buildArgv("orca_terminal_close", {})).toBeNull();
+ expect(buildArgv("orca_terminal_close", { all: true })).toEqual(["terminal", "close", "--all", "--worktree", "active"]);
+ expect(buildArgv("orca_terminal_close", { terminal: "t", tab: true })).toEqual(["terminal", "close", "--terminal", "t", "--tab"]);
+ });
+});
+
+describe("orca-mcp host routing", () => {
+ it("adds --environment for a paired runtime on every routed command", () => {
+ expect(buildArgv("orca_worktree_ps", { host: "antinrml", limit: 3 }))
+ .toEqual(["worktree", "ps", "--environment", "antinrml", "--limit", "3"]);
+ expect(buildArgv("orca_terminal_list", { host: "antinrml" }))
+ .toEqual(["terminal", "list", "--environment", "antinrml"]);
+ });
+
+ it("omits routing flags for the local host", () => {
+ expect(buildArgv("orca_worktree_ps", { limit: 3 })).toEqual(["worktree", "ps", "--limit", "3"]);
+ expect(buildArgv("orca_worktree_ps", { host: "local" })).toEqual(["worktree", "ps"]);
+ });
+
+ it("passes an explicit runtime:/ssh: id straight through as --host", () => {
+ expect(buildArgv("orca_worktree_create", { host: "runtime:46174843-7c8e-4023-adc6-3488a102ae64", name: "x", repo: "name:mso" }))
+ .toEqual(["worktree", "create", "--host", "runtime:46174843-7c8e-4023-adc6-3488a102ae64", "--name", "x", "--repo", "name:mso"]);
+ });
+
+ it("flags a bare environment name that must be resolved to an id", () => {
+ expect(needsEnvironmentId("orca_worktree_create", { host: "antinrml" })).toBe(true);
+ expect(needsEnvironmentId("orca_worktree_create", { host: "runtime:abc" })).toBe(false);
+ expect(needsEnvironmentId("orca_worktree_create", {})).toBe(false);
+ expect(needsEnvironmentId("orca_worktree_ps", { host: "antinrml" })).toBe(false);
+ });
+
+ it("never routes orca_host_list, which rejects --environment", () => {
+ expect(buildArgv("orca_host_list", { host: "antinrml" })).toEqual(["host", "list"]);
+ });
+});
+
+describe("orca-mcp stdio server", () => {
+ it("appends --json and returns the CLI payload as text content", async () => {
+ const reply = await call(fakeBin(), "orca_worktree_ps", { limit: 2 });
+ expect(JSON.parse(reply.result.content[0].text)).toEqual({ argv: ["worktree", "ps", "--limit", "2", "--json"] });
+ expect(reply.result.isError).toBeUndefined();
+ });
+
+ it("surfaces a CLI failure as an MCP error result", async () => {
+ const bin = fakeBin(`process.stderr.write("Orca is not running. Run 'orca open' first."); process.exit(1);`);
+ const reply = await call(bin, "orca_status", {});
+ expect(reply.result.isError).toBe(true);
+ expect(reply.result.content[0].text).toContain("orca open");
+ });
+
+ it("rejects an unknown tool and a missing required argument", async () => {
+ expect((await call(fakeBin(), "orca_nope", {})).result.isError).toBe(true);
+ expect((await call(fakeBin(), "orca_worktree_create", {})).result.isError).toBe(true);
+ });
+
+ it("answers initialize/ping and ignores notifications", async () => {
+ const { handle } = createServer(fakeBin());
+ const init = await handle({ id: 7, method: "initialize", params: { protocolVersion: "2025-06-18" } });
+ expect(init.result.capabilities.tools).toBeDefined();
+ expect(init.result.serverInfo.name).toBe("mso-orca");
+ expect((await handle({ id: 8, method: "ping" })).result).toEqual({});
+ expect(await handle({ method: "notifications/initialized" })).toBeNull();
+ expect((await handle({ id: 9, method: "bogus" })).error.code).toBe(-32601);
+ });
+
+ it("stamps each board row with the host it was routed to", async () => {
+ const bin = fakeBin(`process.stdout.write(JSON.stringify({ result: { worktrees: [{ displayName: "a" }, { displayName: "b" }] } }));`);
+ const local = await call(bin, "orca_worktree_ps", { limit: 2 });
+ const remote = await call(bin, "orca_worktree_ps", { host: "antinrml", limit: 2 });
+ const rows = (reply: { result: { content: { text: string }[] } }) => JSON.parse(reply.result.content[0].text).result.worktrees.map((r: { host: string }) => r.host);
+ expect(rows(local as never)).toEqual(["local", "local"]);
+ expect(rows(remote as never)).toEqual(["antinrml", "antinrml"]);
+ });
+
+ it("times out instead of hanging on a wedged CLI", async () => {
+ const bin = fakeBin("setTimeout(() => {}, 60000);");
+ const result = await orca(bin, ["status"], { timeoutMs: 300 });
+ expect(result.ok).toBe(false);
+ expect(result.error).toContain("timed out");
+ });
+});
diff --git a/package.json b/package.json
index 6db79e34..20320f6e 100644
--- a/package.json
+++ b/package.json
@@ -60,7 +60,8 @@
"test:ci": "node --test scripts/ci/contract.node.mjs",
"parity:nakama": "node scripts/check-nakama-parity.mjs && node scripts/gen-nakama-parity.mjs --check",
"parity:nakama:release": "node scripts/check-nakama-parity.mjs --release",
- "test:parity": "node --test scripts/parity/inventory.node.mjs"
+ "test:parity": "node --test scripts/parity/inventory.node.mjs",
+ "mcp:orca": "node bin/orca-mcp.mjs"
},
"dependencies": {
"@anthropic-ai/sdk": "^0.133.0",