ssh-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP (Model Context Protocol) server for SSH remote server administration. Enables AI models to manage remote servers over SSH — executing commands, transferring files via SFTP, and reading/writing remote files. Documentation is in Spanish.

Commands

npm run build      # Compile TypeScript → dist/
npm start          # Run MCP server (dist/index.js)

No test or lint commands are configured yet.

Architecture

Single-class MCP server (SSHMCPServer in src/index.ts) that manages one SSH connection at a time via the ssh2 library.

Source Files

• src/index.ts — Main server class. Handles MCP tool dispatch, SSH/SFTP connection lifecycle, command execution, interactive exec (PTY + auto-response), persistent shell sessions, and file operations. All tool handlers are methods on SSHMCPServer. Version is read dynamically from package.json.
• src/tools.ts — MCP tool definitions (name, description, JSON Schema). 17 tools: ssh_list_profiles, ssh_connect, ssh_disconnect, ssh_status, ssh_exec, ssh_exec_interactive, ssh_shell_start, ssh_shell_send (includes sensitive flag), ssh_shell_read, ssh_shell_close, ssh_upload, ssh_download, ssh_ls, ssh_read_file, ssh_write_file, ssh_history, ssh_undo.
• src/profiles.ts — Loads and validates SSH profiles from profiles.json at startup (not on first use). Validates required fields (host, port, username, privateKeyPath, hostFingerprint), verifies the key file is readable, and caches private keys in memory. Never exposes private keys or passphrases in responses.
• src/security.ts — Dangerous command detection (regex patterns) and AuditLogger. Uses WriteStream for non-blocking writes with 0o600 permissions (enforced via chmodSync on existing files). Common secret patterns (password=, token=, Bearer) are redacted before writing.
• src/types.ts — TypeScript interfaces: SSHProfile (includes hostFingerprint, localSandboxDir), AuditEntry, PromptResponse, ShellSession, CommandRecord, ReverseInfo.
• src/utils.ts — Pure utility functions: formatUptime, padRight, escapeShellArg, stripAnsi.
• src/validation.ts — Input validation helpers: requireString, optionalString, optionalBoolean, optionalNumber, clampTimeout (bounds: 1s–5min).