winhelm-mcp 1.1.0

package/docs/TOOLS.md

@@ -0,0 +1,366 @@
+# WinHelm MCP — Comprehensive Tools Reference
+
+WinHelm provides **38 native Windows tools** and **1 MCP Resource** designed for AI coding agents and desktop automation.
+
+---
+
+## Tool Profiles Matrix
+
+WinHelm supports loading subset profiles to prevent prompt context bloat:
+
+| Tool Name | `minimal` (6) | `core` (15) | `dev` (28) | `sysadmin` (37) | `full` (38) | Category | Description |
+| :--- | :---: | :---: | :---: | :---: | :---: | :--- | :--- |
+| `terminal_run` | ✅ | ✅ | ✅ | ✅ | ✅ | Terminal | Synchronous PowerShell runner with UTF-8 encoding |
+| `terminal_task_start` | ❌ | ❌ | ✅ | ✅ | ✅ | Terminal | Starts detached background daemon task |
+| `terminal_task_list` | ❌ | ❌ | ✅ | ✅ | ✅ | Terminal | Lists active and exited background tasks |
+| `terminal_task_logs` | ❌ | ❌ | ✅ | ✅ | ✅ | Terminal | Retrieves buffered output logs of a task |
+| `terminal_task_send` | ❌ | ❌ | ✅ | ✅ | ✅ | Terminal | Sends interactive input (`stdin`) to a task |
+| `terminal_task_kill` | ❌ | ❌ | ✅ | ✅ | ✅ | Terminal | Terminates a background task process tree |
+| `file_read` | ✅ | ✅ | ✅ | ✅ | ✅ | Filesystem | Reads file content with optional line slicing |
+| `file_write` | ✅ | ✅ | ✅ | ✅ | ✅ | Filesystem | Writes UTF-8 file (creates directories) |
+| `file_edit` | ❌ | ✅ | ✅ | ✅ | ✅ | Filesystem | Precise surgical text replacement |
+| `file_list` | ✅ | ✅ | ✅ | ✅ | ✅ | Filesystem | Lists directory entries with stats |
+| `file_search` | ✅ | ✅ | ✅ | ✅ | ✅ | Filesystem | Substring search across files |
+| `file_delete_safe` | ❌ | ✅ | ✅ | ✅ | ✅ | Filesystem | Moves file to Windows Recycle Bin (recoverable) |
+| `file_move` | ❌ | ✅ | ✅ | ✅ | ✅ | Filesystem | Atomically moves or renames a file/folder |
+| `file_copy` | ❌ | ✅ | ✅ | ✅ | ✅ | Filesystem | Recursively copies files or directories |
+| `archive_zip` | ❌ | ❌ | ✅ | ✅ | ✅ | Filesystem | Compresses directory to `.zip` via native .NET |
+| `archive_unzip` | ❌ | ❌ | ✅ | ✅ | ✅ | Filesystem | Extracts `.zip` archive via native .NET |
+| `file_tail` | ❌ | ✅ | ✅ | ✅ | ✅ | Filesystem | Reads trailing N lines of large files/logs |
+| `file_hash` | ❌ | ✅ | ✅ | ✅ | ✅ | Filesystem | Computes SHA-256, MD5, or SHA-1 checksum |
+| `file_search_ripgrep` | ❌ | ❌ | ✅ | ✅ | ✅ | Codebase | Fast regex code search with streaming pagination |
+| `pdf_generate` | ❌ | ❌ | ✅ | ❌ | ✅ | Document | Generates styled PDF via headless Edge/Chrome |
+| `file_preview` | ❌ | ❌ | ✅ | ✅ | ✅ | Preview | File metadata and web preview URL |
+| `clipboard_get` | ❌ | ❌ | ❌ | ✅ | ✅ | Desktop | Reads text from Windows Clipboard |
+| `clipboard_set` | ❌ | ❌ | ❌ | ✅ | ✅ | Desktop | Writes text to Windows Clipboard |
+| `screen_capture` | ❌ | ❌ | ❌ | ✅ | ✅ | Desktop | Captures desktop screenshot (base64 PNG) |
+| `system_open` | ❌ | ❌ | ✅ | ✅ | ✅ | Desktop | Opens URL, file, or folder in default app |
+| `notification_send` | ❌ | ❌ | ❌ | ✅ | ✅ | Desktop | Dispatches Windows native Toast Notification |
+| `system_info` | ✅ | ✅ | ✅ | ✅ | ✅ | System | OS version, CPU, RAM, drives & uptime |
+| `gpu_info` | ❌ | ✅ | ✅ | ✅ | ✅ | System | NVIDIA GPU telemetry (VRAM, temp) or WMI |
+| `process_list` | ❌ | ✅ | ✅ | ✅ | ✅ | System | Lists top processes sorted by RAM or CPU |
+| `process_kill` | ❌ | ❌ | ❌ | ✅ | ✅ | System | Kills process by PID or executable name |
+| `port_check` | ❌ | ✅ | ✅ | ✅ | ✅ | System | Checks TCP port usage and owning PID |
+| `eventlog_query` | ❌ | ❌ | ❌ | ✅ | ✅ | System | Queries Windows Event Log (errors/warnings) |
+| `service_list` | ❌ | ❌ | ❌ | ✅ | ✅ | Services | Lists Windows Services and status |
+| `service_status` | ❌ | ❌ | ❌ | ✅ | ✅ | Services | Detailed status and PID of a service |
+| `service_control` | ❌ | ❌ | ❌ | ✅ | ✅ | Services | Starts, stops, or restarts a service |
+| `http_ping` | ❌ | ❌ | ✅ | ✅ | ✅ | Network | Fast HTTP latency and health probe |
+| `http_request` | ❌ | ❌ | ✅ | ✅ | ✅ | Network | Dispatches HTTP requests (GET/POST/etc.) |
+| `network_info` | ❌ | ❌ | ❌ | ✅ | ✅ | Network | Network adapters, IPs, DNS, and Tailscale |
+| `preview://file` *(Resource)* | ❌ | ❌ | ✅ | ✅ | ✅ | MCP Resource | Dynamic interactive HTML preview resource |
+
+---
+
+## Table of Contents
+
+1. [Terminal & Background Execution](#1-terminal--background-execution) (6 tools)
+2. [Filesystem, Safe Delete & Archives](#2-filesystem-safe-delete--archives) (12 tools)
+3. [Codebase Search, PDF & Preview](#3-codebase-search-pdf--preview) (3 tools)
+4. [Desktop & Productivity](#4-desktop--productivity) (5 tools)
+5. [System, Processes & Windows Services](#5-system-processes--windows-services) (9 tools)
+6. [Network & Web Diagnostics](#6-network--web-diagnostics) (3 tools)
+7. [MCP Resources](#7-mcp-resources) (1 resource)
+
+---
+
+## 1. Terminal & Background Execution
+
+### `terminal_run`
+Executes a PowerShell command synchronously with automatic UTF-8 encoding enforcement and timeout handling.
+- **Parameters:**
+  - `command` *(string, required)*: The PowerShell command to execute.
+  - `cwd` *(string, optional)*: Working directory for execution.
+  - `timeout_ms` *(number, optional, default: 60000)*: Timeout in milliseconds.
+- **Returns:** Text output containing stdout and stderr.
+
+### `terminal_task_start`
+Launches a long-running command in the background (e.g. dev servers, npm build, test watchers) returning a Task ID immediately.
+- **Parameters:**
+  - `command` *(string, required)*: Background command to run.
+  - `cwd` *(string, optional)*: Working directory.
+- **Returns:** `{ message: string, task: { id, command, cwd, pid, status, startTime } }`
+
+### `terminal_task_list`
+Lists all active, completed, or failed background tasks managed by WinHelm.
+- **Parameters:** None.
+- **Returns:** Array of background task objects.
+
+### `terminal_task_logs`
+Retrieves live buffered output logs and status from a running or completed background task.
+- **Parameters:**
+  - `task_id` *(string, required)*: Task ID returned from `terminal_task_start`.
+  - `tail_lines` *(number, optional, default: 100)*: Number of trailing lines to view.
+- **Returns:** Header with task status followed by recent standard output and error text.
+
+### `terminal_task_send`
+Sends interactive text/keystrokes directly to the `stdin` stream of a running background process.
+- **Parameters:**
+  - `task_id` *(string, required)*: Task ID of running process.
+  - `input` *(string, required)*: Text to send to stdin.
+- **Returns:** Confirmation message.
+
+### `terminal_task_kill`
+Terminates a running background task and its entire Windows process tree (`taskkill /T /F`) with zero orphan processes.
+- **Parameters:**
+  - `task_id` *(string, required)*: Task ID to terminate.
+- **Returns:** Confirmation message.
+
+---
+
+## 2. Filesystem, Safe Delete & Archives
+
+### `file_read`
+Reads file content in UTF-8, with optional 1-indexed line range slicing to conserve LLM context window.
+- **Parameters:**
+  - `path` *(string, required)*: File path.
+  - `start_line` *(number, optional)*: 1-indexed start line.
+  - `end_line` *(number, optional)*: 1-indexed end line.
+- **Returns:** Content string with line numbers when a range is specified.
+
+### `file_write`
+Writes or creates a file with UTF-8 encoding, creating parent directories automatically.
+- **Parameters:**
+  - `path` *(string, required)*: Target file path.
+  - `content` *(string, required)*: Full content to write.
+- **Returns:** Confirmation with bytes written.
+
+### `file_edit`
+Surgically replaces a unique block of text inside an existing file without modifying unrelated lines. Fails safely if `old_text` does not appear uniquely.
+- **Parameters:**
+  - `path` *(string, required)*: File path to edit.
+  - `old_text` *(string, required)*: Exact text block to replace.
+  - `new_text` *(string, required)*: Replacement text block.
+- **Returns:** Confirmation of successful replacement.
+
+### `file_list`
+Lists files and directories with size, type, and modification dates.
+- **Parameters:**
+  - `path` *(string, optional, default: ".")*: Directory path.
+  - `recursive` *(boolean, optional, default: false)*: Scan subdirectories up to 3 levels.
+- **Returns:** JSON directory listing.
+
+### `file_search`
+Quick substring or pattern search across files in a directory.
+- **Parameters:**
+  - `query` *(string, required)*: Search string to find within files.
+  - `path` *(string, optional, default: ".")*: Base folder path.
+  - `file_pattern` *(string, optional)*: File name filter (e.g. `.ts`, `.json`).
+- **Returns:** List of matching files and occurrences.
+
+### `file_delete_safe`
+Safely moves files or directories to the **Windows Recycle Bin** instead of permanent deletion. Items can be restored from the desktop Recycle Bin if deleted accidentally.
+- **Parameters:**
+  - `path` *(string, required)*: Target file or directory path.
+- **Returns:** Confirmation message.
+
+### `file_move`
+Atomically moves or renames a file or folder.
+- **Parameters:**
+  - `source` *(string, required)*: Source file or folder path.
+  - `destination` *(string, required)*: Destination path.
+  - `overwrite` *(boolean, optional, default: false)*: Overwrite existing destination.
+- **Returns:** Confirmation of move.
+
+### `file_copy`
+Recursively copies files or directories using native Windows shell operations.
+- **Parameters:**
+  - `source` *(string, required)*: Source path.
+  - `destination` *(string, required)*: Target destination path.
+  - `overwrite` *(boolean, optional, default: true)*: Overwrite existing target.
+- **Returns:** Confirmation of copy.
+
+### `archive_zip`
+Compresses a directory into a standard `.zip` archive using native Windows .NET APIs.
+- **Parameters:**
+  - `source_dir` *(string, required)*: Directory path to compress.
+  - `zip_path` *(string, required)*: Destination `.zip` file path.
+- **Returns:** Confirmation message.
+
+### `archive_unzip`
+Extracts a `.zip` archive into a target directory.
+- **Parameters:**
+  - `zip_path` *(string, required)*: Path to `.zip` file.
+  - `target_dir` *(string, required)*: Destination folder path.
+  - `overwrite` *(boolean, optional, default: true)*: Overwrite existing files.
+- **Returns:** Confirmation message.
+
+### `file_tail`
+Reads the trailing N lines of large log or data files with line numbers without exhausting LLM context.
+- **Parameters:**
+  - `path` *(string, required)*: Target file path.
+  - `lines` *(number, optional, default: 50)*: Number of trailing lines.
+- **Returns:** Trailing lines with line numbers.
+
+### `file_hash`
+Computes cryptographic hash digests of a file via low-memory chunked streaming.
+- **Parameters:**
+  - `path` *(string, required)*: Target file path.
+  - `algorithm` *(string, optional, default: "sha256")*: `"sha256"`, `"md5"`, or `"sha1"`.
+- **Returns:** `{ path: string, algorithm: string, hash: string, sizeBytes: number }`
+
+---
+
+## 3. Codebase Search, PDF & Preview
+
+### `file_search_ripgrep`
+High-speed codebase search using `ripgrep` (`rg.exe`) with regex, glob filters, and streaming pagination to prevent token blowups.
+- **Parameters:**
+  - `query` *(string, required)*: Search string or regex pattern.
+  - `path` *(string, optional, default: ".")*: Directory path to search.
+  - `file_pattern` *(string, optional)*: Glob pattern filter (e.g. `'*.ts'`, `'src/**'`).
+  - `case_sensitive` *(boolean, optional, default: false)*: Case-sensitive matching.
+  - `is_regex` *(boolean, optional, default: false)*: Treat query as regex.
+  - `page` *(number, optional, default: 1)*: Page number (1-based).
+  - `page_size` *(number, optional, default: 50, max: 200)*: Matches per page.
+  - `context_lines` *(number, optional, default: 0)*: Lines of context around matches.
+- **Returns:** Formatted list of matches with file, line, column, and text.
+
+### `pdf_generate`
+Converts Markdown text or Markdown file into a styled PDF document using headless Microsoft Edge or Google Chrome.
+- **Parameters:**
+  - `source_path` *(string, required)*: Path to input Markdown (`.md`), HTML, or text file.
+  - `pdf_path` *(string, required)*: Output destination `.pdf` file path.
+  - `landscape` *(boolean, optional, default: false)*: Landscape orientation.
+  - `title` *(string, optional)*: Document title for page headers.
+- **Returns:** PDF generation report with file size and browser engine used.
+
+### `file_preview`
+Generates file metadata and an interactive browser preview link.
+- **Parameters:**
+  - `path` *(string, required)*: File path to preview.
+  - `max_lines` *(number, optional, default: 50)*: Maximum snippet lines in response.
+- **Returns:** JSON object containing `previewUrl`, line count, file size, and preview snippet.
+
+---
+
+## 4. Desktop & Productivity
+
+### `clipboard_get`
+Reads current text from the Windows Clipboard.
+- **Parameters:** None.
+- **Returns:** Text content from clipboard.
+
+### `clipboard_set`
+Copies UTF-8 text into the Windows Clipboard.
+- **Parameters:**
+  - `text` *(string, required)*: Text to copy to clipboard.
+- **Returns:** Confirmation message.
+
+### `screen_capture`
+Takes a high-resolution screenshot of the Windows desktop and returns a base64-encoded PNG image.
+- **Parameters:** None.
+- **Returns:** MCP Image content block (PNG) and descriptive text.
+
+### `system_open`
+Opens a URL in the default browser, or opens a file/folder in Windows File Explorer.
+- **Parameters:**
+  - `target` *(string, required)*: URL, folder path, or file path to open.
+- **Returns:** Confirmation message.
+
+### `notification_send`
+Dispatches a native Windows Toast Notification to the Action Center.
+- **Parameters:**
+  - `title` *(string, required)*: Notification title.
+  - `message` *(string, required)*: Notification body text.
+  - `sound` *(boolean, optional, default: true)*: Play alert chime.
+- **Returns:** Confirmation message.
+
+---
+
+## 5. System, Processes & Windows Services
+
+### `system_info`
+Comprehensive hardware and OS summary: CPU model & cores, RAM (Total/Used/Free), OS version, allowed drive capacities, and uptime.
+- **Parameters:** None.
+- **Returns:** JSON system telemetry snapshot.
+
+### `gpu_info`
+Queries NVIDIA GPU metrics (model, VRAM total/used/free, temperature, driver version) via `nvidia-smi` with WMI fallback.
+- **Parameters:** None.
+- **Returns:** JSON GPU telemetry.
+
+### `process_list`
+Lists running Windows processes with PID, Process Name, RAM usage (Working Set MB), CPU %, and paths.
+- **Parameters:**
+  - `limit` *(number, optional, default: 20, max: 100)*: Max number of processes to return.
+  - `sort_by` *(string, optional, default: "memory")*: `"memory"`, `"cpu"`, `"name"`, or `"pid"`.
+  - `filter` *(string, optional)*: Substring filter on process name or path.
+- **Returns:** JSON array of process objects.
+
+### `process_kill`
+Terminates a Windows process safely by PID or Process Name.
+- **Parameters:**
+  - `pid` *(number, optional)*: Target Process ID.
+  - `name` *(string, optional)*: Target process name (e.g. `'node'`, `'notepad'`).
+- **Returns:** JSON termination result.
+
+### `port_check`
+Checks if a TCP port is currently open/listening and identifies the owning process PID and process name.
+- **Parameters:**
+  - `port` *(number, required)*: TCP port number to inspect (e.g. 8788, 3000).
+- **Returns:** JSON object containing `port`, `inUse`, `pid`, `processName`.
+
+### `eventlog_query`
+Queries the Windows Event Log (Application, System) for crash reports, error traces, and warnings.
+- **Parameters:**
+  - `log_name` *(string, optional, default: "Application")*: `"Application"` or `"System"`.
+  - `level` *(string, optional, default: "Error")*: `"Critical"`, `"Error"`, `"Warning"`, `"Information"`, or `"All"`.
+  - `hours` *(number, optional, default: 24)*: Retrieve events from the past N hours.
+  - `source` *(string, optional)*: Provider or application source filter.
+  - `limit` *(number, optional, default: 20, max: 100)*: Max events to retrieve.
+- **Returns:** JSON array of event log entries.
+
+### `service_list`
+Lists Windows Services with current status (`Running`, `Stopped`) and display names.
+- **Parameters:**
+  - `filter` *(string, optional)*: Substring filter on service name or display name.
+- **Returns:** JSON array of services.
+
+### `service_status`
+Inspects detailed status, startup type, and PID of a specific Windows Service.
+- **Parameters:**
+  - `service_name` *(string, required)*: Exact name of the service (e.g. `'wslservice'`, `'ssh-agent'`).
+- **Returns:** JSON service details.
+
+### `service_control`
+Starts, stops, or restarts a Windows Service (requires appropriate privileges).
+- **Parameters:**
+  - `service_name` *(string, required)*: Exact name of the service.
+  - `action` *(string, required)*: `"start"`, `"stop"`, or `"restart"`.
+- **Returns:** JSON execution status.
+
+---
+
+## 6. Network & Web Diagnostics
+
+### `http_ping`
+Rapidly pings an HTTP/HTTPS endpoint to measure roundtrip latency in milliseconds, status code, and header info.
+- **Parameters:**
+  - `url` *(string, required)*: Target HTTP/HTTPS URL.
+  - `timeout_ms` *(number, optional, default: 5000)*: Timeout in milliseconds.
+  - `expected_status` *(number, optional)*: Expected HTTP status code (default: any 2xx).
+- **Returns:** JSON latency and response status.
+
+### `http_request`
+Dispatches an HTTP request (GET, POST, PUT, DELETE, PATCH, HEAD) with custom headers and payload for REST API testing.
+- **Parameters:**
+  - `url` *(string, required)*: Target URL.
+  - `method` *(string, optional, default: "GET")*: HTTP method.
+  - `headers` *(object, optional)*: Key-value map of HTTP headers.
+  - `body` *(string, optional)*: Request payload string.
+  - `timeout_ms` *(number, optional, default: 15000)*: Timeout in milliseconds.
+- **Returns:** Response status, duration, headers, and parsed body.
+
+### `network_info`
+Retrieves local IP addresses, network adapters, Default Gateway, DNS servers, and Tailscale IP (`100.x.y.z`).
+- **Parameters:**
+  - `include_listening_ports` *(boolean, optional, default: false)*: Include list of listening TCP ports.
+- **Returns:** JSON network summary.
+
+---
+
+## 7. MCP Resources
+
+### `preview://file`
+Interactive file preview resource registered on the MCP Server (`text/html;profile=mcp-app`). Allows MCP client apps and web browsers to view syntax-highlighted code and rendered Markdown at `http://localhost:8788/preview?path=<filepath>`.

package/manifest.json

@@ -0,0 +1,74 @@
+{
+  "manifest_version": "0.3",
+  "name": "winhelm-mcp",
+  "version": "1.1.0",
+  "description": "WinHelm - Windows Native MCP Server with Unified HTTP/SSE/Streamable Gateway and 38 System Tools",
+  "long_description": "WinHelm is a lightweight, all-in-one MCP server designed for the Windows operating system. It embeds a native Streamable HTTP and SSE gateway, complete with Web Monitor, UTF-8 PowerShell runner, surgical file editor, Ripgrep search, PDF generation, clipboard, screen capture, and system inspection tools.",
+  "author": {
+    "name": "dhammawatthumpra-coder",
+    "email": "dhammawatthumpra@gmail.com",
+    "url": "https://github.com/dhammawatthumpra-coder"
+  },
+  "homepage": "https://github.com/dhammawatthumpra-coder/winhelm-mcp",
+  "documentation": "https://github.com/dhammawatthumpra-coder/winhelm-mcp#readme",
+  "server": {
+    "type": "node",
+    "entry_point": "dist/index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/dist/index.js",
+        "--port",
+        "${user_config.port}",
+        "--host",
+        "${user_config.host}"
+      ],
+      "env": {
+        "PORT": "${user_config.port}",
+        "HOST": "${user_config.host}",
+        "MCP_AUTH_TOKEN": "${user_config.auth_token}",
+        "MCP_ALLOWED_DIRECTORIES": "${user_config.allowed_directories}",
+        "MCP_ALLOWED_HOSTS": "${user_config.allowed_hosts}"
+      }
+    }
+  },
+  "user_config": {
+    "port": {
+      "type": "number",
+      "title": "Server Port",
+      "description": "Port on which the HTTP, SSE, and Streamable HTTP gateway listens.",
+      "required": false,
+      "default": 8788,
+      "minimum": 1024,
+      "maximum": 65535
+    },
+    "host": {
+      "type": "string",
+      "title": "Bind Host",
+      "description": "Network host interface to bind (e.g. 127.0.0.1 for local only, 0.0.0.0 for Tailscale/LAN).",
+      "required": false,
+      "default": "127.0.0.1"
+    },
+    "auth_token": {
+      "type": "string",
+      "title": "Authentication Bearer Token",
+      "description": "Optional Bearer token required for all incoming requests (mandatory when binding to non-loopback host 0.0.0.0).",
+      "required": false,
+      "default": ""
+    },
+    "allowed_directories": {
+      "type": "string",
+      "title": "Allowed Directories",
+      "description": "Comma-separated list of directories permitted for file operations. Leave empty to block all filesystem access (fail-closed). Use \"*\" or \"all\" to allow all drives (not recommended for network-exposed servers).",
+      "required": false,
+      "default": ""
+    },
+    "allowed_hosts": {
+      "type": "string",
+      "title": "Allowed Hosts",
+      "description": "Comma-separated list of permitted Host header values for DNS rebinding protection (e.g. \"localhost,127.0.0.1,[::1],*.ts.net\").",
+      "required": false,
+      "default": "localhost,127.0.0.1,[::1],*.ts.net"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "winhelm-mcp",
+  "version": "1.1.0",
+  "description": "WinHelm - Windows Native MCP Server with Unified HTTP/SSE/Streamable Gateway and 38 Tools",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "winhelm": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "manifest.json",
+    "server.json",
+    "winhelm.config.example.json",
+    "scripts/build-exe.ps1",
+    "scripts/manage-service.ps1",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dhammawatthumpra-coder/winhelm-mcp.git"
+  },
+  "homepage": "https://github.com/dhammawatthumpra-coder/winhelm-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/dhammawatthumpra-coder/winhelm-mcp/issues"
+  },
+  "author": {
+    "name": "dhammawatthumpra-coder",
+    "email": "dhammawatthumpra@gmail.com",
+    "url": "https://github.com/dhammawatthumpra-coder"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "windows",
+    "ai",
+    "claude",
+    "cursor",
+    "automation",
+    "powershell",
+    "windows-native",
+    "llm-tools"
+  ],
+  "scripts": {
+    "prepublishOnly": "npm run build && npm test",
+    "build": "rimraf dist && tsc",
+    "build:exe": "powershell -ExecutionPolicy Bypass -File scripts/build-exe.ps1",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "dev:type-check": "tsc --noEmit --watch",
+    "test": "tsx --test \"test/**/*.test.ts\"",
+    "type-check": "tsc --noEmit",
+    "service:install": "powershell -ExecutionPolicy Bypass -File scripts/manage-service.ps1 -Action install",
+    "service:uninstall": "powershell -ExecutionPolicy Bypass -File scripts/manage-service.ps1 -Action uninstall",
+    "service:start": "powershell -ExecutionPolicy Bypass -File scripts/manage-service.ps1 -Action start",
+    "service:stop": "powershell -ExecutionPolicy Bypass -File scripts/manage-service.ps1 -Action stop",
+    "service:status": "powershell -ExecutionPolicy Bypass -File scripts/manage-service.ps1 -Action status"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "cors": "^2.8.5",
+    "express": "^4.21.2",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.13.10",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/scripts/build-exe.ps1

@@ -0,0 +1,37 @@
+# Build Standalone Windows Executable (winhelm.exe)
+$PSScriptRoot = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$ProjectDir = (Get-Item $PSScriptRoot).Parent.FullName
+Set-Location $ProjectDir
+
+Write-Host "==========================================" -ForegroundColor Cyan
+Write-Host "  Building Standalone winhelm.exe..." -ForegroundColor Green
+Write-Host "==========================================" -ForegroundColor Cyan
+
+# 1. Compile TypeScript
+Write-Host "Step 1: Compiling TypeScript..." -ForegroundColor Yellow
+npx rimraf dist
+npx tsc
+
+# 2. Bundle with esbuild
+Write-Host "Step 2: Bundling with esbuild..." -ForegroundColor Yellow
+npx esbuild src/index.ts --bundle --platform=node --target=node22 --outfile=dist/bundle.cjs --format=cjs
+
+# 3. Generate SEA Blob
+Write-Host "Step 3: Generating Single Executable Blob..." -ForegroundColor Yellow
+node --experimental-sea-config sea-config.json
+
+# 4. Copy node.exe
+Write-Host "Step 4: Preparing Executable Binary..." -ForegroundColor Yellow
+$nodeSource = (Get-Command node -ErrorAction Stop).Source
+Copy-Item $nodeSource -Destination dist\winhelm.exe -Force
+
+# 5. Inject Blob
+Write-Host "Step 5: Injecting code into winhelm.exe..." -ForegroundColor Yellow
+npx --yes postject dist\winhelm.exe NODE_SEA_BLOB dist\sea-prep.blob --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
+
+Write-Host ""
+Write-Host "======================================================" -ForegroundColor Green
+Write-Host "  [OK] Standalone Binary Created Successfully!" -ForegroundColor Green
+Write-Host "  Path: $ProjectDir\dist\winhelm.exe" -ForegroundColor Cyan
+Write-Host "======================================================" -ForegroundColor Green
+Write-Host ""

package/scripts/manage-service.ps1

@@ -0,0 +1,112 @@
+# WinHelm - Windows Service & Background Daemon Manager
+param (
+    [Parameter(Mandatory=$true)]
+    [ValidateSet("install", "uninstall", "start", "stop", "status", "restart")]
+    [string]$Action,
+    [int]$Port = 8788,
+    [string]$Auth = "",
+    [string]$AllowedDirs = ""
+)
+
+$TaskName = "WinHelm-MCP-Service"
+$ProjectDir = (Get-Item $PSScriptRoot).Parent.FullName
+$NodeExe = (Get-Command node -ErrorAction SilentlyContinue).Source
+$DistIndex = Join-Path $ProjectDir "dist\index.js"
+
+if (-not $NodeExe) {
+    Write-Error "Node.js executable was not found on PATH."
+    exit 1
+}
+
+function Check-Admin {
+    $currentPrincipal = New-Object Security.Principal.WindowsPrincipal([Security.Principal.WindowsIdentity]::GetCurrent())
+    return $currentPrincipal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+}
+
+switch ($Action) {
+    "install" {
+        Write-Host "Installing WinHelm as an Always-On Windows Background Service..." -ForegroundColor Cyan
+
+        # Make sure build exists
+        if (-not (Test-Path $DistIndex)) {
+            Write-Host "Building project first..." -ForegroundColor Yellow
+            Push-Location $ProjectDir
+            npm run build
+            Pop-Location
+        }
+
+        $argList = "`"$DistIndex`" --port $Port"
+        if ($Auth) { $argList += " --auth `"$Auth`"" }
+        if ($AllowedDirs) { $argList += " --allowed-dirs `"$AllowedDirs`"" }
+
+        # Create Task Action
+        $TaskAction = New-ScheduledTaskAction -Execute $NodeExe -Argument $argList -WorkingDirectory $ProjectDir
+
+        # Create Trigger: At Windows Startup
+        $TaskTrigger = New-ScheduledTaskTrigger -AtStartup
+
+        # Settings: Restart on failure, no execution time limit
+        $TaskSettings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1) -ExecutionTimeLimit 0
+
+        # Unregister existing if present
+        Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue
+
+        # Register Scheduled Task with SYSTEM or Current User
+        if (Check-Admin) {
+            $TaskPrincipal = New-ScheduledTaskPrincipal -UserId "SYSTEM" -LogonType ServiceAccount -RunLevel Highest
+            Register-ScheduledTask -TaskName $TaskName -Action $TaskAction -Trigger $TaskTrigger -Settings $TaskSettings -Principal $TaskPrincipal | Out-Null
+            Write-Host "[OK] Successfully installed as SYSTEM Background Service!" -ForegroundColor Green
+        } else {
+            $TaskPrincipal = New-ScheduledTaskPrincipal -UserId $env:USERNAME -LogonType Interactive -RunLevel Highest
+            Register-ScheduledTask -TaskName $TaskName -Action $TaskAction -Trigger $TaskTrigger -Settings $TaskSettings -Principal $TaskPrincipal | Out-Null
+            Write-Host "[OK] Successfully installed for user '$env:USERNAME' (Run as Admin for SYSTEM-wide daemon)!" -ForegroundColor Green
+        }
+
+        # Start task immediately
+        Start-ScheduledTask -TaskName $TaskName
+        Write-Host "[OK] Service started! Access Web Monitor at http://localhost:$Port/" -ForegroundColor Green
+    }
+
+    "uninstall" {
+        Write-Host "Stopping and uninstalling WinHelm Service..." -ForegroundColor Yellow
+        Stop-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+        Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue
+        Write-Host "[OK] WinHelm Service successfully uninstalled." -ForegroundColor Green
+    }
+
+    "start" {
+        Write-Host "Starting WinHelm Service..." -ForegroundColor Cyan
+        Start-ScheduledTask -TaskName $TaskName
+        Write-Host "[OK] Service started." -ForegroundColor Green
+    }
+
+    "stop" {
+        Write-Host "Stopping WinHelm Service..." -ForegroundColor Yellow
+        Stop-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+        Write-Host "[OK] Service stopped." -ForegroundColor Green
+    }
+
+    "restart" {
+        Write-Host "Restarting WinHelm Service..." -ForegroundColor Cyan
+        Stop-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+        Start-Sleep -Seconds 1
+        Start-ScheduledTask -TaskName $TaskName
+        Write-Host "[OK] Service restarted." -ForegroundColor Green
+    }
+
+    "status" {
+        $task = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+        if ($task) {
+            $info = Get-ScheduledTaskInfo -TaskName $TaskName
+            Write-Host "=== WinHelm Windows Service Status ===" -ForegroundColor Cyan
+            Write-Host "Name:         $($task.TaskName)"
+            Write-Host "State:        $($task.State)" -ForegroundColor $(if ($task.State -eq 'Running') { 'Green' } else { 'Yellow' })
+            Write-Host "Last Run:     $($info.LastRunTime)"
+            Write-Host "Last Result:  $($info.LastTaskResult)"
+            Write-Host "Next Run:     $($info.NextRunTime)"
+        } else {
+            Write-Host "WinHelm Service is NOT installed." -ForegroundColor Red
+            Write-Host "Run: .\scripts\manage-service.ps1 -Action install" -ForegroundColor Gray
+        }
+    }
+}