# 🔧 MCP Terminal Monitor

![demo](./demo.gif)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/mcp-terminal-monitor.svg)](https://badge.fury.io/js/mcp-terminal-monitor)

Production-ready Model Context Protocol (MCP) Server for system monitoring. Provides AI agents with real-time access to Docker containers, system resources, ports, and logs.

## 🚀 Quick Start

```bash
npx mcp-terminal-monitor
```

Or install globally:

```bash
npm install -g mcp-terminal-monitor
mcp-terminal-monitor
```

## 📋 Available Tools

| Tool | Description |
|------|-------------|
| `list_docker_containers` | List Docker containers with status, ports, and health |
| `check_port_conflicts` | Check if a specific port is in use on the system |
| `tail_system_logs` | Retrieve recent system or Docker container logs |
| `get_disk_usage` | Get disk usage statistics for filesystems |
| `monitor_cpu_ram` | Monitor CPU and RAM usage with configurable sampling |

## 🔧 Features

- 🐳 **Docker Integration** - List containers, fetch logs, monitor health
- 🔌 **Port Monitoring** - Detect port conflicts before deployment
- 📊 **System Metrics** - Real-time CPU, RAM, and disk usage
- 📝 **Log Access** - System and container log streaming
- 🔒 **Read-Only Safety** - All operations are non-destructive
- ⚡ **Low Latency** - Optimized system calls for fast responses
- 🛡️ **Strict Validation** - Zod schemas ensure safe argument parsing
- 🌐 **Cross-Platform** - Works on Linux, macOS, and Windows

## 🏗 Architecture

```mermaid
graph TD
    A[AI Client] -->|MCP Protocol| B[MCP Terminal Monitor Server]
    B -->|Docker API| C[Docker Daemon]
    B -->|System Calls| D[OS Kernel]
    B -->|Network Stats| E[Netstat/Lsof]
    B -->|Process Info| F[SystemInformation]
    
    C --> G[Containers]
    D --> H[CPU/RAM/Disk]
    E --> I[Port Conflicts]
    F --> J[System Metrics]
```

## 📖 Usage Examples

### List Docker Containers

```json
{
  "name": "list_docker_containers",
  "arguments": {
    "all": true,
    "limit": 10
  }
}
```

### Check Port Conflicts

```json
{
  "name": "check_port_conflicts",
  "arguments": {
    "port": 3000,
    "host": "0.0.0.0"
  }
}
```

### Tail System Logs

```json
{
  "name": "tail_system_logs",
  "arguments": {
    "service": "nginx",
    "lines": 50,
    "follow": false
  }
}
```

### Get Disk Usage

```json
{
  "name": "get_disk_usage",
  "arguments": {
    "path": "/"
  }
}
```

### Monitor CPU & RAM

```json
{
  "name": "monitor_cpu_ram",
  "arguments": {
    "interval": 1000,
    "samples": 3
  }
}
```

## 🔌 MCP Configuration

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "terminal-monitor": {
      "command": "npx",
      "args": ["mcp-terminal-monitor"]
    }
  }
}
```

## 🛠 Development

```bash
# Clone repository
git clone https://github.com/yourusername/mcp-terminal-monitor.git
cd mcp-terminal-monitor

# Install dependencies
npm install

# Run in development mode
npm start

# Build for production
npm run build
```

## 📦 Requirements

- Node.js >= 18.0.0
- Docker daemon (for Docker-related tools)
- Root/sudo access may be required for some system calls

## 📄 License

MIT © [Your Name](LICENSE)

---

Built with [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk)