ssh-mcp: Instructions file for Codex

AGENTS.md — AI Development Guide for mcp-ssh

Contents:

• Project Overview · Project Layout · Plans & CI
• Testing · Development Workflow
• Coding Conventions · Authorization Model
• Definition of Done · Dependency Management
• Docker / Deployment · Security
• Adding a Tool · File-Touch Checklist

Project Overview

mcp-ssh is a Model Context Protocol server exposing SSH command execution and SFTP file transfer as MCP tools. Runs as Docker behind Traefik, speaking streamable HTTP on port 8080 at /mcp.

Stack: Python 3.13, FastMCP 3.4.x, paramiko 5.0, Starlette 1.4, Prometheus client, watchdog

Six tools: ssh_list_servers, ssh_list_allowed_commands, ssh_execute_command, ssh_check_connection, ssh_download_file, ssh_upload_file — see README.md.

Key patterns: App-factory (create_app(), zero I/O at import), closure DI for tools, thread-pool for SSH I/O, per-target connection pooling, layered auth chain, config hot-reload (15 s poll / 2 s debounce), circuit breaker + exponential-backoff, sliding-window rate limiter, JSONL logging with rotation/gzip.

Project Layout

mcp-ssh/
├── server.py                  # FastMCP app factory + CLI entry point
├── lib/                       # 25 modules (plus __init__.py re-exports)
│   ├── auth.py                # AuthorizationManager, layered allow-list chain
│   ├── circuit_breaker.py     # Per-target failure threshold + recovery timeout
│   ├── command_security.py    # Command segmentation, dangerous-pattern detection, redirector stripping
│   ├── config.py              # ConfigManager — JSON load/validate/hot-reload
│   ├── config_migration.py    # Config schema migration (v1→v2)
│   ├── config_watcher.py      # Filesystem watcher (polling or watchdog)
│   ├── connection_pool.py     # Per-target SSH connection pooling
│   ├── constants.py           # ALL magic numbers, strings, defaults (single source of truth)
│   ├── crypto.py              # PBKDF2-HMAC-SHA256 API-key hashing + constant-time verify
│   ├── exceptions.py          # MCPSSHError hierarchy
│   ├── file_transfer.py       # SFTP download/upload with 7-layer path validation
│   ├── health.py              # GET /health endpoint
│   ├── log_handler.py         # JSONLHandler — stdlib logging → FileLogger bridge
│   ├── loggers.py             # FileLogger (JSONL rotation/truncation/gzip)
│   ├── metrics.py             # Prometheus metrics + GET /metrics endpoint
│   ├── rate_limiter.py        # Sliding-window per-IP rate limiter
│   ├── redos_protection.py    # Safe regex compilation and ReDoS-resistant matching
│   ├── request_context.py     # Starlette middleware: request_id, client IP, API key
│   ├── sanitize.py            # Input sanitization helpers
│   ├── secrets.py             # SecretsManager for secrets.json + env var merging
│   ├── size_utils.py          # parse_size_bytes() for size-string settings
│   ├── ssh_client.py          # SSHClientManager — connect, retry, circuit-break, pool
│   ├── ssh_operations.py      # Standalone SSH functions (check, connect, execute)
│   ├── sudo.py                # SudoHandler — validate, wrap sudo command, password injection
│   └── types.py               # TypedDict models for tool results
├── config-api/                 # Config API + Web Dashboard (GUI)
│   ├── config_api/app.py, auth.py, config_service.py, models.py, routes.py
│   └── config_api/ui/index.html  # SPA dashboard (Tailwind CSS)
├── tests/
│   ├── test_*.py              # 29 unit-test files
│   └── integration/test_mcp_ssh_integration.py  # Real Docker containers
├── docs/SECURITY.md           # Full security model
├── Dockerfile, compose.yaml, Makefile
├── requirements{,-build,-dev}.{in,txt}
├── default-config.json, config.schema.json
└── README.md