remote-server-mcp: Instructions file for Codex

Remote Server MCP — Agent Instructions

Project Overview

remote-server-mcp is a security-first MCP (Model Context Protocol) server for managing remote servers via SSH. It provides AI assistants with controlled, safe operations for debugging services without exposing credentials or allowing dangerous commands.

This is a thin MCP server layer built on top of server-management-lib (a separate library that provides security validation, SSH management, and HTTP clients for InfluxDB/Prometheus).

Architecture

src/remote_server_mcp/          # This project
├── server.py                   # MCP server (13 tools)
└── __init__.py                 # Entry point

server-management-lib           # External dependency (GitHub)
├── security.py                 # SecurityValidator
├── ssh_manager.py              # SSHManager
├── http_clients.py             # InfluxDBClient, PrometheusClient
└── config.py                   # load_config, DEFAULT_CONFIG

Development Workflow

Quick Start

# Install with dev dependencies
uv sync --all-extras

# Install pre-commit hooks
pre-commit install

Development Commands

# Run all tests
uv run pytest tests/ -v

# Security tests only
uv run pytest tests/test_security.py tests/test_security_bypass.py -v

# Database tests (unit + live integration tests)
uv run pytest tests/test_database_tools.py -v
uv run pytest tests/test_database_tools.py -v -k live   # live tests only

# Linting
uv run ruff check .

# Fix linting issues
uv run ruff check --fix .

# Format code
uv run ruff format .

# Type checking
uv run ty check

# Run all checks (what pre-commit does)
env -u VIRTUAL_ENV pre-commit run --all-files

Pre-commit Hooks

Pre-commit hooks run automatically on git commit:

• ruff: Linting and formatting
• ty: Type checking
• pytest: Run all tests
• pymarkdown: Markdown style/formatting
• check-md-links: Markdown link validation

Run manually:

env -u VIRTUAL_ENV pre-commit run --all-files