@yawlabs/ssh-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaw Labs
+
+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/dist/index.js

@@ -0,0 +1,495 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools.ts
+import { z } from "zod";
+
+// src/diagnose.ts
+import { execSync } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+function run(cmd) {
+  try {
+    const stdout = execSync(cmd, { encoding: "utf8", timeout: 1e4, stdio: ["pipe", "pipe", "pipe"] });
+    return { stdout: stdout.trim(), ok: true };
+  } catch (e) {
+    return { stdout: e.stdout?.toString().trim() || e.message || "", ok: false };
+  }
+}
+function checkSshAgent() {
+  const sock = process.env.SSH_AUTH_SOCK;
+  if (!sock) {
+    return {
+      status: "error",
+      message: "SSH_AUTH_SOCK is not set. ssh-agent is not running or not exported to this shell."
+    };
+  }
+  const { stdout, ok } = run("ssh-add -l");
+  if (!ok && stdout.includes("Could not open a connection")) {
+    return {
+      status: "error",
+      message: `SSH_AUTH_SOCK is set to "${sock}" but the agent is not reachable. The agent process may have died. Run: eval "$(ssh-agent -s)"`
+    };
+  }
+  if (stdout.includes("The agent has no identities")) {
+    return {
+      status: "warning",
+      message: "ssh-agent is running but has no keys loaded. Run: ssh-add <key-path>"
+    };
+  }
+  return { status: "ok", message: `ssh-agent running with keys:
+${stdout}` };
+}
+function checkSshKeys() {
+  const home = homedir();
+  const sshDir = join(home, ".ssh");
+  if (!existsSync(sshDir)) {
+    return { status: "error", message: "~/.ssh directory does not exist. Run: mkdir -p ~/.ssh && chmod 700 ~/.ssh" };
+  }
+  const keyTypes = ["id_ed25519", "id_rsa", "id_ecdsa"];
+  const found = [];
+  for (const key of keyTypes) {
+    const keyPath = join(sshDir, key);
+    if (existsSync(keyPath)) {
+      found.push(key);
+    }
+  }
+  try {
+    const { stdout } = run(`ls "${sshDir}"`);
+    const allFiles = stdout.split("\n").filter((f) => !f.endsWith(".pub") && !["known_hosts", "config", "authorized_keys"].includes(f));
+    for (const f of allFiles) {
+      if (!keyTypes.includes(f) && existsSync(join(sshDir, f))) {
+        try {
+          const content = readFileSync(join(sshDir, f), "utf8");
+          if (content.includes("PRIVATE KEY")) {
+            found.push(f);
+          }
+        } catch {
+        }
+      }
+    }
+  } catch {
+  }
+  if (found.length === 0) {
+    return {
+      status: "error",
+      message: 'No SSH private keys found in ~/.ssh/. Generate one: ssh-keygen -t ed25519 -C "your@email.com"'
+    };
+  }
+  return { status: "ok", message: `Found SSH keys: ${found.join(", ")}` };
+}
+function checkKnownHosts(host) {
+  const knownHostsPath = join(homedir(), ".ssh", "known_hosts");
+  if (!existsSync(knownHostsPath)) {
+    return {
+      status: "warning",
+      message: "~/.ssh/known_hosts does not exist. First connection to any host will prompt for verification."
+    };
+  }
+  const { stdout, ok } = run(`ssh-keygen -F "${host}"`);
+  if (!ok || !stdout.trim()) {
+    return {
+      status: "warning",
+      message: `Host "${host}" is not in known_hosts. First connection will prompt for host key verification. To add it: ssh-keyscan -H ${host} >> ~/.ssh/known_hosts`
+    };
+  }
+  return { status: "ok", message: `Host "${host}" found in known_hosts` };
+}
+function checkConnectivity(host, port = 22) {
+  const { ok, stdout } = run(
+    `ssh -o ConnectTimeout=5 -o BatchMode=yes -o StrictHostKeyChecking=no -p ${port} ${host} echo SSH_OK 2>&1`
+  );
+  if (ok && stdout.includes("SSH_OK")) {
+    return { status: "ok", message: `SSH connection to ${host}:${port} succeeded` };
+  }
+  if (stdout.includes("Permission denied")) {
+    return {
+      status: "error",
+      message: `Permission denied connecting to ${host}:${port}. Your key is not authorized on this host. Check: 1) correct key is loaded (ssh-add -l), 2) key is in remote authorized_keys, 3) correct username.`
+    };
+  }
+  if (stdout.includes("Connection refused")) {
+    return {
+      status: "error",
+      message: `Connection refused at ${host}:${port}. SSH server is not running on this port or host is blocking connections.`
+    };
+  }
+  if (stdout.includes("Connection timed out") || stdout.includes("timed out")) {
+    return {
+      status: "error",
+      message: `Connection timed out to ${host}:${port}. Host may be down, port may be blocked by firewall, or DNS resolution failed.`
+    };
+  }
+  if (stdout.includes("Host key verification failed")) {
+    return {
+      status: "error",
+      message: `Host key verification failed for ${host}. The host key changed (instance recreated?). Fix: ssh-keygen -R ${host} && ssh-keyscan -H ${host} >> ~/.ssh/known_hosts`
+    };
+  }
+  if (stdout.includes("Could not resolve hostname")) {
+    return {
+      status: "error",
+      message: `Could not resolve hostname "${host}". Check DNS, /etc/hosts, or SSH config aliases.`
+    };
+  }
+  return { status: "error", message: `SSH connection failed: ${stdout}` };
+}
+function checkSshConfig(host) {
+  const configPath = join(homedir(), ".ssh", "config");
+  if (!existsSync(configPath)) {
+    return { status: "ok", message: "No ~/.ssh/config file (using defaults)" };
+  }
+  try {
+    const content = readFileSync(configPath, "utf8");
+    const lines = content.split("\n");
+    let inHostBlock = false;
+    const hostConfig = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (/^Host\s+/i.test(trimmed)) {
+        const pattern = trimmed.replace(/^Host\s+/i, "").trim();
+        inHostBlock = pattern === host || pattern === "*";
+        if (inHostBlock) hostConfig.push(trimmed);
+      } else if (inHostBlock && trimmed) {
+        hostConfig.push(trimmed);
+      } else if (inHostBlock && !trimmed) {
+        inHostBlock = false;
+      }
+    }
+    if (hostConfig.length === 0) {
+      return { status: "ok", message: `No SSH config entry for "${host}" (using defaults)` };
+    }
+    return { status: "ok", message: `SSH config for "${host}":
+${hostConfig.join("\n")}` };
+  } catch {
+    return { status: "warning", message: "Could not read ~/.ssh/config" };
+  }
+}
+function diagnose(host, port = 22) {
+  const checks = [];
+  const suggestions = [];
+  const agent = checkSshAgent();
+  checks.push({ name: "SSH Agent", ...agent });
+  if (agent.status === "error") suggestions.push('Start ssh-agent: eval "$(ssh-agent -s)"');
+  if (agent.status === "warning") suggestions.push("Load your key: ssh-add ~/.ssh/id_ed25519");
+  const keys = checkSshKeys();
+  checks.push({ name: "SSH Keys", ...keys });
+  if (keys.status === "error") suggestions.push('Generate a key: ssh-keygen -t ed25519 -C "your@email.com"');
+  const config = checkSshConfig(host);
+  checks.push({ name: "SSH Config", ...config });
+  const known = checkKnownHosts(host);
+  checks.push({ name: "Known Hosts", ...known });
+  if (known.status === "warning") suggestions.push(`Add host key: ssh-keyscan -H ${host} >> ~/.ssh/known_hosts`);
+  const conn = checkConnectivity(host, port);
+  checks.push({ name: "Connectivity", ...conn });
+  if (conn.status === "error" && conn.message.includes("Host key verification")) {
+    suggestions.push(`Remove stale host key: ssh-keygen -R ${host}`);
+    suggestions.push(`Re-add host key: ssh-keyscan -H ${host} >> ~/.ssh/known_hosts`);
+  }
+  if (conn.status === "error" && conn.message.includes("Permission denied")) {
+    suggestions.push("Check loaded keys: ssh-add -l");
+    suggestions.push("Verify correct username for this host");
+  }
+  const overall = checks.some((c) => c.status === "error") ? "error" : checks.some((c) => c.status === "warning") ? "warning" : "ok";
+  return { overall, checks, suggestions };
+}
+
+// src/ssh.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+import { Client } from "ssh2";
+function resolveConfig(config) {
+  const connectConfig = {
+    host: config.host,
+    port: config.port || 22,
+    username: config.username || process.env.USER || process.env.USERNAME || "root"
+  };
+  if (config.privateKeyPath) {
+    connectConfig.privateKey = readFileSync2(config.privateKeyPath);
+  } else if (config.password) {
+    connectConfig.password = config.password;
+  } else if (config.agent || process.env.SSH_AUTH_SOCK) {
+    connectConfig.agent = config.agent || process.env.SSH_AUTH_SOCK;
+  } else {
+    const home = homedir2();
+    const defaultKeys = ["id_ed25519", "id_rsa", "id_ecdsa"];
+    for (const keyName of defaultKeys) {
+      const keyPath = join2(home, ".ssh", keyName);
+      try {
+        connectConfig.privateKey = readFileSync2(keyPath);
+        break;
+      } catch {
+      }
+    }
+  }
+  return connectConfig;
+}
+function connect(config) {
+  return new Promise((resolve, reject) => {
+    const client = new Client();
+    const connectConfig = resolveConfig(config);
+    client.on("ready", () => resolve(client)).on("error", (err) => reject(err)).connect(connectConfig);
+  });
+}
+function exec(client, command, timeoutMs = 3e4) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`Command timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    client.exec(command, (err, stream) => {
+      if (err) {
+        clearTimeout(timer);
+        return reject(err);
+      }
+      let stdout = "";
+      let stderr = "";
+      stream.on("close", (code) => {
+        clearTimeout(timer);
+        resolve({ stdout, stderr, code: code ?? 0 });
+      }).on("data", (data) => {
+        stdout += data.toString();
+      }).stderr.on("data", (data) => {
+        stderr += data.toString();
+      });
+    });
+  });
+}
+function readFile(client, remotePath) {
+  return new Promise((resolve, reject) => {
+    client.sftp((err, sftp) => {
+      if (err) return reject(err);
+      sftp.readFile(remotePath, (err2, data) => {
+        if (err2) return reject(err2);
+        resolve(data.toString("utf8"));
+      });
+    });
+  });
+}
+function writeFile(client, remotePath, content) {
+  return new Promise((resolve, reject) => {
+    client.sftp((err, sftp) => {
+      if (err) return reject(err);
+      sftp.writeFile(remotePath, content, (err2) => {
+        if (err2) return reject(err2);
+        resolve();
+      });
+    });
+  });
+}
+function uploadFile(client, localPath, remotePath) {
+  return new Promise((resolve, reject) => {
+    client.sftp((err, sftp) => {
+      if (err) return reject(err);
+      sftp.fastPut(localPath, remotePath, (err2) => {
+        if (err2) return reject(err2);
+        resolve();
+      });
+    });
+  });
+}
+function downloadFile(client, remotePath, localPath) {
+  return new Promise((resolve, reject) => {
+    client.sftp((err, sftp) => {
+      if (err) return reject(err);
+      sftp.fastGet(remotePath, localPath, (err2) => {
+        if (err2) return reject(err2);
+        resolve();
+      });
+    });
+  });
+}
+function listDir(client, remotePath) {
+  return new Promise((resolve, reject) => {
+    client.sftp((err, sftp) => {
+      if (err) return reject(err);
+      sftp.readdir(remotePath, (err2, list) => {
+        if (err2) return reject(err2);
+        resolve(list.map((item) => item.filename));
+      });
+    });
+  });
+}
+
+// src/tools.ts
+var HostSchema = z.string().describe("SSH hostname or IP address");
+var PortSchema = z.number().optional().describe("SSH port (default: 22)");
+var UsernameSchema = z.string().optional().describe("SSH username (default: current user)");
+var KeyPathSchema = z.string().optional().describe("Path to SSH private key");
+var PasswordSchema = z.string().optional().describe("SSH password (prefer keys)");
+var TimeoutSchema = z.number().optional().describe("Command timeout in milliseconds (default: 30000)");
+var connectionParams = {
+  host: HostSchema,
+  port: PortSchema,
+  username: UsernameSchema,
+  privateKeyPath: KeyPathSchema,
+  password: PasswordSchema
+};
+function registerTools(server) {
+  server.tool(
+    "ssh_exec",
+    "Execute a command on a remote host via SSH. Returns stdout, stderr, and exit code.",
+    {
+      ...connectionParams,
+      command: z.string().describe("Shell command to execute on the remote host"),
+      timeout: TimeoutSchema
+    },
+    async ({ host, port, username, privateKeyPath, password, command, timeout }) => {
+      const client = await connect({ host, port, username, privateKeyPath, password });
+      try {
+        const result = await exec(client, command, timeout || 3e4);
+        const parts = [];
+        if (result.stdout) parts.push(result.stdout);
+        if (result.stderr) parts.push(`[stderr]
+${result.stderr}`);
+        parts.push(`[exit code: ${result.code}]`);
+        return { content: [{ type: "text", text: parts.join("\n") }] };
+      } finally {
+        client.end();
+      }
+    }
+  );
+  server.tool(
+    "ssh_read_file",
+    "Read a file from a remote host via SFTP.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path to the remote file")
+    },
+    async ({ host, port, username, privateKeyPath, password, path }) => {
+      const client = await connect({ host, port, username, privateKeyPath, password });
+      try {
+        const content = await readFile(client, path);
+        return { content: [{ type: "text", text: content }] };
+      } finally {
+        client.end();
+      }
+    }
+  );
+  server.tool(
+    "ssh_write_file",
+    "Write content to a file on a remote host via SFTP. Creates or overwrites the file.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path to the remote file"),
+      content: z.string().describe("File content to write")
+    },
+    async ({ host, port, username, privateKeyPath, password, path, content }) => {
+      const client = await connect({ host, port, username, privateKeyPath, password });
+      try {
+        await writeFile(client, path, content);
+        return { content: [{ type: "text", text: `Wrote ${content.length} bytes to ${path}` }] };
+      } finally {
+        client.end();
+      }
+    }
+  );
+  server.tool(
+    "ssh_upload",
+    "Upload a local file to a remote host via SFTP.",
+    {
+      ...connectionParams,
+      localPath: z.string().describe("Path to the local file to upload"),
+      remotePath: z.string().describe("Absolute path on the remote host")
+    },
+    async ({ host, port, username, privateKeyPath, password, localPath, remotePath }) => {
+      const client = await connect({ host, port, username, privateKeyPath, password });
+      try {
+        await uploadFile(client, localPath, remotePath);
+        return { content: [{ type: "text", text: `Uploaded ${localPath} \u2192 ${remotePath}` }] };
+      } finally {
+        client.end();
+      }
+    }
+  );
+  server.tool(
+    "ssh_download",
+    "Download a file from a remote host to local filesystem via SFTP.",
+    {
+      ...connectionParams,
+      remotePath: z.string().describe("Absolute path to the remote file"),
+      localPath: z.string().describe("Local path to save the downloaded file")
+    },
+    async ({ host, port, username, privateKeyPath, password, remotePath, localPath }) => {
+      const client = await connect({ host, port, username, privateKeyPath, password });
+      try {
+        await downloadFile(client, remotePath, localPath);
+        return { content: [{ type: "text", text: `Downloaded ${remotePath} \u2192 ${localPath}` }] };
+      } finally {
+        client.end();
+      }
+    }
+  );
+  server.tool(
+    "ssh_ls",
+    "List files in a directory on a remote host via SFTP.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path to the remote directory")
+    },
+    async ({ host, port, username, privateKeyPath, password, path }) => {
+      const client = await connect({ host, port, username, privateKeyPath, password });
+      try {
+        const files = await listDir(client, path);
+        return { content: [{ type: "text", text: files.join("\n") }] };
+      } finally {
+        client.end();
+      }
+    }
+  );
+  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.",
+    {
+      host: HostSchema,
+      port: PortSchema
+    },
+    async ({ host, port }) => {
+      const report = diagnose(host, port || 22);
+      const lines = [];
+      lines.push(`SSH Diagnostic Report for ${host}:${port || 22}`);
+      lines.push(`Overall: ${report.overall.toUpperCase()}`);
+      lines.push("");
+      for (const check of report.checks) {
+        const icon = check.status === "ok" ? "PASS" : check.status === "warning" ? "WARN" : "FAIL";
+        lines.push(`[${icon}] ${check.name}`);
+        lines.push(`  ${check.message}`);
+        lines.push("");
+      }
+      if (report.suggestions.length > 0) {
+        lines.push("Suggested fixes:");
+        for (const s of report.suggestions) {
+          lines.push(`  - ${s}`);
+        }
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/server.ts
+function createServer() {
+  const server = new McpServer({
+    name: "ssh-mcp",
+    version: "0.1.0"
+  });
+  registerTools(server);
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("ssh-mcp failed to start:", err);
+  process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,47 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from 'ssh2';
+
+declare function registerTools(server: McpServer): void;
+
+interface DiagnosticResult {
+    status: "ok" | "warning" | "error";
+    message: string;
+}
+interface DiagnosticReport {
+    overall: "ok" | "warning" | "error";
+    checks: Array<{
+        name: string;
+    } & DiagnosticResult>;
+    suggestions: string[];
+}
+declare function checkSshAgent(): DiagnosticResult;
+declare function checkSshKeys(): DiagnosticResult;
+declare function checkKnownHosts(host: string): DiagnosticResult;
+declare function checkConnectivity(host: string, port?: number): DiagnosticResult;
+declare function checkSshConfig(host: string): DiagnosticResult;
+declare function diagnose(host: string, port?: number): DiagnosticReport;
+
+interface SSHConfig {
+    host: string;
+    port?: number;
+    username?: string;
+    privateKeyPath?: string;
+    password?: string;
+    agent?: string;
+}
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+declare function connect(config: SSHConfig): Promise<Client>;
+declare function exec(client: Client, command: string, timeoutMs?: number): Promise<ExecResult>;
+declare function readFile(client: Client, remotePath: string): Promise<string>;
+declare function writeFile(client: Client, remotePath: string, content: string): Promise<void>;
+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[]>;
+
+declare function createServer(): McpServer;
+
+export { checkConnectivity, checkKnownHosts, checkSshAgent, checkSshConfig, checkSshKeys, connect, createServer, diagnose, downloadFile, exec, listDir, readFile, registerTools, uploadFile, writeFile };

package/dist/server.js

@@ -0,0 +1,496 @@
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools.ts
+import { z } from "zod";
+
+// src/diagnose.ts
+import { execSync } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+function run(cmd) {
+  try {
+    const stdout = execSync(cmd, { encoding: "utf8", timeout: 1e4, stdio: ["pipe", "pipe", "pipe"] });
+    return { stdout: stdout.trim(), ok: true };
+  } catch (e) {
+    return { stdout: e.stdout?.toString().trim() || e.message || "", ok: false };
+  }
+}
+function checkSshAgent() {
+  const sock = process.env.SSH_AUTH_SOCK;
+  if (!sock) {
+    return {
+      status: "error",
+      message: "SSH_AUTH_SOCK is not set. ssh-agent is not running or not exported to this shell."
+    };
+  }
+  const { stdout, ok } = run("ssh-add -l");
+  if (!ok && stdout.includes("Could not open a connection")) {
+    return {
+      status: "error",
+      message: `SSH_AUTH_SOCK is set to "${sock}" but the agent is not reachable. The agent process may have died. Run: eval "$(ssh-agent -s)"`
+    };
+  }
+  if (stdout.includes("The agent has no identities")) {
+    return {
+      status: "warning",
+      message: "ssh-agent is running but has no keys loaded. Run: ssh-add <key-path>"
+    };
+  }
+  return { status: "ok", message: `ssh-agent running with keys:
+${stdout}` };
+}
+function checkSshKeys() {
+  const home = homedir();
+  const sshDir = join(home, ".ssh");
+  if (!existsSync(sshDir)) {
+    return { status: "error", message: "~/.ssh directory does not exist. Run: mkdir -p ~/.ssh && chmod 700 ~/.ssh" };
+  }
+  const keyTypes = ["id_ed25519", "id_rsa", "id_ecdsa"];
+  const found = [];
+  for (const key of keyTypes) {
+    const keyPath = join(sshDir, key);
+    if (existsSync(keyPath)) {
+      found.push(key);
+    }
+  }
+  try {
+    const { stdout } = run(`ls "${sshDir}"`);
+    const allFiles = stdout.split("\n").filter((f) => !f.endsWith(".pub") && !["known_hosts", "config", "authorized_keys"].includes(f));
+    for (const f of allFiles) {
+      if (!keyTypes.includes(f) && existsSync(join(sshDir, f))) {
+        try {
+          const content = readFileSync(join(sshDir, f), "utf8");
+          if (content.includes("PRIVATE KEY")) {
+            found.push(f);
+          }
+        } catch {
+        }
+      }
+    }
+  } catch {
+  }
+  if (found.length === 0) {
+    return {
+      status: "error",
+      message: 'No SSH private keys found in ~/.ssh/. Generate one: ssh-keygen -t ed25519 -C "your@email.com"'
+    };
+  }
+  return { status: "ok", message: `Found SSH keys: ${found.join(", ")}` };
+}
+function checkKnownHosts(host) {
+  const knownHostsPath = join(homedir(), ".ssh", "known_hosts");
+  if (!existsSync(knownHostsPath)) {
+    return {
+      status: "warning",
+      message: "~/.ssh/known_hosts does not exist. First connection to any host will prompt for verification."
+    };
+  }
+  const { stdout, ok } = run(`ssh-keygen -F "${host}"`);
+  if (!ok || !stdout.trim()) {
+    return {
+      status: "warning",
+      message: `Host "${host}" is not in known_hosts. First connection will prompt for host key verification. To add it: ssh-keyscan -H ${host} >> ~/.ssh/known_hosts`
+    };
+  }
+  return { status: "ok", message: `Host "${host}" found in known_hosts` };
+}
+function checkConnectivity(host, port = 22) {
+  const { ok, stdout } = run(
+    `ssh -o ConnectTimeout=5 -o BatchMode=yes -o StrictHostKeyChecking=no -p ${port} ${host} echo SSH_OK 2>&1`
+  );
+  if (ok && stdout.includes("SSH_OK")) {
+    return { status: "ok", message: `SSH connection to ${host}:${port} succeeded` };
+  }
+  if (stdout.includes("Permission denied")) {
+    return {
+      status: "error",
+      message: `Permission denied connecting to ${host}:${port}. Your key is not authorized on this host. Check: 1) correct key is loaded (ssh-add -l), 2) key is in remote authorized_keys, 3) correct username.`
+    };
+  }
+  if (stdout.includes("Connection refused")) {
+    return {
+      status: "error",
+      message: `Connection refused at ${host}:${port}. SSH server is not running on this port or host is blocking connections.`
+    };
+  }
+  if (stdout.includes("Connection timed out") || stdout.includes("timed out")) {
+    return {
+      status: "error",
+      message: `Connection timed out to ${host}:${port}. Host may be down, port may be blocked by firewall, or DNS resolution failed.`
+    };
+  }
+  if (stdout.includes("Host key verification failed")) {
+    return {
+      status: "error",
+      message: `Host key verification failed for ${host}. The host key changed (instance recreated?). Fix: ssh-keygen -R ${host} && ssh-keyscan -H ${host} >> ~/.ssh/known_hosts`
+    };
+  }
+  if (stdout.includes("Could not resolve hostname")) {
+    return {
+      status: "error",
+      message: `Could not resolve hostname "${host}". Check DNS, /etc/hosts, or SSH config aliases.`
+    };
+  }
+  return { status: "error", message: `SSH connection failed: ${stdout}` };
+}
+function checkSshConfig(host) {
+  const configPath = join(homedir(), ".ssh", "config");
+  if (!existsSync(configPath)) {
+    return { status: "ok", message: "No ~/.ssh/config file (using defaults)" };
+  }
+  try {
+    const content = readFileSync(configPath, "utf8");
+    const lines = content.split("\n");
+    let inHostBlock = false;
+    const hostConfig = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (/^Host\s+/i.test(trimmed)) {
+        const pattern = trimmed.replace(/^Host\s+/i, "").trim();
+        inHostBlock = pattern === host || pattern === "*";
+        if (inHostBlock) hostConfig.push(trimmed);
+      } else if (inHostBlock && trimmed) {
+        hostConfig.push(trimmed);
+      } else if (inHostBlock && !trimmed) {
+        inHostBlock = false;
+      }
+    }
+    if (hostConfig.length === 0) {
+      return { status: "ok", message: `No SSH config entry for "${host}" (using defaults)` };
+    }
+    return { status: "ok", message: `SSH config for "${host}":
+${hostConfig.join("\n")}` };
+  } catch {
+    return { status: "warning", message: "Could not read ~/.ssh/config" };
+  }
+}
+function diagnose(host, port = 22) {
+  const checks = [];
+  const suggestions = [];
+  const agent = checkSshAgent();
+  checks.push({ name: "SSH Agent", ...agent });
+  if (agent.status === "error") suggestions.push('Start ssh-agent: eval "$(ssh-agent -s)"');
+  if (agent.status === "warning") suggestions.push("Load your key: ssh-add ~/.ssh/id_ed25519");
+  const keys = checkSshKeys();
+  checks.push({ name: "SSH Keys", ...keys });
+  if (keys.status === "error") suggestions.push('Generate a key: ssh-keygen -t ed25519 -C "your@email.com"');
+  const config = checkSshConfig(host);
+  checks.push({ name: "SSH Config", ...config });
+  const known = checkKnownHosts(host);
+  checks.push({ name: "Known Hosts", ...known });
+  if (known.status === "warning") suggestions.push(`Add host key: ssh-keyscan -H ${host} >> ~/.ssh/known_hosts`);
+  const conn = checkConnectivity(host, port);
+  checks.push({ name: "Connectivity", ...conn });
+  if (conn.status === "error" && conn.message.includes("Host key verification")) {
+    suggestions.push(`Remove stale host key: ssh-keygen -R ${host}`);
+    suggestions.push(`Re-add host key: ssh-keyscan -H ${host} >> ~/.ssh/known_hosts`);
+  }
+  if (conn.status === "error" && conn.message.includes("Permission denied")) {
+    suggestions.push("Check loaded keys: ssh-add -l");
+    suggestions.push("Verify correct username for this host");
+  }
+  const overall = checks.some((c) => c.status === "error") ? "error" : checks.some((c) => c.status === "warning") ? "warning" : "ok";
+  return { overall, checks, suggestions };
+}
+
+// src/ssh.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+import { Client } from "ssh2";
+function resolveConfig(config) {
+  const connectConfig = {
+    host: config.host,
+    port: config.port || 22,
+    username: config.username || process.env.USER || process.env.USERNAME || "root"
+  };
+  if (config.privateKeyPath) {
+    connectConfig.privateKey = readFileSync2(config.privateKeyPath);
+  } else if (config.password) {
+    connectConfig.password = config.password;
+  } else if (config.agent || process.env.SSH_AUTH_SOCK) {
+    connectConfig.agent = config.agent || process.env.SSH_AUTH_SOCK;
+  } else {
+    const home = homedir2();
+    const defaultKeys = ["id_ed25519", "id_rsa", "id_ecdsa"];
+    for (const keyName of defaultKeys) {
+      const keyPath = join2(home, ".ssh", keyName);
+      try {
+        connectConfig.privateKey = readFileSync2(keyPath);
+        break;
+      } catch {
+      }
+    }
+  }
+  return connectConfig;
+}
+function connect(config) {
+  return new Promise((resolve, reject) => {
+    const client = new Client();
+    const connectConfig = resolveConfig(config);
+    client.on("ready", () => resolve(client)).on("error", (err) => reject(err)).connect(connectConfig);
+  });
+}
+function exec(client, command, timeoutMs = 3e4) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`Command timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    client.exec(command, (err, stream) => {
+      if (err) {
+        clearTimeout(timer);
+        return reject(err);
+      }
+      let stdout = "";
+      let stderr = "";
+      stream.on("close", (code) => {
+        clearTimeout(timer);
+        resolve({ stdout, stderr, code: code ?? 0 });
+      }).on("data", (data) => {
+        stdout += data.toString();
+      }).stderr.on("data", (data) => {
+        stderr += data.toString();
+      });
+    });
+  });
+}
+function readFile(client, remotePath) {
+  return new Promise((resolve, reject) => {
+    client.sftp((err, sftp) => {
+      if (err) return reject(err);
+      sftp.readFile(remotePath, (err2, data) => {
+        if (err2) return reject(err2);
+        resolve(data.toString("utf8"));
+      });
+    });
+  });
+}
+function writeFile(client, remotePath, content) {
+  return new Promise((resolve, reject) => {
+    client.sftp((err, sftp) => {
+      if (err) return reject(err);
+      sftp.writeFile(remotePath, content, (err2) => {
+        if (err2) return reject(err2);
+        resolve();
+      });
+    });
+  });
+}
+function uploadFile(client, localPath, remotePath) {
+  return new Promise((resolve, reject) => {
+    client.sftp((err, sftp) => {
+      if (err) return reject(err);
+      sftp.fastPut(localPath, remotePath, (err2) => {
+        if (err2) return reject(err2);
+        resolve();
+      });
+    });
+  });
+}
+function downloadFile(client, remotePath, localPath) {
+  return new Promise((resolve, reject) => {
+    client.sftp((err, sftp) => {
+      if (err) return reject(err);
+      sftp.fastGet(remotePath, localPath, (err2) => {
+        if (err2) return reject(err2);
+        resolve();
+      });
+    });
+  });
+}
+function listDir(client, remotePath) {
+  return new Promise((resolve, reject) => {
+    client.sftp((err, sftp) => {
+      if (err) return reject(err);
+      sftp.readdir(remotePath, (err2, list) => {
+        if (err2) return reject(err2);
+        resolve(list.map((item) => item.filename));
+      });
+    });
+  });
+}
+
+// src/tools.ts
+var HostSchema = z.string().describe("SSH hostname or IP address");
+var PortSchema = z.number().optional().describe("SSH port (default: 22)");
+var UsernameSchema = z.string().optional().describe("SSH username (default: current user)");
+var KeyPathSchema = z.string().optional().describe("Path to SSH private key");
+var PasswordSchema = z.string().optional().describe("SSH password (prefer keys)");
+var TimeoutSchema = z.number().optional().describe("Command timeout in milliseconds (default: 30000)");
+var connectionParams = {
+  host: HostSchema,
+  port: PortSchema,
+  username: UsernameSchema,
+  privateKeyPath: KeyPathSchema,
+  password: PasswordSchema
+};
+function registerTools(server) {
+  server.tool(
+    "ssh_exec",
+    "Execute a command on a remote host via SSH. Returns stdout, stderr, and exit code.",
+    {
+      ...connectionParams,
+      command: z.string().describe("Shell command to execute on the remote host"),
+      timeout: TimeoutSchema
+    },
+    async ({ host, port, username, privateKeyPath, password, command, timeout }) => {
+      const client = await connect({ host, port, username, privateKeyPath, password });
+      try {
+        const result = await exec(client, command, timeout || 3e4);
+        const parts = [];
+        if (result.stdout) parts.push(result.stdout);
+        if (result.stderr) parts.push(`[stderr]
+${result.stderr}`);
+        parts.push(`[exit code: ${result.code}]`);
+        return { content: [{ type: "text", text: parts.join("\n") }] };
+      } finally {
+        client.end();
+      }
+    }
+  );
+  server.tool(
+    "ssh_read_file",
+    "Read a file from a remote host via SFTP.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path to the remote file")
+    },
+    async ({ host, port, username, privateKeyPath, password, path }) => {
+      const client = await connect({ host, port, username, privateKeyPath, password });
+      try {
+        const content = await readFile(client, path);
+        return { content: [{ type: "text", text: content }] };
+      } finally {
+        client.end();
+      }
+    }
+  );
+  server.tool(
+    "ssh_write_file",
+    "Write content to a file on a remote host via SFTP. Creates or overwrites the file.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path to the remote file"),
+      content: z.string().describe("File content to write")
+    },
+    async ({ host, port, username, privateKeyPath, password, path, content }) => {
+      const client = await connect({ host, port, username, privateKeyPath, password });
+      try {
+        await writeFile(client, path, content);
+        return { content: [{ type: "text", text: `Wrote ${content.length} bytes to ${path}` }] };
+      } finally {
+        client.end();
+      }
+    }
+  );
+  server.tool(
+    "ssh_upload",
+    "Upload a local file to a remote host via SFTP.",
+    {
+      ...connectionParams,
+      localPath: z.string().describe("Path to the local file to upload"),
+      remotePath: z.string().describe("Absolute path on the remote host")
+    },
+    async ({ host, port, username, privateKeyPath, password, localPath, remotePath }) => {
+      const client = await connect({ host, port, username, privateKeyPath, password });
+      try {
+        await uploadFile(client, localPath, remotePath);
+        return { content: [{ type: "text", text: `Uploaded ${localPath} \u2192 ${remotePath}` }] };
+      } finally {
+        client.end();
+      }
+    }
+  );
+  server.tool(
+    "ssh_download",
+    "Download a file from a remote host to local filesystem via SFTP.",
+    {
+      ...connectionParams,
+      remotePath: z.string().describe("Absolute path to the remote file"),
+      localPath: z.string().describe("Local path to save the downloaded file")
+    },
+    async ({ host, port, username, privateKeyPath, password, remotePath, localPath }) => {
+      const client = await connect({ host, port, username, privateKeyPath, password });
+      try {
+        await downloadFile(client, remotePath, localPath);
+        return { content: [{ type: "text", text: `Downloaded ${remotePath} \u2192 ${localPath}` }] };
+      } finally {
+        client.end();
+      }
+    }
+  );
+  server.tool(
+    "ssh_ls",
+    "List files in a directory on a remote host via SFTP.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path to the remote directory")
+    },
+    async ({ host, port, username, privateKeyPath, password, path }) => {
+      const client = await connect({ host, port, username, privateKeyPath, password });
+      try {
+        const files = await listDir(client, path);
+        return { content: [{ type: "text", text: files.join("\n") }] };
+      } finally {
+        client.end();
+      }
+    }
+  );
+  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.",
+    {
+      host: HostSchema,
+      port: PortSchema
+    },
+    async ({ host, port }) => {
+      const report = diagnose(host, port || 22);
+      const lines = [];
+      lines.push(`SSH Diagnostic Report for ${host}:${port || 22}`);
+      lines.push(`Overall: ${report.overall.toUpperCase()}`);
+      lines.push("");
+      for (const check of report.checks) {
+        const icon = check.status === "ok" ? "PASS" : check.status === "warning" ? "WARN" : "FAIL";
+        lines.push(`[${icon}] ${check.name}`);
+        lines.push(`  ${check.message}`);
+        lines.push("");
+      }
+      if (report.suggestions.length > 0) {
+        lines.push("Suggested fixes:");
+        for (const s of report.suggestions) {
+          lines.push(`  - ${s}`);
+        }
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/server.ts
+function createServer() {
+  const server = new McpServer({
+    name: "ssh-mcp",
+    version: "0.1.0"
+  });
+  registerTools(server);
+  return server;
+}
+export {
+  checkConnectivity,
+  checkKnownHosts,
+  checkSshAgent,
+  checkSshConfig,
+  checkSshKeys,
+  connect,
+  createServer,
+  diagnose,
+  downloadFile,
+  exec,
+  listDir,
+  readFile,
+  registerTools,
+  uploadFile,
+  writeFile
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@yawlabs/ssh-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for SSH operations with built-in diagnostics",
+  "type": "module",
+  "bin": {
+    "ssh-mcp": "dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/server.js",
+      "types": "./dist/server.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:ci": "npm run build && npm test",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "ssh",
+    "remote",
+    "model-context-protocol",
+    "ai",
+    "devops"
+  ],
+  "author": "Yaw Labs <contact@yaw.sh>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YawLabs/ssh-mcp.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ssh2": "^1.16.0",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.15.2",
+    "@types/ssh2": "^1.15.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}