# SentinelMCP: Autonomous Self-Healing AI MCP Server

SentinelMCP is an enterprise-grade Model Context Protocol (MCP) server written in TypeScript using the **NitroStack** framework. It acts as an autonomous execution and monitoring layer for LLM-driven agents to detect, diagnose, repair, verify, and prevent software and hardware failures on local and remote systems.

## Hackathon Track: Open Innovation
SentinelMCP is submitted under the **Open Innovation** track. It tackles a real-world problem that cuts across every industry — unplanned system downtime and manual IT-ops firefighting — by giving LLM-driven agents a safe, autonomous execution layer to detect, diagnose, repair, verify, and prevent software and hardware failures on local and remote systems, with built-in safety checks (OSV.dev CVE database) and automatic rollbacks to protect continuity regardless of domain.

## Key Features

1. **State Lock Mutex**: Enforces single-repair execution globally. Prevents concurrent file updates or conflicting service restarts.
2. **Local Log Processor & Deduplicator**: Summarizes system/application logs locally before transferring them to the LLM, reducing token consumption.
3. **Safe Command Executor**: Blocks dangerous arbitrary terminal command executions by utilizing a strict whitelist and running commands via `execFile` (bypassing shell evaluation).
4. **Transparent Safety Engine**: Automatically creates checksummed backups of configuration files before modifying them, supporting **Automated Rollback** if post-repair verification checks fail.
5. **Infinite Loop Breaker**: Logs repair history per diagnostic fingerprint, dropping confidence scores or blocking strategies that have repeatedly failed.
6. **Hardware Diagnosis & Cost Lookup**: Distinguishes hardware from software issues. Prevents software modifications on bad hardware, outputs recommendations, and looks up estimated replacement/repair costs (in INR and USD).
7. **Remote Targets Support (`targetHost`)**: Allows tools to target a specified remote server over secure SSH connections, executing remote diagnostics and configs while maintaining local safety backups.
8. **OSV.dev API Vulnerability Integration**: Live API queries to check for package CVEs during root cause analysis.

---

## Architecture Layout

```
sentinel-mcp/
├── src/
│   ├── index.ts                # Application Entry Point & Bootstrap
│   ├── app.module.ts           # Root Module Configuration
│   ├── config/
│   │   ├── env.config.ts       # Runtime configuration variables
│   │   └── hardware-costs.json # Hardware component replacement estimates
│   ├── interfaces/             # Typings for Incidents, Backups, and Snapshots
│   ├── modules/
│   │   └── sentinel/
│   │       └── sentinel.module.ts # Sentinel Module Registry
│   ├── prompts/
│   │   └── sentinel.prompts.ts # Reusable prompt templates (diagnose-and-repair, postmortem)
│   ├── resources/
│   │   └── sentinel.resources.ts # Exposes incident logs and prevention rules resources
│   ├── services/               # Shared Dependency Injected Services
│   │   ├── lock.service.ts     # Concurrency Mutex
│   │   ├── safety.service.ts   # Backup/Rollback Manager
│   │   ├── log.service.ts      # Local Log Aggregator & Deduplicator
│   │   └── memory.service.ts   # JSON File database storing incident states
│   ├── tools/                  # Decorated MCP Tool Controllers
│   │   ├── detection/          # scan_system_logs, get_service_states, get_system_metrics, check_network_status
│   │   ├── diagnosis/          # analyze_root_cause (integrated with OSV.dev API)
│   │   ├── correction/         # execute_service_repair, execute_config_patch, execute_package_repair
│   │   ├── verification/       # verify_repair_state (with automated rollback)
│   │   ├── memory/             # retrieve_similar_incidents, get_incident_history, check_repair_strategy_limit
│   │   └── prevention/         # register_prevention_rule, get_prevention_rules
│   └── utils/
│       ├── command-executor.ts  # Whitelisted execFile commander (supports SSH targetHost)
│       └── file-helper.ts       # Backup and file operations helper (supports remote files)
```

---

## Exposed MCP Primitives (Tools, Resources, Prompts)

### 1. MCP Tools

#### Detection Layer
- `scan_system_logs`: Summarizes systemd errors and warning logs. Supports `targetHost`.
- `get_service_states`: Checks if specified systemd services are running, stopped, or disabled. Supports `targetHost`.
- `get_system_metrics`: Retrieves CPU, RAM, disk partitions, sensor temperatures, and S.M.A.R.T indicators. Supports `targetHost`.
- `check_network_status`: Diagnoses IP configurations, listening TCP sockets (`ss`), DNS resolution, and gateway pings. Supports `targetHost`.

#### Diagnosis Layer
- `analyze_root_cause`: Synthesizes evidence to rank repair hypotheses or flag hardware failure indicators. Queries **OSV.dev API** if a `packageName` is supplied to discover known CVE vulnerabilities.

#### Correction Layer
- `execute_service_repair`: Restarts, starts, or enables a systemd service under the global lock. Supports `targetHost`.
- `execute_config_patch`: Safely patches config files after making pre-repair backups. Supports `targetHost`.
- `execute_package_repair`: Installs or reinstalls missing system packages or npm packages. Supports `targetHost`.

#### Verification Layer
- `verify_repair_state`: Tests system parameters. **If checks fail, automatically restores backup files on the target to return the system to its pre-repair state.** Supports `targetHost`.

#### Memory Layer
- `retrieve_similar_incidents`: Looks up past incidents matching the current error profile.
- `get_incident_history`: Lists all logged incidents.
- `check_repair_strategy_limit`: Blocks repair strategies that have failed 2+ times.

#### Prevention Layer
- `register_prevention_rule`: Logs recommended hardiness configuration guidelines.
- `get_prevention_rules`: Lists registered rules.

### 2. MCP Resources
- `incident://history`: Read-only JSON list of all past diagnostic and self-healing incidents, sorted by recency.
- `prevention://rules`: Read-only JSON list of all registered hardening rules.

### 3. MCP Prompts
- `diagnose-and-repair`: Guides the AI client step-by-step through the detection → analysis → correction → verification flow.
- `incident-postmortem`: Formulates a post-mortem summary request for any resolved incident by its UUID.

---

## Setup & Running

1. **Install Dependencies**:
   ```bash
   npm install
   ```

2. **Configuration**:
   Copy `.env.example` to `.env` and set environment variables. 
   - Set `OAUTH_REQUIRED=false` for local developer STDIO executions.
   - Set `SENTINEL_TARGET_HOST` and `SENTINEL_TARGET_MODE` to target remote machines via SSH.

3. **Build the Server**:
   ```bash
   npm run build
   ```

4. **Run Dev / Dev Client**:
   ```bash
   npm run dev
   ```

5. **Start Production Server**:
   ```bash
   npm start
   ```

---

## Demo Script

Follow this sequence of tool calls in an MCP client (such as Claude Desktop or NitroStudio) to demonstrate SentinelMCP's end-to-end self-healing and automated rollback feature:

1. **Check System Health (Detection)**:
   Call `get_service_states` with:
   ```json
   {
     "services": ["nginx"],
     "targetHost": "localhost"
   }
   ```
   *Result*: Shows that the nginx service is inactive or down.

2. **Retrieve Log Patterns (Detection)**:
   Call `scan_system_logs` with:
   ```json
   {
     "service": "nginx",
     "maxLines": 50,
     "targetHost": "localhost"
   }
   ```
   *Result*: Aggregates recent nginx logs (e.g., "Address already in use").

3. **Diagnose and Scan Vulnerabilities (Diagnosis)**:
   Call `analyze_root_cause` with:
   ```json
   {
     "evidenceFingerprint": "nginx-port-80-conflict",
     "severity": "high",
     "logs": ["nginx: Address already in use", "nginx: failed to bind to port 80"],
     "packageName": "nginx"
   }
   ```
   *Result*: Returns a ranked list of repair hypotheses and queries the **OSV.dev API** to show any known vulnerabilities for nginx. Creates a new incident in the local database.

4. **Apply Patch (Correction)**:
   Call `execute_config_patch` with:
   ```json
   {
     "filePath": "/etc/nginx/nginx.conf",
     "patchContent": "events {} http { server { listen 8080; } }",
     "incidentId": "<UUID_FROM_PREVIOUS_STEP>",
     "dryRun": false
   }
   ```
   *Result*: Acquires the global repair lock, creates a checksummed backup of the config locally, and writes the new configuration.

5. **Verify State & Demonstrate Rollback (Verification)**:
   To demonstrate safety, request verification of a port that will fail (e.g., port 80):
   Call `verify_repair_state` with:
   ```json
   {
     "incidentId": "<UUID_FROM_PREVIOUS_STEP>",
     "criteria": {
       "serviceName": "nginx",
       "listeningPorts": [80]
     }
   }
   ```
   *Result*: SentinelMCP detects that the verification checks failed. It immediately triggers a **rollback**, restoring `/etc/nginx/nginx.conf` to its original checksummed state, updates the incident database status to `failed`, releases the global state lock, and notifies the caller.