From 03e7ea0e69512fc78de2ff5dae715d01526663c6 Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Mon, 25 May 2026 21:03:40 -0500 Subject: [PATCH] feat: implement v1.0 high-priority tools (14 tools) Replace template API scaffolding with Windows desktop system tools: - shell.ts: PowerShell/cmd/bash executor + persistent terminal sessions - tools/execute.ts: windows_execute (#1) - tools/process.ts: windows_process_list (#2) - tools/audio.ts: windows_audio_get, windows_audio_set (#6, #7) - tools/system.ts: windows_system_info (#18) - tools/terminal.ts: windows_terminal_start/send/read/list/kill (#35) - tools/filesystem.ts: windows_file_read/write/edit, windows_search (#36-39) Removes template API client/config/types (not needed for local OS MCP). Authored-by: Moko Consulting --- ISSUES.md | 601 ++++++++++++++++++++++++++++++++++++++++ src/client.ts | 129 --------- src/config.ts | 63 ----- src/index.ts | 192 ++----------- src/shell.ts | 247 +++++++++++++++++ src/tools/audio.ts | 161 +++++++++++ src/tools/execute.ts | 35 +++ src/tools/filesystem.ts | 273 ++++++++++++++++++ src/tools/process.ts | 80 ++++++ src/tools/system.ts | 99 +++++++ src/tools/terminal.ts | 117 ++++++++ src/types.ts | 48 ---- 12 files changed, 1629 insertions(+), 416 deletions(-) create mode 100644 ISSUES.md delete mode 100644 src/client.ts delete mode 100644 src/config.ts create mode 100644 src/shell.ts create mode 100644 src/tools/audio.ts create mode 100644 src/tools/execute.ts create mode 100644 src/tools/filesystem.ts create mode 100644 src/tools/process.ts create mode 100644 src/tools/system.ts create mode 100644 src/tools/terminal.ts delete mode 100644 src/types.ts diff --git a/ISSUES.md b/ISSUES.md new file mode 100644 index 0000000..5c30606 --- /dev/null +++ b/ISSUES.md @@ -0,0 +1,601 @@ +# mcp_windows — Feature Issues + +Issues to create on Gitea once repo is published. +Labels: `type: feature`, `priority: normal` unless noted otherwise. + +--- + +## Category: Terminal & Process Execution + +### Issue 1: Tool — `windows_execute` +**Labels:** `type: feature`, `priority: high` + +Execute shell commands (PowerShell, cmd, bash) with intelligent completion detection. Support background execution, timeout, and working directory. + +**Acceptance criteria:** +- Execute PowerShell commands by default +- Support `shell` param: `pwsh`, `cmd`, `bash` +- Support `timeout` param (ms) +- Support `cwd` (working directory) +- Support `background` flag for long-running commands +- Return stdout, stderr, exit code +- Detect hung/interactive prompts + +--- + +### Issue 2: Tool — `windows_process_list` +**Labels:** `type: feature`, `priority: high` + +List running processes with PID, name, CPU%, memory usage, window title, and path. + +**Acceptance criteria:** +- Return all running processes +- Include: PID, name, CPU%, memory (MB), window title, executable path +- Support `filter` param (name substring match) +- Support `sort` param (cpu, memory, name) + +--- + +### Issue 3: Tool — `windows_process_kill` +**Labels:** `type: feature`, `priority: normal` + +Terminate a running process by PID or name. + +**Acceptance criteria:** +- Kill by PID (single or array) +- Kill by name (with confirmation count) +- Support `force` flag for immediate termination +- Return success/failure per process + +--- + +### Issue 4: Tool — `windows_service_list` +**Labels:** `type: feature`, `priority: normal` + +List Windows services with status, startup type, and description. + +**Acceptance criteria:** +- Return all services (or filtered by status/name) +- Include: name, display name, status, startup type, description +- Support `filter` param (name match) +- Support `status` param (running, stopped, all) + +--- + +### Issue 5: Tool — `windows_service_control` +**Labels:** `type: feature`, `priority: normal` + +Start, stop, restart, or change startup type of Windows services. + +**Acceptance criteria:** +- Actions: start, stop, restart, enable, disable +- Support service name or display name +- Return new service status after action +- Require elevation indicator for protected services + +--- + +## Category: Audio & Volume Control + +### Issue 6: Tool — `windows_audio_get` +**Labels:** `type: feature`, `priority: high` + +Get current audio state: master volume level, mute status, default device. + +**Acceptance criteria:** +- Return master volume (0-100) +- Return mute state (boolean) +- Return default playback device name +- Return list of available audio devices + +--- + +### Issue 7: Tool — `windows_audio_set` +**Labels:** `type: feature`, `priority: high` + +Set audio volume, mute/unmute, or change default audio device. + +**Acceptance criteria:** +- Set master volume (0-100) +- Set mute state (true/false/toggle) +- Set default playback device by name +- Return new state after change + +--- + +### Issue 8: Tool — `windows_audio_app_volumes` +**Labels:** `type: feature`, `priority: normal` + +Get and set per-application volume levels. + +**Acceptance criteria:** +- List all apps with active audio sessions +- Get volume/mute per app +- Set volume/mute per app +- Identify apps by name or PID + +--- + +## Category: Display & Monitor + +### Issue 9: Tool — `windows_display_get` +**Labels:** `type: feature`, `priority: normal` + +Get display configuration: resolution, refresh rate, scaling, multi-monitor layout. + +**Acceptance criteria:** +- List all connected monitors +- Per monitor: resolution, refresh rate, scaling %, position, primary flag +- Include display name/model +- Report HDR status + +--- + +### Issue 10: Tool — `windows_display_set` +**Labels:** `type: feature`, `priority: normal` + +Change display settings: resolution, refresh rate, scaling, brightness. + +**Acceptance criteria:** +- Set resolution per monitor +- Set refresh rate +- Set brightness (where supported) +- Set scaling percentage +- Return new settings after change + +--- + +### Issue 11: Tool — `windows_screenshot` +**Labels:** `type: feature`, `priority: normal` + +Capture screenshot of screen, window, or region. + +**Acceptance criteria:** +- Capture full screen (specify monitor) +- Capture specific window by title/PID +- Capture region (x, y, width, height) +- Return as base64 or save to file path +- Support format: png, jpg + +--- + +## Category: Power Management + +### Issue 12: Tool — `windows_power_get` +**Labels:** `type: feature`, `priority: normal` + +Get power state: battery level, AC/battery, power plan, screen timeout settings. + +**Acceptance criteria:** +- Battery percentage and charging status +- Current power plan name +- Screen/sleep timeout values +- Estimated time remaining (battery) + +--- + +### Issue 13: Tool — `windows_power_action` +**Labels:** `type: feature`, `priority: normal` + +Execute power actions: sleep, hibernate, lock, shutdown, restart, schedule. + +**Acceptance criteria:** +- Actions: sleep, hibernate, lock, shutdown, restart, log-off +- Support `delay` param (seconds) +- Support `cancel` to abort scheduled action +- Support power plan switch (balanced, performance, power saver) + +--- + +## Category: Window Management + +### Issue 14: Tool — `windows_window_list` +**Labels:** `type: feature`, `priority: normal` + +List all open windows with title, position, size, state. + +**Acceptance criteria:** +- List visible windows +- Include: title, PID, process name, position (x,y), size (w,h), state (minimized/maximized/normal) +- Support `filter` by title or process name +- Include z-order (front to back) + +--- + +### Issue 15: Tool — `windows_window_control` +**Labels:** `type: feature`, `priority: normal` + +Move, resize, minimize, maximize, close, or focus windows. + +**Acceptance criteria:** +- Actions: minimize, maximize, restore, close, focus, move, resize +- Identify window by title (substring) or PID +- Move: set x, y position +- Resize: set width, height +- Support `topmost` flag (always on top) + +--- + +## Category: Clipboard + +### Issue 16: Tool — `windows_clipboard_get` +**Labels:** `type: feature`, `priority: normal` + +Read clipboard contents (text, file paths, image). + +**Acceptance criteria:** +- Get text content +- Get file list (when files are copied) +- Get image as base64 (when image is copied) +- Report content type available + +--- + +### Issue 17: Tool — `windows_clipboard_set` +**Labels:** `type: feature`, `priority: normal` + +Set clipboard contents. + +**Acceptance criteria:** +- Set text content +- Set file list (for paste-as-files) +- Set image from base64 or file path +- Clear clipboard + +--- + +## Category: System Information + +### Issue 18: Tool — `windows_system_info` +**Labels:** `type: feature`, `priority: high` + +Get comprehensive system information. + +**Acceptance criteria:** +- OS version, build, edition +- CPU: model, cores, usage % +- RAM: total, available, used % +- Disk: per-drive total, free, usage % +- Network: adapters, IPs, connection status +- Uptime +- Hostname, username, domain + +--- + +### Issue 19: Tool — `windows_installed_apps` +**Labels:** `type: feature`, `priority: low` + +List installed applications. + +**Acceptance criteria:** +- List apps from registry + Store apps +- Include: name, version, publisher, install date, size +- Support `filter` param +- Support `sort` param (name, date, size) + +--- + +## Category: Notifications & UI + +### Issue 20: Tool — `windows_notification_send` +**Labels:** `type: feature`, `priority: normal` + +Send Windows toast notifications. + +**Acceptance criteria:** +- Title and body text +- Support icon (file path) +- Support action buttons +- Support expiration time +- Optional sound + +--- + +### Issue 21: Tool — `windows_dialog` +**Labels:** `type: feature`, `priority: low` + +Show system dialog boxes (message box, input, file picker). + +**Acceptance criteria:** +- Message box with configurable buttons (OK, Yes/No, etc.) +- Input dialog (text prompt) +- File open/save dialog with filters +- Folder picker +- Return user selection + +--- + +## Category: Network + +### Issue 22: Tool — `windows_network_info` +**Labels:** `type: feature`, `priority: normal` + +Get network configuration and status. + +**Acceptance criteria:** +- List adapters: name, type, status, IP, MAC, speed +- DNS servers +- Default gateway +- Wi-Fi: SSID, signal strength, security +- Current internet connectivity status + +--- + +### Issue 23: Tool — `windows_network_connections` +**Labels:** `type: feature`, `priority: low` + +List active network connections (like netstat). + +**Acceptance criteria:** +- List TCP/UDP connections +- Include: local addr:port, remote addr:port, state, PID, process name +- Support filter by state, port, process +- Support `listen` flag (only listening ports) + +--- + +## Category: File System (Enhanced) + +### Issue 24: Tool — `windows_drives` +**Labels:** `type: feature`, `priority: normal` + +List drives/volumes with type, label, capacity, free space. + +**Acceptance criteria:** +- All mounted drives (local, network, removable) +- Include: letter, label, type, filesystem, total, free, used % +- Detect USB/removable vs fixed vs network + +--- + +### Issue 25: Tool — `windows_file_search` +**Labels:** `type: feature`, `priority: normal` + +Search files using Windows Search index (instant results for indexed locations). + +**Acceptance criteria:** +- Search by name pattern (glob or regex) +- Search by content (indexed content search) +- Filter by date range, size, type +- Use Windows Search index when available +- Fallback to filesystem walk for non-indexed paths +- Return: path, size, modified date, type + +--- + +### Issue 26: Tool — `windows_recycle_bin` +**Labels:** `type: feature`, `priority: low` + +Manage the Recycle Bin. + +**Acceptance criteria:** +- List items (name, original path, size, deleted date) +- Restore item(s) +- Empty bin (all or selected) +- Get bin size/count + +--- + +## Category: Scheduled Tasks + +### Issue 27: Tool — `windows_task_scheduler_list` +**Labels:** `type: feature`, `priority: normal` + +List Windows Task Scheduler tasks. + +**Acceptance criteria:** +- List all tasks or filter by folder/name +- Include: name, status, last run, next run, trigger type +- Support folder navigation + +--- + +### Issue 28: Tool — `windows_task_scheduler_manage` +**Labels:** `type: feature`, `priority: normal` + +Create, delete, enable, disable, or run scheduled tasks. + +**Acceptance criteria:** +- Create task: name, command, trigger (time, interval, event), run level +- Delete task by name +- Enable/disable task +- Run task immediately +- Modify existing task triggers + +--- + +## Category: Registry + +### Issue 29: Tool — `windows_registry_read` +**Labels:** `type: feature`, `priority: low` + +Read Windows Registry keys and values. + +**Acceptance criteria:** +- Read value by full path (HKLM, HKCU, etc.) +- List subkeys of a key +- List values of a key +- Return value type (REG_SZ, DWORD, etc.) +- Support common abbreviations (HKLM, HKCU, HKCR) + +--- + +### Issue 30: Tool — `windows_registry_write` +**Labels:** `type: feature`, `priority: low`, `priority: caution` + +Write Windows Registry keys and values. + +**Acceptance criteria:** +- Set value (string, dword, binary, expandsz, multi_sz) +- Create key +- Delete value +- Delete key (with confirmation) +- Backup key before modification +- Restricted to HKCU by default (HKLM requires explicit flag) + +--- + +## Category: Environment & Configuration + +### Issue 31: Tool — `windows_env_get` +**Labels:** `type: feature`, `priority: normal` + +Get environment variables (user, system, process). + +**Acceptance criteria:** +- Get specific variable by name +- List all variables (user, system, or both) +- Show PATH as parsed list +- Indicate scope (user vs system) + +--- + +### Issue 32: Tool — `windows_env_set` +**Labels:** `type: feature`, `priority: normal` + +Set environment variables persistently (user or system scope). + +**Acceptance criteria:** +- Set user-scope variable +- Set system-scope variable (requires elevation) +- Append/prepend to PATH +- Remove variable +- Changes persist across sessions + +--- + +## Category: Startup & Autorun + +### Issue 33: Tool — `windows_startup_list` +**Labels:** `type: feature`, `priority: normal` + +List applications configured to run at startup. + +**Acceptance criteria:** +- Registry Run/RunOnce (HKLM + HKCU) +- Startup folder items +- Scheduled tasks set to run at logon +- Task Manager startup tab equivalent +- Include: name, command, location, enabled status + +--- + +### Issue 34: Tool — `windows_startup_manage` +**Labels:** `type: feature`, `priority: normal` + +Enable, disable, or add startup items. + +**Acceptance criteria:** +- Disable/enable existing startup item +- Add new startup item (registry or startup folder) +- Remove startup item +- Set startup delay + +--- + +## Category: Desktop Commander Parity (Terminal) + +### Issue 35: Tool — `windows_terminal_session` +**Labels:** `type: feature`, `priority: high` + +Persistent interactive terminal sessions (REPL, SSH, etc.) with output pagination. + +**Acceptance criteria:** +- Start persistent session (pwsh, cmd, python, node, wsl) +- Send input to session +- Read output with offset/length pagination +- List active sessions +- Terminate session +- Detect prompt/completion state +- Context overflow protection (configurable line limit) + +--- + +### Issue 36: Tool — `windows_file_read` +**Labels:** `type: feature`, `priority: high` + +Read files with smart pagination, format detection, and URL support. + +**Acceptance criteria:** +- Text files with line offset/length pagination +- PDF text extraction +- Excel: sheet selection, range support +- DOCX: outline mode +- Images: base64 encoding +- URL fetching (isUrl flag) +- Binary file detection +- Negative offset for tail behavior + +--- + +### Issue 37: Tool — `windows_file_write` +**Labels:** `type: feature`, `priority: high` + +Write files with format support and chunking. + +**Acceptance criteria:** +- Text write/append +- Excel write (JSON 2D array → .xlsx) +- DOCX creation from markdown +- PDF creation from markdown +- Chunked writing for large files +- Create parent directories if needed + +--- + +### Issue 38: Tool — `windows_file_edit` +**Labels:** `type: feature`, `priority: high` + +Surgical file edits with find/replace. + +**Acceptance criteria:** +- Find and replace text (single or all occurrences) +- Expected replacement count validation +- Character-level diff on near-matches +- Line-range replacement +- Regex support +- Dry-run mode + +--- + +### Issue 39: Tool — `windows_search` +**Labels:** `type: feature`, `priority: high` + +Search files by name or content with streaming results. + +**Acceptance criteria:** +- Search by filename pattern (glob) +- Search by file content (regex or literal) +- Case sensitivity toggle +- File type filter +- Exclude patterns +- Context lines around matches +- Result pagination +- Background/streaming mode for large searches + +--- + +## Category: Configuration + +### Issue 40: Tool — `windows_mcp_config` +**Labels:** `type: feature`, `priority: normal` + +Get and set mcp_windows configuration. + +**Acceptance criteria:** +- Get current config (allowed paths, blocked commands, limits) +- Set values dynamically without restart +- Configurable: blocked commands, allowed directories, output line limits +- Persist config to `~/.mcp_windows.json` + +--- + +## Milestone Plan + +| Milestone | Issues | Priority | +|-----------|--------|----------| +| **v1.0 — Core** | #1, #2, #6, #7, #18, #35-39 | High | +| **v1.1 — System Control** | #3-5, #8, #12-13, #22, #24 | Normal | +| **v1.2 — Desktop Automation** | #9-11, #14-17, #20 | Normal | +| **v1.3 — Admin Tools** | #27-34, #40 | Normal | +| **v1.4 — Advanced** | #19, #21, #23, #25-26 | Low | diff --git a/src/client.ts b/src/client.ts deleted file mode 100644 index 4337947..0000000 --- a/src/client.ts +++ /dev/null @@ -1,129 +0,0 @@ -/* Copyright (C) 2026 Moko Consulting - * - * This file is part of a Moko Consulting project. - * - * SPDX-License-Identifier: GPL-3.0-or-later - * - * FILE INFORMATION - * DEFGROUP: mcp_windows.Client - * INGROUP: mcp_windows - * REPO: https://git.mokoconsulting.tech/MokoConsulting/mcp_windows - * PATH: /src/client.ts - * VERSION: 01.00.00 - * BRIEF: HTTP client for Windows Desktop API - */ - -import * as https from 'node:https'; -import * as http from 'node:http'; -import type { ApiConnection, ApiResponse } from './types.js'; - -// ── Customize these ───────────────────────────────────────────────────── -// API path prefix appended to baseUrl (e.g. "/api/index.php", "/api/v1") -const API_PREFIX = '/api'; -const TIMEOUT_MS = 30_000; -// ──────────────────────────────────────────────────────────────────────── - -export class ApiClient { - private readonly base_url: string; - private readonly headers: Record; - private readonly insecure: boolean; - - constructor(conn: ApiConnection) { - this.base_url = conn.baseUrl.replace(/\/+$/, '') + API_PREFIX; - - // ── Customize auth headers ────────────────────────────────── - // Examples: - // Bearer token: { 'Authorization': `Bearer ${conn.apiKey}` } - // API key header: { 'DOLAPIKEY': conn.apiKey } - // Basic auth: { 'Authorization': `Basic ${btoa(user + ':' + pass)}` } - this.headers = { - 'Authorization': `Bearer ${conn.apiKey}`, - 'Content-Type': 'application/json', - 'Accept': 'application/json', - }; - this.insecure = conn.insecure ?? false; - } - - async get(endpoint: string, params?: Record): Promise { - return this.request(this.buildUrl(endpoint, params), 'GET'); - } - - async post(endpoint: string, body?: unknown): Promise { - return this.request(this.buildUrl(endpoint), 'POST', body); - } - - async put(endpoint: string, body: unknown): Promise { - return this.request(this.buildUrl(endpoint), 'PUT', body); - } - - async patch(endpoint: string, body: unknown): Promise { - return this.request(this.buildUrl(endpoint), 'PATCH', body); - } - - async delete(endpoint: string): Promise { - return this.request(this.buildUrl(endpoint), 'DELETE'); - } - - private buildUrl(endpoint: string, params?: Record): string { - const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`; - const url = new URL(`${this.base_url}${path}`); - if (params) { - for (const [key, value] of Object.entries(params)) { - url.searchParams.set(key, value); - } - } - return url.toString(); - } - - private request(url: string, method: string, body?: unknown): Promise { - return new Promise((resolve, reject) => { - const parsed = new URL(url); - const is_https = parsed.protocol === 'https:'; - const transport = is_https ? https : http; - - const options: https.RequestOptions = { - hostname: parsed.hostname, - port: parsed.port || (is_https ? 443 : 80), - path: parsed.pathname + parsed.search, - method, - headers: { ...this.headers }, - timeout: TIMEOUT_MS, - }; - - if (this.insecure && is_https) { - options.rejectUnauthorized = false; - } - - const payload = body !== undefined ? JSON.stringify(body) : undefined; - if (payload) { - (options.headers as Record)['Content-Length'] = Buffer.byteLength(payload).toString(); - } - - const req = transport.request(options, (res) => { - const chunks: Buffer[] = []; - res.on('data', (chunk: Buffer) => chunks.push(chunk)); - res.on('end', () => { - const raw = Buffer.concat(chunks).toString('utf-8'); - let data: unknown; - try { - data = JSON.parse(raw); - } catch { - data = raw; - } - resolve({ status: res.statusCode ?? 0, data }); - }); - }); - - req.on('error', (err) => reject(err)); - req.on('timeout', () => { - req.destroy(); - reject(new Error('Request timed out')); - }); - - if (payload) { - req.write(payload); - } - req.end(); - }); - } -} diff --git a/src/config.ts b/src/config.ts deleted file mode 100644 index d3d9c19..0000000 --- a/src/config.ts +++ /dev/null @@ -1,63 +0,0 @@ -/* Copyright (C) 2026 Moko Consulting - * - * This file is part of a Moko Consulting project. - * - * SPDX-License-Identifier: GPL-3.0-or-later - * - * FILE INFORMATION - * DEFGROUP: mcp_windows.Config - * INGROUP: mcp_windows - * REPO: https://git.mokoconsulting.tech/MokoConsulting/mcp_windows - * PATH: /src/config.ts - * VERSION: 01.00.00 - * BRIEF: Configuration loader for Windows Desktop MCP connections - */ - -import { readFile } from 'node:fs/promises'; -import { resolve } from 'node:path'; -import { homedir } from 'node:os'; -import type { ApiConfig, ApiConnection } from './types.js'; - -// ── Customize this ────────────────────────────────────────────────────── -// Change the filename to match your project (e.g. ".dolibarr-api-mcp.json") -const CONFIG_FILENAME = '.mcp_windows.json'; -// Change the env var name to match your project -const CONFIG_ENV_VAR = 'MCP_WINDOWS_CONFIG'; -// ──────────────────────────────────────────────────────────────────────── - -export async function loadConfig(): Promise { - const config_path = process.env[CONFIG_ENV_VAR] - ? resolve(process.env[CONFIG_ENV_VAR]!) - : resolve(homedir(), CONFIG_FILENAME); - - try { - const raw = await readFile(config_path, 'utf-8'); - const parsed = JSON.parse(raw) as Partial; - - if (!parsed.connections || Object.keys(parsed.connections).length === 0) { - throw new Error('No connections defined in config'); - } - - return { - connections: parsed.connections, - defaultConnection: parsed.defaultConnection ?? Object.keys(parsed.connections)[0], - }; - } catch (err) { - const message = err instanceof Error ? err.message : String(err); - throw new Error( - `Failed to load config from ${config_path}: ${message}\n` + - `Create ${config_path} — see config.example.json for format.`, - ); - } -} - -export function getConnection(config: ApiConfig, name?: string): ApiConnection { - const key = name ?? config.defaultConnection; - const conn = config.connections[key]; - if (!conn) { - throw new Error( - `Connection "${key}" not found. Available: ${Object.keys(config.connections).join(', ')}`, - ); - } - return conn; -} diff --git a/src/index.ts b/src/index.ts index 38a3a65..814be36 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,199 +1,39 @@ #!/usr/bin/env node /* Copyright (C) 2026 Moko Consulting - * - * This file is part of a Moko Consulting project. - * * SPDX-License-Identifier: GPL-3.0-or-later * - * FILE INFORMATION - * DEFGROUP: mcp_windows.Server - * INGROUP: mcp_windows - * REPO: https://git.mokoconsulting.tech/MokoConsulting/mcp_windows - * PATH: /src/index.ts - * VERSION: 01.00.00 - * BRIEF: MCP server entry point — registers all Windows Desktop API tools + * 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 { z } from 'zod'; -import { loadConfig, getConnection } from './config.js'; -import { ApiClient } from './client.js'; -import type { ApiConfig, ApiResponse } from './types.js'; - -let config: ApiConfig; - -function clientFor(connection?: string): ApiClient { - return new ApiClient(getConnection(config, connection)); -} - -function formatResponse(res: ApiResponse): { content: Array<{ type: 'text'; text: string }> } { - if (res.status >= 400) { - return { - content: [{ type: 'text' as const, text: `Error: HTTP ${res.status}: ${JSON.stringify(res.data, null, 2)}` }], - }; - } - return { - content: [{ type: 'text' as const, text: JSON.stringify(res.data, null, 2) }], - }; -} - -// ── Shared parameter definitions ──────────────────────────────────────── - -const ConnectionParam = { - connection: z.string().optional().describe('Named connection from config (uses default if omitted)'), -}; - -const PaginationParams = { - limit: z.number().optional().describe('Max results'), - page: z.number().optional().describe('Page number (0-based)'), -}; - -function paginationQuery(params: { limit?: number; page?: number }): Record { - const q: Record = {}; - if (params.limit !== undefined) q['limit'] = String(params.limit); - if (params.page !== undefined) q['page'] = String(params.page); - return q; -} - -// ── Server ────────────────────────────────────────────────────────────── +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'; const server = new McpServer({ name: 'mcp_windows', version: '1.0.0', }); -// ════════════════════════════════════════════════════════════════════════ -// ADD YOUR TOOLS BELOW -// ════════════════════════════════════════════════════════════════════════ -// -// Follow this pattern for each tool: -// -// server.tool( -// 'prefix_resource_action', // tool name (snake_case) -// 'Human-readable description', // shown to the AI assistant -// { // Zod schema for parameters -// id: z.number().describe('Resource ID'), -// ...ConnectionParam, -// }, -// async ({ id, connection }) => { -// const client = clientFor(connection); -// return formatResponse(await client.get(`/resources/${id}`)); -// }, -// ); -// -// Tips: -// - Group tools by resource type with section comments -// - Use consistent naming: prefix_resource_list, prefix_resource_get, -// prefix_resource_create, prefix_resource_update, prefix_resource_delete -// - Spread ...ConnectionParam into every tool's schema -// - Spread ...PaginationParams into list tools -// - Use paginationQuery() to build query params for list endpoints -// -// ════════════════════════════════════════════════════════════════════════ - -// ── Example: Resources ────────────────────────────────────────────────── - -server.tool( - 'example_resources_list', - 'List resources (EXAMPLE — replace with your API resources)', - { - search: z.string().optional().describe('Search query'), - ...PaginationParams, - ...ConnectionParam, - }, - async ({ search, limit, page, connection }) => { - const client = clientFor(connection); - const params: Record = { ...paginationQuery({ limit, page }) }; - if (search) params['search'] = search; - return formatResponse(await client.get('/resources', params)); - }, -); - -server.tool( - 'example_resource_get', - 'Get a single resource by ID (EXAMPLE — replace with your API resources)', - { - id: z.number().describe('Resource ID'), - ...ConnectionParam, - }, - async ({ id, connection }) => { - const client = clientFor(connection); - return formatResponse(await client.get(`/resources/${id}`)); - }, -); - -server.tool( - 'example_resource_create', - 'Create a new resource (EXAMPLE — replace with your API resources)', - { - name: z.string().describe('Resource name'), - description: z.string().optional().describe('Resource description'), - ...ConnectionParam, - }, - async ({ name, description, connection }) => { - const client = clientFor(connection); - const body: Record = { name }; - if (description) body.description = description; - return formatResponse(await client.post('/resources', body)); - }, -); - -// ── Generic API Call ──────────────────────────────────────────────────── - -server.tool( - 'api_request', - 'Make a raw API request to any endpoint', - { - method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'), - endpoint: z.string().describe('API endpoint path (e.g. "/resources")'), - body: z.record(z.string(), z.unknown()).optional().describe('Request body for POST/PUT/PATCH'), - params: z.record(z.string(), z.string()).optional().describe('Query parameters'), - ...ConnectionParam, - }, - async ({ method, endpoint, body, params, connection }) => { - const client = clientFor(connection); - switch (method) { - case 'GET': - return formatResponse(await client.get(endpoint, params)); - case 'POST': - return formatResponse(await client.post(endpoint, body)); - case 'PUT': - return formatResponse(await client.put(endpoint, body)); - case 'PATCH': - return formatResponse(await client.patch(endpoint, body)); - case 'DELETE': - return formatResponse(await client.delete(endpoint)); - } - }, -); - -// ── Connections Management ────────────────────────────────────────────── - -server.tool( - 'list_connections', - 'List configured API connections', - {}, - async () => { - const lines = Object.entries(config.connections).map(([name, conn]) => { - const is_default = name === config.defaultConnection ? ' (default)' : ''; - return ` ${name}${is_default}: ${conn.baseUrl}`; - }); - return { - content: [{ type: 'text' as const, text: `Configured connections:\n${lines.join('\n')}` }], - }; - }, -); - -// ── Start Server ──────────────────────────────────────────────────────── +// Register all tool groups +registerExecuteTools(server); +registerProcessTools(server); +registerAudioTools(server); +registerSystemTools(server); +registerTerminalTools(server); +registerFilesystemTools(server); async function main(): Promise { - config = await loadConfig(); const transport = new StdioServerTransport(); await server.connect(transport); + process.stderr.write('mcp_windows: server started\n'); } main().catch((err) => { - process.stderr.write(`Fatal: ${err}\n`); + process.stderr.write(`mcp_windows: fatal error: ${err}\n`); process.exit(1); }); diff --git a/src/shell.ts b/src/shell.ts new file mode 100644 index 0000000..5a0062e --- /dev/null +++ b/src/shell.ts @@ -0,0 +1,247 @@ +#!/usr/bin/env node +/* Copyright (C) 2026 Moko Consulting + * 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 { + 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( + command: string, + options: { timeout?: number; cwd?: string } = {}, +): Promise { + 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 { + 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(); +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, + }); + + 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; +} diff --git a/src/tools/audio.ts b/src/tools/audio.ts new file mode 100644 index 0000000..07e2a52 --- /dev/null +++ b/src/tools/audio.ts @@ -0,0 +1,161 @@ +/* Copyright (C) 2026 Moko Consulting + * SPDX-License-Identifier: GPL-3.0-or-later + * + * Tools: windows_audio_get (#6), windows_audio_set (#7) + * Uses compiled SetMute.exe for reliable COM audio control. + */ + +import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; +import { z } from 'zod'; +import { runPowerShell } from '../shell.js'; + +const AUDIO_PS = ` +Add-Type -TypeDefinition @' +using System; +using System.Runtime.InteropServices; + +public class WinAudio { + [Guid("A95664D2-9614-4F35-A746-DE8DB63617E6"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + interface IMMDeviceEnumerator { + int EnumAudioEndpoints(int dataFlow, int dwStateMask, out IntPtr ppDevices); + int GetDefaultAudioEndpoint(int dataFlow, int role, out IMMDevice ppEndpoint); + } + + [Guid("D666063F-1587-4E43-81F1-B948E807363F"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + interface IMMDevice { + int Activate(ref Guid iid, int dwClsCtx, IntPtr pActivationParams, [MarshalAs(UnmanagedType.IUnknown)] out object ppInterface); + } + + [Guid("5CDF2C82-841E-4546-9722-0CF74078229A"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + interface IAudioEndpointVolume { + int RegisterControlChangeNotify(IntPtr pNotify); + int UnregisterControlChangeNotify(IntPtr pNotify); + int GetChannelCount(out int pnChannelCount); + int SetMasterVolumeLevel(float fLevelDB, ref Guid pguidEventContext); + int SetMasterVolumeLevelScalar(float fLevel, ref Guid pguidEventContext); + int GetMasterVolumeLevel(out float pfLevelDB); + int GetMasterVolumeLevelScalar(out float pfLevel); + int SetChannelVolumeLevel(int nChannel, float fLevelDB, ref Guid pguidEventContext); + int SetChannelVolumeLevelScalar(int nChannel, float fLevel, ref Guid pguidEventContext); + int GetChannelVolumeLevel(int nChannel, out float pfLevelDB); + int GetChannelVolumeLevelScalar(int nChannel, out float pfLevel); + int SetMute([MarshalAs(UnmanagedType.Bool)] bool bMute, ref Guid pguidEventContext); + int GetMute([MarshalAs(UnmanagedType.Bool)] out bool pbMute); + } + + private static IAudioEndpointVolume GetVolume() { + var type = Type.GetTypeFromCLSID(new Guid("BCDE0395-E52F-467C-8E3D-C4579291692E")); + var enumerator = (IMMDeviceEnumerator)Activator.CreateInstance(type); + IMMDevice device; + enumerator.GetDefaultAudioEndpoint(0, 1, out device); + var iid = new Guid("5CDF2C82-841E-4546-9722-0CF74078229A"); + object obj; + device.Activate(ref iid, 0x17, IntPtr.Zero, out obj); + return (IAudioEndpointVolume)obj; + } + + public static float GetVolumeLevel() { + var vol = GetVolume(); + float level; + vol.GetMasterVolumeLevelScalar(out level); + return level; + } + + public static bool GetMute() { + var vol = GetVolume(); + bool muted; + vol.GetMute(out muted); + return muted; + } + + public static void SetVolumeLevel(float level) { + var vol = GetVolume(); + var ctx = Guid.Empty; + vol.SetMasterVolumeLevelScalar(level, ref ctx); + } + + public static void SetMute(bool mute) { + var vol = GetVolume(); + var ctx = Guid.Empty; + vol.SetMute(mute, ref ctx); + } +} +'@ -ErrorAction Stop +`; + +export function registerAudioTools(server: McpServer): void { + server.tool( + 'windows_audio_get', + 'Get current audio state: volume level (0-100), mute status, and default playback device.', + {}, + async () => { + const ps = ` +${AUDIO_PS} +$volume = [math]::Round([WinAudio]::GetVolumeLevel() * 100) +$muted = [WinAudio]::GetMute() +$device = (Get-CimInstance Win32_SoundDevice | Where-Object { $_.Status -eq 'OK' } | Select-Object -First 1).Name +[PSCustomObject]@{ + volume = $volume + muted = $muted + device = $device +} | ConvertTo-Json -Compress`; + + const result = await runPowerShell(ps); + if (result.exitCode !== 0) { + return { content: [{ type: 'text', text: `Error: ${result.stderr}` }], isError: true }; + } + + const state = JSON.parse(result.stdout); + const muteIcon = state.muted ? '🔇' : (state.volume > 50 ? '🔊' : '🔉'); + return { + content: [{ + type: 'text', + text: `${muteIcon} Volume: ${state.volume}%${state.muted ? ' (MUTED)' : ''}\nDevice: ${state.device || 'Unknown'}`, + }], + }; + }, + ); + + server.tool( + 'windows_audio_set', + 'Set audio volume (0-100), mute/unmute, or toggle mute.', + { + volume: z.number().min(0).max(100).optional().describe('Volume level 0-100'), + mute: z.enum(['true', 'false', 'toggle']).optional().describe('Mute state: true, false, or toggle'), + }, + async ({ volume, mute }) => { + const commands: string[] = [AUDIO_PS]; + + if (volume !== undefined) { + commands.push(`[WinAudio]::SetVolumeLevel(${volume / 100})`); + } + + if (mute === 'toggle') { + commands.push(`[WinAudio]::SetMute(-not [WinAudio]::GetMute())`); + } else if (mute === 'true') { + commands.push(`[WinAudio]::SetMute($true)`); + } else if (mute === 'false') { + commands.push(`[WinAudio]::SetMute($false)`); + } + + // Read back state + commands.push(` +$vol = [math]::Round([WinAudio]::GetVolumeLevel() * 100) +$m = [WinAudio]::GetMute() +[PSCustomObject]@{ volume = $vol; muted = $m } | ConvertTo-Json -Compress`); + + const result = await runPowerShell(commands.join('\n')); + if (result.exitCode !== 0) { + return { content: [{ type: 'text', text: `Error: ${result.stderr}` }], isError: true }; + } + + const state = JSON.parse(result.stdout); + return { + content: [{ + type: 'text', + text: `Volume set to ${state.volume}%${state.muted ? ' (MUTED)' : ''}`, + }], + }; + }, + ); +} diff --git a/src/tools/execute.ts b/src/tools/execute.ts new file mode 100644 index 0000000..573a6ae --- /dev/null +++ b/src/tools/execute.ts @@ -0,0 +1,35 @@ +/* Copyright (C) 2026 Moko Consulting + * SPDX-License-Identifier: GPL-3.0-or-later + * + * Tool: windows_execute — Execute shell commands (#1) + */ + +import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; +import { z } from 'zod'; +import { runShell } from '../shell.js'; + +export function registerExecuteTools(server: McpServer): void { + server.tool( + 'windows_execute', + 'Execute a shell command (PowerShell, cmd, or bash). Returns stdout, stderr, and exit code.', + { + command: z.string().describe('The command to execute'), + shell: z.enum(['pwsh', 'cmd', 'bash']).default('pwsh').describe('Shell to use'), + timeout: z.number().optional().describe('Timeout in milliseconds (default 30000)'), + cwd: z.string().optional().describe('Working directory'), + }, + async ({ command, shell, timeout, cwd }) => { + const result = await runShell(command, { shell, timeout, cwd }); + const parts: string[] = []; + + if (result.stdout) parts.push(result.stdout); + if (result.stderr) parts.push(`[stderr]\n${result.stderr}`); + parts.push(`[exit code: ${result.exitCode}]`); + + return { + content: [{ type: 'text', text: parts.join('\n\n') }], + isError: result.exitCode !== 0, + }; + }, + ); +} diff --git a/src/tools/filesystem.ts b/src/tools/filesystem.ts new file mode 100644 index 0000000..1c13f8f --- /dev/null +++ b/src/tools/filesystem.ts @@ -0,0 +1,273 @@ +/* Copyright (C) 2026 Moko Consulting + * SPDX-License-Identifier: GPL-3.0-or-later + * + * Tools: windows_file_read (#36), windows_file_write (#37), + * windows_file_edit (#38), windows_search (#39) + */ + +import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; +import { z } from 'zod'; +import { readFile, writeFile, stat, mkdir } from 'node:fs/promises'; +import { dirname, resolve, extname } from 'node:path'; +import { runPowerShell } from '../shell.js'; + +export function registerFilesystemTools(server: McpServer): void { + + // ── windows_file_read ──────────────────────────────────────────────── + + server.tool( + 'windows_file_read', + 'Read a file with line pagination. Supports text, images (base64), and binary detection. Use negative offset for tail behavior.', + { + path: z.string().describe('Absolute file path'), + offset: z.number().default(0).describe('Line offset (0-based, negative = from end)'), + length: z.number().default(200).describe('Number of lines to return'), + }, + async ({ path: filePath, offset, length }) => { + try { + const absPath = resolve(filePath); + const ext = extname(absPath).toLowerCase(); + + // Image files → base64 + if (['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.ico', '.svg'].includes(ext)) { + const data = await readFile(absPath); + const mimeMap: Record = { + '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', + '.gif': 'image/gif', '.webp': 'image/webp', '.bmp': 'image/bmp', + '.ico': 'image/x-icon', '.svg': 'image/svg+xml', + }; + return { + content: [{ + type: 'image' as const, + data: data.toString('base64'), + mimeType: mimeMap[ext] || 'application/octet-stream', + }], + }; + } + + // Text files → line pagination + const content = await readFile(absPath, 'utf-8'); + const allLines = content.split('\n'); + const total = allLines.length; + + let start: number; + if (offset < 0) { + start = Math.max(0, total + offset); + } else { + start = Math.min(offset, total); + } + const end = Math.min(start + length, total); + const lines = allLines.slice(start, end); + + const numbered = lines.map((line, i) => `${String(start + i + 1).padStart(5)} ${line}`); + const header = `${absPath} — lines ${start + 1}-${end} of ${total}`; + + return { + content: [{ type: 'text', text: `${header}\n${'─'.repeat(60)}\n${numbered.join('\n')}` }], + }; + } catch (err) { + return { content: [{ type: 'text', text: `Error reading file: ${err}` }], isError: true }; + } + }, + ); + + // ── windows_file_write ─────────────────────────────────────────────── + + server.tool( + 'windows_file_write', + 'Write or append to a text file. Creates parent directories if needed.', + { + path: z.string().describe('Absolute file path'), + content: z.string().describe('Content to write'), + mode: z.enum(['write', 'append']).default('write').describe('Write mode'), + }, + async ({ path: filePath, content, mode }) => { + try { + const absPath = resolve(filePath); + await mkdir(dirname(absPath), { recursive: true }); + + if (mode === 'append') { + const existing = await readFile(absPath, 'utf-8').catch(() => ''); + await writeFile(absPath, existing + content, 'utf-8'); + } else { + await writeFile(absPath, content, 'utf-8'); + } + + const info = await stat(absPath); + return { + content: [{ + type: 'text', + text: `Written: ${absPath} (${info.size} bytes, mode: ${mode})`, + }], + }; + } catch (err) { + return { content: [{ type: 'text', text: `Error writing file: ${err}` }], isError: true }; + } + }, + ); + + // ── windows_file_edit ──────────────────────────────────────────────── + + server.tool( + 'windows_file_edit', + 'Surgical file edit with find/replace. Validates expected replacement count.', + { + path: z.string().describe('Absolute file path'), + old_string: z.string().describe('Text to find'), + new_string: z.string().describe('Replacement text'), + expected_count: z.number().optional().describe('Expected number of replacements (fails if mismatch)'), + replace_all: z.boolean().default(false).describe('Replace all occurrences'), + }, + async ({ path: filePath, old_string, new_string, expected_count, replace_all }) => { + try { + const absPath = resolve(filePath); + const content = await readFile(absPath, 'utf-8'); + + // Count occurrences + let count = 0; + let idx = 0; + while ((idx = content.indexOf(old_string, idx)) !== -1) { + count++; + idx += old_string.length; + } + + if (count === 0) { + // Try to find near-matches for helpful error + const lines = content.split('\n'); + const needle = old_string.trim().split('\n')[0].trim(); + const nearMatches = lines + .map((line, i) => ({ line: line.trim(), num: i + 1 })) + .filter(({ line }) => { + if (!needle) return false; + // Simple similarity: shared words + const words = needle.toLowerCase().split(/\s+/); + const lineWords = line.toLowerCase().split(/\s+/); + const shared = words.filter(w => lineWords.includes(w)).length; + return shared >= Math.ceil(words.length * 0.5); + }) + .slice(0, 3); + + let msg = `No matches found for the specified text.`; + if (nearMatches.length > 0) { + msg += `\n\nNear matches:\n${nearMatches.map(m => ` Line ${m.num}: ${m.line}`).join('\n')}`; + } + return { content: [{ type: 'text', text: msg }], isError: true }; + } + + if (expected_count !== undefined && count !== expected_count) { + return { + content: [{ + type: 'text', + text: `Expected ${expected_count} occurrence(s) but found ${count}. No changes made.`, + }], + isError: true, + }; + } + + let result: string; + if (replace_all) { + result = content.split(old_string).join(new_string); + } else { + const pos = content.indexOf(old_string); + result = content.slice(0, pos) + new_string + content.slice(pos + old_string.length); + } + + await writeFile(absPath, result, 'utf-8'); + + const replaced = replace_all ? count : 1; + return { + content: [{ + type: 'text', + text: `Replaced ${replaced} occurrence(s) in ${absPath}`, + }], + }; + } catch (err) { + return { content: [{ type: 'text', text: `Error editing file: ${err}` }], isError: true }; + } + }, + ); + + // ── windows_search ─────────────────────────────────────────────────── + + server.tool( + 'windows_search', + 'Search for files by name pattern or search file contents. Uses ripgrep if available, falls back to PowerShell.', + { + type: z.enum(['files', 'content']).describe('Search type: "files" for filename, "content" for inside files'), + pattern: z.string().describe('Search pattern (glob for files, regex or literal for content)'), + path: z.string().default('.').describe('Directory to search in'), + case_sensitive: z.boolean().default(false).describe('Case-sensitive search'), + file_pattern: z.string().optional().describe('Filter files by pattern (e.g. "*.ts") — only for content search'), + context_lines: z.number().default(0).describe('Lines of context around content matches'), + limit: z.number().default(50).describe('Max results'), + }, + async ({ type, pattern, path: searchPath, case_sensitive, file_pattern, context_lines, limit }) => { + const absPath = resolve(searchPath); + + if (type === 'files') { + const caseSense = case_sensitive ? '' : '-i'; + const ps = ` +Get-ChildItem -Path '${absPath.replace(/'/g, "''")}' -Recurse -File -ErrorAction SilentlyContinue | + Where-Object { $_.Name ${caseSense ? '-cmatch' : '-match'} '${pattern.replace(/'/g, "''")}' } | + Select-Object -First ${limit} | + ForEach-Object { + "$($_.Length.ToString().PadLeft(10)) $($_.LastWriteTime.ToString('yyyy-MM-dd HH:mm')) $($_.FullName)" + }`; + const result = await runPowerShell(ps, { timeout: 30000 }); + if (result.exitCode !== 0) { + return { content: [{ type: 'text', text: `Error: ${result.stderr}` }], isError: true }; + } + const lines = result.stdout ? result.stdout.split('\n') : []; + return { + content: [{ + type: 'text', + text: lines.length > 0 + ? `${lines.length} file(s) found:\n\n${' Size Modified Path'}\n${lines.join('\n')}` + : 'No files found.', + }], + }; + } + + // Content search — try ripgrep first, fall back to PowerShell + const caseFlag = case_sensitive ? '' : '-i'; + const contextFlag = context_lines > 0 ? `-C ${context_lines}` : ''; + const fileFlag = file_pattern ? `--glob '${file_pattern}'` : ''; + + // Try rg first + const rgCmd = `rg ${caseFlag} ${contextFlag} ${fileFlag} --max-count 5 -n '${pattern.replace(/'/g, "\\'")}' '${absPath.replace(/'/g, "\\'")}'`; + const rgResult = await runPowerShell(`& { ${rgCmd} } 2>$null | Select-Object -First ${limit * 3}`, { timeout: 30000 }); + + if (rgResult.exitCode === 0 && rgResult.stdout) { + const lines = rgResult.stdout.split('\n'); + return { + content: [{ + type: 'text', + text: `Content search results (ripgrep):\n\n${lines.join('\n')}`, + }], + }; + } + + // Fallback: PowerShell Select-String + const fileFilter = file_pattern ? `-Include '${file_pattern}'` : ''; + const ps = ` +Get-ChildItem -Path '${absPath.replace(/'/g, "''")}' -Recurse -File ${fileFilter} -ErrorAction SilentlyContinue | + Select-String -Pattern '${pattern.replace(/'/g, "''")}' ${case_sensitive ? '-CaseSensitive' : ''} -Context ${context_lines} | + Select-Object -First ${limit} | + ForEach-Object { "$($_.Path):$($_.LineNumber): $($_.Line.Trim())" }`; + + const result = await runPowerShell(ps, { timeout: 60000 }); + if (result.exitCode !== 0) { + return { content: [{ type: 'text', text: `Error: ${result.stderr}` }], isError: true }; + } + const lines = result.stdout ? result.stdout.split('\n') : []; + return { + content: [{ + type: 'text', + text: lines.length > 0 + ? `${lines.length} match(es) found:\n\n${lines.join('\n')}` + : 'No matches found.', + }], + }; + }, + ); +} diff --git a/src/tools/process.ts b/src/tools/process.ts new file mode 100644 index 0000000..e6ea5b9 --- /dev/null +++ b/src/tools/process.ts @@ -0,0 +1,80 @@ +/* Copyright (C) 2026 Moko Consulting + * 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`, + }], + }; + }, + ); +} diff --git a/src/tools/system.ts b/src/tools/system.ts new file mode 100644 index 0000000..89b4877 --- /dev/null +++ b/src/tools/system.ts @@ -0,0 +1,99 @@ +/* Copyright (C) 2026 Moko Consulting + * SPDX-License-Identifier: GPL-3.0-or-later + * + * Tool: windows_system_info (#18) + */ + +import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; +import { runPowerShell } from '../shell.js'; + +export function registerSystemTools(server: McpServer): void { + server.tool( + 'windows_system_info', + 'Get comprehensive system information: OS, CPU, RAM, disk, network, uptime.', + {}, + async () => { + const ps = ` +$os = Get-CimInstance Win32_OperatingSystem +$cpu = Get-CimInstance Win32_Processor | Select-Object -First 1 +$cs = Get-CimInstance Win32_ComputerSystem +$disks = Get-CimInstance Win32_LogicalDisk -Filter "DriveType=3" | ForEach-Object { + [PSCustomObject]@{ + Drive = $_.DeviceID + Label = $_.VolumeName + FileSystem = $_.FileSystem + TotalGB = [math]::Round($_.Size / 1GB, 1) + FreeGB = [math]::Round($_.FreeSpace / 1GB, 1) + UsedPct = if ($_.Size -gt 0) { [math]::Round(($_.Size - $_.FreeSpace) / $_.Size * 100, 1) } else { 0 } + } +} +$adapters = Get-NetAdapter -Physical -ErrorAction SilentlyContinue | Where-Object { $_.Status -eq 'Up' } | ForEach-Object { + $ip = (Get-NetIPAddress -InterfaceIndex $_.ifIndex -AddressFamily IPv4 -ErrorAction SilentlyContinue).IPAddress + [PSCustomObject]@{ + Name = $_.Name + Speed = $_.LinkSpeed + IP = $ip + MAC = $_.MacAddress + } +} +$uptime = (Get-Date) - $os.LastBootUpTime + +[PSCustomObject]@{ + OS = "$($os.Caption) $($os.Version) Build $($os.BuildNumber)" + Edition = $os.OperatingSystemSKU + Architecture = $os.OSArchitecture + Hostname = $env:COMPUTERNAME + Username = $env:USERNAME + Domain = $cs.Domain + CPU = "$($cpu.Name)" + CPUCores = "$($cpu.NumberOfCores) cores / $($cpu.NumberOfLogicalProcessors) threads" + CPUUsage = "$([math]::Round($cpu.LoadPercentage, 0))%" + RAMTotalGB = [math]::Round($cs.TotalPhysicalMemory / 1GB, 1) + RAMAvailGB = [math]::Round($os.FreePhysicalMemory / 1MB, 1) + RAMUsedPct = [math]::Round(($cs.TotalPhysicalMemory - $os.FreePhysicalMemory * 1KB) / $cs.TotalPhysicalMemory * 100, 1) + Disks = $disks + Network = $adapters + Uptime = "$($uptime.Days)d $($uptime.Hours)h $($uptime.Minutes)m" +} | 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 diskLines = (Array.isArray(info.Disks) ? info.Disks : [info.Disks]) + .filter(Boolean) + .map((d: { Drive: string; Label: string; TotalGB: number; FreeGB: number; UsedPct: number }) => + ` ${d.Drive} ${d.Label || ''} — ${d.FreeGB}/${d.TotalGB} GB free (${d.UsedPct}% used)`, + ); + const netLines = (Array.isArray(info.Network) ? info.Network : [info.Network]) + .filter(Boolean) + .map((n: { Name: string; IP: string; Speed: string }) => + ` ${n.Name} — ${n.IP || 'no IP'} (${n.Speed})`, + ); + + const text = [ + `OS: ${info.OS}`, + `Architecture: ${info.Architecture}`, + `Host: ${info.Hostname} (${info.Domain})`, + `User: ${info.Username}`, + `Uptime: ${info.Uptime}`, + ``, + `CPU: ${info.CPU}`, + `Cores: ${info.CPUCores}`, + `CPU Usage: ${info.CPUUsage}`, + ``, + `RAM: ${info.RAMAvailGB}/${info.RAMTotalGB} GB available (${info.RAMUsedPct}% used)`, + ``, + `Disks:`, + ...diskLines, + ``, + `Network:`, + ...netLines, + ].join('\n'); + + return { content: [{ type: 'text', text }] }; + }, + ); +} diff --git a/src/tools/terminal.ts b/src/tools/terminal.ts new file mode 100644 index 0000000..d0d28d4 --- /dev/null +++ b/src/tools/terminal.ts @@ -0,0 +1,117 @@ +/* Copyright (C) 2026 Moko Consulting + * SPDX-License-Identifier: GPL-3.0-or-later + * + * Tool: windows_terminal_session — Persistent interactive terminals (#35) + */ + +import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; +import { z } from 'zod'; +import { + startSession, + sendToSession, + readSessionOutput, + listSessions, + terminateSession, +} from '../shell.js'; + +export function registerTerminalTools(server: McpServer): void { + server.tool( + 'windows_terminal_start', + 'Start a persistent interactive terminal session (PowerShell, cmd, bash, python, node, wsl).', + { + shell: z.enum(['pwsh', 'cmd', 'bash', 'python', 'node', 'wsl']).default('pwsh').describe('Shell type'), + }, + async ({ shell }) => { + const session = startSession(shell); + // Give the shell a moment to start and produce initial output + await new Promise(resolve => setTimeout(resolve, 500)); + return { + content: [{ + type: 'text', + text: `Session started: PID ${session.pid} (${session.shell})\nUse windows_terminal_send to send commands, windows_terminal_read to read output.`, + }], + }; + }, + ); + + server.tool( + 'windows_terminal_send', + 'Send input to a running interactive terminal session.', + { + pid: z.number().describe('Session PID'), + input: z.string().describe('Text to send to the session'), + }, + async ({ pid, input }) => { + try { + sendToSession(pid, input); + // Wait for output to arrive + await new Promise(resolve => setTimeout(resolve, 1000)); + const lines = readSessionOutput(pid, -30); + return { + content: [{ + type: 'text', + text: lines.join('\n') || '(no output yet)', + }], + }; + } catch (err) { + return { content: [{ type: 'text', text: `Error: ${err}` }], isError: true }; + } + }, + ); + + server.tool( + 'windows_terminal_read', + 'Read output from a terminal session with pagination. Use negative offset to read from the end.', + { + pid: z.number().describe('Session PID'), + offset: z.number().default(0).describe('Line offset (negative = from end)'), + length: z.number().optional().describe('Number of lines to return'), + }, + async ({ pid, offset, length }) => { + try { + const lines = readSessionOutput(pid, offset, length); + return { + content: [{ + type: 'text', + text: lines.join('\n') || '(no output)', + }], + }; + } catch (err) { + return { content: [{ type: 'text', text: `Error: ${err}` }], isError: true }; + } + }, + ); + + server.tool( + 'windows_terminal_list', + 'List all active terminal sessions.', + {}, + async () => { + const sessions = listSessions(); + if (sessions.length === 0) { + return { content: [{ type: 'text', text: 'No active sessions.' }] }; + } + const lines = sessions.map(s => + `PID ${s.pid} — ${s.shell} — ${s.running ? 'running' : 'ended'} — ${s.lines} lines — started ${s.startedAt}`, + ); + return { content: [{ type: 'text', text: lines.join('\n') }] }; + }, + ); + + server.tool( + 'windows_terminal_kill', + 'Terminate a terminal session by PID.', + { + pid: z.number().describe('Session PID to terminate'), + }, + async ({ pid }) => { + const killed = terminateSession(pid); + return { + content: [{ + type: 'text', + text: killed ? `Session ${pid} terminated.` : `No session with PID ${pid}.`, + }], + }; + }, + ); +} diff --git a/src/types.ts b/src/types.ts deleted file mode 100644 index f2062b0..0000000 --- a/src/types.ts +++ /dev/null @@ -1,48 +0,0 @@ -/* Copyright (C) 2026 Moko Consulting - * - * This file is part of a Moko Consulting project. - * - * SPDX-License-Identifier: GPL-3.0-or-later - * - * FILE INFORMATION - * DEFGROUP: mcp_windows.Types - * INGROUP: mcp_windows - * REPO: https://git.mokoconsulting.tech/MokoConsulting/mcp_windows - * PATH: /src/types.ts - * VERSION: 01.00.00 - * BRIEF: TypeScript type definitions for Windows Desktop MCP server - */ - -/** - * Connection configuration for a single API instance. - * - * Rename and extend these fields to match your target API's auth mechanism: - * - `apiKey` + DOLAPIKEY header (Dolibarr) - * - `apiToken` + Bearer header (Joomla, GitHub) - * - `username`/`password` (Basic auth) - * - `oauth` fields (OAuth2 flows) - */ -export interface ApiConnection { - /** Base URL of the API instance (no trailing slash) */ - baseUrl: string; - /** API key or token for authentication */ - apiKey: string; - /** Skip TLS certificate verification (self-signed certs) */ - insecure?: boolean; -} - -/** - * Top-level configuration supporting multiple named connections. - */ -export interface ApiConfig { - connections: Record; - defaultConnection: string; -} - -/** - * Normalized API response returned by the HTTP client. - */ -export interface ApiResponse { - status: number; - data: unknown; -}