linux-mcp-server 0.1.0.dev0__py3-none-any.whl

linux_mcp_server-0.1.0.dev0.dist-info/METADATA

@@ -0,0 +1,331 @@
+Metadata-Version: 2.4
+Name: linux-mcp-server
+Version: 0.1.0.dev0
+Summary: MCP server for read-only Linux system administration, diagnostics, and troubleshooting
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: asyncssh>=2.14.0
+Requires-Dist: mcp>=0.9.0
+Requires-Dist: psutil>=5.9.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Linux MCP Server
+
+A Model Context Protocol (MCP) server for read-only Linux system administration, diagnostics, and troubleshooting on RHEL-based systems.
+
+## Features
+
+- **Read-Only Operations**: All tools are strictly read-only for safe diagnostics
+- **Remote SSH Execution**: Execute commands on remote systems via SSH with key-based authentication
+- **Multi-Host Management**: Connect to different remote hosts in the same session
+- **Comprehensive Diagnostics**: System info, services, processes, logs, network, and storage
+- **Configurable Log Access**: Control which log files can be accessed via environment variables
+- **RHEL/systemd Focused**: Optimized for Red Hat Enterprise Linux systems
+
+## Architecture Overview
+
+```mermaid
+graph TB
+    Client["Client Layer<br/>MCP Client (e.g. Claude Desktop)"]
+    
+    subgraph Server["MCP Server"]
+        FastMCP[FastMCP Server]
+        
+        subgraph Tools["Tool Categories"]
+            direction LR
+            subgraph Row1[" "]
+                SystemInfo[System Info]
+                Services[Services]
+                Processes[Processes]
+            end
+            subgraph Row2[" "]
+            Logs[Logs & Audit]
+                Network[Network]
+                Storage[Storage]
+            end
+        end
+        
+        Executor[SSH Executor]
+        Logger[Audit Logger]
+    end
+    
+    subgraph Targets["Execution Targets"]
+        direction LR
+        Local[Local System]
+        Remote[Remote Hosts<br/>SSH]
+    end
+    
+    Client -->|MCP Protocol| FastMCP
+    FastMCP --> Tools
+    Tools --> Executor
+    Executor --> Targets
+    
+    FastMCP -.-> Logger
+    Executor -.-> Logger
+    
+    style Client fill:#4a9eff,stroke:#2563eb,color:#fff
+    style FastMCP fill:#f59e0b,stroke:#d97706,color:#fff
+    style SystemInfo fill:#64748b,stroke:#475569,color:#fff
+    style Services fill:#64748b,stroke:#475569,color:#fff
+    style Processes fill:#64748b,stroke:#475569,color:#fff
+    style Logs fill:#64748b,stroke:#475569,color:#fff
+    style Network fill:#64748b,stroke:#475569,color:#fff
+    style Storage fill:#64748b,stroke:#475569,color:#fff
+    style Executor fill:#10b981,stroke:#059669,color:#fff
+    style Logger fill:#8b5cf6,stroke:#7c3aed,color:#fff
+    style Local fill:#eab308,stroke:#ca8a04,color:#fff
+    style Remote fill:#eab308,stroke:#ca8a04,color:#fff
+    style Row1 fill:none,stroke:none
+    style Row2 fill:none,stroke:none
+```
+
+### Key Components
+
+- **FastMCP Server**: Core MCP protocol server handling tool registration and invocation
+- **Tool Categories**: Six categories of read-only diagnostic tools (system info, services, processes, logs, network, storage)
+- **SSH Executor**: Routes commands to local subprocess or remote SSH execution with connection pooling
+- **Audit Logger**: Comprehensive logging in both human-readable and JSON formats with automatic rotation
+- **Multi-Target Execution**: Single server instance can execute commands on local system or multiple remote hosts
+
+## Available Tools
+
+### System Information
+- `get_system_info` - OS version, kernel, hostname, uptime
+- `get_cpu_info` - CPU details and load averages
+- `get_memory_info` - RAM usage and swap details
+- `get_disk_usage` - Filesystem usage and mount points
+- `get_hardware_info` - Hardware details (CPU architecture, PCI/USB devices, memory hardware)
+
+### Service Management
+- `list_services` - List all systemd services with status
+- `get_service_status` - Detailed status of a specific service
+- `get_service_logs` - Recent logs for a specific service
+
+### Process Management
+- `list_processes` - Running processes with CPU/memory usage
+- `get_process_info` - Detailed information about a specific process
+
+### Logs & Audit
+- `get_journal_logs` - Query systemd journal with filters
+- `get_audit_logs` - Read audit logs (if available)
+- `read_log_file` - Read specific log file (whitelist-controlled)
+
+### Network Diagnostics
+- `get_network_interfaces` - Network interface information
+- `get_network_connections` - Active network connections
+- `get_listening_ports` - Ports listening on the system
+
+### Storage & Disk Analysis
+- `list_block_devices` - Block devices and partitions
+- `list_directories_by_size` - List directories sorted by size (largest first) with top N limit
+- `list_directories_by_name` - List all directories sorted alphabetically (A-Z or Z-A)
+- `list_directories_by_modified_date` - List all directories sorted by modification date (newest/oldest first)
+
+## Installation
+
+### Prerequisites
+- Python 3.10 or higher
+- [uv](https://github.com/astral-sh/uv) package manager
+
+### Setup
+
+1. Clone the repository:
+```bash
+git clone <repository-url>
+cd linux-mcp-server
+```
+
+2. Create virtual environment and install dependencies:
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+```
+
+## Configuration
+
+Configure the server using environment variables:
+
+```bash
+# Comma-separated list of allowed log file paths
+export LINUX_MCP_ALLOWED_LOG_PATHS="/var/log/messages,/var/log/secure,/var/log/audit/audit.log"
+
+# Optional: Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+export LINUX_MCP_LOG_LEVEL="INFO"
+
+# Optional: Custom log directory (default: ~/.local/share/linux-mcp-server/logs/)
+export LINUX_MCP_LOG_DIR="/var/log/linux-mcp-server"
+
+# Optional: Log retention in days (default: 10)
+export LINUX_MCP_LOG_RETENTION_DAYS="30"
+
+# Optional: Specify SSH private key path (defaults to ~/.ssh/id_ed25519, ~/.ssh/id_rsa, etc.)
+export LINUX_MCP_SSH_KEY_PATH="/path/to/your/private/key"
+```
+
+### Audit Logging
+
+The server includes comprehensive audit logging for all operations:
+
+**Features:**
+- **Dual Format**: Logs written in both human-readable text and JSON formats
+- **Daily Rotation**: Automatic log rotation at midnight
+- **Configurable Retention**: Keep logs for a specified number of days (default: 10)
+- **Tiered Verbosity**: INFO for operations, DEBUG for detailed diagnostics
+- **Sanitization**: Automatic redaction of sensitive data (passwords, tokens, API keys)
+
+**Log Files:**
+- Human-readable: `~/.local/share/linux-mcp-server/logs/server.log`
+- JSON format: `~/.local/share/linux-mcp-server/logs/server.json`
+- Rotated files: `server.log.YYYY-MM-DD` and `server.json.YYYY-MM-DD`
+
+**What Gets Logged:**
+- Server startup and shutdown
+- All tool invocations with parameters (sanitized)
+- Tool execution time and completion status
+- SSH connections (success/failure)
+- Remote command execution
+- Error conditions with full context
+
+**Log Levels:**
+- `DEBUG`: Detailed flow, connection reuse, function entry/exit, timing details
+- `INFO`: Tool calls, command executions, connection events, operation results
+- `WARNING`: Authentication failures, retryable errors, missing optional data
+- `ERROR`: Failed operations, exceptions, connection failures
+- `CRITICAL`: Server startup/shutdown failures, unrecoverable errors
+
+**Example Log Entries:**
+
+```
+# Human-readable format (server.log)
+2025-10-10 14:23:45.123 | INFO | server | TOOL_CALL: list_services | host=server1.example.com | username=admin | execution_mode=remote
+2025-10-10 14:23:45.234 | INFO | ssh_executor | SSH_CONNECT: admin@server1.example.com | status=success
+2025-10-10 14:23:45.345 | INFO | ssh_executor | REMOTE_EXEC: systemctl list-units --type=service | host=server1.example.com | exit_code=0
+2025-10-10 14:23:45.456 | INFO | server | TOOL_COMPLETE: list_services | status=success | duration=0.333s
+
+# JSON format (server.json)
+{"timestamp": "2025-10-10T14:23:45.123Z", "level": "INFO", "logger": "server", "message": "TOOL_CALL: list_services", "event": "TOOL_CALL", "tool": "list_services", "host": "server1.example.com", "username": "admin", "execution_mode": "remote"}
+```
+
+### Remote SSH Execution
+
+All tools support optional `host` and `username` parameters for remote execution via SSH:
+
+- **Authentication**: SSH key-based authentication only (no password support)
+- **Key Discovery**: Automatically discovers SSH keys from `~/.ssh/` or use `LINUX_MCP_SSH_KEY_PATH`
+- **Connection Pooling**: Reuses SSH connections for efficiency
+- **Multi-Host**: Each tool call can target a different remote host
+
+**Requirements**:
+- SSH key-based authentication must be configured on remote hosts
+- Remote user must have appropriate permissions for diagnostic commands
+
+**Example Usage**:
+```python
+# Local execution
+await list_services()
+
+# Remote execution
+await list_services(host="server1.example.com", username="admin")
+
+# Different host in same session
+await get_service_status("nginx", host="server2.example.com", username="sysadmin")
+```
+
+## Usage
+
+### Running the Server
+
+You can run the server in multiple ways:
+
+**Using uv run (recommended for development):**
+```bash
+uv run linux-mcp-server
+```
+
+**Using uvx (recommended for one-off execution without installation):**
+```bash
+uvx --from /path/to/linux-mcp-server linux-mcp-server
+```
+
+**Traditional Python module execution:**
+```bash
+python -m linux_mcp_server
+```
+
+### Using with Claude Desktop
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+**Option 1: Using uv run (simpler):**
+```json
+{
+  "mcpServers": {
+    "linux-diagnostics": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/path/to/linux-mcp-server",
+        "run",
+        "linux-mcp-server"
+      ],
+      "env": {
+        "LINUX_MCP_ALLOWED_LOG_PATHS": "/var/log/messages,/var/log/secure,/var/log/audit/audit.log"
+      }
+    }
+  }
+}
+```
+
+**Option 2: Using uvx (from local directory):**
+```json
+{
+  "mcpServers": {
+    "linux-diagnostics": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "/path/to/linux-mcp-server",
+        "linux-mcp-server"
+      ],
+      "env": {
+        "LINUX_MCP_ALLOWED_LOG_PATHS": "/var/log/messages,/var/log/secure,/var/log/audit/audit.log"
+      }
+    }
+  }
+}
+```
+
+## Development
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Running Tests with Coverage
+
+```bash
+pytest --cov=src --cov-report=html
+```
+
+## Security Considerations
+
+- All operations are **read-only**
+- Log file access is controlled via whitelist (`LINUX_MCP_ALLOWED_LOG_PATHS`)
+- **SSH key-based authentication only** - no password support
+- SSH host key verification is disabled for flexibility (use with caution)
+- No arbitrary command execution
+- Input validation on all parameters
+- Requires appropriate system permissions for diagnostics
+- Remote user needs proper sudo/permissions for privileged commands
+
+## License
+
+MIT License
+

linux_mcp_server-0.1.0.dev0.dist-info/RECORD

@@ -0,0 +1,20 @@
+linux_mcp_server/__init__.py,sha256=kqCUoAViNPXAv7NLdtm_QNkRWw3UAUYb-VdtrEirjgw,109
+linux_mcp_server/__main__.py,sha256=KCxRzk4GcqIEhDKHWbsuJZ4OvUnDj0WIDcBcegztF1w,768
+linux_mcp_server/audit.py,sha256=nT6wrc9EbjGRPQYkTexwceDibMDMzmjsrRKtyqbFAlw,7763
+linux_mcp_server/logging_config.py,sha256=4fJbmAhNVHr99721aHIzvfEFjwHAHJYG0nutCu_c9lU,5007
+linux_mcp_server/server.py,sha256=WFvbc4a4IU4sC9JcNeb2BLxQErqGI_-TsdfGXaqw4w4,13646
+linux_mcp_server/tools/__init__.py,sha256=tmts0--UGw0PoDJARq5rurlxNXIdmYQwZddbiViatZY,43
+linux_mcp_server/tools/logs.py,sha256=OT61rh_2LwLTdK0rCm-bQvMQMPBFq-kHmeG5QKsnDUE,7538
+linux_mcp_server/tools/network.py,sha256=TRyDDAouTLoV3xhL1IUJLhlNhzIHnEj_WXwQkrg8XKw,11050
+linux_mcp_server/tools/processes.py,sha256=kDeeQZkuUf-pLU2UA3Aox70-bJjZATnkVmvLbGiCi1Q,10251
+linux_mcp_server/tools/services.py,sha256=IUD0gK-UAljvH11PUW9lgkFyd234EgHOahZgqfLNuHo,5135
+linux_mcp_server/tools/ssh_executor.py,sha256=UBPs9io_T9yF9GNrKIau1yKnWnEOW2QjNw9ZmDwWrV0,11301
+linux_mcp_server/tools/storage.py,sha256=VvOXPuLRHHp_dNAXWev0cVWhswz9qwB8uRZgx3vdQXQ,12977
+linux_mcp_server/tools/system_info.py,sha256=dJJmA3_2KP8yQY2kks8PndGTwS4iWInRc7sSDfoUHLw,19622
+linux_mcp_server/tools/utils.py,sha256=BsrJsHvrdrJKP8-usBtF5KCWU2MKa2P7oEB6MW5hrzY,675
+linux_mcp_server/tools/validation.py,sha256=8EN_Ny9kPVTR0ABoP0GZshuzD-CFAiYk1Qj1Oeiqvm0,1825
+linux_mcp_server-0.1.0.dev0.dist-info/METADATA,sha256=0T5z9LuE4FggUG6V2sqY3lq0oguQanwMHDmidSAMCDg,10972
+linux_mcp_server-0.1.0.dev0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+linux_mcp_server-0.1.0.dev0.dist-info/entry_points.txt,sha256=TVzOzNkzp99ltOQ8SHTA1U-92A_hydczj6EhsqPVChg,67
+linux_mcp_server-0.1.0.dev0.dist-info/licenses/LICENSE,sha256=ji9Aq1nWt4NHP7Abfp-ovzCGgno_QDSAUxDh2dmxyd4,1068
+linux_mcp_server-0.1.0.dev0.dist-info/RECORD,,

linux_mcp_server-0.1.0.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

linux_mcp_server-0.1.0.dev0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+linux-mcp-server = linux_mcp_server.__main__:cli

linux_mcp_server-0.1.0.dev0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nicolás M.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.