@mokoconsulting/mcp-windows 3.0.0

package/README.md

@@ -0,0 +1,80 @@
+# Template-MCP
+
+![Language](https://img.shields.io/badge/language-TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white) ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green?style=flat-square) ![Platform](https://img.shields.io/badge/platform-Node.js%20%7C%20MCP-339933?style=flat-square&logo=node.js&logoColor=white) ![Wiki](https://img.shields.io/badge/wiki-Template--MCP-blue?style=flat-square)
+
+Template repository for creating MokoCLI-compliant Model Context Protocol (MCP) API servers. Provides the scaffolding, configuration patterns, and architecture conventions used by all Moko Consulting MCP servers, enabling AI assistants like Claude to interact with REST APIs through a standardized tool interface.
+
+## Features
+
+- **MCP server scaffolding** -- pre-configured TypeScript project structure with entry point, tool registration, and stdio transport ready to go
+- **Multi-connection support** -- built-in `config.json` pattern for managing multiple named API connections with a default fallback; all tools accept an optional `connection` parameter
+- **REST API bridge architecture** -- standardized pattern for bridging any REST API as MCP tools, with typed request/response handling
+- **TypeScript-first** -- full TypeScript setup with `tsconfig.json`, strict mode, and ES module output
+- **Build tooling** -- Makefile with `build`, `dev`, `clean`, and `lint` targets; npm scripts for compilation and development
+- **MokoCLI compliant** -- follows all Moko Consulting governance conventions: file headers, commit messages, `.gitattributes`, `.gitmessage`, PR/issue templates
+- **Example configuration** -- `config.example.json` demonstrates the connection configuration schema
+- **Documentation templates** -- wiki pages for API reference, architecture overview, and installation pre-generated
+
+## Installation
+
+1. Create a new repository from this template (or clone directly):
+   ```bash
+   git clone https://git.mokoconsulting.tech/MokoConsulting/Template-MCP.git my-mcp-server
+   cd my-mcp-server
+   ```
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+3. Copy and configure the connection file:
+   ```bash
+   cp config.example.json config.json
+   # Edit config.json with your API credentials
+   ```
+4. Build the project:
+   ```bash
+   npm run build
+   ```
+5. Run the server:
+   ```bash
+   node build/index.js
+   ```
+
+## Configuration
+
+| Path | Purpose |
+|---|---|
+| `src/` | TypeScript source files (server entry, tool definitions, API client) |
+| `config.example.json` | Example multi-connection configuration schema |
+| `config.json` | Local connection configuration (gitignored) |
+| `package.json` | npm dependencies and scripts |
+| `tsconfig.json` | TypeScript compiler configuration |
+| `scripts/` | Build and development utility scripts |
+| `docs/` | Developer documentation |
+| `Makefile` | Build, dev, clean, and lint targets |
+
+## Requirements
+
+- Node.js 20.0.0 or later
+- npm 9+
+- TypeScript 5+ (installed via npm)
+
+## Documentation
+
+Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki), including:
+
+- [API](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki/API) -- tool reference and connection parameter documentation
+- [ARCHITECTURE](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki/ARCHITECTURE) -- MCP server design and REST API bridge pattern
+- [INSTALLATION](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki/INSTALLATION) -- setup prerequisites and configuration guide
+
+## Contributing
+
+See the wiki for development guidelines and contribution instructions.
+
+## License
+
+This project is licensed under the GNU General Public License v3.0 or later -- see the [LICENSE](LICENSE) file.
+
+---
+
+*[Moko Consulting](https://mokoconsulting.tech) -- [MokoCLI](https://git.mokoconsulting.tech/MokoConsulting/mokocli)*

package/automation/ci-issue-reporter.sh

@@ -0,0 +1,237 @@
+#!/usr/bin/env bash
+# ============================================================================
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: Automation.CI
+# INGROUP: moko-platform.Automation
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+# PATH: /automation/ci-issue-reporter.sh
+# VERSION: 09.23.00
+# BRIEF: Creates or updates a Gitea issue when a CI gate fails.
+#        Deduplicates by searching open issues with the "ci-auto" label
+#        whose title matches the gate. If a matching issue exists, a comment
+#        is appended instead of opening a duplicate.
+# ============================================================================
+
+set -euo pipefail
+
+# ── Defaults ────────────────────────────────────────────────────────────────
+GITEA_URL="${GITEA_URL:-https://git.mokoconsulting.tech}"
+GITEA_TOKEN="${GITEA_TOKEN:-}"
+REPO="${GITHUB_REPOSITORY:-}"
+RUN_URL="${GITHUB_SERVER_URL:-${GITEA_URL}}/${REPO}/actions/runs/${GITHUB_RUN_ID:-0}"
+LABEL_NAME="ci-auto"
+LABEL_COLOR="#e11d48"
+
+GATE=""
+DETAILS=""
+SEVERITY="error"
+WORKFLOW=""
+
+# ── Parse arguments ─────────────────────────────────────────────────────────
+usage() {
+  cat <<EOF
+Usage: ci-issue-reporter.sh --gate NAME --details TEXT [OPTIONS]
+
+Required:
+  --gate      CI gate name (e.g. "Code Quality", "Self-Health")
+  --details   Human-readable failure description
+
+Optional:
+  --severity  "error" (default) or "warning"
+  --workflow  Workflow name for the issue title
+  --repo      owner/repo (default: \$GITHUB_REPOSITORY)
+  --run-url   URL to the CI run (auto-detected from env)
+  --token     Gitea API token (default: \$GITEA_TOKEN)
+  --url       Gitea base URL (default: \$GITEA_URL)
+EOF
+  exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --gate)     GATE="$2";       shift 2 ;;
+    --details)  DETAILS="$2";    shift 2 ;;
+    --severity) SEVERITY="$2";   shift 2 ;;
+    --workflow) WORKFLOW="$2";   shift 2 ;;
+    --repo)     REPO="$2";      shift 2 ;;
+    --run-url)  RUN_URL="$2";   shift 2 ;;
+    --token)    GITEA_TOKEN="$2"; shift 2 ;;
+    --url)      GITEA_URL="$2"; shift 2 ;;
+    -h|--help)  usage ;;
+    *)          echo "Unknown option: $1"; usage ;;
+  esac
+done
+
+[[ -z "$GATE" ]]         && { echo "ERROR: --gate is required"; usage; }
+[[ -z "$DETAILS" ]]      && { echo "ERROR: --details is required"; usage; }
+[[ -z "$GITEA_TOKEN" ]]  && { echo "ERROR: GITEA_TOKEN not set"; exit 1; }
+[[ -z "$REPO" ]]         && { echo "ERROR: GITHUB_REPOSITORY not set"; exit 1; }
+
+API="${GITEA_URL}/api/v1/repos/${REPO}"
+
+# ── Build title ─────────────────────────────────────────────────────────────
+if [[ -n "$WORKFLOW" ]]; then
+  TITLE="[CI] ${WORKFLOW}: ${GATE} failed"
+else
+  TITLE="[CI] ${GATE} failed"
+fi
+
+# ── Ensure label exists ─────────────────────────────────────────────────────
+ensure_label() {
+  local exists
+  exists=$(curl -sf -o /dev/null -w '%{http_code}' \
+    -H "Authorization: token ${GITEA_TOKEN}" \
+    "${API}/labels" 2>/dev/null || echo "000")
+
+  if [[ "$exists" == "200" ]]; then
+    # Check if label already exists
+    local found
+    found=$(curl -sf \
+      -H "Authorization: token ${GITEA_TOKEN}" \
+      "${API}/labels" 2>/dev/null \
+      | grep -o "\"name\":\"${LABEL_NAME}\"" || true)
+
+    if [[ -z "$found" ]]; then
+      curl -sf -X POST \
+        -H "Authorization: token ${GITEA_TOKEN}" \
+        -H "Content-Type: application/json" \
+        "${API}/labels" \
+        -d "{\"name\":\"${LABEL_NAME}\",\"color\":\"${LABEL_COLOR}\",\"description\":\"Auto-created by CI issue reporter\"}" \
+        > /dev/null 2>&1 || true
+    fi
+  fi
+}
+
+# ── Search for existing open issue ──────────────────────────────────────────
+find_existing_issue() {
+  # URL-encode the gate name for the query
+  local query
+  query=$(printf '%s' "[CI] ${GATE}" | sed 's/ /%20/g; s/\[/%5B/g; s/\]/%5D/g')
+
+  local response
+  response=$(curl -sf \
+    -H "Authorization: token ${GITEA_TOKEN}" \
+    "${API}/issues?type=issues&state=open&labels=${LABEL_NAME}&q=${query}&limit=5" \
+    2>/dev/null || echo "[]")
+
+  # Extract the first matching issue number
+  echo "$response" \
+    | grep -oP '"number":\s*\K[0-9]+' \
+    | head -1
+}
+
+# ── Build issue body ────────────────────────────────────────────────────────
+build_body() {
+  local severity_badge
+  if [[ "$SEVERITY" == "error" ]]; then
+    severity_badge="**Severity:** Error"
+  else
+    severity_badge="**Severity:** Warning"
+  fi
+
+  cat <<BODY
+## CI Gate Failure: ${GATE}
+
+${severity_badge}
+**Workflow:** ${WORKFLOW:-unknown}
+**Branch:** ${GITHUB_REF_NAME:-unknown}
+**Commit:** \`${GITHUB_SHA:0:8}\`
+**Run:** [View CI run](${RUN_URL})
+
+### Details
+
+${DETAILS}
+
+### Resolution
+
+Fix the issue described above and push a new commit. This issue will be closed automatically when the gate passes, or can be closed manually.
+
+---
+*Auto-created by [ci-issue-reporter](${GITEA_URL}/${REPO}/src/branch/main/automation/ci-issue-reporter.sh)*
+BODY
+}
+
+# ── Build comment body (for existing issues) ────────────────────────────────
+build_comment() {
+  cat <<COMMENT
+### CI failure recurrence
+
+**Branch:** ${GITHUB_REF_NAME:-unknown}
+**Commit:** \`${GITHUB_SHA:0:8}\`
+**Run:** [View CI run](${RUN_URL})
+
+${DETAILS}
+COMMENT
+}
+
+# ── Main ────────────────────────────────────────────────────────────────────
+ensure_label
+
+EXISTING=$(find_existing_issue)
+
+if [[ -n "$EXISTING" ]]; then
+  # Append comment to existing issue
+  COMMENT_BODY=$(build_comment)
+  COMMENT_JSON=$(printf '%s' "$COMMENT_BODY" | python3 -c "
+import sys, json
+print(json.dumps({'body': sys.stdin.read()}))" 2>/dev/null)
+
+  HTTP=$(curl -sf -o /dev/null -w '%{http_code}' -X POST \
+    -H "Authorization: token ${GITEA_TOKEN}" \
+    -H "Content-Type: application/json" \
+    "${API}/issues/${EXISTING}/comments" \
+    -d "${COMMENT_JSON}" 2>/dev/null || echo "000")
+
+  if [[ "$HTTP" == "201" ]]; then
+    echo "Commented on existing issue #${EXISTING}"
+  else
+    echo "WARNING: Failed to comment on issue #${EXISTING} (HTTP ${HTTP})"
+  fi
+else
+  # Create new issue
+  ISSUE_BODY=$(build_body)
+  ISSUE_JSON=$(python3 -c "
+import sys, json
+body = sys.stdin.read()
+print(json.dumps({
+    'title': sys.argv[1],
+    'body': body,
+    'labels': []
+}))" "$TITLE" <<< "$ISSUE_BODY" 2>/dev/null)
+
+  # Create the issue
+  RESPONSE=$(curl -sf -X POST \
+    -H "Authorization: token ${GITEA_TOKEN}" \
+    -H "Content-Type: application/json" \
+    "${API}/issues" \
+    -d "${ISSUE_JSON}" 2>/dev/null || echo "{}")
+
+  ISSUE_NUM=$(echo "$RESPONSE" | grep -oP '"number":\s*\K[0-9]+' | head -1)
+
+  if [[ -n "$ISSUE_NUM" ]]; then
+    # Apply label (separate call — more reliable across Gitea versions)
+    LABEL_ID=$(curl -sf \
+      -H "Authorization: token ${GITEA_TOKEN}" \
+      "${API}/labels" 2>/dev/null \
+      | grep -oP "\"id\":\s*\K[0-9]+(?=[^}]*\"name\":\s*\"${LABEL_NAME}\")" \
+      | head -1 || true)
+
+    if [[ -n "$LABEL_ID" ]]; then
+      curl -sf -X POST \
+        -H "Authorization: token ${GITEA_TOKEN}" \
+        -H "Content-Type: application/json" \
+        "${API}/issues/${ISSUE_NUM}/labels" \
+        -d "{\"labels\":[${LABEL_ID}]}" \
+        > /dev/null 2>&1 || true
+    fi
+
+    echo "Created issue #${ISSUE_NUM}: ${TITLE}"
+  else
+    echo "WARNING: Failed to create issue"
+    echo "Response: ${RESPONSE}"
+  fi
+fi

package/config.example.json

@@ -0,0 +1,18 @@
+{
+	"defaultConnection": "production",
+	"connections": {
+		"local-dev": {
+			"baseUrl": "https://localhost:8080",
+			"apiKey": "your-api-key-here",
+			"insecure": true
+		},
+		"production": {
+			"baseUrl": "https://api.example.com",
+			"apiKey": "your-production-api-key"
+		},
+		"staging": {
+			"baseUrl": "https://api-staging.example.com",
+			"apiKey": "your-staging-api-key"
+		}
+	}
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,111 @@
+#!/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() {
+    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);
+});
+//# sourceMappingURL=index.js.map

package/dist/shell.d.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { ChildProcess } from 'node:child_process';
+export interface ShellResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Run a PowerShell command and return stdout/stderr/exitCode.
+ * Commands are wrapped with -NoProfile -NonInteractive for speed and safety.
+ */
+export declare function runPowerShell(command: string, options?: {
+    timeout?: number;
+    cwd?: string;
+}): Promise<ShellResult>;
+/**
+ * Run a PowerShell command that returns JSON. Wraps output with ConvertTo-Json
+ * and parses the result.
+ */
+export declare function runPowerShellJson<T = unknown>(command: string, options?: {
+    timeout?: number;
+    cwd?: string;
+}): Promise<T>;
+/**
+ * Run a generic shell command (cmd, bash, pwsh).
+ */
+export declare function runShell(command: string, options?: {
+    shell?: 'pwsh' | 'cmd' | 'bash';
+    timeout?: number;
+    cwd?: string;
+}): Promise<ShellResult>;
+export interface TerminalSession {
+    pid: number;
+    shell: string;
+    process: ChildProcess;
+    output: string[];
+    startedAt: Date;
+}
+export declare function startSession(shell?: 'pwsh' | 'cmd' | 'bash' | 'python' | 'node' | 'wsl'): TerminalSession;
+export declare function sendToSession(pid: number, input: string): void;
+export declare function readSessionOutput(pid: number, offset?: number, length?: number): string[];
+export declare function listSessions(): Array<{
+    pid: number;
+    shell: string;
+    running: boolean;
+    lines: number;
+    startedAt: string;
+}>;
+export declare function terminateSession(pid: number): boolean;
+//# sourceMappingURL=shell.d.ts.map