@yawlabs/ssh-mcp 0.10.0 → 0.11.1

package/README.md

@@ -7,6 +7,10 @@
 
 Built and maintained by [Yaw Labs](https://yaw.sh).
 
+[![Add to mcp.hosting](https://mcp.hosting/install-button.svg)](https://mcp.hosting/install?name=SSH&command=npx&args=-y%2C%40yawlabs%2Fssh-mcp&description=Run%20commands%20on%20remote%20hosts%2C%20transfer%20files%2C%20manage%20SSH%20tunnels%20and%20keys&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fssh-mcp)
+
+One click adds this to your [mcp.hosting](https://mcp.hosting) account so it syncs to every MCP client you use. Or install manually below.
+
 ## The problem
 
 AI CLI tools run in subprocesses where SSH is constantly broken. The agent tries to `git pull` and gets `Permission denied (publickey)`. It tries to SSH into a server and the agent socket is stale. It tries to deploy and the host key changed because the instance was recreated. Every time, the AI has no idea what's wrong and spirals.
@@ -66,12 +70,15 @@ Tools that fix your local SSH setup so everything else — git, deploys, tunnels
 
 | Tool | Description |
 |------|-------------|
-| `ssh_exec` | Execute a command on a remote host. Returns stdout, stderr, and exit code (or `[signal: NAME]` and `code: -1` when the channel closed signal-only). Subject to [command policy](#command-policy) if configured. |
+| `ssh_exec` | Execute a command on a remote host. Returns stdout, stderr, and exit code (or `[signal: NAME]` and `code: -1` when the channel closed signal-only). Optional `env` param sets per-call environment variables (POSIX-safe prefix, works regardless of sshd's `AcceptEnv`). Subject to [command policy](#command-policy) if configured. |
 | `ssh_read_file` | Read a file from a remote host via SFTP. |
 | `ssh_write_file` | Write content to a file on a remote host via SFTP. |
 | `ssh_upload` | Upload a local file to a remote host via SFTP. |
 | `ssh_download` | Download a file from a remote host to local filesystem. |
 | `ssh_ls` | List files in a directory on a remote host. |
+| `ssh_stat` | Get metadata for a file or directory (size, mode in octal, uid/gid, mtime/atime, isFile/isDirectory/isSymbolicLink). Use instead of parsing `ls -la`. |
+| `ssh_mkdir` | Create a directory via SFTP. Set `recursive: true` for `mkdir -p` behavior. |
+| `ssh_delete` | Delete a file or empty directory via SFTP. Auto-dispatches unlink vs rmdir based on the path's type. Recursive directory delete is intentionally NOT supported -- use `ssh_exec rm -rf` if you need it. |
 
 ### Higher-level operations
 
@@ -135,6 +142,29 @@ Blocked commands surface as a clear error mentioning which pattern (or which env
 
 The structured higher-level tools (`ssh_find`, `ssh_tail`, `ssh_service_status`, SFTP ops) are exempt from policy. They build commands from typed parameters, so a tight `^ls` whitelist would otherwise force you to allow `^find `, `^tail `, `^systemctl ` just to keep those tools working — defeating the point of a tight whitelist.
 
+#### Policy interaction with `ssh_exec`'s `env` parameter
+
+When `ssh_exec` is called with `env: { KEY: "value" }`, the values are injected as a `KEY='value' ...` shell prefix before the command (see the `ssh_exec` description). **Policy is checked against the full prefixed command**, not the bare `command` argument. That's the safer ordering at the protocol layer — but it means whitelist patterns need to anticipate the prefix and must be **anchored**, not substring matches:
+
+```bash
+# WRONG -- blocks any ssh_exec call that uses `env`, because the final command
+# starts with `KEY='value' ` and never matches `^ls`.
+SSH_MCP_COMMAND_WHITELIST="^ls "
+
+# RIGHT -- allow zero or more `KEY='value' ` prefixes before the real command.
+SSH_MCP_COMMAND_WHITELIST="^([A-Za-z_][A-Za-z0-9_]*='[^']*' )*ls( |$)"
+```
+
+**Avoid substring-match patterns** like ` ls ` if you're worried about a hostile agent. An agent could pass `env: { ATTACK: " ls " }` to make the final command `ATTACK=' ls ' rm -rf /`, which matches a substring ` ls ` and bypasses the whitelist. Anchored patterns of the form above don't have this weakness because they require the real command name to follow the env-prefix block, not appear inside a quoted env value.
+
+Blacklists need the same care. `^rm ` blocks a bare `rm` call, but doesn't block `FOO='bar' rm`. Use the same env-prefix-tolerant anchor:
+
+```bash
+SSH_MCP_COMMAND_BLACKLIST="^([A-Za-z_][A-Za-z0-9_]*='[^']*' )*rm( |$)"
+```
+
+If you don't trust the agent's `env` values at all, the simplest mitigation is to leave `env` unused in your client config and pass everything through the `command` string yourself.
+
 ### Windows support
 
 On Windows, ssh-mcp detects the OpenSSH Authentication Agent service automatically (via the `\\.\pipe\openssh-ssh-agent` named pipe). No `SSH_AUTH_SOCK` needed — just make sure the OpenSSH agent service is running.

package/dist/index.js

@@ -953,6 +953,77 @@ async function listDir(client, remotePath) {
     sftp.end();
   }
 }
+async function statFile(client, remotePath) {
+  const sftp = await getSftp(client);
+  try {
+    return await new Promise((resolve, reject) => {
+      sftp.stat(remotePath, (err, stats) => {
+        if (err) return reject(err);
+        resolve({
+          size: stats.size,
+          mode: stats.mode,
+          modeOctal: (stats.mode & 4095).toString(8).padStart(4, "0"),
+          uid: stats.uid,
+          gid: stats.gid,
+          mtime: stats.mtime,
+          atime: stats.atime,
+          isFile: stats.isFile(),
+          isDirectory: stats.isDirectory(),
+          isSymbolicLink: stats.isSymbolicLink()
+        });
+      });
+    });
+  } finally {
+    sftp.end();
+  }
+}
+async function deleteFile(client, remotePath) {
+  const sftp = await getSftp(client);
+  try {
+    const stats = await new Promise((resolve, reject) => {
+      sftp.stat(remotePath, (err, stats2) => {
+        if (err) return reject(err);
+        resolve(stats2);
+      });
+    });
+    await new Promise((resolve, reject) => {
+      const done = (err) => err ? reject(err) : resolve();
+      if (stats.isDirectory()) {
+        sftp.rmdir(remotePath, done);
+      } else {
+        sftp.unlink(remotePath, done);
+      }
+    });
+  } finally {
+    sftp.end();
+  }
+}
+async function makeDir(client, remotePath, recursive = false) {
+  const sftp = await getSftp(client);
+  try {
+    const mkOne = (path) => new Promise((resolve, reject) => {
+      sftp.mkdir(path, (err) => err ? reject(err) : resolve());
+    });
+    if (!recursive) {
+      await mkOne(remotePath);
+      return;
+    }
+    const isAbsolute = remotePath.startsWith("/");
+    const parts = remotePath.split("/").filter(Boolean);
+    let cur = isAbsolute ? "" : ".";
+    for (let i = 0; i < parts.length; i++) {
+      cur = isAbsolute ? `${cur}/${parts[i]}` : `${cur}/${parts[i]}`;
+      const isLeaf = i === parts.length - 1;
+      try {
+        await mkOne(cur);
+      } catch (e) {
+        if (isLeaf) throw e;
+      }
+    }
+  } finally {
+    sftp.end();
+  }
+}
 
 // src/pool.ts
 function defaultMaxPoolSize() {
@@ -1291,16 +1362,24 @@ function registerTools(server, pool) {
   const connectionPool = pool ?? new ConnectionPool();
   server.tool(
     "ssh_exec",
-    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured.",
+    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code. Use `env` to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked against the env-prefixed command).",
     {
       ...connectionParams,
       command: z.string().describe("Shell command to execute on the remote host (interpreted by the remote login shell)"),
+      env: z.record(z.string(), z.string()).optional().describe(
+        "Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. Values are POSIX-single-quoted, so any byte is safe."
+      ),
       timeout: TimeoutSchema
     },
-    async ({ command, timeout, ...conn }) => {
-      enforcePolicy(command);
+    async ({ command, env, timeout, ...conn }) => {
+      let finalCommand = command;
+      if (env && Object.keys(env).length > 0) {
+        const prefix = Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`).join(" ");
+        finalCommand = `${prefix} ${command}`;
+      }
+      enforcePolicy(finalCommand);
       return connectionPool.withConnection(conn, async (client) => {
-        const result = await exec(client, command, timeout || 3e4);
+        const result = await exec(client, finalCommand, timeout || 3e4);
         const parts = [];
         if (result.stdout) parts.push(result.stdout);
         if (result.stderr) parts.push(`[stderr]
@@ -1384,6 +1463,57 @@ ${result.stderr}`);
       });
     }
   );
+  server.tool(
+    "ssh_stat",
+    "Get metadata for a file or directory on a remote host via SFTP. Returns size, permissions (octal), uid/gid, mtime/atime, and type flags (isFile, isDirectory, isSymbolicLink). Use this instead of parsing `ls -la` output.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path to the remote file or directory")
+    },
+    async ({ path, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
+        const stats = await statFile(client, path);
+        const lines = [];
+        const kind = stats.isDirectory ? "directory" : stats.isSymbolicLink ? "symlink" : stats.isFile ? "file" : "other";
+        lines.push(`${path}: ${kind}`);
+        lines.push(`  Size: ${stats.size} bytes`);
+        lines.push(`  Mode: ${stats.modeOctal}`);
+        lines.push(`  Owner: uid=${stats.uid} gid=${stats.gid}`);
+        lines.push(`  Modified: ${new Date(stats.mtime * 1e3).toISOString()}`);
+        lines.push(`  Accessed: ${new Date(stats.atime * 1e3).toISOString()}`);
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      });
+    }
+  );
+  server.tool(
+    "ssh_mkdir",
+    "Create a directory on a remote host via SFTP. Set `recursive: true` to create parent directories as needed (like `mkdir -p`). Existing intermediate dirs are tolerated; an existing leaf path is still an error.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path of the directory to create"),
+      recursive: z.boolean().optional().describe("Create parent directories as needed (default: false). Like `mkdir -p`.")
+    },
+    async ({ path, recursive, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
+        await makeDir(client, path, recursive ?? false);
+        return { content: [{ type: "text", text: `Created directory ${path}` }] };
+      });
+    }
+  );
+  server.tool(
+    "ssh_delete",
+    "Delete a file or empty directory on a remote host via SFTP. Auto-detects the path type and calls the right SFTP op (unlink for files/symlinks, rmdir for empty dirs). Recursive directory delete is intentionally NOT supported -- for that, use ssh_exec with `rm -rf` explicitly so the destructive intent is visible in the tool trace.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path of the file or empty directory to delete")
+    },
+    async ({ path, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
+        await deleteFile(client, path);
+        return { content: [{ type: "text", text: `Deleted ${path}` }] };
+      });
+    }
+  );
   server.tool(
     "ssh_diagnose",
     "Diagnose SSH connectivity issues. Checks ssh-agent status, loaded keys, known_hosts, SSH config, and attempts a test connection. Use this BEFORE attempting SSH operations if you suspect connectivity issues, or AFTER a failed SSH operation to understand why it failed.",

package/dist/server.d.ts

@@ -36,6 +36,25 @@ declare function writeFile(client: Client, remotePath: string, content: string):
 declare function uploadFile(client: Client, localPath: string, remotePath: string): Promise<void>;
 declare function downloadFile(client: Client, remotePath: string, localPath: string): Promise<void>;
 declare function listDir(client: Client, remotePath: string): Promise<string[]>;
+interface FileStats {
+    size: number;
+    /** POSIX mode as a decimal number. Use modeOctal for the human-readable form. */
+    mode: number;
+    /** POSIX mode formatted as a 4-digit octal string (e.g. "0755"). */
+    modeOctal: string;
+    uid: number;
+    gid: number;
+    /** Unix timestamp (seconds since epoch) of last modification. */
+    mtime: number;
+    /** Unix timestamp (seconds since epoch) of last access. */
+    atime: number;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+}
+declare function statFile(client: Client, remotePath: string): Promise<FileStats>;
+declare function deleteFile(client: Client, remotePath: string): Promise<void>;
+declare function makeDir(client: Client, remotePath: string, recursive?: boolean): Promise<void>;
 
 interface PoolOptions {
     /** Milliseconds before an idle connection is closed. Default: 60000 (60s) */
@@ -200,4 +219,4 @@ declare function registerTools(server: McpServer, pool?: ConnectionPool): void;
 
 declare function createServer(pool?: ConnectionPool): McpServer;
 
-export { type AgentResult, type ConfigLookupResult, ConnectionPool, type DiagnosticReport, type DiagnosticResult, type ExecResult, type FindOptions, type KeyInfo, type MultiExecHost, type MultiExecResult, type PoolOptions, type ResolvedConfig, type SSHConfig, type ServiceStatus, checkConnectivity, checkGitSsh, checkKnownHosts, checkSshAgent, checkSshConfig, checkSshKeys, configLookup, connect, connectRaw, connectWithProxy, createServer, diagnose, downloadFile, enforcePolicy, ensureAgent, exec, find, fixKnownHosts, formatDiagnostics, isPolicyConfigured, listDir, listSshKeys, loadKey, multiExec, readFile, readKnownHostsKeys, registerTools, resolveConfig, serviceStatus, tail, testConnection, uploadFile, writeFile };
+export { type AgentResult, type ConfigLookupResult, ConnectionPool, type DiagnosticReport, type DiagnosticResult, type ExecResult, type FileStats, type FindOptions, type KeyInfo, type MultiExecHost, type MultiExecResult, type PoolOptions, type ResolvedConfig, type SSHConfig, type ServiceStatus, checkConnectivity, checkGitSsh, checkKnownHosts, checkSshAgent, checkSshConfig, checkSshKeys, configLookup, connect, connectRaw, connectWithProxy, createServer, deleteFile, diagnose, downloadFile, enforcePolicy, ensureAgent, exec, find, fixKnownHosts, formatDiagnostics, isPolicyConfigured, listDir, listSshKeys, loadKey, makeDir, multiExec, readFile, readKnownHostsKeys, registerTools, resolveConfig, serviceStatus, statFile, tail, testConnection, uploadFile, writeFile };

package/dist/server.js

@@ -967,6 +967,77 @@ async function listDir(client, remotePath) {
     sftp.end();
   }
 }
+async function statFile(client, remotePath) {
+  const sftp = await getSftp(client);
+  try {
+    return await new Promise((resolve, reject) => {
+      sftp.stat(remotePath, (err, stats) => {
+        if (err) return reject(err);
+        resolve({
+          size: stats.size,
+          mode: stats.mode,
+          modeOctal: (stats.mode & 4095).toString(8).padStart(4, "0"),
+          uid: stats.uid,
+          gid: stats.gid,
+          mtime: stats.mtime,
+          atime: stats.atime,
+          isFile: stats.isFile(),
+          isDirectory: stats.isDirectory(),
+          isSymbolicLink: stats.isSymbolicLink()
+        });
+      });
+    });
+  } finally {
+    sftp.end();
+  }
+}
+async function deleteFile(client, remotePath) {
+  const sftp = await getSftp(client);
+  try {
+    const stats = await new Promise((resolve, reject) => {
+      sftp.stat(remotePath, (err, stats2) => {
+        if (err) return reject(err);
+        resolve(stats2);
+      });
+    });
+    await new Promise((resolve, reject) => {
+      const done = (err) => err ? reject(err) : resolve();
+      if (stats.isDirectory()) {
+        sftp.rmdir(remotePath, done);
+      } else {
+        sftp.unlink(remotePath, done);
+      }
+    });
+  } finally {
+    sftp.end();
+  }
+}
+async function makeDir(client, remotePath, recursive = false) {
+  const sftp = await getSftp(client);
+  try {
+    const mkOne = (path) => new Promise((resolve, reject) => {
+      sftp.mkdir(path, (err) => err ? reject(err) : resolve());
+    });
+    if (!recursive) {
+      await mkOne(remotePath);
+      return;
+    }
+    const isAbsolute = remotePath.startsWith("/");
+    const parts = remotePath.split("/").filter(Boolean);
+    let cur = isAbsolute ? "" : ".";
+    for (let i = 0; i < parts.length; i++) {
+      cur = isAbsolute ? `${cur}/${parts[i]}` : `${cur}/${parts[i]}`;
+      const isLeaf = i === parts.length - 1;
+      try {
+        await mkOne(cur);
+      } catch (e) {
+        if (isLeaf) throw e;
+      }
+    }
+  } finally {
+    sftp.end();
+  }
+}
 
 // src/ops.ts
 function shellQuote(s) {
@@ -1299,16 +1370,24 @@ function registerTools(server, pool) {
   const connectionPool = pool ?? new ConnectionPool();
   server.tool(
     "ssh_exec",
-    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured.",
+    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code. Use `env` to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked against the env-prefixed command).",
     {
       ...connectionParams,
       command: z.string().describe("Shell command to execute on the remote host (interpreted by the remote login shell)"),
+      env: z.record(z.string(), z.string()).optional().describe(
+        "Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. Values are POSIX-single-quoted, so any byte is safe."
+      ),
       timeout: TimeoutSchema
     },
-    async ({ command, timeout, ...conn }) => {
-      enforcePolicy(command);
+    async ({ command, env, timeout, ...conn }) => {
+      let finalCommand = command;
+      if (env && Object.keys(env).length > 0) {
+        const prefix = Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`).join(" ");
+        finalCommand = `${prefix} ${command}`;
+      }
+      enforcePolicy(finalCommand);
       return connectionPool.withConnection(conn, async (client) => {
-        const result = await exec(client, command, timeout || 3e4);
+        const result = await exec(client, finalCommand, timeout || 3e4);
         const parts = [];
         if (result.stdout) parts.push(result.stdout);
         if (result.stderr) parts.push(`[stderr]
@@ -1392,6 +1471,57 @@ ${result.stderr}`);
       });
     }
   );
+  server.tool(
+    "ssh_stat",
+    "Get metadata for a file or directory on a remote host via SFTP. Returns size, permissions (octal), uid/gid, mtime/atime, and type flags (isFile, isDirectory, isSymbolicLink). Use this instead of parsing `ls -la` output.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path to the remote file or directory")
+    },
+    async ({ path, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
+        const stats = await statFile(client, path);
+        const lines = [];
+        const kind = stats.isDirectory ? "directory" : stats.isSymbolicLink ? "symlink" : stats.isFile ? "file" : "other";
+        lines.push(`${path}: ${kind}`);
+        lines.push(`  Size: ${stats.size} bytes`);
+        lines.push(`  Mode: ${stats.modeOctal}`);
+        lines.push(`  Owner: uid=${stats.uid} gid=${stats.gid}`);
+        lines.push(`  Modified: ${new Date(stats.mtime * 1e3).toISOString()}`);
+        lines.push(`  Accessed: ${new Date(stats.atime * 1e3).toISOString()}`);
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      });
+    }
+  );
+  server.tool(
+    "ssh_mkdir",
+    "Create a directory on a remote host via SFTP. Set `recursive: true` to create parent directories as needed (like `mkdir -p`). Existing intermediate dirs are tolerated; an existing leaf path is still an error.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path of the directory to create"),
+      recursive: z.boolean().optional().describe("Create parent directories as needed (default: false). Like `mkdir -p`.")
+    },
+    async ({ path, recursive, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
+        await makeDir(client, path, recursive ?? false);
+        return { content: [{ type: "text", text: `Created directory ${path}` }] };
+      });
+    }
+  );
+  server.tool(
+    "ssh_delete",
+    "Delete a file or empty directory on a remote host via SFTP. Auto-detects the path type and calls the right SFTP op (unlink for files/symlinks, rmdir for empty dirs). Recursive directory delete is intentionally NOT supported -- for that, use ssh_exec with `rm -rf` explicitly so the destructive intent is visible in the tool trace.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path of the file or empty directory to delete")
+    },
+    async ({ path, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
+        await deleteFile(client, path);
+        return { content: [{ type: "text", text: `Deleted ${path}` }] };
+      });
+    }
+  );
   server.tool(
     "ssh_diagnose",
     "Diagnose SSH connectivity issues. Checks ssh-agent status, loaded keys, known_hosts, SSH config, and attempts a test connection. Use this BEFORE attempting SSH operations if you suspect connectivity issues, or AFTER a failed SSH operation to understand why it failed.",
@@ -1681,6 +1811,7 @@ export {
   connectRaw,
   connectWithProxy,
   createServer,
+  deleteFile,
   diagnose,
   downloadFile,
   enforcePolicy,
@@ -1693,12 +1824,14 @@ export {
   listDir,
   listSshKeys,
   loadKey,
+  makeDir,
   multiExec,
   readFile,
   readKnownHostsKeys,
   registerTools,
   resolveConfig,
   serviceStatus,
+  statFile,
   tail,
   testConnection,
   uploadFile,

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@yawlabs/ssh-mcp",
-  "version": "0.10.0",
+  "version": "0.11.1",
+  "mcpName": "io.github.YawLabs/ssh-mcp",
   "description": "MCP server for SSH operations with built-in diagnostics",
   "type": "module",
   "bin": {