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

![License](https://img.shields.io/badge/license-ISC-blue.svg)
![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-success.svg)
![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)

*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 `cat`ting 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
```bash
# 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`):
```json
{
  "mcpServers": {
    "system-monitor": {
      "command": "node",
      "args": ["D:/Project/MCP/status/dist/index.js"]
    }
  }
}
```

**macOS/Linux** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```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.*