linux-mcp-server: Instructions file for Codex

Linux MCP Server

MCP server for Linux system diagnostics. Two operating modes, selected by the LINUX_MCP_TOOLSET env var:

• fixed (default) — a fixed set of read-only diagnostic tools.
• run_script / both — additionally exposes guarded command execution (run_script), which may modify the system. Writes there are permitted only because the gatekeeper, user confirmation, and sandbox guard that path — no other tool has that backstop.

Commands

uv sync                      # Install dependencies
uv run pytest                # Run tests
uv run ruff check src tests  # Lint
uv run pyright               # Type check
make verify                  # All checks (required before commit)

Project Layout

• src/linux_mcp_server/tools/ - MCP tools (logs, network, pcp, processes, services, storage, system_info, run_script)
• src/linux_mcp_server/commands.py - Command definitions (the COMMANDS registry)
• src/linux_mcp_server/formatters.py / parsers.py - Output formatting and parsing
• src/linux_mcp_server/gatekeeper/ - LLM-based safety validation of run_script scripts
• src/linux_mcp_server/auth.py / auth_policy.py - Authentication and authorization policy
• src/linux_mcp_server/audit.py - Audit logging of executed operations
• src/linux_mcp_server/redaction/ - Credential redaction of tool output and error messages
• src/linux_mcp_server/tool_result.py - ToolResult for tools whose text differs from their structured content
• src/linux_mcp_server/connection/ssh.py - Remote execution over SSH
• src/linux_mcp_server/config.py / execution_context.py / toolset.py - Config, per-call context, toolset selection
• tests/ - Mirrors src structure

Rules

Code: PEP 8, type hints required, async/await for I/O, 120 char max, prefer Pydantic over dataclasses

• Tools take host: Host - localhost runs locally, anything else over SSH
• All network/SSH operations must have timeouts; prefer asyncssh-native timeouts over asyncio.wait_for
• SSH uses key-based auth only (no plaintext passwords); connection and command errors must include the host for debugging
• Validate config and env vars at startup (Pydantic model_validator), not lazily; use secure defaults
• Error messages must be clear enough for an LLM to understand and act on