winhelm-mcp 1.1.0

package/dist/utils/file-logger.js

@@ -0,0 +1,117 @@
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { sanitizeText } from "./sanitizer.js";
+export class FileLogger {
+    static instance = null;
+    logDir;
+    maxRetentionDays = 7;
+    writeQueue = Promise.resolve();
+    constructor() {
+        this.logDir = path.resolve(process.cwd(), "logs");
+    }
+    static getInstance() {
+        if (!FileLogger.instance) {
+            FileLogger.instance = new FileLogger();
+        }
+        return FileLogger.instance;
+    }
+    getTodayLogFileName() {
+        const d = new Date();
+        const yyyy = d.getFullYear();
+        const mm = String(d.getMonth() + 1).padStart(2, "0");
+        const dd = String(d.getDate()).padStart(2, "0");
+        return `winhelm-${yyyy}-${mm}-${dd}.log`;
+    }
+    /**
+     * Append log entry to persistent log file asynchronously
+     */
+    log(entry) {
+        // Chain writes to guarantee sequential, non-corrupting file writes
+        this.writeQueue = this.writeQueue
+            .then(async () => {
+            if (!existsSync(this.logDir)) {
+                await fs.mkdir(this.logDir, { recursive: true });
+            }
+            const fileName = this.getTodayLogFileName();
+            const filePath = path.join(this.logDir, fileName);
+            const sanitizedTitle = sanitizeText(entry.title);
+            const sanitizedDetail = entry.detail ? sanitizeText(entry.detail) : "";
+            const sanitizedEntry = {
+                ...entry,
+                title: sanitizedTitle,
+                detail: sanitizedDetail,
+            };
+            const line = JSON.stringify(sanitizedEntry) + "\n";
+            await fs.appendFile(filePath, line, "utf-8");
+            // Check if rotation or cleanup needed occasionally
+            if (Math.random() < 0.05) {
+                await this.cleanOldLogs();
+            }
+        })
+            .catch((err) => {
+            // Never throw from file logger to prevent crashing the server
+            console.error("[FileLogger] Error writing log file:", err.message);
+        });
+    }
+    /**
+     * Remove log files older than maxRetentionDays
+     */
+    async cleanOldLogs() {
+        try {
+            if (!existsSync(this.logDir))
+                return;
+            const files = await fs.readdir(this.logDir);
+            const now = Date.now();
+            const maxAgeMs = this.maxRetentionDays * 24 * 60 * 60 * 1000;
+            for (const file of files) {
+                if (file.endsWith(".log")) {
+                    const fullPath = path.join(this.logDir, file);
+                    const stat = await fs.stat(fullPath);
+                    if (now - stat.mtimeMs > maxAgeMs) {
+                        await fs.unlink(fullPath);
+                    }
+                }
+            }
+        }
+        catch {
+            // ignore cleanup errors
+        }
+    }
+    /**
+     * Export audit logs in JSON or CSV format
+     */
+    async exportLogs(format = "json") {
+        const todayFile = path.join(this.logDir, this.getTodayLogFileName());
+        let rawContent = "";
+        if (existsSync(todayFile)) {
+            rawContent = await fs.readFile(todayFile, "utf-8");
+        }
+        const lines = rawContent.split(/\r?\n/).filter(Boolean);
+        const entries = [];
+        for (const line of lines) {
+            try {
+                entries.push(JSON.parse(line));
+            }
+            catch {
+                // ignore parse error on bad line
+            }
+        }
+        if (format === "csv") {
+            const headers = ["Timestamp", "Type", "Level", "Title", "Status", "DurationMs", "Detail"];
+            const rows = entries.map((e) => [
+                `"${e.timestamp}"`,
+                `"${e.type}"`,
+                `"${e.level}"`,
+                `"${(e.title || "").replace(/"/g, '""')}"`,
+                `"${e.status ?? ""}"`,
+                e.durationMs ?? 0,
+                `"${(e.detail || "").replace(/"/g, '""')}"`,
+            ]);
+            return [headers.join(","), ...rows.map((r) => r.join(","))].join("\n");
+        }
+        return JSON.stringify(entries, null, 2);
+    }
+}
+export const fileLogger = FileLogger.getInstance();
+//# sourceMappingURL=file-logger.js.map

package/dist/utils/file-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-logger.js","sourceRoot":"","sources":["../../src/utils/file-logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,51 @@
+export interface LogEntry {
+    id: string;
+    timestamp: string;
+    type: "tool" | "req" | "security" | "system" | "error";
+    level: "info" | "warn" | "error" | "success";
+    title: string;
+    detail?: string;
+    durationMs?: number;
+    status?: string | number;
+}
+export declare class Logger {
+    private static instance;
+    private logs;
+    private readonly maxLogs;
+    private constructor();
+    static getInstance(): Logger;
+    private getFormattedTime;
+    private addLog;
+    getRecentLogs(limit?: number): LogEntry[];
+    clearLogs(): void;
+    /**
+     * Log incoming & completed HTTP requests
+     */
+    req(method: string, url: string, statusCode: number, durationMs: number, ip?: string, sessionId?: string): void;
+    /**
+     * Log tool invocation start
+     */
+    toolStart(name: string, args: Record<string, any>): void;
+    /**
+     * Log tool invocation success
+     */
+    toolDone(name: string, durationMs: number, summary?: string): void;
+    /**
+     * Log tool invocation failure
+     */
+    toolFail(name: string, durationMs: number, error: string): void;
+    /**
+     * Log security events (e.g. command blocked, path denied, unauthorized)
+     */
+    security(message: string, detail?: string): void;
+    /**
+     * General info message
+     */
+    info(message: string, detail?: string): void;
+    /**
+     * Error message
+     */
+    error(message: string, detail?: string): void;
+}
+export declare const logger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;IACvD,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAkBD,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAuB;IAC9C,OAAO,CAAC,IAAI,CAAkB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAO;IAE/B,OAAO,eAAiB;IAExB,OAAc,WAAW,IAAI,MAAM,CAKlC;IAED,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,MAAM;IAqBP,aAAa,CAAC,KAAK,SAAM,GAAG,QAAQ,EAAE,CAE5C;IAEM,SAAS,IAAI,IAAI,CAEvB;IAED;;OAEG;IACI,GAAG,CACR,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,EAAE,SAAM,EACR,SAAS,CAAC,EAAE,MAAM,GACjB,IAAI,CA0BN;IAED;;OAEG;IACI,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAwB9D;IAED;;OAEG;IACI,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAgBxE;IAED;;OAEG;IACI,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAcrE;IAED;;OAEG;IACI,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAatD;IAED;;OAEG;IACI,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAYlD;IAED;;OAEG;IACI,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAYnD;CACF;AAED,eAAO,MAAM,MAAM,QAAuB,CAAC"}

package/dist/utils/logger.js

@@ -0,0 +1,189 @@
+import { randomUUID } from "node:crypto";
+import { sanitizeText } from "./sanitizer.js";
+import { fileLogger } from "./file-logger.js";
+// ANSI Escape Codes for Terminal Colors
+const C = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    blue: "\x1b[34m",
+    magenta: "\x1b[35m",
+    cyan: "\x1b[36m",
+    red: "\x1b[31m",
+    gray: "\x1b[90m",
+    bgRed: "\x1b[41m",
+    bgGreen: "\x1b[42m",
+};
+export class Logger {
+    static instance = null;
+    logs = [];
+    maxLogs = 200;
+    constructor() { }
+    static getInstance() {
+        if (!Logger.instance) {
+            Logger.instance = new Logger();
+        }
+        return Logger.instance;
+    }
+    getFormattedTime() {
+        const d = new Date();
+        const pad = (n, s = 2) => String(n).padStart(s, "0");
+        const h = pad(d.getHours());
+        const m = pad(d.getMinutes());
+        const s = pad(d.getSeconds());
+        const ms = pad(d.getMilliseconds(), 3);
+        return `${h}:${m}:${s}.${ms}`;
+    }
+    addLog(entry) {
+        const cleanTitle = sanitizeText(entry.title);
+        const cleanDetail = entry.detail ? sanitizeText(entry.detail) : undefined;
+        const fullEntry = {
+            id: randomUUID(),
+            timestamp: new Date().toISOString(),
+            ...entry,
+            title: cleanTitle,
+            detail: cleanDetail,
+        };
+        this.logs.unshift(fullEntry);
+        if (this.logs.length > this.maxLogs) {
+            this.logs.pop();
+        }
+        // Persist to rotating disk log
+        fileLogger.log(fullEntry);
+    }
+    getRecentLogs(limit = 100) {
+        return this.logs.slice(0, limit);
+    }
+    clearLogs() {
+        this.logs = [];
+    }
+    /**
+     * Log incoming & completed HTTP requests
+     */
+    req(method, url, statusCode, durationMs, ip = "-", sessionId) {
+        const time = this.getFormattedTime();
+        let statusColor = C.green;
+        let level = "info";
+        if (statusCode >= 500) {
+            statusColor = C.red;
+            level = "error";
+        }
+        else if (statusCode >= 400) {
+            statusColor = C.yellow;
+            level = "warn";
+        }
+        const sessTag = sessionId ? `${C.gray}[sess:${sessionId.slice(0, 8)}]${C.reset} ` : "";
+        const cleanUrl = sanitizeText(url);
+        const line = `${C.gray}[${time}]${C.reset} ${C.cyan}[HTTP]${C.reset} ${C.bold}${method}${C.reset} ${cleanUrl} ${statusColor}${statusCode}${C.reset} ${C.dim}(${durationMs}ms)${C.reset} ${sessTag}${C.gray}${ip}${C.reset}`;
+        console.log(line);
+        this.addLog({
+            type: "req",
+            level,
+            title: `${method} ${url}`,
+            detail: `IP: ${ip}${sessionId ? ` | Session: ${sessionId}` : ""}`,
+            durationMs,
+            status: statusCode,
+        });
+    }
+    /**
+     * Log tool invocation start
+     */
+    toolStart(name, args) {
+        const time = this.getFormattedTime();
+        // Sanitize parameters so long content/base64 doesn't spam console
+        const cleanArgs = {};
+        for (const [key, val] of Object.entries(args || {})) {
+            if (typeof val === "string" && val.length > 80) {
+                cleanArgs[key] = val.slice(0, 77) + "...";
+            }
+            else {
+                cleanArgs[key] = val;
+            }
+        }
+        const preview = sanitizeText(JSON.stringify(cleanArgs));
+        console.log(`${C.gray}[${time}]${C.reset} ${C.magenta}[TOOL-START]${C.reset} ${C.bold}${name}${C.reset} ${C.dim}${preview}${C.reset}`);
+        this.addLog({
+            type: "tool",
+            level: "info",
+            title: `tool_call: ${name}`,
+            detail: preview,
+            status: "RUNNING",
+        });
+    }
+    /**
+     * Log tool invocation success
+     */
+    toolDone(name, durationMs, summary) {
+        const time = this.getFormattedTime();
+        const cleanSummary = summary ? sanitizeText(summary) : undefined;
+        const sum = cleanSummary ? ` ${C.dim}-> ${cleanSummary.slice(0, 90)}${cleanSummary.length > 90 ? "..." : ""}${C.reset}` : "";
+        console.log(`${C.gray}[${time}]${C.reset} ${C.green}[TOOL-DONE]${C.reset}  ${C.bold}${name}${C.reset} ${C.green}✔ OK${C.reset} ${C.dim}(${durationMs}ms)${C.reset}${sum}`);
+        this.addLog({
+            type: "tool",
+            level: "success",
+            title: `tool_done: ${name}`,
+            detail: cleanSummary ? cleanSummary.slice(0, 150) : "Success",
+            durationMs,
+            status: "SUCCESS",
+        });
+    }
+    /**
+     * Log tool invocation failure
+     */
+    toolFail(name, durationMs, error) {
+        const time = this.getFormattedTime();
+        console.log(`${C.gray}[${time}]${C.reset} ${C.red}[TOOL-FAIL]${C.reset}  ${C.bold}${name}${C.reset} ${C.red}✖ ERROR${C.reset} ${C.dim}(${durationMs}ms)${C.reset} ${C.red}${error}${C.reset}`);
+        this.addLog({
+            type: "tool",
+            level: "error",
+            title: `tool_fail: ${name}`,
+            detail: error,
+            durationMs,
+            status: "FAILED",
+        });
+    }
+    /**
+     * Log security events (e.g. command blocked, path denied, unauthorized)
+     */
+    security(message, detail) {
+        const time = this.getFormattedTime();
+        console.warn(`${C.gray}[${time}]${C.reset} ${C.yellow}${C.bold}[SECURITY]${C.reset} ${C.yellow}⚠️  ${message}${C.reset}${detail ? ` ${C.dim}(${detail})${C.reset}` : ""}`);
+        this.addLog({
+            type: "security",
+            level: "warn",
+            title: message,
+            detail,
+            status: "BLOCKED",
+        });
+    }
+    /**
+     * General info message
+     */
+    info(message, detail) {
+        const time = this.getFormattedTime();
+        console.log(`${C.gray}[${time}]${C.reset} ${C.blue}[INFO]${C.reset} ${message}${detail ? ` ${C.dim}${detail}${C.reset}` : ""}`);
+        this.addLog({
+            type: "system",
+            level: "info",
+            title: message,
+            detail,
+        });
+    }
+    /**
+     * Error message
+     */
+    error(message, detail) {
+        const time = this.getFormattedTime();
+        console.error(`${C.gray}[${time}]${C.reset} ${C.red}[ERROR]${C.reset} ${C.bold}${message}${C.reset}${detail ? ` ${C.dim}${detail}${C.reset}` : ""}`);
+        this.addLog({
+            type: "error",
+            level: "error",
+            title: message,
+            detail,
+        });
+    }
+}
+export const logger = Logger.getInstance();
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/sanitizer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Secret & Credential Redaction Utility for WinCommander
+ * Automatically detects and masks sensitive keys, tokens, and credentials in logs and outputs.
+ */
+/**
+ * Mask sensitive credentials within a text string
+ */
+export declare function sanitizeText(text: string): string;
+/**
+ * Deep-sanitize objects, payloads, or argument maps
+ */
+export declare function sanitizeObject<T>(obj: T): T;
+//# sourceMappingURL=sanitizer.d.ts.map

package/dist/utils/sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizer.d.ts","sourceRoot":"","sources":["../../src/utils/sanitizer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAsBjD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAiC3C"}

package/dist/utils/sanitizer.js

@@ -0,0 +1,60 @@
+/**
+ * Secret & Credential Redaction Utility for WinCommander
+ * Automatically detects and masks sensitive keys, tokens, and credentials in logs and outputs.
+ */
+/**
+ * Mask sensitive credentials within a text string
+ */
+export function sanitizeText(text) {
+    if (!text || typeof text !== "string")
+        return text;
+    return text
+        // Bearer tokens
+        .replace(/(bearer\s+)([a-zA-Z0-9_\-\.]{8,})/gi, (_m, p, s) => `${p}${"*".repeat(Math.min(s.length, 12))}`)
+        // AWS Access Key ID (AKIA...)
+        .replace(/\b(AKIA)([0-9A-Z]{16})\b/g, (_m, p, s) => `${p}${"*".repeat(Math.min(s.length, 12))}`)
+        // API keys (sk-..., ghp_...)
+        .replace(/(sk-[a-zA-Z0-9_\-]{4})([a-zA-Z0-9_\-]+)/gi, (_m, p) => `${p}${"*".repeat(12)}`)
+        .replace(/(gh[pousr]_[a-zA-Z0-9]{4})([a-zA-Z0-9]+)/gi, (_m, p) => `${p}${"*".repeat(12)}`)
+        // JSON quoted keys like "authToken": "...", "password": "...", "x-api-key": "..."
+        .replace(/((\\")|["'])([\w\-]*?(?:token|password|passwd|secret|api[_-]?key|auth(?!(?:or|ors)\b))[\w\-]*?)\1(\s*:\s*)((\\")|["'])([^"'\r\n]+?)\5/gi, (_m, q1, _g2, k, colon, q2, _g5, v) => `${q1}${k}${q1}${colon}${q2}${"*".repeat(Math.min(v.length, 12))}${q2}`)
+        // Query/unquoted fields like password=xyz, token=xyz
+        .replace(/((?:token|api[_-]?key|secret|password|passwd|auth(?!(?:or|ors)\b))\s*[:=]\s*["']?)([^"'&\s]{4,})(["']?)/gi, (_m, p, s, suf) => `${p}${"*".repeat(Math.min(s.length, 12))}${suf}`)
+        // CLI flags e.g. --auth xyz
+        .replace(/(--(?:auth|token|password|secret)\s+)([^\s]{4,})/gi, (_m, p, s) => `${p}${"*".repeat(Math.min(s.length, 12))}`)
+        // Basic Auth in URLs
+        .replace(/(https?:\/\/[^:]+:)([^@]+)(@)/gi, (_m, p, _s, at) => `${p}********${at}`);
+}
+/**
+ * Deep-sanitize objects, payloads, or argument maps
+ */
+export function sanitizeObject(obj) {
+    if (obj === null || obj === undefined)
+        return obj;
+    if (typeof obj === "string") {
+        return sanitizeText(obj);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => sanitizeObject(item));
+    }
+    if (typeof obj === "object") {
+        const cleanObj = {};
+        for (const [key, val] of Object.entries(obj)) {
+            const lowerKey = key.toLowerCase();
+            if (lowerKey.includes("password") ||
+                lowerKey.includes("token") ||
+                lowerKey.includes("secret") ||
+                (lowerKey.includes("auth") && !lowerKey.includes("author")) ||
+                (lowerKey.includes("key") && !lowerKey.includes("keyboard"))) {
+                if (typeof val === "string") {
+                    cleanObj[key] = "************";
+                    continue;
+                }
+            }
+            cleanObj[key] = sanitizeObject(val);
+        }
+        return cleanObj;
+    }
+    return obj;
+}
+//# sourceMappingURL=sanitizer.js.map

package/dist/utils/sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizer.js","sourceRoot":"","sources":["../../src/utils/sanitizer.ts"],"names":[],"mappings":"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"}

package/docs/EXAMPLES.md

@@ -0,0 +1,171 @@
+# WinHelm MCP — Real-World Agent Workflows & Use Cases
+
+This guide demonstrates concrete workflows for LLM coding agents (e.g. Claude Desktop, Cursor, Cline, Windsurf) using WinHelm tools across different profiles.
+
+---
+
+## Use Case 1: Autonomous Build, Test, and Self-Healing
+**Recommended Profile:** `dev` (28 tools)
+
+When an AI agent needs to compile a large project, monitor progress in the background, and fix build errors without blocking the conversation:
+
+### Step 1: Start background build task
+The agent starts the build asynchronously:
+
+**Tool:** `terminal_task_start`
+```json
+{
+  "command": "npm run build",
+  "cwd": "D:\\Projects\\MyWebApp"
+}
+```
+*WinHelm returns Task ID `a4f891b2` immediately.*
+
+### Step 2: Poll live progress
+The agent checks progress after 3 seconds:
+
+**Tool:** `terminal_task_logs`
+```json
+{
+  "task_id": "a4f891b2",
+  "tail_lines": 15
+}
+```
+*Output shows a TypeScript compilation error in `src/utils.ts:42`.*
+
+### Step 3: Surgically fix the code
+The agent patches the specific line without touching adjacent lines:
+
+**Tool:** `file_edit`
+```json
+{
+  "path": "D:\\Projects\\MyWebApp\\src\\utils.ts",
+  "old_text": "const port = process.env.PORT || undefined;",
+  "new_text": "const port = Number(process.env.PORT) || 8080;"
+}
+```
+
+### Step 4: Verify test passes
+The agent executes the test suite synchronously:
+
+**Tool:** `terminal_run`
+```json
+{
+  "command": "npm test",
+  "cwd": "D:\\Projects\\MyWebApp"
+}
+```
+
+---
+
+## Use Case 2: System Health Inspection & Troubleshooting
+**Recommended Profile:** `sysadmin` (37 tools)
+
+When an AI agent is asked: *"Why is my Windows computer sluggish or why did my application crash?"*
+
+### Step 1: Check hardware utilization
+**Tool:** `system_info`
+```json
+{}
+```
+*Returns CPU utilization %, RAM usage (Total/Used/Free), OS version, and allowed drive capacities.*
+
+### Step 2: Query GPU telemetry
+**Tool:** `gpu_info`
+```json
+{}
+```
+*Returns NVIDIA GPU name, driver version, temperature, and VRAM utilization.*
+
+### Step 3: Identify resource-heavy processes
+**Tool:** `process_list`
+```json
+{
+  "sort_by": "memory",
+  "limit": 10
+}
+```
+*Returns top 10 processes sorted by RAM usage.*
+
+### Step 4: Query Windows Event Log for crashes
+**Tool:** `eventlog_query`
+```json
+{
+  "log_name": "Application",
+  "level": "Error",
+  "limit": 5
+}
+```
+*Identifies exact exception codes, faulted module names, and crash timestamps.*
+
+### Step 5: Notify the developer
+**Tool:** `notification_send`
+```json
+{
+  "title": "WinHelm Diagnostic Complete",
+  "message": "Found memory leak in rogue node.exe process (PID 4120). Recommending process_kill.",
+  "sound": true
+}
+```
+
+---
+
+## Use Case 3: Code Search & Automated PDF Report
+**Recommended Profile:** `dev` (28 tools) or `full` (38 tools)
+
+When an agent performs an audit and generates a client-ready PDF document:
+
+### Step 1: High-speed code search across project
+**Tool:** `file_search_ripgrep`
+```json
+{
+  "query": "TODO|FIXME|SECURITY",
+  "path": "D:\\mcp\\winhelm-mcp",
+  "page_size": 20
+}
+```
+
+### Step 2: Write markdown report
+**Tool:** `file_write`
+```json
+{
+  "path": "D:\\AuditReport.md",
+  "content": "# Codebase Audit Report\n\nFound 3 unresolved TODOs in codebase..."
+}
+```
+
+### Step 3: Compile report to PDF using native Chromium
+**Tool:** `pdf_generate`
+```json
+{
+  "source_path": "D:\\AuditReport.md",
+  "pdf_path": "D:\\AuditReport.pdf",
+  "title": "Security & Code Audit Report"
+}
+```
+*Generates formatted, print-ready PDF using headless Microsoft Edge or Google Chrome.*
+
+---
+
+## Use Case 4: Safe File Operations & Archival
+**Recommended Profile:** `dev` (28 tools) or `core` (15 tools)
+
+Safe file management that avoids accidental permanent loss:
+
+### Step 1: Zip backup before modifying
+**Tool:** `archive_zip`
+```json
+{
+  "source_dir": "D:\\Projects\\ImportantData",
+  "zip_path": "D:\\Backups\\ImportantData-2026-09-27.zip"
+}
+```
+
+### Step 2: Recycle old temporary files (safe delete)
+**Tool:** `file_delete_safe`
+```json
+{
+  "path": "D:\\Projects\\TempCache"
+}
+```
+*Item is moved to Windows Recycle Bin where it can be restored if needed.*