@mokoconsulting/mcp-windows 3.0.0

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

package/Makefile

@@ -0,0 +1,70 @@
+# MCP Server Makefile
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+PROJECT_NAME := mcp_windows
+PROJECT_VERSION := 1.0.0
+
+NPM := npm
+
+COLOR_RESET := \033[0m
+COLOR_GREEN := \033[32m
+COLOR_BLUE := \033[34m
+
+.PHONY: help
+help: ## Show this help message
+	@echo "$(COLOR_BLUE)$(PROJECT_NAME) v$(PROJECT_VERSION)$(COLOR_RESET)"
+	@echo ""
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  $(COLOR_BLUE)%-20s$(COLOR_RESET) %s\n", $$1, $$2}'
+	@echo ""
+
+.PHONY: install-deps
+install-deps: ## Install dependencies
+	@$(NPM) install
+	@echo "$(COLOR_GREEN)✓ Dependencies installed$(COLOR_RESET)"
+
+MOKO_PLATFORM ?= $(or $(wildcard ../moko-platform),$(wildcard $(HOME)/moko-platform),$(wildcard /opt/moko-platform))
+MINIFY_SCRIPT := $(MOKO_PLATFORM)/build/minify.js
+
+.PHONY: minify
+minify: ## Minify CSS/JS assets
+	@echo "Minifying assets..."
+	@if [ -f "$(MINIFY_SCRIPT)" ]; then \
+		node "$(MINIFY_SCRIPT)" $(SRC_DIR); \
+	elif [ -f "scripts/minify.js" ]; then \
+		node scripts/minify.js; \
+	else \
+		echo "No minify script found"; \
+	fi
+
+.PHONY: build
+build: minify ## Build TypeScript
+	@$(NPM) run build
+	@echo "$(COLOR_GREEN)✓ Build complete$(COLOR_RESET)"
+
+.PHONY: dev
+dev: ## Watch and rebuild on changes
+	@$(NPM) run dev
+
+.PHONY: clean
+clean: ## Clean build artifacts
+	@rm -rf dist
+	@echo "$(COLOR_GREEN)✓ Cleaned$(COLOR_RESET)"
+
+.PHONY: setup
+setup: ## Run interactive setup wizard
+	@$(NPM) run setup
+
+.PHONY: start
+start: ## Start the MCP server
+	@$(NPM) run start
+
+.PHONY: lint
+lint: ## Run linter
+	@$(NPM) run lint
+
+.PHONY: ci
+ci: install-deps build ## Run CI pipeline
+	@echo "$(COLOR_GREEN)✓ CI pipeline complete$(COLOR_RESET)"
+
+.DEFAULT_GOAL := help