SSH MCP Server

Instructions

Implementation Reference

• src/index.ts:318-369 (handler)

  The handler function for the 'create_connection' tool. It validates inputs, finds the machine config, creates an SSH client, connects, retrieves the initial working directory, stores the connection in the global 'connections' map, and returns the connection details.

  if (name === "create_connection") {
    const { machine_id, title } = args as { machine_id: string; title: string };
  
    if (!machine_id || !title)
      throw new Error("Both machine_id and title are required.");
  
    const machine = findMachine(machine_id);
    if (!machine) throw new Error(`Unknown machine_id '${machine_id}'.`);
  
    const client = new SSHClient();
    const connection_id = crypto.randomUUID();
  
    return new Promise((resolve, reject) => {
      client
        .on("ready", async () => {
          try {
            const { stdout } = await wrapExec(client, "pwd");
            const connInfo = {
              connection_id,
              machine_id,
              title,
              currentPath: stdout.trim(),
              client,
            };
            connections.set(connection_id, connInfo);
  
            resolve({
              content: [
                {
                  type: "text",
                  text: JSON.stringify(
                    {
                      connection_id,
                      machine_id,
                      title,
                      currentPath: connInfo.currentPath,
                    },
                    null,
                    2
                  ),
                },
              ],
            });
          } catch (e) {
            client.end();
            reject(e);
          }
        })
        .on("error", (err) => reject(err))
        .connect(buildSshConfig(machine));
    });
  }

• src/index.ts:148-161 (schema)

  Input schema definition for the 'create_connection' tool, specifying required 'machine_id' and 'title' parameters.

  {
    name: "create_connection",
    description:
      "Open an SSH session to the given machine and track it in global state so subsequent tool calls can reuse it.",
    inputSchema: {
      type: "object",
      required: ["machine_id", "title"],
      properties: {
        machine_id: { type: "string", description: "ID from get_available_connections" },
        title: { type: "string", description: "Purpose of this session (displayed in UIs)" },
      },
      additionalProperties: false,
    },
  },

• src/index.ts:140-207 (registration)

  Registers the 'create_connection' tool (among others) by including it in the ListTools response.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: "get_available_connections",
        description:
          "List every SSH-capable machine this server knows about (but is NOT yet connected).",
        inputSchema: { type: "object", properties: {}, additionalProperties: false },
      },
      {
        name: "create_connection",
        description:
          "Open an SSH session to the given machine and track it in global state so subsequent tool calls can reuse it.",
        inputSchema: {
          type: "object",
          required: ["machine_id", "title"],
          properties: {
            machine_id: { type: "string", description: "ID from get_available_connections" },
            title: { type: "string", description: "Purpose of this session (displayed in UIs)" },
          },
          additionalProperties: false,
        },
      },
      {
        name: "get_connections",
        description: "Return every STILL-OPEN SSH session in global state.",
        inputSchema: { type: "object", properties: {}, additionalProperties: false },
      },
      {
        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,
        },
      },
      {
        name: "secure_execute_command",
        description:
          "Run a **read‑only** shell command (i.e., one that does not mutate state) 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: "Read‑only shell command to execute (e.g., ls, cat)." },
          },
          additionalProperties: false,
        },
      },
  
      {
        name: "close_connection",
        description: "Terminate an SSH session and remove it from global state.",
        inputSchema: {
          type: "object",
          required: ["connection_id"],
          properties: { connection_id: { type: "string" } },
          additionalProperties: false,
        },
      },
    ],
  }));

• src/index.ts:75-77 (helper)

  Helper function used by create_connection to locate the machine configuration by ID.

  function findMachine(machine_id) {
    return availableMachines.find((m) => m.machine_id === machine_id);
  }

• src/index.ts:79-90 (helper)

  Helper function used by create_connection to construct the SSH configuration object.

  function buildSshConfig(m) {
    const cfg: any = {
      host: m.ssh.host,
      port: m.ssh.port,
      username: m.ssh.username,
    };
    if (m.ssh.password) cfg.password = m.ssh.password;
    if (m.ssh.keyPath) {
      // Lazy‑load fs so we don’t pay the I/O cost unless needed
      cfg.privateKey = readFileSync(m.ssh.keyPath, "utf8");
    }
    return cfg;