# WinHelm — Windows Native MCP Server

[![npm version](https://img.shields.io/npm/v/winhelm-mcp.svg)](https://www.npmjs.com/package/winhelm-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Platform](https://img.shields.io/badge/platform-Windows%2010%20%7C%2011-blue.svg)](https://microsoft.com/windows)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
[![Tests](https://img.shields.io/badge/tests-114%2F114%20passing-success.svg)]()
[![Protocol](https://img.shields.io/badge/MCP-1.9.0-purple.svg)](https://modelcontextprotocol.io/)

> **WinHelm MCP** — *The helm for your Windows workspace.*  
> A lightweight, production-grade Windows Native Model Context Protocol (MCP) server featuring a built-in Single-Process Web Gateway (Streamable HTTP `/mcp` + Server-Sent Events `/sse`), Real-Time Web Monitor Dashboard, 38 System Tools with Dynamic Profile Loading, and MCP File Preview Resource.

[📖 Tools Reference](docs/TOOLS.md) • [⚙️ Tool Profiles](docs/PROFILES.md) • [🛡️ Security Architecture](docs/SECURITY.md) • [💡 Agent Examples](docs/EXAMPLES.md) • [📝 Changelog](CHANGELOG.md) • [🤝 Contributing](CONTRIBUTING.md)

---

## Table of Contents

- [Overview](#overview)
- [Key Features](#key-features)
- [System Requirements](#system-requirements)
- [Architecture & Live Dashboard](#architecture--live-dashboard)
- [Quick Start](#quick-start)
- [Tool Profiles ("Load Only What You Need")](#tool-profiles-load-only-what-you-need)
- [Client Configuration](#client-configuration)
  - [Claude Desktop](#1-claude-desktop-claude_desktop_configjson)
  - [Cursor IDE](#2-cursor-ide)
  - [ChatGPT & OpenAI MCP Tunnel](#3-chatgpt--openai-mcp-tunnel-tunnel-client)
  - [Remote & Tailscale Connection](#4-remote--tailscale-connection)
- [Tools Overview (38 Tools)](#tools-overview-38-tools)
- [MCP Resources & Web Endpoints](#mcp-resources--web-endpoints)
- [Configuration & Environment Variables](#configuration--environment-variables)
- [Standalone Executable (`winhelm.exe`)](#standalone-executable-winhelmexe)
- [Documentation & Deep Dive](#documentation--deep-dive)
- [License](#license)

---

## Overview

**WinHelm** bridges the gap between AI assistants (Claude, Cursor, LibreChat, ChatGPT) and the Windows operating system. Unlike generic cross-platform servers, WinHelm is built from the ground up for Windows with:

- **Zero Gateway Overhead:** Native single-process Web Gateway supporting both modern Streamable HTTP (`/mcp`) and standard Server-Sent Events (`/sse`). No external proxy (`supergateway` or reverse proxy) required.
- **Safety First:** Accidental deletions go to the **Windows Recycle Bin** instead of permanent destruction. Dangerous commands (`format-volume`, `rmdir /s /q c:\`) are strictly blocked by default.
- **First-class Windows Integrations:** NVIDIA/WMI GPU telemetry, Windows Services management, native UTF-8 PowerShell runner, and headless Microsoft Edge PDF compilation.

---

## Key Features

1. **All-in-One Gateway & Web Monitor:**
   - **Streamable HTTP:** `http://<HOST>:8788/mcp` (Modern MCP standard)
   - **SSE Stream & POST:** `http://<HOST>:8788/sse` and `/message`
   - **Web Monitor Dashboard:** `http://<HOST>:8788/` (Interactive metrics, sessions, drives, memory, GPU, and live audit logs)
   - **Interactive File Viewer:** `http://<HOST>:8788/preview?path=...` (Rich Markdown & code viewer with syntax formatting)
   - **Health Check:** `http://<HOST>:8788/health`
2. **High-Observability Logging & Secret Masking:**
   - Microsecond execution timings with ANSI color-coded tags (`[HTTP]`, `[TOOL-START]`, `[TOOL-DONE]`, `[SECURITY]`).
   - Automatically sanitizes Bearer tokens, API keys (`sk-***`, `ghp_***`), AWS credentials (`AKIA***`), JSON properties (`"authToken"`, `"password"`, `"x-api-key"`), and sensitive arguments before printing or writing logs.
3. **Background Daemon Task Engine:**
   - Execute long-running dev servers (`npm run dev`, `docker compose up`) as background tasks with detached PIDs, non-blocking logs streaming, and interactive stdin support.
4. **High-Performance Code Search (Ripgrep):**
   - Integrates `ripgrep` (`rg.exe`) for fast regex search with streaming pagination (`page`, `pageSize`, `hasMore`) to prevent context window overflow.
5. **Headless PDF Generation:**
   - Converts Markdown and HTML into clean PDF documents using pre-installed Microsoft Edge or Chrome without requiring heavy dependencies like Puppeteer.
6. **Tailscale & Remote Ready:**
   - Optionally bind to `0.0.0.0` or your Tailscale IP (`100.x.y.z`) for cross-device access. Default is `127.0.0.1` (loopback-only). Non-loopback binding requires Bearer Token verification and is guarded by a startup safety gate.

---

## System Requirements

| Component | Minimum Requirement | Recommended | Notes |
| :--- | :--- | :--- | :--- |
| **Operating System** | Windows 10 / 11 / Server 2019+ | Windows 11 (64-bit) | Native Win32 & PowerShell APIs |
| **Node.js** | Node.js >= 20.0.0 | Node.js 20+ LTS | Not required if using `dist/winhelm.exe` |
| **PowerShell** | Windows PowerShell 5.1 | PowerShell 7+ (pwsh) | Auto-detects pwsh with UTF-8 encoding |
| **PDF Engine** | Microsoft Edge | Pre-installed on Win 10/11 | Google Chrome is also auto-detected |
| **Search Engine** | Built-in recursive search | `ripgrep` (`rg.exe`) | Install via `winget install BurntSushi.ripgrep.MSVC` |
| **Privileges** | Standard User | Standard User | Administrator is only needed for `service:install` |

---

## Architecture & Dashboard

### System Architecture

```mermaid
flowchart TD
    Client["AI Client (Claude / Cursor / Remote)"]

    subgraph WinHelm["WinHelm Server (Port 8788)"]
        subgraph Gateway["Single-Process Unified Gateway"]
            MCP_HTTP["Streamable HTTP (/mcp)"]
            MCP_SSE["SSE Gateway (/sse, /message)"]
            Dashboard["Web Monitor (/ & /dashboard)"]
            PreviewUI["File Preview (/preview)"]
            Health["Health & Audit Export (/health, /api/monitor/*)"]
        end

        subgraph Security["Security & Governance"]
            AuthGuard["Bearer Token Authentication"]
            RateLimit["Rate Limiter (120 req/min)"]
            PathGuard["Allowed Directories Guard"]
            CmdGuard["Blocked Commands Guard"]
            Sanitizer["Secret Masking (API Keys / Passwords)"]
        end

        subgraph Engines["Core Engine Layer"]
            PSEngine["PowerShell UTF-8 Runner"]
            TaskEngine["Background Daemon Task Engine"]
            FSEngine["Filesystem & Safe Delete (Recycle Bin)"]
            SearchEngine["Ripgrep Streaming Engine"]
            PDFEngine["Edge / Chrome Headless PDF Engine"]
            SysEngine["System, GPU & Windows Services Inspector"]
        end
    end

    subgraph Windows["Windows Operating System"]
        Win32["Win32 Shell / Recycle Bin"]
        PowerShell["PowerShell CLI / Tasks"]
        WMI_NVIDIA["WMI & nvidia-smi Telemetry"]
        SCM["Windows Service Control Manager"]
    end

    Client <--> Gateway
    Gateway --> Security
    Security --> Engines
    Engines <--> Windows
```

### Web Monitor & Live Dashboard

Access the built-in real-time dashboard in your browser at `http://localhost:8788/`:

![WinHelm Live Dashboard](assets/dashboard.png)

#### Live Task Execution & Telemetry Streaming

![WinHelm Live Demo](assets/demo.gif)

#### Interactive File & Markdown Preview (`preview://file`)

Access syntax-highlighted code and rendered Markdown directly at `http://localhost:8788/preview?path=<filepath>`:

![WinHelm Interactive File Preview](assets/preview.png)

---

## Quick Start

### 1. Installation & Setup

#### Option A: Standalone Executable (Recommended for Production)
Download the portable zero-dependency `winhelm.exe` from [GitHub Releases](https://github.com/dhammawatthumpra-coder/winhelm-mcp/releases) or compile locally with `npm run build:exe`. Requires no Node.js runtime on Windows 10/11.

#### Option B: NPM CLI (Convenient for Dev & Testing)
```powershell
# Install globally
npm install -g winhelm-mcp

# Run immediately
winhelm --profile dev

# Or run on-demand with npx (no global install required)
npx winhelm-mcp --profile dev
```

#### Option C: Clone & Build from Source
```powershell
git clone https://github.com/dhammawatthumpra-coder/winhelm-mcp.git
cd winhelm-mcp
npm install
npm run build
```

### 2. Start the Server

```powershell
# Start standard server on port 8788 (full profile)
npm start

# Or start with a lightweight profile for coding agents (dev) or small models (minimal)
node dist/index.js --profile dev

# Or customize port and bearer token via CLI flags
node dist/index.js --port 8788 --auth my-secret-token

# Or run in Read-Only mode (disallows file edits, deletions, and killing processes)
node dist/index.js --read-only
```

### 3. Verify Health Check

Visit `http://localhost:8788/health` in your browser. You should receive:
```json
{
  "status": "ok",
  "server": "winhelm-mcp",
  "version": "1.1.0",
  "activeSessions": {
    "sse": 0,
    "streamableHttp": 0
  },
  "uptimeSeconds": 12,
  "timestamp": "2026-09-28T08:00:00.000Z"
}
```

---

## Tool Profiles ("Load Only What You Need")

AI coding assistants perform much better when their context window isn't bloated with dozens of unneeded tool schemas. WinHelm implements a **Dynamic Profile System** so your agent sees only the tools it actually needs:

```powershell
# 1. Minimal Profile: 6 essential tools for small models (Haiku, Llama 8B, local LLMs)
winhelm --profile minimal

# 2. Core Profile: 15 essential tools (terminal, file read/write/edit/search/hash, process list, telemetry)
winhelm --profile core

# 3. Developer Profile: 28 tools (Core + background tasks, ripgrep, zip archives, HTTP requests, PDF reports, system open & file preview)
winhelm --profile dev

# 4. SysAdmin Profile: 37 tools (All Core + tasks, ripgrep, archives, services, event logs, network, process kill, desktop automation & preview — all except pdf_generate)
winhelm --profile sysadmin

# 5. Full Suite: All 38 tools + interactive preview resource (default)
winhelm --profile full
```

### Profile Inclusions

| Profile | Active Tools | Key Inclusions | Context Window Savings |
| :--- | :---: | :--- | :--- |
| **`minimal`** | **6** | `terminal_run`, `file_read`, `file_write`, `file_list`, `file_search`, `system_info` | 🟢 **~85% token reduction** |
| **`core`** | **15** | `terminal_run`, `file_read`, `file_write`, `file_edit`, `file_list`, `file_search`, `file_copy`, `file_move`, `file_tail`, `file_hash`, `file_delete_safe`, `system_info`, `gpu_info`, `process_list`, `port_check` | 🟢 **~60% token reduction** |
| **`dev`** | **28** | All Core + `terminal_task_*` (5 tasks), `file_search_ripgrep`, `archive_zip/unzip`, `http_ping/request`, `pdf_generate`, `system_open`, `preview://file` | 🟡 **~30% token reduction** |
| **`sysadmin`** | **37** | All tools except `pdf_generate`: Core + tasks, ripgrep, archives, services, event logs, network, process kill, desktop actions & preview | 🟠 Full Windows ops toolkit |
| **`full`** | **38** | All 38 tools + interactive HTML preview resource (default when omitted) | 🔵 Complete Windows control |

### Token Economics & Model Optimization

| Profile | Tools | Approx Context Tokens | Token Savings | Recommended Target Models & Use Cases |
| :--- | :---: | :---: | :---: | :--- |
| **`minimal`** | **6** | **~1,500** | 🟢 **−85%** | **Claude 3.5 Haiku, Llama 3 8B, local LLMs** or token-constrained pipelines |
| **`core`** | **15** | **~4,000** | 🟢 **−60%** | Everyday coding & file operations without background processes |
| **`dev`** | **28** | **~6,800** | 🟡 **−32%** | **Claude 3.7 Sonnet, GPT-4o, Cursor** full-stack software development |
| **`sysadmin`** | **37** | **~9,200** | 🟠 **−8%** | Headless server management, Windows DevOps, diagnostics & audit |
| **`full`** | **38** | **~10,000** | 🔵 **Baseline** | Complete Windows native desktop suite with PDF & HTML visual previews |

> **Pro Tip:** In `claude_desktop_config.json`, pass `["--profile", "dev"]` under `args` for software development, or `["--profile", "minimal"]` for Claude Haiku!

---

## Client Configuration

### 1. Claude Desktop (`claude_desktop_config.json`)

Path: `%APPDATA%\Claude\claude_desktop_config.json`

#### Option A: Zero-Install via npx (Easiest & Recommended)
```json
{
  "mcpServers": {
    "winhelm": {
      "command": "npx",
      "args": ["-y", "winhelm-mcp", "--stdio", "--profile", "dev"],
      "env": {
        "MCP_ALLOWED_DIRECTORIES": "D:\\Workspace,C:\\Projects"
      }
    }
  }
}
```
> **Instant Setup:** Runs the latest official `winhelm-mcp` directly from npm on demand without manual cloning or global installation. Specify permitted workspace paths in `MCP_ALLOWED_DIRECTORIES`.

#### Option B: Remote / Local SSE Gateway
```json
{
  "mcpServers": {
    "winhelm": {
      "url": "http://127.0.0.1:8788/sse",
      "headers": {
        "Authorization": "Bearer my-secret-token"
      }
    }
  }
}
```

#### Option C: Direct Stdio / Node Process (From Source)
```json
{
  "mcpServers": {
    "winhelm": {
      "command": "node",
      "args": ["<PATH_TO_WINHELM>/dist/index.js", "--stdio", "--profile", "dev"],
      "env": {
        "MCP_ALLOWED_DIRECTORIES": "D:\\mcp,C:\\Projects"
      }
    }
  }
}
```
> **Context Optimization:** Supplying `"--profile", "dev"` restricts tools to 28 developer essentials, saving ~32% context tokens while preserving all coding, ripgrep, background task, PDF, archive, and preview capabilities.

#### Option D: Standalone Executable (`winhelm.exe`)
```json
{
  "mcpServers": {
    "winhelm": {
      "command": "<PATH_TO_WINHELM>\\dist\\winhelm.exe",
      "args": ["--stdio", "--profile", "dev"]
    }
  }
}
```

#### Option E: Per-Project Dedicated Config File (Isolated Profiles & Roots)
```json
{
  "mcpServers": {
    "winhelm-project-a": {
      "command": "winhelm",
      "args": ["--stdio", "--config", "D:\\mcp\\configs\\project-a.json"]
    }
  }
}
```
> **Multi-Instance Isolation:** Each project config file maintains its own isolated `allowedDirectories`, `profile`, and security rules without modifying the shared default `winhelm.config.json`. CLI overrides are session-only (`--no-persist` by default) to prevent instances from colliding.

---

### 2. Cursor IDE

In Cursor Settings (`Settings` -> `Features` -> `MCP` -> `Add new MCP server`):

- **Name:** `winhelm`
- **Type:** `sse`
- **URL:** `http://127.0.0.1:8788/sse`

*(If authentication is configured, add `"Authorization": "Bearer <YOUR_TOKEN>"` to the headers section).*

---

### 3. ChatGPT & OpenAI MCP Tunnel (`tunnel-client`)

WinHelm integrates seamlessly with OpenAI's official `tunnel-client` daemon, allowing ChatGPT to execute Windows commands, inspect files, and manage background tasks directly over a secure Cloudflare Tunnel:

#### Profile Configuration (`winhelm-mcp.yaml`)
```yaml
config_version: 1

control_plane:
  base_url: "https://api.openai.com"
  tunnel_id: "your-tunnel-id-here"
  api_key: "env:CONTROL_PLANE_API_KEY"

health:
  listen_addr: "127.0.0.1:18026"

admin_ui:
  open_browser: false

log:
  level: info
  format: json

mcp:
  commands:
    # Direct stdio connection with dev profile (~32% token savings for ChatGPT)
    - channel: main
      command: 'node D:/mcp/winhelm-mcp/dist/index.js --stdio --profile dev'
```

#### Running the Tunnel
```powershell
.\tunnel-client.exe run --profile-file winhelm-mcp.yaml
```
> **Purity Guard:** In `--stdio` mode, WinHelm routes all operational logs to `stderr`, leaving `stdout` purely for JSON-RPC messages to guarantee zero parsing errors on ChatGPT.

---

### 4. Remote & Tailscale Connection

WinHelm binds by default to `127.0.0.1` (localhost only). To allow secure cross-device access over private networks like Tailscale or WireGuard, bind to `0.0.0.0` or your Tailscale IP:

1. Retrieve your machine's Tailscale IP (e.g. `100.80.20.10`) or Tailscale Funnel domain (e.g. `https://your-node.ts.net`).
2. Start WinHelm with `--host 0.0.0.0` and a strong authentication token:
   ```powershell
   node dist/index.js --port 8788 --host 0.0.0.0 --auth super-secure-token-here
   ```
   > ⚠️ **Host Safety Gate:** Binding to `--host 0.0.0.0` exposes the server to your local network and Tailscale. You **must** supply an authentication token (`--auth`), otherwise startup will be rejected with exit code 1 by the host safety gate.
3. Connect your mobile or remote Claude / Cursor / ChatGPT client:
   - **Streamable HTTP:** `http://100.80.20.10:8788/mcp`
   - **SSE Stream:** `http://100.80.20.10:8788/sse`
   - **Web Monitor Dashboard:** `http://100.80.20.10:8788/?token=super-secure-token-here` (or Tailscale Funnel URL)
   - **Header:** `Authorization: Bearer super-secure-token-here`

#### Claude.ai Custom Connectors (URL Query Token)

Claude.ai Custom Connectors and certain web/mobile clients do not provide a UI field to enter custom HTTP headers (such as `Authorization: Bearer <token>`). WinHelm natively supports passing the authentication token directly via the URL query parameter:

- **Server URL:** `https://<your-tailnet-domain>.ts.net/mcp?token=<YOUR_AUTH_TOKEN>`
- **Authentication:** Select **`No sign-in`**
- **Transport (under Advanced):** Streamable HTTP (Default)

> 🔒 **Security Guarantee:** Passing the token in the URL query parameter still triggers full timing-safe cryptographic verification on the server, ensuring your Windows machine remains completely protected from unauthorized internet access without needing a complex OAuth setup.

---

## Tools Overview (38 Tools)

WinHelm provides 38 focused Windows native tools grouped across 6 functional categories. Each tool is loaded dynamically based on your active `--profile`:

| Category | Tools | In Profiles | Summary |
| :--- | :---: | :--- | :--- |
| **Terminal & Background Tasks** | 6 | `minimal` (run only), `core` (run only), `dev`, `sysadmin`, `full` | Synchronous PowerShell runner and detached daemon processes with live logs & stdin. |
| **Filesystem, Safe Delete & Archives** | 12 | `minimal` (read, write, list, search), `core` (10 tools), `dev` (all 12), `sysadmin` (all 12), `full` (all 12) | Surgical file edits, streaming tails, SHA-256 hashes, .NET zip archives, and **Recycle Bin safe delete**. |
| **Codebase Search, PDF & Preview** | 3 | `dev` (all 3), `sysadmin` (search & preview), `full` (all 3) | Streaming paginated `ripgrep` regex search (`query` parameter), headless Chromium PDF printer, and web previewer. |
| **Desktop, Clipboard & Toast** | 5 | `dev` (`system_open`), `sysadmin` (all 5), `full` (all 5) | Windows clipboard read/write, primary screen capture, system app launcher (`system_open`), and native Toast notifications. |
| **System, Processes & Services** | 9 | `minimal` (`system_info`), `core` (info, gpu, procs, port), `sysadmin` (all 9), `full` (all 9) | CPU/RAM/Drive telemetry, NVIDIA GPU stats, process list/kill, port inspector, event logs, and service control. |
| **Network & Connectivity** | 3 | `dev` (ping, req), `sysadmin` (all 3), `full` (all 3) | HTTP latency probe, full REST client (`http_request`), and local/Tailscale adapter inspector. |

📖 **See [docs/TOOLS.md](docs/TOOLS.md) for full parameter specifications, types, returns, and schemas.**

---

## MCP Resources & Web Endpoints

### MCP Resources

WinHelm exposes 1 dedicated Model Context Protocol resource:

| URI | MIME Type | Description |
| :--- | :--- | :--- |
| `preview://file` | `text/html;profile=mcp-app` | Dynamically renders rich HTML preview for Markdown and source code files with line numbers and syntax highlighting. |

---

### Gateway Web Endpoints

WinHelm hosts a full web application on a single port (default: `8788`):

- **`/` & `/dashboard`** — Real-time Web Monitor Dashboard (CPU, RAM, GPU, sessions, requests, live logs).
- **`/mcp`** — Streamable HTTP transport endpoint.
- **`/sse`** — Server-Sent Events transport endpoint for clients like Claude Desktop and Cursor.
- **`/message`** — POST endpoint for incoming JSON-RPC messages in SSE mode.
- **`/preview`** — Interactive browser file viewer (`/preview?path=D:\project\README.md`).
- **`/health`** — JSON health status and server uptime probe.
- **`/api/monitor/stats`** — JSON hardware and session statistics.
- **`/api/monitor/export?format=json|csv`** — Audit log export for security compliance.

> 💡 **Browser Dashboard Access with Authentication:**  
> When authentication is enabled (`--auth <token>` or `authToken`), accessing the Web Monitor Dashboard or Previewer via your browser requires passing the token once in the URL:  
> - **Dashboard:** `http://<HOST>:8788/?token=<YOUR_AUTH_TOKEN>` (or `https://<your-tailnet-domain>.ts.net/?token=<YOUR_AUTH_TOKEN>`)  
> - **File Preview:** `http://<HOST>:8788/preview?path=D:\project\README.md&token=<YOUR_AUTH_TOKEN>`  
> WinHelm validates the token, displays live metrics and real-time logs, and sets a secure `HttpOnly` session cookie so subsequent dashboard navigation stays authenticated without re-entering the token.

---

## Configuration & Environment Variables

WinHelm loads configuration in the following order of precedence:
1. CLI Flags
2. Environment Variables
3. `winhelm.config.json`
4. Default settings

### Reference Table

| CLI Flag | Environment Variable | Default | Description |
| :--- | :--- | :--- | :--- |
| `--config <path>` | *N/A* | *auto* | Load configuration from a specific JSON file (for per-project multi-agent isolation). |
| `--stdio` | *N/A* | `false` | Run in standard I/O mode for local MCP clients (OpenAI tunnel-client, Claude, Cursor). |
| `--profile, -p <name>` | `WINHELM_PROFILE` | `full` | Tool profile to load: `minimal` (6), `core` (15), `dev` (28), `sysadmin` (37), or `full` (38). |
| `--tools <list>` | *N/A* | *auto* | Explicit comma-separated tools to load or `+tool`/`-tool` modifiers. |
| `--transport <type>` | `WINHELM_TRANSPORT` | `http` | Transport mode: `http` (Web Gateway + SSE) or `stdio`. |
| `--port <number>` | `PORT` | `8788` | Port number for the Web Gateway and MCP server. |
| `--host <string>` | `HOST` | `127.0.0.1` | Network interface to bind (`127.0.0.1` loopback default, `0.0.0.0` for LAN/Tailscale). |
| `--auth <token>` | `MCP_AUTH_TOKEN` | *none* | Bearer token for authentication. Rejects unauthenticated requests with HTTP 401. |
| `--read-only` | `MCP_READ_ONLY` | `false` | Enables read-only mode (strictly blocks file writing, shell execution, process killing, service modification, and mutating HTTP requests). |
| `--allowed-dirs <list>`| `MCP_ALLOWED_DIRECTORIES` | `[]` *(block all)* | Comma-separated directory paths permitted for file access (e.g. `"D:\mcp,C:\Workspace"`). Empty = block all filesystem operations (fail-closed). |
| `--no-persist` | *N/A* | `true` | Keep CLI overrides session-only without writing to `winhelm.config.json` (default behavior / explicit no-op). |
| `--persist` | *N/A* | `false` | Persist CLI overrides back to the active configuration file. |
| *N/A* | `MCP_BLOCKED_COMMANDS` | *(see below)* | Additional comma-separated commands to block from execution. |
| *N/A* | `MCP_ALLOWED_HOSTS` | `localhost,127.0.0.1,*.ts.net` | Comma-separated allowed hostnames for Host header validation (DNS Rebinding protection). |

### `winhelm.config.json`

Create or modify `winhelm.config.json` in your project root or `%USERPROFILE%\.winhelm\config.json`:

```json
{
  "blockedCommands": [
    "format-volume",
    "format-disk",
    "clear-disk",
    "stop-computer",
    "restart-computer",
    "rmdir /s /q c:\\",
    "del /f /s /q c:\\"
  ],
  "allowedDirectories": ["D:\\mcp", "C:\\Workspace"],
  "allowSystemExecution": true,
  "profile": "dev",
  "fileReadLineLimit": 2000,
  "defaultTimeoutMs": 60000,
  "telemetryEnabled": false,
  "authToken": null,
  "readOnly": false,
  "rateLimitWindowMs": 60000,
  "rateLimitMaxRequests": 120
}
```

> **Security Boundaries vs. Defense-in-Depth:**  
> - **True Security Boundaries:** **Authentication Token (`authToken`)**, **Tool Profiles (`minimal`, `core`)**, and **Read-Only Mode (`readOnly`)**. For untrusted or public environments, configure an `authToken` and use `--profile core` to exclude terminal execution completely.  
> - **Defense-in-Depth:** The command blocklist protects against accidental destructive commands (`format-volume`, `rmdir /s /q c:\`), but is not an impenetrable sandbox. `allowedDirectories` strictly bounds native File Tools (`file_read`, `file_write`, `create_zip`, etc.) and default CWD.  
> - **DNS Rebinding Defense:** WinHelm validates `Host` headers against an allowlist (`localhost`, `127.0.0.1`, `[::1]`, `*.ts.net`). Requests from unauthorized hostnames are rejected with **HTTP 403 Forbidden**.  
> - **Remote Tunnel Fail-Closed Gate:** Requests arriving through a reverse proxy or tunnel without an `authToken` configured are rejected immediately with **HTTP 403 Forbidden**.  
> - **Fail-Closed Filesystem:** `allowedDirectories: []` blocks all filesystem operations by default. Specify target paths (e.g. `["D:\\mcp", "C:\\Workspace"]`). Wildcard `["*"]` is strictly discouraged for unauthenticated or public network exposures.

---

## Windows Background Service (Always-On Daemon)

WinHelm includes a built-in service manager using Windows Task Scheduler to run reliably in the background across system reboots:

```powershell
# Install as a persistent Windows Service (Run PowerShell as Administrator)
npm run service:install

# Check service status
npm run service:status

# Stop / Start the service
npm run service:stop
npm run service:start

# Uninstall the service
npm run service:uninstall
```

---

## Standalone Single-File Executable (`winhelm.exe`)

You can compile WinHelm into a standalone `.exe` (~2.6 MB) that requires **no Node.js installation** on target machines:

```powershell
npm run build:exe
```

The resulting executable will be generated at `dist/winhelm.exe`:

```powershell
# Run standalone executable with custom port
.\dist\winhelm.exe --port 9000 --auth my-token
```

---

## Security, Rate Limiting & Auditing

1. **Automatic Secret Redaction:**
   - Automatically sanitizes sensitive keys (`sk-...`, `ghp_...`, `Bearer ********`, and password values) from terminal output, dashboard UI, and log files.
2. **Built-in Rate Limiting (Sliding Window):**
   - Enforces a sliding window ceiling of 120 requests per minute per IP address, preventing runaway client loops.
3. **Auditing & Log Rotation:**
   - Logs are stored in `logs/winhelm-YYYY-MM-DD.log` (capped at 10 MB per file, auto-pruning logs older than 7 days).
   - Export audit logs anytime via browser or API:
     - `http://localhost:8788/api/monitor/export?format=json`
     - `http://localhost:8788/api/monitor/export?format=csv`
4. **Fail-Closed Filesystem Confinement:**
   - `allowedDirectories: []` blocks all filesystem operations by default for safety.
   - Symlinks and NTFS directory junctions are resolved via `fs.realpathSync` before boundary evaluation.
5. **Loopback-First Network Binding:**
   - Default host is `127.0.0.1` (loopback only).
   - Non-loopback binding (such as `0.0.0.0`) without `--auth` is blocked at startup with exit code 1.
   - Bearer tokens are compared using `crypto.timingSafeEqual` with buffer length validation to prevent timing side-channels.

---

## Troubleshooting

### 1. Port Conflict (`EADDRINUSE: address already in use :::8788`)
- **Cause:** Another process or previous instance is using port 8788.
- **Solution:** Specify a different port using `--port`:
  ```powershell
  node dist/index.js --port 8790
  ```
  Or check which process is holding port 8788:
  ```powershell
  Get-NetTCPConnection -LocalPort 8788 | Select-Object OwningProcess
  ```

### 2. HTTP 401 Unauthorized
- **Cause:** WinHelm was started with `--auth <token>` or `MCP_AUTH_TOKEN`, but the MCP client didn't supply matching credentials.
- **Solution 1 (Clients with Custom Header Support):** Add the Bearer token header to your client configuration:
  ```json
  "headers": {
    "Authorization": "Bearer <YOUR_TOKEN>"
  }
  ```
- **Solution 2 (Claude.ai Custom Connectors without Header UI):** Append the token directly to the Server URL and select **No sign-in**:
  ```text
  https://<your-domain>/mcp?token=<YOUR_TOKEN>
  ```
- **Solution 3 (Browser Dashboard & File Preview):** Append `?token=<YOUR_TOKEN>` to the URL in your browser:
  ```text
  https://<your-domain>/?token=<YOUR_TOKEN>
  https://<your-domain>/preview?path=...&token=<YOUR_TOKEN>
  ```

### 3. PowerShell Execution Policy Restriction
- **Cause:** Windows blocks script execution (`File cannot be loaded because running scripts is disabled on this system`).
- **Solution:** Run with bypass flag:
  ```powershell
  Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
  ```

### 4. Windows Service Installation Error (`Access is denied`)
- **Cause:** `npm run service:install` registers a task in Windows Task Scheduler, which requires elevated privileges.
- **Solution:** Open PowerShell as **Administrator** and re-run `npm run service:install`.

### 5. Tailscale / Remote Timeout
- **Cause:** Windows Defender Firewall is blocking inbound connections on port 8788.
- **Solution:** Allow port 8788 in Windows Firewall:
  ```powershell
  New-NetFirewallRule -DisplayName "WinHelm MCP Gateway" -Direction Inbound -LocalPort 8788 -Protocol TCP -Action Allow
  ```

### 6. PDF Generation Headless Browser Not Found
- **Cause:** Neither Microsoft Edge nor Google Chrome could be located in default system paths.
- **Solution:** Ensure Microsoft Edge is installed at its standard location (`C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`) or install Google Chrome.

### 7. Host Safety Gate Blocks Startup (`Non-loopback binding requires --auth`)
- **Cause:** You attempted to bind to a non-loopback address (such as `0.0.0.0`) without specifying an authentication token.
- **Solution:** Add `--auth <token>` or set the `MCP_AUTH_TOKEN` environment variable. This security gate prevents accidental public exposure of your host system without authentication.

---

## Documentation & Deep Dive

For in-depth guides, architectural references, and developer guidelines, explore the `docs/` folder:

- 📖 **[Comprehensive Tools Reference](docs/TOOLS.md)**: Exhaustive documentation for all 38 tools, including parameter types, options, return formats, and JSON-RPC examples.
- ⚙️ **[Tool Profiles & Context Optimization](docs/PROFILES.md)**: Deep dive into the 5 built-in profiles (minimal, core, dev, sysadmin, full), custom `--tools` filtering, token economics, and LLM optimization recipes.
- 🛡️ **[Security Model & Architecture](docs/SECURITY.md)**: Deep dive into the 5-layer security model, path confinement, regex command blacklists, and secret masking.
- 💡 **[Real-World Agent Examples](docs/EXAMPLES.md)**: End-to-end workflows showing how AI agents build projects, troubleshoot Windows crashes, and generate executive PDFs.
- 📝 **[Changelog](CHANGELOG.md)**: Release notes and version history following Keep a Changelog.
- 🤝 **[Contributing Guide](CONTRIBUTING.md)**: Instructions for developing, running tests, and opening Pull Requests.

---

## License

This project is licensed under the [MIT License](LICENSE) — see the [LICENSE](LICENSE) file for details.  
Built cleanly from the ground up for the Windows Model Context Protocol developer community.