SSH MCP Server

Instructions

Implementation Reference

• src/index.ts:394-418 (handler)

  Main handler logic for the execute_command tool. Validates inputs, executes the command on the SSH connection using wrapExec helper, updates currentPath for cd commands, and returns structured output with stdout, stderr, and exitCode.

  // execute_command
  if (name === "execute_command") {
    const { connection_id, command } = args as { connection_id: string; command: string };
    if (!command?.trim()) throw new Error("Command cannot be empty.");
  
    const conn = connections.get(connection_id);
    if (!conn) throw new Error(`connection_id '${connection_id}' not found.`);
  
    const { stdout, stderr, exitCode } = await wrapExec(conn.client, command);
  
    // update PWD if the agent just cd’d somewhere
    if (/^cd\\s+/.test(command.trim())) {
      const { stdout: cwd } = await wrapExec(conn.client, "pwd");
      conn.currentPath = cwd.trim();
    }
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({ stdout, stderr, exitCode }, null, 2),
        },
      ],
    };
  }

• src/index.ts:167-180 (registration)

  Registration of the execute_command tool within the ListTools handler, including name, description, and input schema definition.

  {
    name: "execute_command",
    description:
      "Run a shell command in an existing SSH session and return stdout/stderr/exitCode.",
    inputSchema: {
      type: "object",
      required: ["connection_id", "command"],
      properties: {
        connection_id: { type: "string" },
        command: { type: "string", description: "Shell command to execute" },
      },
      additionalProperties: false,
    },
  },

• src/index.ts:171-179 (schema)

  Input schema definition for the execute_command tool, specifying required connection_id and command parameters.

  inputSchema: {
    type: "object",
    required: ["connection_id", "command"],
    properties: {
      connection_id: { type: "string" },
      command: { type: "string", description: "Shell command to execute" },
    },
    additionalProperties: false,
  },

• src/index.ts:93-111 (helper)

  Supporting helper function used by the execute_command handler to wrap SSH client.exec, capturing stdout, stderr, and exit code in a Promise.

  function wrapExec(client, command): any {
    return new Promise((resolve, reject) => {
      let stdout = "";
      let stderr = "";
      client.exec(command, (err, stream) => {
        if (err) return reject(err);
        stream
          .on("close", (code) => {
            resolve({ stdout, stderr, exitCode: code });
          })
          .on("data", (data) => {
            stdout += data.toString();
          })
          .stderr.on("data", (data) => {
            stderr += data.toString();
          });
      });
    });
  }