@mokoconsulting/mcp-windows 3.0.0

package/scripts/setup.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: mcp_windows.Scripts
+ * INGROUP: mcp_windows
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mcp_windows
+ * PATH: /scripts/setup.mjs
+ * VERSION: 01.00.00
+ * BRIEF: Interactive setup — prompts for API connection details and writes config
+ */
+
+import { createInterface } from 'node:readline/promises';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+// ── Customize these ─────────────────────────────────────────────────────
+const PROJECT_NAME = 'mcp_windows';
+const CONFIG_PATH = resolve(homedir(), `.${PROJECT_NAME}.json`);
+const API_LABEL = 'Windows Desktop';       // e.g. "Dolibarr", "Joomla"
+const AUTH_FIELD = 'apiKey';                 // field name in config
+const AUTH_PROMPT = 'API key';              // what to ask the user for
+// ────────────────────────────────────────────────────────────────────────
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+async function prompt(question, defaultValue) {
+	const suffix = defaultValue ? ` [${defaultValue}]` : '';
+	const answer = await rl.question(`${question}${suffix}: `);
+	return answer.trim() || defaultValue || '';
+}
+
+async function promptRequired(question) {
+	let answer = '';
+	while (!answer) {
+		answer = (await rl.question(`${question}: `)).trim();
+		if (!answer) {
+			console.log('  This field is required.');
+		}
+	}
+	return answer;
+}
+
+async function main() {
+	console.log('');
+	console.log(`=== ${PROJECT_NAME} Setup ===`);
+	console.log('');
+	console.log('This will create your configuration file at:');
+	console.log(`  ${CONFIG_PATH}`);
+	console.log('');
+
+	let existing = null;
+	try {
+		const raw = await readFile(CONFIG_PATH, 'utf-8');
+		existing = JSON.parse(raw);
+		console.log('Existing config found. You can add a new connection or overwrite.');
+		console.log(`  Current connections: ${Object.keys(existing.connections).join(', ')}`);
+		console.log('');
+	} catch {
+		// No existing config
+	}
+
+	const connectionName = await prompt('Connection name', 'production');
+	const baseUrl = await promptRequired(`${API_LABEL} URL (e.g. https://api.example.com)`);
+	const authValue = await promptRequired(`${API_LABEL} ${AUTH_PROMPT}`);
+
+	const cleanUrl = baseUrl.replace(/\/+$/, '');
+
+	const insecureAnswer = await prompt('Skip TLS verification for self-signed certs? (y/N)', 'N');
+	const insecure = insecureAnswer.toLowerCase() === 'y';
+
+	const connection = { baseUrl: cleanUrl, [AUTH_FIELD]: authValue };
+	if (insecure) {
+		connection.insecure = true;
+	}
+
+	let config;
+	if (existing) {
+		config = existing;
+		config.connections[connectionName] = connection;
+		const setDefault = await prompt(`Set "${connectionName}" as default connection? (y/N)`, 'N');
+		if (setDefault.toLowerCase() === 'y') {
+			config.defaultConnection = connectionName;
+		}
+	} else {
+		config = {
+			defaultConnection: connectionName,
+			connections: {
+				[connectionName]: connection,
+			},
+		};
+	}
+
+	await writeFile(CONFIG_PATH, JSON.stringify(config, null, '\t') + '\n', 'utf-8');
+
+	console.log('');
+	console.log(`Config written to ${CONFIG_PATH}`);
+	console.log(`  Connection "${connectionName}" configured for ${cleanUrl}`);
+	console.log('');
+
+	const addAnother = await prompt('Add another connection? (y/N)', 'N');
+	if (addAnother.toLowerCase() === 'y') {
+		rl.close();
+		const { execFileSync } = await import('node:child_process');
+		execFileSync('node', [new URL(import.meta.url).pathname], { stdio: 'inherit' });
+		return;
+	}
+
+	console.log('Setup complete. You can now use the MCP server.');
+	console.log('');
+	rl.close();
+}
+
+main().catch((err) => {
+	console.error(`Setup failed: ${err.message}`);
+	rl.close();
+	process.exit(1);
+});

package/src/index.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * mcp_windows — MCP server for Windows desktop system operations
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerExecuteTools } from './tools/execute.js';
+import { registerProcessTools } from './tools/process.js';
+import { registerAudioTools } from './tools/audio.js';
+import { registerSystemTools } from './tools/system.js';
+import { registerTerminalTools } from './tools/terminal.js';
+import { registerFilesystemTools } from './tools/filesystem.js';
+import { registerProcessKillTools } from './tools/process_kill.js';
+import { registerServiceTools } from './tools/service.js';
+import { registerAudioAppTools } from './tools/audio_apps.js';
+import { registerPowerTools } from './tools/power.js';
+import { registerNetworkTools } from './tools/network.js';
+import { registerDriveTools } from './tools/drives.js';
+import { registerDisplayTools } from './tools/display.js';
+import { registerWindowTools } from './tools/window.js';
+import { registerClipboardTools } from './tools/clipboard.js';
+import { registerNotificationTools } from './tools/notification.js';
+import { registerSchedulerTools } from './tools/scheduler.js';
+import { registerRegistryTools } from './tools/registry.js';
+import { registerEnvironmentTools } from './tools/environment.js';
+import { registerStartupTools } from './tools/startup.js';
+import { registerConfigTools } from './tools/config.js';
+import { registerAppsTools } from './tools/apps.js';
+import { registerDialogTools } from './tools/dialog.js';
+import { registerNetstatTools } from './tools/netstat.js';
+import { registerRecycleBinTools } from './tools/recycle_bin.js';
+import { registerBluetoothTools } from './tools/bluetooth.js';
+import { registerWifiTools } from './tools/wifi.js';
+import { registerUsbTools } from './tools/usb.js';
+import { registerPrinterTools } from './tools/printer.js';
+import { registerHostsTools } from './tools/hosts.js';
+import { registerThemeTools } from './tools/theme.js';
+import { registerVirtualDesktopTools } from './tools/virtual_desktop.js';
+import { registerFirewallTools } from './tools/firewall.js';
+import { registerMaintenanceTools } from './tools/maintenance.js';
+import { registerWslTools } from './tools/wsl.js';
+import { registerWingetTools } from './tools/winget.js';
+import { registerStorageTools } from './tools/storage.js';
+import { registerSystemMgmtTools } from './tools/system_mgmt.js';
+import { registerAutomationTools } from './tools/automation.js';
+
+const server = new McpServer({
+	name: 'mcp_windows',
+	version: '3.0.0',
+});
+
+// v1.0 — Core
+registerExecuteTools(server);
+registerProcessTools(server);
+registerAudioTools(server);
+registerSystemTools(server);
+registerTerminalTools(server);
+registerFilesystemTools(server);
+
+// v1.1 — System Control
+registerProcessKillTools(server);
+registerServiceTools(server);
+registerAudioAppTools(server);
+registerPowerTools(server);
+registerNetworkTools(server);
+registerDriveTools(server);
+
+// v1.2 — Desktop Automation
+registerDisplayTools(server);
+registerWindowTools(server);
+registerClipboardTools(server);
+registerNotificationTools(server);
+
+// v1.3 — Admin Tools
+registerSchedulerTools(server);
+registerRegistryTools(server);
+registerEnvironmentTools(server);
+registerStartupTools(server);
+registerConfigTools(server);
+
+// v1.4 — Advanced
+registerAppsTools(server);
+registerDialogTools(server);
+registerNetstatTools(server);
+registerRecycleBinTools(server);
+
+// v2.0 — Connectivity & Hardware
+registerBluetoothTools(server);
+registerWifiTools(server);
+registerUsbTools(server);
+registerPrinterTools(server);
+registerHostsTools(server);
+
+// v2.1 — Appearance & Desktop
+registerThemeTools(server);
+registerVirtualDesktopTools(server);
+
+// v2.2 — Security & Maintenance
+registerFirewallTools(server);
+registerMaintenanceTools(server);
+
+// v3.0 — WSL & Package Management
+registerWslTools(server);
+registerWingetTools(server);
+
+// v3.1 — Storage & System Management
+registerStorageTools(server);
+registerSystemMgmtTools(server);
+
+// v3.2 — Automation & Advanced
+registerAutomationTools(server);
+
+async function main(): Promise<void> {
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	process.stderr.write('mcp_windows: server started\n');
+}
+
+main().catch((err) => {
+	process.stderr.write(`mcp_windows: fatal error: ${err}\n`);
+	process.exit(1);
+});

package/src/shell.ts

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { execFile, spawn, ChildProcess } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export interface ShellResult {
+	stdout: string;
+	stderr: string;
+	exitCode: number;
+}
+
+const POWERSHELL = 'powershell.exe';
+const DEFAULT_TIMEOUT = 30_000;
+
+/**
+ * Run a PowerShell command and return stdout/stderr/exitCode.
+ * Commands are wrapped with -NoProfile -NonInteractive for speed and safety.
+ */
+export async function runPowerShell(
+	command: string,
+	options: { timeout?: number; cwd?: string } = {},
+): Promise<ShellResult> {
+	const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+	try {
+		const { stdout, stderr } = await execFileAsync(POWERSHELL, [
+			'-NoProfile',
+			'-NonInteractive',
+			'-Command',
+			command,
+		], {
+			timeout,
+			cwd: options.cwd,
+			maxBuffer: 10 * 1024 * 1024,
+			windowsHide: true,
+		});
+		return { stdout: stdout.trimEnd(), stderr: stderr.trimEnd(), exitCode: 0 };
+	} catch (err: unknown) {
+		const e = err as { stdout?: string; stderr?: string; code?: number | string; killed?: boolean };
+		if (e.killed) {
+			return {
+				stdout: e.stdout?.trimEnd() ?? '',
+				stderr: `Command timed out after ${timeout}ms`,
+				exitCode: -1,
+			};
+		}
+		return {
+			stdout: e.stdout?.trimEnd() ?? '',
+			stderr: e.stderr?.trimEnd() ?? String(err),
+			exitCode: typeof e.code === 'number' ? e.code : 1,
+		};
+	}
+}
+
+/**
+ * Run a PowerShell command that returns JSON. Wraps output with ConvertTo-Json
+ * and parses the result.
+ */
+export async function runPowerShellJson<T = unknown>(
+	command: string,
+	options: { timeout?: number; cwd?: string } = {},
+): Promise<T> {
+	const wrapped = `${command} | ConvertTo-Json -Depth 10 -Compress`;
+	const result = await runPowerShell(wrapped, options);
+	if (result.exitCode !== 0) {
+		throw new Error(result.stderr || `PowerShell exited with code ${result.exitCode}`);
+	}
+	if (!result.stdout) {
+		return [] as unknown as T;
+	}
+	return JSON.parse(result.stdout) as T;
+}
+
+/**
+ * Run a generic shell command (cmd, bash, pwsh).
+ */
+export async function runShell(
+	command: string,
+	options: {
+		shell?: 'pwsh' | 'cmd' | 'bash';
+		timeout?: number;
+		cwd?: string;
+	} = {},
+): Promise<ShellResult> {
+	const shell = options.shell ?? 'pwsh';
+	const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+
+	let executable: string;
+	let args: string[];
+
+	switch (shell) {
+		case 'cmd':
+			executable = 'cmd.exe';
+			args = ['/c', command];
+			break;
+		case 'bash':
+			executable = 'bash';
+			args = ['-c', command];
+			break;
+		case 'pwsh':
+		default:
+			executable = POWERSHELL;
+			args = ['-NoProfile', '-NonInteractive', '-Command', command];
+			break;
+	}
+
+	try {
+		const { stdout, stderr } = await execFileAsync(executable, args, {
+			timeout,
+			cwd: options.cwd,
+			maxBuffer: 10 * 1024 * 1024,
+			windowsHide: true,
+		});
+		return { stdout: stdout.trimEnd(), stderr: stderr.trimEnd(), exitCode: 0 };
+	} catch (err: unknown) {
+		const e = err as { stdout?: string; stderr?: string; code?: number | string; killed?: boolean };
+		if (e.killed) {
+			return {
+				stdout: e.stdout?.trimEnd() ?? '',
+				stderr: `Command timed out after ${timeout}ms`,
+				exitCode: -1,
+			};
+		}
+		return {
+			stdout: e.stdout?.trimEnd() ?? '',
+			stderr: e.stderr?.trimEnd() ?? String(err),
+			exitCode: typeof e.code === 'number' ? e.code : 1,
+		};
+	}
+}
+
+
+// ── Persistent Terminal Sessions ─────────────────────────────────────────
+
+export interface TerminalSession {
+	pid: number;
+	shell: string;
+	process: ChildProcess;
+	output: string[];
+	startedAt: Date;
+}
+
+const sessions = new Map<number, TerminalSession>();
+const MAX_OUTPUT_LINES = 5000;
+
+export function startSession(shell: 'pwsh' | 'cmd' | 'bash' | 'python' | 'node' | 'wsl' = 'pwsh'): TerminalSession {
+	let executable: string;
+	let args: string[];
+
+	switch (shell) {
+		case 'cmd':
+			executable = 'cmd.exe';
+			args = [];
+			break;
+		case 'bash':
+			executable = 'bash';
+			args = [];
+			break;
+		case 'python':
+			executable = 'python';
+			args = ['-i'];
+			break;
+		case 'node':
+			executable = 'node';
+			args = [];
+			break;
+		case 'wsl':
+			executable = 'wsl.exe';
+			args = [];
+			break;
+		case 'pwsh':
+		default:
+			executable = POWERSHELL;
+			args = ['-NoProfile', '-NoLogo'];
+			break;
+	}
+
+	const proc = spawn(executable, args, {
+		stdio: ['pipe', 'pipe', 'pipe'],
+		windowsHide: true,
+		detached: false,
+	});
+	// Don't let terminal sessions prevent the MCP server from exiting
+	proc.unref();
+	(proc.stdout as any)?.unref?.();
+	(proc.stderr as any)?.unref?.();
+	(proc.stdin as any)?.unref?.();
+
+	const session: TerminalSession = {
+		pid: proc.pid!,
+		shell,
+		process: proc,
+		output: [],
+		startedAt: new Date(),
+	};
+
+	const pushLine = (line: string) => {
+		session.output.push(line);
+		if (session.output.length > MAX_OUTPUT_LINES) {
+			session.output.splice(0, session.output.length - MAX_OUTPUT_LINES);
+		}
+	};
+
+	proc.stdout?.on('data', (data: Buffer) => {
+		data.toString().split('\n').forEach(pushLine);
+	});
+	proc.stderr?.on('data', (data: Buffer) => {
+		data.toString().split('\n').forEach(l => pushLine(`[stderr] ${l}`));
+	});
+	proc.on('exit', () => {
+		pushLine(`[session ended]`);
+	});
+
+	sessions.set(proc.pid!, session);
+	return session;
+}
+
+export function sendToSession(pid: number, input: string): void {
+	const session = sessions.get(pid);
+	if (!session) throw new Error(`No session with PID ${pid}`);
+	if (session.process.exitCode !== null) throw new Error(`Session ${pid} has ended`);
+	session.process.stdin?.write(input + '\n');
+}
+
+export function readSessionOutput(pid: number, offset = 0, length?: number): string[] {
+	const session = sessions.get(pid);
+	if (!session) throw new Error(`No session with PID ${pid}`);
+	const start = offset < 0 ? Math.max(0, session.output.length + offset) : offset;
+	const end = length !== undefined ? start + length : undefined;
+	return session.output.slice(start, end);
+}
+
+export function listSessions(): Array<{ pid: number; shell: string; running: boolean; lines: number; startedAt: string }> {
+	return Array.from(sessions.values()).map(s => ({
+		pid: s.pid,
+		shell: s.shell,
+		running: s.process.exitCode === null,
+		lines: s.output.length,
+		startedAt: s.startedAt.toISOString(),
+	}));
+}
+
+export function terminateSession(pid: number): boolean {
+	const session = sessions.get(pid);
+	if (!session) return false;
+	session.process.kill();
+	sessions.delete(pid);
+	return true;
+}

package/src/tools/apps.ts

@@ -0,0 +1,76 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * Tool: windows_installed_apps (#19)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { runPowerShell } from '../shell.js';
+
+export function registerAppsTools(server: McpServer): void {
+	server.tool(
+		'windows_installed_apps',
+		'List installed applications from registry and Microsoft Store.',
+		{
+			filter: z.string().optional().describe('Filter by app name (substring)'),
+			sort: z.enum(['name', 'date', 'size']).default('name').describe('Sort order'),
+			limit: z.number().default(50).describe('Max results'),
+		},
+		async ({ filter, sort, limit }) => {
+			const filterClause = filter
+				? `| Where-Object { $_.DisplayName -like '*${filter.replace(/'/g, "''")}*' }`
+				: '';
+
+			const sortClause = sort === 'date'
+				? '| Sort-Object InstallDate -Descending'
+				: sort === 'size'
+					? '| Sort-Object { [int]$_.EstimatedSize } -Descending'
+					: '| Sort-Object DisplayName';
+
+			const ps = `
+$regPaths = @(
+  'HKLM:\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\*',
+  'HKLM:\\Software\\WOW6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\*',
+  'HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\*'
+)
+
+$apps = $regPaths | ForEach-Object {
+  Get-ItemProperty -Path $_ -ErrorAction SilentlyContinue
+} | Where-Object { $_.DisplayName } ${filterClause} ${sortClause} |
+  Select-Object -First ${limit} |
+  ForEach-Object {
+    [PSCustomObject]@{
+      Name = $_.DisplayName
+      Version = $_.DisplayVersion
+      Publisher = $_.Publisher
+      InstallDate = $_.InstallDate
+      SizeMB = if ($_.EstimatedSize) { [math]::Round($_.EstimatedSize / 1024, 1) } else { $null }
+    }
+  }
+
+$apps | 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: 'No apps found.' }] };
+			}
+
+			const apps = Array.isArray(JSON.parse(result.stdout)) ? JSON.parse(result.stdout) : [JSON.parse(result.stdout)];
+			const lines = apps.map((a: { Name: string; Version: string; Publisher: string; InstallDate: string; SizeMB: number | null }) => {
+				const size = a.SizeMB ? `${String(a.SizeMB).padStart(8)} MB` : '          ';
+				const date = a.InstallDate || '          ';
+				return `${(a.Name || '').padEnd(45).slice(0, 45)}  ${(a.Version || '').padEnd(15).slice(0, 15)}  ${date.padEnd(10)}  ${size}  ${(a.Publisher || '').slice(0, 25)}`;
+			});
+
+			const header = `${'Name'.padEnd(45)}  ${'Version'.padEnd(15)}  ${'Installed'.padEnd(10)}  ${'Size'.padStart(11)}  Publisher`;
+			return {
+				content: [{ type: 'text', text: `${header}\n${'─'.repeat(115)}\n${lines.join('\n')}\n\n${apps.length} applications` }],
+			};
+		},
+	);
+}