CLAUDE.md · bvisible/mcp-ssh-manager

Sections

1. Project Overview
2. Architecture
3. Commands
4. MCP Tools Available
5. Server Configuration
6. Key Implementation Details
7. Security Considerations
8. Validation and Quality
9. Claude Code Integration

First lines (shown under the repo's MIT license)

# CLAUDE.md

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

## Project Overview

MCP SSH Manager is a Model Context Protocol server that enables Claude Code to manage multiple SSH connections. It provides tools for executing commands, transferring files, and managing deployments across remote servers.

## Architecture

The system consists of three main components:

1. **MCP Server** (`src/index.js`): Node.js-based MCP server using the Model Context Protocol SDK
   - Handles SSH connections via node-ssh library
   - Manages connection pooling to avoid reconnecting
   - Provides MCP tools for Claude Code integration

2. **Server Management** (`tools/server_manager.py`): Python CLI for configuration
   - Manages `.env` file with server configurations
   - Tests connections using Paramiko
   - Configures Claude Code integration

3. **Deployment Helpers** (`src/deploy-helper.js`, `src/server-aliases.js`): Advanced features
   - Automated deployment strategies with permission handling
   - Server alias management for simplified access
   - Batch deployment scripts generation

## Commands

### Setup and Installation
```bash
npm install                                    # Install Node.js dependencies
./scripts/setup-hooks.sh                      # Setup pre-commit hooks for development
```

### Server Management (Bash CLI)
```bash
ssh-manager server add                        # Add a new server
ssh-manager server list                       # List configured servers
ssh-manager server test SERVER                # Test connection to specific server
ssh-manager server remove SERVER              # Remove a server
ssh-manager server show SERVER                # Show server details
```

### OpenAI Codex Integration
```bash
ssh-manager codex setup                       # Configure for Codex
ssh-manager codex migrate                     # Convert servers to TOML
ssh-manager codex test                        # Test Codex integration
ssh-manager codex convert to-toml            # Convert .env to TOML
ssh-manager codex convert to-env             # Convert TOML to .env
```

### Tool Management (NEW in v3.1)
```bash
ssh-manager tools list                        # Show all tools and status
ssh-manager tools configure                   # Interactive configuration wizard
ssh-manager tools enable <group>              # Enable a tool group
ssh-manager tools disable <group>             # Disable a tool group
ssh-manager tools reset                       # Reset to defaults (all tools)
ssh-manager tools export-claude               # Export auto-approval config
```

**Tool Groups**: core (5), sessions (4), monitoring (6), backup (4), database (4), advanced (14)

**Modes**: all (37 tools, ~43.5k tokens), minimal (5 tools, ~3.5k tokens), custom (variable)

See [docs/TOOL_MANAGEMENT.md](docs/TOOL_MANAGEMENT.md) for complete guide.

### Development and Testing
```bash
npm ci                                        # Install the exact tree from package-lock.json
npm start                                     # Start MCP server (requires stdin)
npm test                                      # Run the full test suite
npm run typecheck                             # Type-check JSDoc with tsc (no build, nothing emitted)
npm run build:ui                              # Build the interface (ui/) into dist/ui: generated, git-ignored, run by `prepack`;
                                              # needed before `ssh-manager control` from a checkout and before the browser tests
npm run test:all                              # Tests + typecheck + validation
./scripts/validate.sh                        # Run all validation checks
node --check src/index.js                   # Check JavaScript syntax
python -m py_compile tools/*.py             # Check Python syntax
```

**Typecheck**: `tsconfig.json` runs TypeScript in `checkJs`/`noEmit` mode over the plain JS —
this project ships JavaScript straight from `src/` with no build step, and that must stay true.
The interface is the one generated thing: `dist/ui` is built from `ui/` when the package is packed and when the desktop
app is assembled, never committed (`scripts/build-interface.mjs`; CI fails if `dist/` is tracked).
The baseline is 0 errors and CI enforces it, so add JSDoc annotations (or a narrow
`/** @type {...} */` cast) rather than leaving new errors. `typescript` is pinned to `^6`
because knip 5 declares `peer typescript ">=5.0.4 <7"` — bumping one requires bumping the other.

**Lockfile**: `package-lock.json` is committed and CI installs with `npm ci`, so the tree is
reproducible and auditable. npm never ships a lockfile inside a published tarball, so this is
invisible to consumers of the package. Two consequences for maintainers:

- **Releases bump three version spots, not one**: `package.json`, `package-lock.json`
  (`.version` *and* `.packages[""].version`) and the README badge. `npm version <x.y.z>` does
  the first two together; a hand edit does not. `npm run test:lockfile` fails when they diverge,
  and so does `npm ci`.
- **Dependency changes must commit the regenerated lockfile.** After editing `package.json` by
  hand, run `npm install --package-lock-only` and commit both files.

`tests/test-lockfile.js` guards the rest: every package resolves to registry.npmjs.org with an
integrity hash, no `file:`/`git+`/`link:` entries, install scripts limited to a reviewed
allowlist (`ssh2`, `cpu-features`), and no runtime dependency requiring a newer Node than
`engines.node` advertises — that last check carries one documented exception,
`@hono/node-server` (needs Node >=20, pulled by the MCP SDK for its HTTP transport, never
imported by the stdio server we ship; re-check it when bumping the SDK).

**Required status checks on `main`** are `lint`, `test (18.x)` and `test (20.x)`. Renaming those
jobs or dropping a matrix entry makes `main` unmergeable until branch protection is updated.

### Debug Tools (in `debug/` directory)
```bash
./debug/test-claude-code.sh                 # Test Claude Code integration
node debug/test-mcp.js                      # Test MCP connection
node debug/test-ssh-command.js              # Test SSH command execution
python debug/test_basic.py                  # Basic Python tests
python debug/test_fastmcp.py                # FastMCP integration test
```

## MCP Tools Available

The server exposes these tools to Claude Code and OpenAI Codex:

### Core Tools
- `ssh_list_servers`: List all configured SSH servers
- `ssh_execute`: Execute commands on remote servers (supports default directories)
- `ssh_upload`: Upload files to remote servers
- `ssh_download`: Download files from remote servers

### Backup & Restore (v2.1+)
- `ssh_backup_create`: Create database or file backups (MySQL, PostgreSQL, MongoDB, Files)
- `ssh_backup_list`: List all available backups with metadata
- `ssh_backup_restore`: Restore from previous backups
- `ssh_backup_schedule`: Schedule automatic backups using cron

### Health & Monitoring (v2.2+)
- `ssh_health_check`: Comprehensive server health check (CPU, RAM, Disk, Network)
- `ssh_service_status`: Check status of services (nginx, mysql, docker, etc.)
- `ssh_process_manager`: List, monitor, or kill processes
- `ssh_alert_setup`: Configure health monitoring alerts and thresholds

### Database Management (v2.3+)
- `ssh_db_dump`: Create database dumps (MySQL, PostgreSQL, MongoDB)
- `ssh_db_import`: Import SQL dumps or restore databases
- `ssh_db_list`: List databases or tables/collections
- `ssh_db_query`: Execute read-only SELECT queries (security validated)

### Deployment & Management
- `ssh_deploy`: Deploy files with automatic permission/backup handling
- `ssh_execute_sudo`: Execute commands with sudo privileges
- `ssh_alias`: Manage server aliases (add/remove/list)
- `ssh_sync`: Bidirectional file synchronization with rsync
- `ssh_monitor`: System resource monitoring
- `ssh_tail`: Real-time log monitoring

### Advanced Features
- `ssh_session_*`: Persistent SSH sessions
- `ssh_tunnel_*`: SSH tunnel management (local/remote/SOCKS)