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:

   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:

   npm run build
   

4. Run Dev / Dev Client:

   npm run dev
   

5. Start Production Server:

   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:

   {
     "services": ["nginx"],
     "targetHost": "localhost"
   }
   

   Result: Shows that the nginx service is inactive or down.

2. Retrieve Log Patterns (Detection): Call scan_system_logs with:

   {
     "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:

   {
     "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:

   {
     "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:

   {
     "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.