@yawlabs/ssh-mcp 0.9.3 → 0.11.0

package/README.md

@@ -66,12 +66,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. |
+| `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
 
@@ -79,10 +82,10 @@ Tools that wrap common patterns agents build with ssh_exec — faster and less e
 
 | Tool | Description |
 |------|-------------|
-| `ssh_multi_exec` | Run a command on multiple hosts in parallel. Returns results per host. |
-| `ssh_find` | Search for files remotely with structured parameters (name, type, size, depth). |
+| `ssh_multi_exec` | Run a command on multiple hosts in parallel. Returns results per host. Subject to [command policy](#command-policy) if configured (policy is checked once before fan-out). |
+| `ssh_find` | Search for files remotely with structured parameters (`name`, `type`, `size`, `depth`, `newer` — match files modified more recently than a reference path). |
 | `ssh_tail` | Read the last N lines of a file, optionally filtered by a grep pattern. |
-| `ssh_service_status` | Check systemd service status (active, PID, uptime, description). |
+| `ssh_service_status` | Check systemd service status (active, PID, uptime, description). Flags `isError` only when the unit could not be found / queried, not when an existing unit is intentionally stopped. |
 
 ### Auto-diagnostics
 
@@ -92,6 +95,8 @@ When any remote operation fails, ssh-mcp automatically runs diagnostics and incl
 
 Remote operations reuse SSH connections automatically. When your agent makes multiple calls to the same host, the first call opens a connection and subsequent calls reuse it. Connections are kept alive for 60 seconds after the last use, then closed automatically.
 
+The pool caps at 100 active connections by default. Set `SSH_MCP_MAX_POOL_SIZE=<n>` to raise it for fan-out workloads against many distinct hosts (e.g. `ssh_multi_exec` across a large fleet). When the cap is reached, the pool evicts an idle entry to make room; if every entry is in use it rejects with `Connection pool is full`.
+
 ### SSH config support
 
 All connections respect your `~/.ssh/config`. Host aliases, custom ports, usernames, identity files, and ProxyJump settings are used automatically. If you have `Host myserver` configured in your SSH config, just pass `host: "myserver"` — ssh-mcp resolves everything.
@@ -110,6 +115,29 @@ For stricter environments, set `SSH_MCP_STRICT_HOST_KEY=1` to reject unknown hos
 
 The diagnostic tools (`ssh_test`, `ssh_diagnose`) use `StrictHostKeyChecking=no` for their probe commands. Those probes only run `echo SSH_OK` — no credentials or data pass through — so the relaxed setting is safe for connectivity testing. Real operations always go through the `hostVerifier`.
 
+### Command policy
+
+`ssh_exec` and `ssh_multi_exec` accept free-form shell commands from the agent. For security-conscious deployments, you can restrict which commands run via two env vars, each accepting a comma-separated list of regex patterns:
+
+- `SSH_MCP_COMMAND_WHITELIST` — if set, the command **must** match at least one pattern, else it's blocked.
+- `SSH_MCP_COMMAND_BLACKLIST` — if set, the command **must not** match any pattern, else it's blocked.
+
+When both are set, the command must pass both checks (whitelist first, then blacklist). When neither is set (the default), all commands are allowed.
+
+Patterns are JavaScript regexes. Use `^` and `$` for anchored matches; otherwise patterns are treated as substring matches. Commas are the delimiter, so a literal comma in a pattern needs to be expressed as `\x2c` or via a character class.
+
+```bash
+# Read-only allowlist: only ls / df / cat / find / tail
+SSH_MCP_COMMAND_WHITELIST="^ls( .*)?,^df( .*)?,^cat ,^find ,^tail "
+
+# Block destructive ops even if your agent goes off-script
+SSH_MCP_COMMAND_BLACKLIST="^rm ,^shutdown,^reboot,^mkfs,^dd if=,>\s*/dev/"
+```
+
+Blocked commands surface as a clear error mentioning which pattern (or which env var) rejected the call, so the agent can adapt rather than guess. Policy is enforced before the SSH connection opens — no remote process is started for a blocked command.
+
+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.
+
 ### 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() {
@@ -1241,6 +1312,36 @@ async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
   };
 }
 
+// src/policy.ts
+function parsePatterns(raw) {
+  if (!raw) return [];
+  const patterns = [];
+  for (const p of raw.split(",")) {
+    const cleaned = p.replace(/^\s+/, "");
+    if (!cleaned) continue;
+    try {
+      patterns.push(new RegExp(cleaned));
+    } catch {
+      console.error(`ssh-mcp: ignoring malformed regex in command policy: "${cleaned}"`);
+    }
+  }
+  return patterns;
+}
+function enforcePolicy(command) {
+  const whitelist = parsePatterns(process.env.SSH_MCP_COMMAND_WHITELIST);
+  if (whitelist.length > 0 && !whitelist.some((r) => r.test(command))) {
+    throw new Error(
+      `Command blocked: does not match any pattern in SSH_MCP_COMMAND_WHITELIST. Configured patterns: ${whitelist.map((r) => r.source).join(", ")}`
+    );
+  }
+  const blacklist = parsePatterns(process.env.SSH_MCP_COMMAND_BLACKLIST);
+  for (const pattern of blacklist) {
+    if (pattern.test(command)) {
+      throw new Error(`Command blocked by SSH_MCP_COMMAND_BLACKLIST: pattern "${pattern.source}"`);
+    }
+  }
+}
+
 // src/tools.ts
 var HostSchema = z.string().describe("SSH hostname or IP address");
 var PortSchema = z.number().int().min(1).max(65535).optional().describe("SSH port (default: 22)");
@@ -1261,15 +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.",
+    "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 }) => {
+    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]
@@ -1353,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.",
@@ -1511,7 +1672,7 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_multi_exec",
-    "Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side.",
+    "Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once before fan-out).",
     {
       hosts: z.array(z.string()).describe("List of SSH hostnames or IPs"),
       command: z.string().describe("Shell command to execute on all hosts"),
@@ -1522,6 +1683,7 @@ ${result.stderr}`);
       timeout: TimeoutSchema
     },
     async ({ hosts, command, port, username, privateKeyPath, password, timeout }) => {
+      enforcePolicy(command);
       const hostConfigs = hosts.map((host) => ({ host, port, username, privateKeyPath, password }));
       const results = await multiExec(connectionPool, hostConfigs, command, timeout || 3e4);
       const lines = [];

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) */
@@ -185,8 +204,19 @@ interface ServiceStatus {
 }
 declare function serviceStatus(client: Client, serviceName: string, timeoutMs?: number): Promise<ServiceStatus>;
 
+/**
+ * Check a command against the env-configured policy. Throws if blocked.
+ *
+ * Called from MCP tool handlers (ssh_exec, ssh_multi_exec) -- not from `exec()` itself,
+ * so library consumers using the programmatic API don't get policy enforcement (they're
+ * outside the MCP trust boundary and write their own gating).
+ */
+declare function enforcePolicy(command: string): void;
+/** Returns true if any policy is currently configured. Used by tool descriptions to surface that. */
+declare function isPolicyConfigured(): boolean;
+
 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, ensureAgent, exec, find, fixKnownHosts, formatDiagnostics, 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) {
@@ -1052,6 +1123,39 @@ async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
   };
 }
 
+// src/policy.ts
+function parsePatterns(raw) {
+  if (!raw) return [];
+  const patterns = [];
+  for (const p of raw.split(",")) {
+    const cleaned = p.replace(/^\s+/, "");
+    if (!cleaned) continue;
+    try {
+      patterns.push(new RegExp(cleaned));
+    } catch {
+      console.error(`ssh-mcp: ignoring malformed regex in command policy: "${cleaned}"`);
+    }
+  }
+  return patterns;
+}
+function enforcePolicy(command) {
+  const whitelist = parsePatterns(process.env.SSH_MCP_COMMAND_WHITELIST);
+  if (whitelist.length > 0 && !whitelist.some((r) => r.test(command))) {
+    throw new Error(
+      `Command blocked: does not match any pattern in SSH_MCP_COMMAND_WHITELIST. Configured patterns: ${whitelist.map((r) => r.source).join(", ")}`
+    );
+  }
+  const blacklist = parsePatterns(process.env.SSH_MCP_COMMAND_BLACKLIST);
+  for (const pattern of blacklist) {
+    if (pattern.test(command)) {
+      throw new Error(`Command blocked by SSH_MCP_COMMAND_BLACKLIST: pattern "${pattern.source}"`);
+    }
+  }
+}
+function isPolicyConfigured() {
+  return Boolean(process.env.SSH_MCP_COMMAND_WHITELIST?.trim() || process.env.SSH_MCP_COMMAND_BLACKLIST?.trim());
+}
+
 // src/pool.ts
 function defaultMaxPoolSize() {
   const raw = process.env.SSH_MCP_MAX_POOL_SIZE;
@@ -1266,15 +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.",
+    "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 }) => {
+    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]
@@ -1358,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.",
@@ -1516,7 +1680,7 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_multi_exec",
-    "Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side.",
+    "Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once before fan-out).",
     {
       hosts: z.array(z.string()).describe("List of SSH hostnames or IPs"),
       command: z.string().describe("Shell command to execute on all hosts"),
@@ -1527,6 +1691,7 @@ ${result.stderr}`);
       timeout: TimeoutSchema
     },
     async ({ hosts, command, port, username, privateKeyPath, password, timeout }) => {
+      enforcePolicy(command);
       const hostConfigs = hosts.map((host) => ({ host, port, username, privateKeyPath, password }));
       const results = await multiExec(connectionPool, hostConfigs, command, timeout || 3e4);
       const lines = [];
@@ -1646,22 +1811,27 @@ export {
   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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/ssh-mcp",
-  "version": "0.9.3",
+  "version": "0.11.0",
   "description": "MCP server for SSH operations with built-in diagnostics",
   "type": "module",
   "bin": {