ssh_stat

Instructions

Implementation Reference

• src/ssh.ts:547-572 (handler)

  The core implementation of statFile - uses ssh2 SFTP to stat a remote file/directory and returns a FileStats object with size, permissions, uid/gid, timestamps, and type flags.

  export async function statFile(client: Client, remotePath: string): Promise<FileStats> {
    const sftp = await getSftp(client);
    try {
      return await new Promise((resolve, reject) => {
        sftp.stat(remotePath, (err, stats) => {
          if (err) return reject(err);
          // ssh2 exposes the type checks as methods, not boolean fields -- materialize them
          // up front so the result is a plain JSON-safe object the MCP layer can serialize.
          resolve({
            size: stats.size,
            mode: stats.mode,
            modeOctal: (stats.mode & 0o7777).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();
    }
  }

• src/ssh.ts:530-545 (schema)

  FileStats interface - defines the shape of the stat result returned by statFile, including size, mode, modeOctal, uid, gid, mtime, atime, isFile, isDirectory, isSymbolicLink.

  export 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;
  }

• src/tools.ts:159-186 (handler)

  Registration of the 'ssh_stat' MCP tool with its Zod schema, description, and handler that calls statFile and formats the output as human-readable text.

  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: string[] = [];
        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 * 1000).toISOString()}`);
        lines.push(`  Accessed: ${new Date(stats.atime * 1000).toISOString()}`);
        return { content: [{ type: "text", text: lines.join("\n") }] };
      });
    },
  );

• src/tools.ts:162-165 (schema)

  Zod schema for ssh_stat tool input: connection params (host, port, username, privateKeyPath, password) plus a required 'path' string.

  {
    ...connectionParams,
    path: z.string().describe("Absolute path to the remote file or directory"),
  },

• src/server.ts:49-67 (registration)

  Re-export of FileStats type and statFile function from ssh.ts, and re-export of registerTools from tools.ts which registers the ssh_stat tool.

  export type { ExecResult, FileStats, ResolvedConfig, SSHConfig } from "./ssh.js";
  export {
    connect,
    connectRaw,
    connectWithProxy,
    deleteFile,
    downloadFile,
    exec,
    formatDiagnostics,
    listDir,
    makeDir,
    readFile,
    readKnownHostsKeys,
    resolveConfig,
    statFile,
    uploadFile,
    writeFile,
  } from "./ssh.js";
  export { registerTools } from "./tools.js";