🛡️ System Status & Config MCP Server (Agentic AIOps)

The ultimate "eyes and ears" for your AI assistants. Give LLMs (like Claude, Cursor, or your autonomous agents) safe, read-only, and token-optimized access to your server's physical reality.

---

🌟 Why This Exists?

Large Language Models (LLMs) possess vast knowledge of system administration, architecture, and debugging. However, they suffer from a "reality gap" — they know how to fix an OOM error, but they don't know your server's RAM usage, your active configuration paths, or your current logs.

If you give an AI raw shell access (bash), it is extremely dangerous (e.g., accidental rm -rf or crashing the server by catting a 50GB log file).

This MCP (Model Context Protocol) Server solves this by acting as a Secure, Read-Only Abstraction Layer. It empowers AI to perform sub-second, cross-platform infrastructure audits and root-cause analysis without risking system integrity.

🚀 Core Features

1. 📊 High-Concurrency System Probes (get_system_status)

Gathers real-time OS metrics across 17 distinct categories (CPU, Memory, Docker, Network, Processes, Windows WMI internals, etc.).

• Smart Concurrency: Windows WMI/CIM queries are executed in parallel (Promise.all), reducing response times from seconds to ~200ms.
• Cross-Platform: Normalizes complex metrics across Linux, macOS, and Windows into clean JSON.

2. 🔍 Intelligent Config Radar (discover_configs)

AI doesn't need to guess where your config files are.

• Auto-locates 36+ well-known services (Nginx, Redis, SSH, WSL, VSCode, Git, etc.).
• Directory Sniffing: Point it to a project directory (directory: "/path/to/project"), and it will automatically detect hidden . files and configuration extensions (.yaml, .ini, .env).

3. 🧠 Token-Optimized Config Reader (read_config)

Reads and parses structured configurations (JSON, YAML, INI, TOML, etc.).

• keys-only Mode: Designed specifically for LLMs. If an AI needs to read a massive package-lock.json, this mode strips out heavy values and returns only the structural schema (e.g., replacing arrays with [Array of 8 items]), saving tens of thousands of tokens while preserving context.

4. 🛡️ Safe Log Tailing (read_log)

A purpose-built, high-performance log analyzer.

• Reverse Chunk Reading: Directly reads 64KB chunks from the end of the file backwards. Never loads the entire file into memory (OOM-safe).
• Native Grep: Search for keywords (e.g., grep: "ERROR") across massive log files.
• Circuit Breakers: Hard-capped at 1000 lines and a 10MB backwards-search limit to protect the Node.js event loop during high CPU loads.

---

🛠️ Installation & Setup

Prerequisites

• Node.js >= 18.x
• TypeScript installed globally or locally

Build from source

# Clone the repository
git clone https://github.com/yourusername/system-status-mcp.git
cd system-status-mcp

# Install dependencies
npm install

# Build the project
npm run build

Usage with Claude Desktop

Add the following configuration to your Claude Desktop claude_desktop_config.json:

Windows (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "system-monitor": {
      "command": "node",
      "args": ["D:/Project/MCP/status/dist/index.js"]
    }
  }
}

macOS/Linux (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "system-monitor": {
      "command": "node",
      "args": ["/path/to/system-status-mcp/dist/index.js"]
    }
  }
}

---

🧰 Available MCP Tools

Tool Name	Description	Key Arguments
get_system_status	Retrieve system metrics.	category ("all", "performance", "docker", "windows", etc.)
discover_configs	Scan for known configs or project dotfiles.	service (filter by name), directory (scan a specific folder)
read_config	Parse a specific config file.	path, service, compactMode ("none", "keys-only")
read_log	Safely tail and grep massive log files.	path, lines (default 100), grep (optional filter)

---

🏗️ Architecture & Safety Highlights

• Embedded Error Reporting: Instead of failing silently or returning 500 Internal Error, the server captures explicit filesystem errors (EACCES, ENOENT) and PowerShell timeouts, embedding them directly into the JSON response (e.g., { "_error": "Permission denied" }). This allows the AI to autonomously adjust its strategy (e.g., asking the user for sudo privileges).
• Graceful Timeouts: All heavy subprocess executions (like Windows WMI) are strictly timed out at 15 seconds. If the CPU is pegged at 99%, the MCP server will gracefully report timeout failures rather than hanging the AI indefinitely.

---

Built for the Agentic Era. Open-sourced under the ISC License.