@mokoconsulting/mcp-windows 3.0.0

package/src/tools/network.ts

@@ -0,0 +1,84 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * Tool: windows_network_info (#22)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { runPowerShell } from '../shell.js';
+
+export function registerNetworkTools(server: McpServer): void {
+	server.tool(
+		'windows_network_info',
+		'Get network configuration: adapters, IPs, DNS, gateway, Wi-Fi status, and connectivity.',
+		{},
+		async () => {
+			const ps = `
+$adapters = Get-NetAdapter | Where-Object { $_.Status -eq 'Up' } | ForEach-Object {
+  $ipInfo = Get-NetIPAddress -InterfaceIndex $_.ifIndex -AddressFamily IPv4 -ErrorAction SilentlyContinue
+  $dns = (Get-DnsClientServerAddress -InterfaceIndex $_.ifIndex -AddressFamily IPv4 -ErrorAction SilentlyContinue).ServerAddresses
+  $gw = (Get-NetRoute -InterfaceIndex $_.ifIndex -DestinationPrefix '0.0.0.0/0' -ErrorAction SilentlyContinue).NextHop
+  [PSCustomObject]@{
+    Name = $_.Name
+    Description = $_.InterfaceDescription
+    Type = $_.MediaType
+    Status = $_.Status
+    Speed = $_.LinkSpeed
+    MAC = $_.MacAddress
+    IP = if ($ipInfo) { $ipInfo.IPAddress -join ', ' } else { 'N/A' }
+    Subnet = if ($ipInfo) { $ipInfo.PrefixLength -join ', ' } else { 'N/A' }
+    Gateway = if ($gw) { $gw -join ', ' } else { 'N/A' }
+    DNS = if ($dns) { $dns -join ', ' } else { 'N/A' }
+  }
+}
+
+# Wi-Fi info
+$wifi = $null
+try {
+  $wifiProfile = netsh wlan show interfaces 2>$null
+  if ($wifiProfile) {
+    $ssid = ($wifiProfile | Select-String 'SSID\s+:' | Select-Object -First 1) -replace '.*:\s*',''
+    $signal = ($wifiProfile | Select-String 'Signal' | Select-Object -First 1) -replace '.*:\s*',''
+    $auth = ($wifiProfile | Select-String 'Authentication' | Select-Object -First 1) -replace '.*:\s*',''
+    $wifi = [PSCustomObject]@{ SSID = $ssid.Trim(); Signal = $signal.Trim(); Security = $auth.Trim() }
+  }
+} catch {}
+
+# Connectivity
+$connected = Test-Connection -ComputerName 8.8.8.8 -Count 1 -Quiet -ErrorAction SilentlyContinue
+
+[PSCustomObject]@{
+  Adapters = $adapters
+  WiFi = $wifi
+  InternetConnected = $connected
+} | ConvertTo-Json -Depth 4 -Compress`;
+
+			const result = await runPowerShell(ps, { timeout: 15000 });
+			if (result.exitCode !== 0) {
+				return { content: [{ type: 'text', text: `Error: ${result.stderr}` }], isError: true };
+			}
+
+			const info = JSON.parse(result.stdout);
+			const lines: string[] = [];
+
+			lines.push(`Internet: ${info.InternetConnected ? 'Connected' : 'Disconnected'}`);
+
+			if (info.WiFi) {
+				lines.push(`Wi-Fi: ${info.WiFi.SSID} (${info.WiFi.Signal}, ${info.WiFi.Security})`);
+			}
+
+			lines.push('');
+			lines.push('Adapters:');
+
+			const adapters = Array.isArray(info.Adapters) ? info.Adapters : [info.Adapters];
+			for (const a of adapters.filter(Boolean)) {
+				lines.push(`  ${a.Name} (${a.Description})`);
+				lines.push(`    IP: ${a.IP}/${a.Subnet}  Gateway: ${a.Gateway}`);
+				lines.push(`    DNS: ${a.DNS}`);
+				lines.push(`    MAC: ${a.MAC}  Speed: ${a.Speed}`);
+			}
+
+			return { content: [{ type: 'text', text: lines.join('\n') }] };
+		},
+	);
+}

package/src/tools/notification.ts

@@ -0,0 +1,50 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * Tool: windows_notification_send (#20)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { runPowerShell } from '../shell.js';
+
+export function registerNotificationTools(server: McpServer): void {
+	server.tool(
+		'windows_notification_send',
+		'Send a Windows toast notification with title, body, and optional icon.',
+		{
+			title: z.string().describe('Notification title'),
+			body: z.string().describe('Notification body text'),
+			icon: z.string().optional().describe('Path to icon file (optional)'),
+			sound: z.boolean().default(true).describe('Play notification sound'),
+		},
+		async ({ title, body, icon, sound }) => {
+			const iconParam = icon
+				? `$notify.Icon = [System.Drawing.Icon]::ExtractAssociatedIcon('${icon.replace(/'/g, "''")}');`
+				: `$notify.Icon = [System.Drawing.SystemIcons]::Information;`;
+
+			const ps = `
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+$notify = New-Object System.Windows.Forms.NotifyIcon
+${iconParam}
+$notify.Visible = $true
+$notify.BalloonTipTitle = '${title.replace(/'/g, "''")}'
+$notify.BalloonTipText = '${body.replace(/'/g, "''")}'
+$notify.BalloonTipIcon = [System.Windows.Forms.ToolTipIcon]::Info
+$notify.ShowBalloonTip(5000)
+
+# Keep alive briefly so notification displays
+Start-Sleep -Milliseconds 100
+$notify.Dispose()
+"Notification sent: ${title.replace(/"/g, '\\"')}"`;
+
+			const result = await runPowerShell(ps, { timeout: 10000 });
+			return {
+				content: [{ type: 'text', text: result.stdout || result.stderr }],
+				isError: result.exitCode !== 0,
+			};
+		},
+	);
+}

package/src/tools/power.ts

@@ -0,0 +1,123 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * Tools: windows_power_get (#12), windows_power_action (#13)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { runPowerShell } from '../shell.js';
+
+export function registerPowerTools(server: McpServer): void {
+	server.tool(
+		'windows_power_get',
+		'Get power state: battery level, AC/battery, power plan, screen/sleep timeouts.',
+		{},
+		async () => {
+			const ps = `
+$battery = Get-CimInstance Win32_Battery -ErrorAction SilentlyContinue
+$plan = powercfg /getactivescheme 2>$null
+$planName = if ($plan) { ($plan -replace '^.*\\((.*)\\).*$','$1').Trim() } else { 'Unknown' }
+
+# Get timeout values
+$acScreen = (powercfg /query SCHEME_CURRENT SUB_VIDEO VIDEOIDLE 2>$null | Select-String 'Current AC Power Setting Index' | ForEach-Object { ($_ -split '0x')[1] }) -as [int]
+$dcScreen = (powercfg /query SCHEME_CURRENT SUB_VIDEO VIDEOIDLE 2>$null | Select-String 'Current DC Power Setting Index' | ForEach-Object { ($_ -split '0x')[1] }) -as [int]
+$acSleep = (powercfg /query SCHEME_CURRENT SUB_SLEEP STANDBYIDLE 2>$null | Select-String 'Current AC Power Setting Index' | ForEach-Object { ($_ -split '0x')[1] }) -as [int]
+$dcSleep = (powercfg /query SCHEME_CURRENT SUB_SLEEP STANDBYIDLE 2>$null | Select-String 'Current DC Power Setting Index' | ForEach-Object { ($_ -split '0x')[1] }) -as [int]
+
+[PSCustomObject]@{
+  HasBattery = $null -ne $battery
+  BatteryPct = if ($battery) { $battery.EstimatedChargeRemaining } else { $null }
+  Charging = if ($battery) { $battery.BatteryStatus -eq 2 } else { $null }
+  ACPower = if ($battery) { $battery.BatteryStatus -eq 2 -or $battery.BatteryStatus -eq 6 } else { $true }
+  TimeRemaining = if ($battery -and $battery.EstimatedRunTime -and $battery.EstimatedRunTime -lt 71582788) { "$([math]::Floor($battery.EstimatedRunTime / 60))h $($battery.EstimatedRunTime % 60)m" } else { $null }
+  PowerPlan = $planName
+  ScreenTimeout_AC = if ($acScreen) { "$([math]::Floor($acScreen / 60))m" } else { 'Never' }
+  ScreenTimeout_DC = if ($dcScreen) { "$([math]::Floor($dcScreen / 60))m" } else { 'Never' }
+  SleepTimeout_AC = if ($acSleep) { "$([math]::Floor($acSleep / 60))m" } else { 'Never' }
+  SleepTimeout_DC = if ($dcSleep) { "$([math]::Floor($dcSleep / 60))m" } else { 'Never' }
+} | ConvertTo-Json -Compress`;
+
+			const result = await runPowerShell(ps, { timeout: 30000 });
+			if (result.exitCode !== 0) {
+				return { content: [{ type: 'text', text: `Error: ${result.stderr}` }], isError: true };
+			}
+
+			const info = JSON.parse(result.stdout);
+			const lines: string[] = [];
+
+			if (info.HasBattery) {
+				const icon = info.Charging ? '🔌' : '🔋';
+				lines.push(`${icon} Battery: ${info.BatteryPct}%${info.Charging ? ' (charging)' : ''}`);
+				if (info.TimeRemaining) lines.push(`Estimated remaining: ${info.TimeRemaining}`);
+			} else {
+				lines.push(`AC Power (no battery)`);
+			}
+
+			lines.push(`Power Plan: ${info.PowerPlan}`);
+			lines.push(``);
+			lines.push(`Screen timeout: ${info.ScreenTimeout_AC} (AC) / ${info.ScreenTimeout_DC} (battery)`);
+			lines.push(`Sleep timeout: ${info.SleepTimeout_AC} (AC) / ${info.SleepTimeout_DC} (battery)`);
+
+			return { content: [{ type: 'text', text: lines.join('\n') }] };
+		},
+	);
+
+	server.tool(
+		'windows_power_action',
+		'Execute power actions: sleep, hibernate, lock, shutdown, restart, or switch power plan.',
+		{
+			action: z.enum(['sleep', 'hibernate', 'lock', 'shutdown', 'restart', 'logoff', 'plan']).describe('Power action'),
+			delay: z.number().optional().describe('Delay in seconds (for shutdown/restart)'),
+			cancel: z.boolean().optional().describe('Cancel a scheduled shutdown/restart'),
+			plan: z.enum(['balanced', 'performance', 'powersaver']).optional().describe('Power plan to switch to (when action=plan)'),
+		},
+		async ({ action, delay, cancel, plan }) => {
+			if (cancel) {
+				const result = await runPowerShell('shutdown /a 2>&1; "Scheduled shutdown cancelled"');
+				return { content: [{ type: 'text', text: result.stdout || result.stderr }] };
+			}
+
+			let ps: string;
+			const delayArg = delay ? `/t ${delay}` : '';
+
+			switch (action) {
+				case 'sleep':
+					ps = `Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Application]::SetSuspendState('Suspend', $false, $false); "Sleeping..."`;
+					break;
+				case 'hibernate':
+					ps = `Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Application]::SetSuspendState('Hibernate', $false, $false); "Hibernating..."`;
+					break;
+				case 'lock':
+					ps = `rundll32.exe user32.dll,LockWorkStation; "Workstation locked"`;
+					break;
+				case 'shutdown':
+					ps = `shutdown /s /f ${delayArg}; "Shutdown initiated${delay ? ` in ${delay}s` : ''}"`;
+					break;
+				case 'restart':
+					ps = `shutdown /r /f ${delayArg}; "Restart initiated${delay ? ` in ${delay}s` : ''}"`;
+					break;
+				case 'logoff':
+					ps = `shutdown /l; "Logging off..."`;
+					break;
+				case 'plan':
+					if (!plan) {
+						return { content: [{ type: 'text', text: 'Specify a plan: balanced, performance, or powersaver' }], isError: true };
+					}
+					const planGuids: Record<string, string> = {
+						balanced: '381b4222-f694-41f0-9685-ff5bb260df2e',
+						performance: '8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c',
+						powersaver: 'a1841308-3541-4fab-bc81-f71556f20b4a',
+					};
+					ps = `powercfg /setactive ${planGuids[plan]}; $p = powercfg /getactivescheme; "Switched to: $($p -replace '^.*\\((.*)\\).*$','$1')"`;
+					break;
+			}
+
+			const result = await runPowerShell(ps, { timeout: 30000 });
+			return {
+				content: [{ type: 'text', text: result.stdout || result.stderr }],
+				isError: result.exitCode !== 0,
+			};
+		},
+	);
+}

package/src/tools/printer.ts

@@ -0,0 +1,114 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * Tool: windows_printer_list (#50)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { runPowerShell } from '../shell.js';
+
+export function registerPrinterTools(server: McpServer): void {
+	server.tool(
+		'windows_printer_list',
+		'List printers, show print queues, set default, or clear a queue.',
+		{
+			action: z.enum(['list', 'queue', 'set_default', 'clear_queue']).default('list').describe('Action'),
+			printer: z.string().optional().describe('Printer name (for queue/set_default/clear_queue)'),
+		},
+		async ({ action, printer }) => {
+			switch (action) {
+				case 'list': {
+					const ps = `
+Get-Printer -ErrorAction SilentlyContinue | ForEach-Object {
+  $default = if ((Get-CimInstance Win32_Printer -Filter "Name='$($_.Name.Replace("'","''"))'" -ErrorAction SilentlyContinue).Default) { $true } else { $false }
+  [PSCustomObject]@{
+    Name = $_.Name
+    Status = $_.PrinterStatus
+    Type = $_.Type
+    Port = $_.PortName
+    Driver = $_.DriverName
+    Default = $default
+    Shared = $_.Shared
+  }
+} | ConvertTo-Json -Depth 3 -Compress`;
+
+					const result = await runPowerShell(ps, { timeout: 45000 });
+					if (result.exitCode !== 0) {
+						return { content: [{ type: 'text', text: `Error: ${result.stderr}` }], isError: true };
+					}
+					if (!result.stdout) {
+						return { content: [{ type: 'text', text: 'No printers found.' }] };
+					}
+
+					const printers = Array.isArray(JSON.parse(result.stdout)) ? JSON.parse(result.stdout) : [JSON.parse(result.stdout)];
+					const lines = printers.map((p: { Name: string; Status: string; Driver: string; Port: string; Default: boolean }) => {
+						const def = p.Default ? ' *' : '  ';
+						return `${def} ${(p.Name || '').padEnd(35).slice(0, 35)}  ${(p.Driver || '').padEnd(25).slice(0, 25)}  ${p.Port || ''}`;
+					});
+
+					const header = `   ${'Name'.padEnd(35)}  ${'Driver'.padEnd(25)}  Port`;
+					return {
+						content: [{ type: 'text', text: `${header}\n${'─'.repeat(80)}\n${lines.join('\n')}\n\n${printers.length} printers (* = default)` }],
+					};
+				}
+
+				case 'queue': {
+					if (!printer) {
+						return { content: [{ type: 'text', text: 'Queue requires printer name.' }], isError: true };
+					}
+					const ps = `
+Get-PrintJob -PrinterName '${printer.replace(/'/g, "''")}' -ErrorAction Stop | ForEach-Object {
+  [PSCustomObject]@{
+    Id = $_.Id
+    Document = $_.DocumentName
+    Status = $_.JobStatus
+    Pages = $_.TotalPages
+    Size = "$([math]::Round($_.Size / 1KB, 1)) KB"
+    Submitted = $_.SubmittedTime.ToString('yyyy-MM-dd HH:mm')
+  }
+} | ConvertTo-Json -Depth 3 -Compress`;
+
+					const result = await runPowerShell(ps, { timeout: 10000 });
+					if (result.exitCode !== 0) {
+						return { content: [{ type: 'text', text: `Error: ${result.stderr}` }], isError: true };
+					}
+					if (!result.stdout) {
+						return { content: [{ type: 'text', text: `Print queue for "${printer}" is empty.` }] };
+					}
+
+					const jobs = Array.isArray(JSON.parse(result.stdout)) ? JSON.parse(result.stdout) : [JSON.parse(result.stdout)];
+					const lines = jobs.map((j: { Id: number; Document: string; Status: string; Pages: number; Size: string }) =>
+						`  #${j.Id}  ${(j.Document || '').padEnd(30).slice(0, 30)}  ${(j.Status || '').padEnd(12)}  ${j.Pages} pg  ${j.Size}`,
+					);
+					return { content: [{ type: 'text', text: `Queue for "${printer}":\n${lines.join('\n')}` }] };
+				}
+
+				case 'set_default': {
+					if (!printer) {
+						return { content: [{ type: 'text', text: 'set_default requires printer name.' }], isError: true };
+					}
+					const ps = `
+$p = Get-CimInstance Win32_Printer -Filter "Name='${printer.replace(/'/g, "''")}'" -ErrorAction Stop
+Invoke-CimMethod -InputObject $p -MethodName SetDefaultPrinter | Out-Null
+"Default printer set to: ${printer}"`;
+					const result = await runPowerShell(ps, { timeout: 10000 });
+					return { content: [{ type: 'text', text: result.stdout || result.stderr }] };
+				}
+
+				case 'clear_queue': {
+					if (!printer) {
+						return { content: [{ type: 'text', text: 'clear_queue requires printer name.' }], isError: true };
+					}
+					const ps = `
+$jobs = Get-PrintJob -PrinterName '${printer.replace(/'/g, "''")}' -ErrorAction Stop
+$count = @($jobs).Count
+$jobs | Remove-PrintJob -ErrorAction SilentlyContinue
+"Cleared $count job(s) from ${printer}"`;
+					const result = await runPowerShell(ps, { timeout: 10000 });
+					return { content: [{ type: 'text', text: result.stdout || result.stderr }] };
+				}
+			}
+		},
+	);
+}

package/src/tools/process.ts

@@ -0,0 +1,80 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * Tool: windows_process_list — List running processes (#2)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { runPowerShell } from '../shell.js';
+
+interface ProcessInfo {
+	PID: number;
+	Name: string;
+	CPU: number;
+	MemoryMB: number;
+	WindowTitle: string;
+	Path: string;
+}
+
+export function registerProcessTools(server: McpServer): void {
+	server.tool(
+		'windows_process_list',
+		'List running processes with PID, name, CPU, memory, window title, and path.',
+		{
+			filter: z.string().optional().describe('Filter by process name (substring match)'),
+			sort: z.enum(['cpu', 'memory', 'name']).default('memory').describe('Sort order'),
+			limit: z.number().default(50).describe('Max results to return'),
+		},
+		async ({ filter, sort, limit }) => {
+			const filterClause = filter
+				? `| Where-Object { $_.Name -like '*${filter.replace(/'/g, "''")}*' }`
+				: '';
+
+			const sortClause = sort === 'cpu'
+				? '| Sort-Object CPU -Descending'
+				: sort === 'name'
+					? '| Sort-Object Name'
+					: '| Sort-Object WorkingSet64 -Descending';
+
+			const ps = `
+Get-Process ${filterClause} ${sortClause} | Select-Object -First ${limit} |
+ForEach-Object {
+  [PSCustomObject]@{
+    PID = $_.Id
+    Name = $_.ProcessName
+    CPU = [math]::Round($_.CPU, 1)
+    MemoryMB = [math]::Round($_.WorkingSet64 / 1MB, 1)
+    WindowTitle = $_.MainWindowTitle
+    Path = $_.Path
+  }
+} | ConvertTo-Json -Depth 3 -Compress`;
+
+			const result = await runPowerShell(ps);
+
+			if (result.exitCode !== 0) {
+				return { content: [{ type: 'text', text: `Error: ${result.stderr}` }], isError: true };
+			}
+
+			let processes: ProcessInfo[] = [];
+			if (result.stdout) {
+				const parsed = JSON.parse(result.stdout);
+				processes = Array.isArray(parsed) ? parsed : [parsed];
+			}
+
+			const lines = processes.map(p =>
+				`${String(p.PID).padStart(7)}  ${p.Name.padEnd(25).slice(0, 25)}  ${String(p.CPU ?? 0).padStart(8)}s  ${String(p.MemoryMB).padStart(8)} MB  ${p.WindowTitle || ''}`,
+			);
+
+			const header = `${'PID'.padStart(7)}  ${'Name'.padEnd(25)}  ${'CPU'.padStart(8)}   ${'Memory'.padStart(8)}     Window Title`;
+			const separator = '-'.repeat(90);
+
+			return {
+				content: [{
+					type: 'text',
+					text: `${header}\n${separator}\n${lines.join('\n')}\n\n${processes.length} processes`,
+				}],
+			};
+		},
+	);
+}

package/src/tools/process_kill.ts

@@ -0,0 +1,57 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * Tool: windows_process_kill (#3)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { runPowerShell } from '../shell.js';
+
+export function registerProcessKillTools(server: McpServer): void {
+	server.tool(
+		'windows_process_kill',
+		'Terminate running processes by PID or name.',
+		{
+			pid: z.number().optional().describe('Process ID to kill'),
+			name: z.string().optional().describe('Process name to kill (all matching)'),
+			force: z.boolean().default(false).describe('Force termination'),
+		},
+		async ({ pid, name, force }) => {
+			if (!pid && !name) {
+				return { content: [{ type: 'text', text: 'Provide either pid or name.' }], isError: true };
+			}
+
+			const forceFlag = force ? ' -Force' : '';
+			let ps: string;
+
+			if (pid) {
+				ps = `
+$p = Get-Process -Id ${pid} -ErrorAction SilentlyContinue
+if ($p) {
+  $n = $p.ProcessName
+  Stop-Process -Id ${pid}${forceFlag} -ErrorAction Stop
+  "Killed PID ${pid} ($n)"
+} else {
+  "No process with PID ${pid}"
+}`;
+			} else {
+				ps = `
+$procs = Get-Process -Name '${name!.replace(/'/g, "''")}' -ErrorAction SilentlyContinue
+if ($procs) {
+  $count = @($procs).Count
+  $procs | Stop-Process${forceFlag} -ErrorAction Stop
+  "Killed $count process(es) named '${name}'"
+} else {
+  "No processes named '${name}'"
+}`;
+			}
+
+			const result = await runPowerShell(ps);
+			return {
+				content: [{ type: 'text', text: result.stdout || result.stderr }],
+				isError: result.exitCode !== 0,
+			};
+		},
+	);
+}

package/src/tools/recycle_bin.ts

@@ -0,0 +1,126 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * Tool: windows_recycle_bin (#26)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { runPowerShell } from '../shell.js';
+
+export function registerRecycleBinTools(server: McpServer): void {
+	server.tool(
+		'windows_recycle_bin',
+		'Manage the Recycle Bin: list items, get size, restore items, or empty.',
+		{
+			action: z.enum(['list', 'size', 'empty', 'restore']).default('list').describe('Action'),
+			filter: z.string().optional().describe('Filter by filename (for list/restore)'),
+			limit: z.number().default(30).describe('Max items (for list)'),
+		},
+		async ({ action, filter, limit }) => {
+			switch (action) {
+				case 'size': {
+					const ps = `
+$shell = New-Object -ComObject Shell.Application
+$bin = $shell.Namespace(10)
+$items = $bin.Items()
+$count = $items.Count
+$totalSize = 0
+for ($i = 0; $i -lt $count; $i++) {
+  $totalSize += $bin.GetDetailsOf($items.Item($i), 2) -replace '[^0-9]','' -as [long]
+}
+[PSCustomObject]@{
+  Count = $count
+  SizeMB = [math]::Round($totalSize / 1MB, 1)
+} | ConvertTo-Json -Compress`;
+
+					const result = await runPowerShell(ps, { timeout: 15000 });
+					if (result.exitCode !== 0) {
+						return { content: [{ type: 'text', text: `Error: ${result.stderr}` }], isError: true };
+					}
+					const info = JSON.parse(result.stdout);
+					return { content: [{ type: 'text', text: `Recycle Bin: ${info.Count} items, ${info.SizeMB} MB` }] };
+				}
+
+				case 'list': {
+					const filterClause = filter
+						? `| Where-Object { $_.Name -like '*${filter.replace(/'/g, "''")}*' }`
+						: '';
+
+					const ps = `
+$shell = New-Object -ComObject Shell.Application
+$bin = $shell.Namespace(10)
+$items = @()
+foreach ($item in $bin.Items()) {
+  $items += [PSCustomObject]@{
+    Name = $item.Name
+    OriginalPath = $bin.GetDetailsOf($item, 1)
+    Size = $bin.GetDetailsOf($item, 2)
+    DeletedDate = $bin.GetDetailsOf($item, 3)
+    Type = $bin.GetDetailsOf($item, 4)
+  }
+}
+$items ${filterClause} | Select-Object -First ${limit} | ConvertTo-Json -Depth 3 -Compress`;
+
+					const result = await runPowerShell(ps, { timeout: 20000 });
+					if (result.exitCode !== 0) {
+						return { content: [{ type: 'text', text: `Error: ${result.stderr}` }], isError: true };
+					}
+					if (!result.stdout) {
+						return { content: [{ type: 'text', text: 'Recycle Bin is empty.' }] };
+					}
+
+					const items = Array.isArray(JSON.parse(result.stdout)) ? JSON.parse(result.stdout) : [JSON.parse(result.stdout)];
+					const lines = items.map((i: { Name: string; OriginalPath: string; Size: string; DeletedDate: string }) =>
+						`${(i.Name || '').padEnd(35).slice(0, 35)}  ${(i.Size || '').padStart(10)}  ${(i.DeletedDate || '').padEnd(20)}  ${(i.OriginalPath || '').slice(0, 40)}`,
+					);
+
+					const header = `${'Name'.padEnd(35)}  ${'Size'.padStart(10)}  ${'Deleted'.padEnd(20)}  Original Path`;
+					return {
+						content: [{ type: 'text', text: `${header}\n${'─'.repeat(110)}\n${lines.join('\n')}\n\n${items.length} items` }],
+					};
+				}
+
+				case 'empty': {
+					const ps = `
+$shell = New-Object -ComObject Shell.Application
+$count = $shell.Namespace(10).Items().Count
+if ($count -eq 0) { "Recycle Bin is already empty." }
+else {
+  Clear-RecycleBin -Force -ErrorAction Stop
+  "Emptied Recycle Bin ($count items removed)"
+}`;
+					const result = await runPowerShell(ps, { timeout: 15000 });
+					return {
+						content: [{ type: 'text', text: result.stdout || result.stderr }],
+						isError: result.exitCode !== 0,
+					};
+				}
+
+				case 'restore': {
+					if (!filter) {
+						return { content: [{ type: 'text', text: 'Restore requires a filter to identify which item(s) to restore.' }], isError: true };
+					}
+					const ps = `
+$shell = New-Object -ComObject Shell.Application
+$bin = $shell.Namespace(10)
+$restored = 0
+foreach ($item in $bin.Items()) {
+  if ($item.Name -like '*${filter.replace(/'/g, "''")}*') {
+    $origPath = $bin.GetDetailsOf($item, 1)
+    $item.InvokeVerb('undelete')
+    $restored++
+  }
+}
+if ($restored -gt 0) { "Restored $restored item(s)" } else { "No matching items found" }`;
+
+					const result = await runPowerShell(ps, { timeout: 15000 });
+					return {
+						content: [{ type: 'text', text: result.stdout || result.stderr }],
+						isError: result.exitCode !== 0,
+					};
+				}
+			}
+		},
+	);
+}