<div align="center">
  <img src="assets/logo.svg" alt="WinFolio MCP" width="480" />
  <br /><br />
  <p><strong>The most comprehensive Windows system health toolkit for AI assistants.</strong></p>
  <p>
    <a href="https://github.com/reprodev/winfolio-mcp/actions/workflows/ci.yml"><img src="https://github.com/reprodev/winfolio-mcp/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
    <img src="https://img.shields.io/badge/tools-85-2563eb?style=flat-square" alt="85 tools" />
    <img src="https://img.shields.io/badge/platform-Windows_10%2F11-0078D6?style=flat-square&logo=windows" alt="Windows" />
    <img src="https://img.shields.io/badge/transport-MCP_%7C_HTTP-10b981?style=flat-square" alt="MCP + HTTP" />
    <img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node 20+" />
    <img src="https://img.shields.io/badge/license-MIT-yellow?style=flat-square" alt="MIT License" />
    <img src="https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" />
  </p>
  <p>
    85 tools covering diagnostics, security, developer workflows, hardware monitoring, networking, and system maintenance — accessible via MCP (Claude, Kiro, Cursor) or OpenAI-compatible HTTP (Ollama, LM Studio, Open WebUI).
  </p>
  <p><em>Every tool returns actionable recommendations, not just raw data.</em></p>
</div>

---

## Quick Start

```bash
# Install dependencies
npm install

# Build
npm run build

# Run in MCP mode (Claude, Kiro, Cursor)
npm start

# Run with write actions enabled
npm run start:actions

# Run as HTTP server for local LLMs
npm run serve

# Check version and tool count
node dist/index.js --version

# List all available tools
node dist/index.js --list-tools
```

## MCP Configuration

Add to your MCP client config (Claude Desktop, Kiro, Cursor):

```json
{
  "mcpServers": {
    "winfolio": {
      "command": "node",
      "args": ["C:/path/to/winfolio-mcp/dist/index.js"]
    }
  }
}
```

With actions enabled:

```json
{
  "mcpServers": {
    "winfolio": {
      "command": "node",
      "args": ["C:/path/to/winfolio-mcp/dist/index.js", "--allow-actions"]
    }
  }
}
```

## HTTP Mode (OpenAI-Compatible)

```bash
npm run serve
# Server starts on http://localhost:7890

# Custom port
node dist/index.js --serve --port=8080
```

Endpoints:
- `GET /` — Server info and tool list
- `GET /v1/tools` — Tools in OpenAI function-calling format
- `POST /v1/tools/:name` — Invoke a tool directly
- `POST /v1/chat/completions` — OpenAI-compatible chat with auto tool routing

## Tools (85 total)

### Core Diagnostics (7)

| Tool | Description |
|------|-------------|
| `system_overview` | CPU, RAM, uptime, OS version with health recommendations |
| `top_processes` | Top CPU/memory consumers with resource hog detection |
| `port_check` | Listening ports with conflict detection for dev ports |
| `services_status` | Windows services health, critical service monitoring |
| `event_log_errors` | Recent errors with plain-English explanations |
| `disk_usage` | Drive space analysis with cleanup suggestions |
| `startup_programs` | Boot programs with safe-to-disable recommendations |

### System & OS (4)

| Tool | Description |
|------|-------------|
| `windows_license` | Activation status, edition, license type |
| `virtual_memory` | Page file config, commit charge, swap analysis |
| `time_sync` | NTP server, clock skew, W32Time service |
| `system_errors` | Categorized critical/error events (disk, driver, network, etc.) |

### Hardware (6)

| Tool | Description |
|------|-------------|
| `gpu_status` | GPU model, VRAM, driver version, utilization |
| `battery_status` | Charge, health %, cycle count, time remaining |
| `thermal_status` | CPU/system temperatures, overheat detection |
| `ram_details` | DIMM slots, speed, type, upgrade potential |
| `bios_info` | UEFI/BIOS version, Secure Boot, TPM status |
| `display_info` | Monitors, resolution, refresh rate, scaling |

### Networking (9)

| Tool | Description |
|------|-------------|
| `network_info` | Adapters, IP, DNS, gateway, public IP |
| `wifi_networks` | Visible networks, signal strength, saved profiles |
| `active_connections` | TCP connections grouped by process (netstat) |
| `hosts_file` | Hosts entries with suspicious redirect detection |
| `vpn_status` | Connected VPNs, third-party adapter detection |
| `proxy_settings` | System proxy, WPAD, env var proxies |
| `network_speed` | Adapter link speeds, throughput stats |
| `bluetooth_devices` | Paired devices, battery levels, connection status |
| `audio_devices` | Playback/recording devices, status |

### Storage & Cleanup (2)

| Tool | Description |
|------|-------------|
| `large_files` | Find biggest files on disk by size |
| `duplicate_files` | Find identical files wasting space (MD5 hash) |

### Performance & Troubleshooting (4)

| Tool | Description |
|------|-------------|
| `memory_leaks` | Detect processes with growing memory, excessive handles |
| `crash_dumps` | BSOD minidumps, app crashes, crash frequency |
| `pending_reboots` | Check all reboot-required flags |
| `slow_boot_analysis` | Boot time phases, slow startup items |

### Security (7)

| Tool | Description |
|------|-------------|
| `firewall_status` | Profile states, rules count, recent blocks |
| `defender_status` | Real-time protection, definitions, threats |
| `open_shares` | SMB shares with permission audit |
| `user_accounts` | Local accounts, admin audit, password age |
| `bitlocker_status` | Drive encryption status per volume |
| `exploit_protection` | DEP, ASLR, CFG, HVCI, Credential Guard |
| `privacy_settings` | Telemetry, advertising ID, location, camera/mic |

### Developer Tools (12)

| Tool | Description |
|------|-------------|
| `dev_environments` | Installed SDKs (Node, Python, .NET, Java, Go, Rust) |
| `git_repos` | Repos with uncommitted/unpushed changes |
| `npm_global_packages` | Global packages, deprecated detection |
| `vscode_extensions` | Extensions with heavy/deprecated flagging |
| `ssh_keys` | Key inventory, passphrase audit, agent status |
| `wsl_disk_usage` | WSL VHD sizes, compaction recommendations |
| `localhost_servers` | Dev ports scan (what's running locally) |
| `dotnet_sdks` | .NET SDK/runtime versions, global.json verification |
| `docker_status` | Containers, images, daemon status |
| `wsl_status` | Distros, versions, running state |
| `installed_software` | Programs with bloatware detection |
| `environment_variables` | PATH analysis, key env vars |

### Maintenance (8)

| Tool | Description |
|------|-------------|
| `windows_updates` | Pending updates, history, auto-update health |
| `scheduled_tasks` | Non-system tasks, failed task detection |
| `windows_features` | Optional features (Hyper-V, WSL, IIS, Sandbox) |
| `startup_impact` | Startup items with boot impact rating |
| `driver_issues` | Missing/failed/outdated drivers |
| `windows_search` | Indexer status, index size |
| `certificate_store` | Expiring/expired SSL certs |
| `system_restore_points` | Restore points, age, creation triggers |

### Monitoring (2)

| Tool | Description |
|------|-------------|
| `uptime_history` | Boot/shutdown events, stability score |
| `performance_baseline` | Snapshot and compare system metrics over time |

### Workflow & Productivity (3)

| Tool | Description |
|------|-------------|
| `clipboard_history` | Current clipboard, history entries |
| `recent_files` | Recently accessed files with search |
| `power_plan` | Active plan, throttle detection |

### Automation (2)

| Tool | Description |
|------|-------------|
| `powershell_profile` | Profile load time, module imports audit |
| `startup_services` | Auto-start services, failed detection |

### Additional Diagnostics (5)

| Tool | Description |
|------|-------------|
| `font_list` | Installed fonts with search |
| `usb_devices` | Connected USB peripherals and drives |
| `disk_health` | S.M.A.R.T. data, wear level, drive failure prediction |
| `screen_recording` | Detect active recording/sharing software |
| `task_manager_summary` | All-in-one CPU/RAM/Disk/Network/GPU snapshot |

### Integrations (2)

| Tool | Description |
|------|-------------|
| `ollama_models` | Local Ollama model inventory |
| `system_report` | Generate full Markdown health report |

### Write Actions (12, require `--allow-actions`)

| Tool | Description |
|------|-------------|
| `kill_process` | Terminate a process by PID or name |
| `restart_service` | Restart/start/stop a Windows service |
| `free_port` | Kill the process holding a port |
| `clear_temp_files` | Delete temp files to free space |
| `flush_dns` | Clear DNS resolver cache |
| `empty_recycle_bin` | Permanently delete Recycle Bin contents |
| `toggle_dark_mode` | Switch Windows dark/light theme |
| `restart_computer` | Schedule a system restart |
| `disable_startup_item` | Disable a startup program |
| `create_restore_point` | Create a System Restore point |
| `set_power_plan` | Switch power plan (Balanced/High Performance/etc.) |
| `toast_notify` | Send a native Windows notification |

## Architecture

```
src/
  index.ts              — Entry point, CLI flags, MCP/HTTP transport selection
  powershell.ts         — AV-safe PowerShell executor (temp .ps1 files)
  http-server.ts        — Hono-based OpenAI-compatible HTTP server
  tools/
    registry.ts         — Unified tool registry (both transports consume this)
    *.ts                — Individual tool implementations
```

Key design decisions:
- **AV-safe execution**: PowerShell scripts written to temp `.ps1` files and run with `-File` flag (not `-EncodedCommand` which triggers antivirus heuristics)
- **Unified registry**: Single tool definition consumed by both MCP and HTTP transports
- **Graceful degradation**: Tools detect when features aren't available (Docker not installed, no WiFi adapter, etc.) and return helpful messages instead of errors
- **Actionable recommendations**: Every tool returns not just data but what to do about it
- **Gated write actions**: Dangerous operations require explicit `--allow-actions` flag

## CLI Flags

| Flag | Description |
|------|-------------|
| `--serve` | Start HTTP server instead of MCP stdio |
| `--port=N` | HTTP server port (default: 7890) |
| `--allow-actions` | Enable write action tools |
| `--version`, `-v` | Print version and tool count |
| `--list-tools` | Print all tools with descriptions |

## Requirements

- Windows 10/11
- Node.js 20+
- PowerShell 5.1+ (ships with Windows)

## License

MIT