GhostInTheShell

A Sandboxed, Read-Only System Oracle for AI Agents

Because it sees everything… but touches nothing.

---

GhostInTheShell is an advanced Model Context Protocol (MCP) server for local DevOps, Container Diagnostics, and System Monitoring. It safely exposes metrics, container states, and logs to AI agents while minimizing token usage and preventing malicious directory traversal.

Unlike raw wrapper servers, it provides Diagnostics Intelligence and Strict Sandboxing. Instead of dumping raw command outputs that exhaust LLM tokens, it employs contextual compression to return highly targeted diagnostic intelligence.

🌟 Key Features

Security First Model

Built to be strictly read-only:

• Symlink Traversal Blocker: Protects against malicious directory escapes (/../).
• Whitelist Paths: Hard-blocks system sensitive directories like /etc and /root.
• Virtual Log Registry: Log reading is done via aliases (e.g., app_error -> /tmp/app.log) so the LLM doesn't even know the real disk paths.

Diagnostics Intelligence Layer

Computes states locally before hitting the LLM:

• analyze_containers: Parses Docker states for Crash Loops, OOMKilled flags, and healthcheck failures.
• check_cpu_anomalies: Uses exact process uptimes to find runaway loops holding threads.
• check_port_conflicts: Finds exactly what process is stealing port 3000 during your web dev.
• check_log_errors: Scans the tail of safe logs for spikes of exceptions/fatals.

Context Compression Engine

A custom logging parser that helps prevent LLM context exhaustion:

• Strips variable noise (timestamps, IDs)
• Deduplicates identical screaming loops
• Truncates giant lines (like massive JSON stack traces) to a tight 500-character cap.

---

🛠 Installation & Usage

Requires uv and Python 3.10+.

# Clone the repository
git clone https://github.com/pronzzz/GhostInTheShell-mcp.git
cd GhostInTheShell-mcp

# Install as a uv tool globally
uv tool install ./

Or run directly from source:

GHOST_ALLOWED_DIRS="/var/log,/tmp" uv run ghostinshell

Adding to Claude Desktop

To grant Claude Desktop access to your machine's diagnostics securely, edit your claude_desktop_config.json:

{
  "mcpServers": {
    "ghostinshell": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/ghostinshell",
        "run",
        "ghostinshell"
      ]
    }
  }
}

---

🧰 Tools Provided to the LLM

• get_system_health: High-level multi-platform CPU, Disk, and RAM status.
• list_processes(sort_by="cpu|memory"): Details on top running processes.
• docker_status: Raw Docker daemon read-only status.
• analyze_containers: Intelligent diagnosis of crash loops, OOM flags, and resource limits.
• check_cpu_anomalies: Detects runaway processes based on load and uptime.
• check_memory_pressure: Identifies system memory hogs.
• check_disk_pressure: Warnings for saturated root disks.
• list_available_virtual_logs: Look up registered safe-to-read log files.
• tail_log(alias, lines): Returns token-compressed tail of a file.
• check_log_errors(alias): Rapid regex anomaly detection for error spikes.
• check_port_conflicts: Detect processes attempting to bind identical local ports.

---

👩‍💻 Development

Want to add new safe capabilities? Check out the GUIDE.md and CONTRIBUTING.md.

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest tests/

We test heavily against:

• Sandbox symlink jailbreaks
• Log compression deduplication logic
• OS cross-platform wrappers (Darwin vs Linux)
• Port conflict topological structures.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.