@hheei/ssh-exec-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hheei
+
+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,162 @@
+# SSH Exec
+
+SSH Exec is an MCP server for non-interactive remote command execution and sshfs mounting over OpenSSH.
+
+It can be used in two ways:
+
+- as a Codex plugin
+- as a standalone stdio MCP server for other clients such as `pi-agent`
+
+It exposes two tools:
+
+- `ssh_exec`
+- `ssh_mount`
+
+The server reuses OpenSSH ControlMaster connections, keeps session state hidden from the agent, and returns bounded command output with structured exit metadata.
+
+## Codex Install
+
+Install the marketplace from GitHub:
+
+```bash
+codex plugin marketplace add hheei/ssh-exec --ref main
+```
+
+Install the plugin:
+
+```bash
+codex plugin add ssh-exec@ssh-exec
+```
+
+Start a new Codex thread after installation so the MCP tool is loaded.
+
+## Standalone MCP
+
+You can also run SSH Exec directly as a stdio MCP server without the Codex plugin harness:
+
+```bash
+bun ./ssh-exec-mcp.ts
+```
+
+This gives other MCP clients a stable repo-root entrypoint instead of making them depend on the internal plugin path under `plugins/ssh-exec/...`.
+
+## bunx / npx
+
+The repo is also packaged as a CLI so other agents can install it more directly:
+
+```bash
+bunx @hheei/ssh-exec-mcp
+```
+
+```bash
+npx @hheei/ssh-exec-mcp
+```
+
+Current package behavior:
+
+- `bunx @hheei/ssh-exec-mcp` works directly
+- `npx @hheei/ssh-exec-mcp` works through a thin Node wrapper that launches `bun`
+- for `npx`, Bun still needs to be installed on the machine
+
+## pi-agent Example
+
+Example config is provided in [examples/pi-agent.mcp.json](./examples/pi-agent.mcp.json).
+
+Typical config:
+
+```json
+{
+  "mcpServers": {
+    "ssh-exec": {
+      "command": "bun",
+      "args": [
+        "/absolute/path/to/ssh-exec-mcp.ts"
+      ]
+    }
+  }
+}
+```
+
+Replace the path with your local checkout path.
+
+If you install from npm instead of a local checkout, a typical config can also look like:
+
+```json
+{
+  "mcpServers": {
+    "ssh-exec": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@hheei/ssh-exec-mcp"
+      ]
+    }
+  }
+}
+```
+
+Or with Bun:
+
+```json
+{
+  "mcpServers": {
+    "ssh-exec": {
+      "command": "bunx",
+      "args": [
+        "@hheei/ssh-exec-mcp"
+      ]
+    }
+  }
+}
+```
+
+## Requirements
+
+- Bun
+- OpenSSH client
+- Existing SSH configuration with destination names resolvable by `ssh`
+- `sshfs` if you want `ssh_mount`
+
+## Tools
+
+### `ssh_exec`
+
+Runs a non-interactive command on a remote OpenSSH destination.
+
+Input:
+
+- `host`: OpenSSH destination, for example `prod` or `user@example.com`
+- `command`: command passed to the remote shell by OpenSSH
+- `timeout`: optional timeout in seconds, default `10`, clamped to `1..3600`
+
+Output:
+
+- text content containing the combined stdout/stderr tail or `(no output)`
+- `structuredContent` with `host`, `exitCode`, `stdout`, `stderr`, `durationMs`, `truncated`, and output size metadata
+
+Non-zero exits, timeouts, and SSH startup failures are returned as MCP tool errors when captured output is available.
+
+### `ssh_mount`
+
+Mounts the remote host locally through `sshfs`.
+
+Input:
+
+- `host`: OpenSSH destination, for example `prod` or `user@example.com`
+
+Output:
+
+- compact success text with local mount path
+- `structuredContent` with `host`, `localPath`, and mount `status`
+
+## Scope
+
+SSH Exec intentionally does not expose interactive shell sessions, file upload/download commands, host discovery, or batch orchestration APIs beyond `ssh_exec` and `ssh_mount`.
+
+## Development
+
+Run tests:
+
+```bash
+bun test plugins/ssh-exec/scripts/*.test.ts
+```

package/bin/ssh-exec-mcp.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const entrypoint = resolve(__dirname, "..", "ssh-exec-mcp.ts");
+const bunBin = process.env.BUN_BIN || "bun";
+
+const child = spawn(bunBin, [entrypoint, ...process.argv.slice(2)], {
+	stdio: "inherit",
+});
+
+child.on("error", (error) => {
+	if (error && "code" in error && error.code === "ENOENT") {
+		process.stderr.write(
+			[
+				"ssh-exec-mcp requires Bun at runtime.",
+				"Install Bun from https://bun.sh/ or set BUN_BIN to the Bun executable path.",
+			].join("\n") + "\n",
+		);
+		process.exit(1);
+		return;
+	}
+
+	process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+	process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+	if (signal) {
+		process.kill(process.pid, signal);
+		return;
+	}
+	process.exit(code ?? 1);
+});

package/examples/pi-agent.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "ssh-exec": {
+      "command": "bun",
+      "args": [
+        "/absolute/path/to/ssh-exec-mcp.ts"
+      ]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@hheei/ssh-exec-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for remote command execution and sshfs mounting over OpenSSH",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/hheei/ssh-exec",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hheei/ssh-exec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hheei/ssh-exec/issues"
+  },
+  "author": "hheei",
+  "bin": {
+    "ssh-exec-mcp": "bin/ssh-exec-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "examples/",
+    "plugins/ssh-exec/",
+    "ssh-exec-mcp.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "ssh",
+    "sshfs",
+    "openssh",
+    "remote",
+    "codex"
+  ]
+}

package/plugins/ssh-exec/.codex-plugin/plugin.json

@@ -0,0 +1,35 @@
+{
+  "name": "ssh-exec",
+  "version": "0.1.0+codex.20260703175642",
+  "description": "Remote command execution and sshfs mounting over OpenSSH",
+  "author": {
+    "name": "hheei",
+    "url": "https://github.com/hheei"
+  },
+  "homepage": "https://github.com/hheei/ssh-exec",
+  "repository": "https://github.com/hheei/ssh-exec",
+  "license": "MIT",
+  "keywords": [
+    "ssh",
+    "mcp",
+    "codex",
+    "openssh",
+    "sshfs"
+  ],
+  "interface": {
+    "displayName": "SSH Exec",
+    "shortDescription": "Run remote commands and mount remote files over OpenSSH.",
+    "longDescription": "SSH Exec provides two tools: ssh_mount for mounting a remote host locally so Codex can use built-in file tools, and ssh_exec for remote commands such as inspection, verification, and service control.",
+    "developerName": "hheei",
+    "category": "Productivity",
+    "capabilities": [
+      "MCP",
+      "SSH"
+    ],
+    "websiteURL": "https://github.com/hheei/ssh-exec",
+    "defaultPrompt": "Use ssh_mount before editing remote files, then use ssh_exec to inspect or verify the remote host.",
+    "brandColor": "#111827",
+    "composerIcon": "./assets/icon.svg"
+  },
+  "mcpServers": "./.mcp.json"
+}

package/plugins/ssh-exec/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "ssh-exec": {
+      "cwd": ".",
+      "command": "bun",
+      "args": [
+        "./scripts/ssh-exec-mcp.ts"
+      ]
+    }
+  }
+}

package/plugins/ssh-exec/assets/icon.svg

@@ -0,0 +1,34 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-label="SSH Exec plugin icon">
+  <rect x="28" y="40" width="200" height="176" rx="34" fill="#FFFFFF"/>
+  <rect x="28" y="40" width="200" height="176" rx="34" fill="none" stroke="#1D4ED8" stroke-width="14"/>
+  <path
+    d="M72 100l32 28-32 28"
+    fill="none"
+    stroke="#1D4ED8"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    stroke-width="16"
+  />
+  <path
+    d="M124 156h44"
+    fill="none"
+    stroke="#1D4ED8"
+    stroke-linecap="round"
+    stroke-width="16"
+  />
+  <circle cx="186" cy="88" r="18" fill="#1D4ED8"/>
+  <path
+    d="M186 70v14"
+    fill="none"
+    stroke="#FFFFFF"
+    stroke-linecap="round"
+    stroke-width="10"
+  />
+  <path
+    d="M176 88h20"
+    fill="none"
+    stroke="#FFFFFF"
+    stroke-linecap="round"
+    stroke-width="10"
+  />
+</svg>

package/plugins/ssh-exec/scripts/output-tail-sink.test.ts

@@ -0,0 +1,69 @@
+import { expect, test } from "bun:test";
+import { OutputTailSink } from "./output-tail-sink";
+import { MAX_OUTPUT_BYTES } from "./ssh-exec";
+
+test("OutputTailSink retains only the last maxBytes bytes", () => {
+  const sink = new OutputTailSink(8);
+
+  sink.write(Buffer.from("12345"));
+  sink.write(Buffer.from("67890"));
+
+  expect(sink.dump()).toMatchObject({ text: "34567890", stdout: "34567890", stderr: "", truncated: true });
+});
+
+test("OutputTailSink reports untruncated small output", () => {
+  const sink = new OutputTailSink(MAX_OUTPUT_BYTES);
+
+  sink.write(Buffer.from("small output\n"));
+
+  expect(sink.dump()).toMatchObject({
+    text: "small output\n",
+    stdout: "small output\n",
+    stderr: "",
+    truncated: false,
+    totalBytes: Buffer.byteLength("small output\n"),
+    outputBytes: Buffer.byteLength("small output\n"),
+  });
+});
+
+test("OutputTailSink retains one combined tail across stdout and stderr", () => {
+  const sink = new OutputTailSink(10);
+
+  sink.write("stdout", "out-12345");
+  sink.write("stderr", "err-67890");
+
+  const dump = sink.dump();
+  expect(Buffer.byteLength(dump.text)).toBeLessThanOrEqual(10);
+  expect(dump).toMatchObject({
+    text: "5err-67890",
+    stdout: "5",
+    stderr: "err-67890",
+    truncated: true,
+  });
+});
+
+test("OutputTailSink preserves retained stdout and stderr order in combined output", () => {
+  const sink = new OutputTailSink(MAX_OUTPUT_BYTES);
+
+  sink.write("stdout", "out-1\n");
+  sink.write("stderr", "err-1\n");
+  sink.write("stdout", "out-2\n");
+  sink.write("stderr", "err-2\n");
+
+  expect(sink.dump()).toMatchObject({
+    text: "out-1\nerr-1\nout-2\nerr-2\n",
+    stdout: "out-1\nout-2\n",
+    stderr: "err-1\nerr-2\n",
+    truncated: false,
+  });
+});
+
+test("OutputTailSink truncates on UTF-8 boundaries", () => {
+  const sink = new OutputTailSink(4);
+
+  sink.write("stdout", "x🙂y");
+
+  const dump = sink.dump();
+  expect(dump.text).toBe("y");
+  expect(dump.text).not.toContain("\uFFFD");
+});

package/plugins/ssh-exec/scripts/output-tail-sink.ts

@@ -0,0 +1,182 @@
+export interface TailDump {
+  text: string;
+  stdout: string;
+  stderr: string;
+  truncated: boolean;
+  totalBytes: number;
+  outputBytes: number;
+  totalLines: number;
+  outputLines: number;
+}
+
+export type OutputSource = "stdout" | "stderr";
+
+interface TailEntry {
+  source: OutputSource;
+  buffer: Buffer;
+}
+
+export class OutputTailSink {
+  private entries: TailEntry[] = [];
+  private didTruncate = false;
+  private retainedBytes = 0;
+  private writtenBytes = 0;
+  private writtenLines = 0;
+
+  constructor(private readonly maxBytes: number) {}
+
+  write(chunk: Uint8Array | string): void;
+  write(source: OutputSource, chunk: Uint8Array | string): void;
+  write(sourceOrChunk: OutputSource | Uint8Array | string, maybeChunk?: Uint8Array | string): void {
+    const source = maybeChunk === undefined ? "stdout" : (sourceOrChunk as OutputSource);
+    const chunk = maybeChunk === undefined ? (sourceOrChunk as Uint8Array | string) : maybeChunk;
+    const next = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk);
+    if (next.length === 0) return;
+
+    this.entries.push({ source, buffer: next });
+    this.retainedBytes += next.length;
+    this.writtenBytes += next.length;
+    this.writtenLines += countNewlines(next.toString("utf8"));
+    this.trim();
+  }
+
+  dump(): TailDump {
+    const combined: Buffer[] = [];
+    const stdoutBuffers: Buffer[] = [];
+    const stderrBuffers: Buffer[] = [];
+
+    for (const entry of this.entries) {
+      combined.push(entry.buffer);
+      if (entry.source === "stdout") {
+        stdoutBuffers.push(entry.buffer);
+      } else {
+        stderrBuffers.push(entry.buffer);
+      }
+    }
+
+    const text = Buffer.concat(combined).toString("utf8");
+    const stdout = Buffer.concat(stdoutBuffers).toString("utf8");
+    const stderr = Buffer.concat(stderrBuffers).toString("utf8");
+
+    return {
+      text,
+      stdout,
+      stderr,
+      truncated: this.didTruncate,
+      totalBytes: this.writtenBytes,
+      outputBytes: this.retainedBytes,
+      totalLines: this.writtenLines,
+      outputLines: countNewlines(text),
+    };
+  }
+
+  private trim(): void {
+    if (this.maxBytes <= 0) {
+      if (this.entries.length > 0) this.didTruncate = true;
+      this.entries = [];
+      this.retainedBytes = 0;
+      return;
+    }
+
+    if (this.retainedBytes <= this.maxBytes) {
+      return;
+    }
+
+    this.didTruncate = true;
+    this.rebuildTail();
+  }
+
+  private rebuildTail(): void {
+    const combined = Buffer.concat(this.entries.map((entry) => entry.buffer));
+    const safeStart = findUtf8TailStart(combined, this.maxBytes);
+    const sliced = combined.subarray(safeStart);
+
+    const rebuilt: TailEntry[] = [];
+    let offset = 0;
+    let retainedBytes = 0;
+
+    for (const entry of this.entries) {
+      const entryStart = offset;
+      const entryEnd = offset + entry.buffer.length;
+      offset = entryEnd;
+
+      if (entryEnd <= safeStart) continue;
+
+      const sliceStart = Math.max(safeStart, entryStart) - entryStart;
+      const sliceEnd = Math.min(combined.length, entryEnd) - entryStart;
+      const buffer = entry.buffer.subarray(sliceStart, sliceEnd);
+      if (buffer.length === 0) continue;
+
+      rebuilt.push({ source: entry.source, buffer });
+      retainedBytes += buffer.length;
+    }
+
+    this.entries = rebuilt.length > 0 || sliced.length === 0 ? rebuilt : [{ source: "stdout", buffer: sliced }];
+    this.retainedBytes = retainedBytes;
+  }
+}
+
+export async function readStreamTail(
+  stream: ReadableStream<Uint8Array> | null,
+  maxBytes: number,
+): Promise<TailDump> {
+  const sink = new OutputTailSink(maxBytes);
+  if (!stream) return sink.dump();
+
+  const reader = stream.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) sink.write(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  return sink.dump();
+}
+
+function countNewlines(text: string): number {
+  let count = 0;
+  let index = text.indexOf("\n");
+  while (index !== -1) {
+    count += 1;
+    index = text.indexOf("\n", index + 1);
+  }
+  return count;
+}
+
+function findUtf8TailStart(buffer: Buffer, maxBytes: number): number {
+  if (buffer.length <= maxBytes) return 0;
+
+  let start = buffer.length - maxBytes;
+  while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) {
+    start += 1;
+  }
+
+  while (start < buffer.length) {
+    const width = utf8SequenceWidth(buffer[start]);
+    if (width === 0) {
+      start += 1;
+      continue;
+    }
+    if (start + width <= buffer.length) {
+      return start;
+    }
+    start += 1;
+    while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) {
+      start += 1;
+    }
+  }
+
+  return buffer.length;
+}
+
+function utf8SequenceWidth(byte: number): number {
+  if ((byte & 0x80) === 0) return 1;
+  if ((byte & 0xe0) === 0xc0) return 2;
+  if ((byte & 0xf0) === 0xe0) return 3;
+  if ((byte & 0xf8) === 0xf0) return 4;
+  return 0;
+}