winfolio

<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> <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

# 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):

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

With actions enabled:

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

HTTP Mode (OpenAI-Compatible)

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