@yawlabs/ssh-mcp 0.10.0 → 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 (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
 

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,6 @@
 {
   "name": "@yawlabs/ssh-mcp",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "MCP server for SSH operations with built-in diagnostics",
   "type": "module",
   "bin": {