windows-server-mcp 1.0.0__py3-none-any.whl

windows_server_mcp/__init__.py

@@ -0,0 +1 @@
+# This file makes windows_server_mcp a Python package

windows_server_mcp/registry.py

@@ -0,0 +1,118 @@
+import functools
+import inspect
+import logging
+import time
+
+log = logging.getLogger("windows_server_mcp")
+
+registered_tools = []
+
+#: Hard ceiling (seconds) for a single tool call.  Commands have their own,
+#: shorter timeouts (see shell.py); this only frees the server when something
+#: blocks inside Python itself (a stuck syscall, a hung handle query...).
+DEFAULT_TOOL_DEADLINE = 180
+LONG_TOOL_DEADLINE = 3700  # update/driver installs
+
+
+def _deadline_for(name: str, kwargs: dict) -> int:
+    if name == "execute_powershell":
+        try:
+            return min(int(kwargs.get("timeout_seconds", 60)), 3600) + 30
+        except (TypeError, ValueError):
+            return 90
+    if "install" in name:
+        return LONG_TOOL_DEADLINE
+    return DEFAULT_TOOL_DEADLINE
+
+
+def _run_in_thread(func):
+    """Run a blocking tool in a worker thread with a hard deadline.
+
+    * With ``mcp`` 1.x plain sync tools run on the event loop, so one slow call
+      froze the whole server.  A thread keeps the server responsive.
+    * If the thread blocks forever (e.g. a stuck syscall), the call is
+      abandoned after the deadline and an error is returned, instead of the
+      client waiting until its own timeout.
+    * Every call is logged (start/finish/abandon) so a hang can be traced to a
+      specific tool: a ``start`` line with no ``finished`` line is the culprit.
+    """
+    if inspect.iscoroutinefunction(func):
+        return func
+
+    @functools.wraps(func)
+    async def wrapper(*args, **kwargs):
+        import anyio
+
+        name = func.__name__
+        deadline = _deadline_for(name, kwargs)
+        started = time.monotonic()
+        log.info("tool start: %s (deadline %ss)", name, deadline)
+
+        def target():
+            try:
+                return func(*args, **kwargs)
+            finally:
+                log.info("tool finished: %s in %.1fs", name, time.monotonic() - started)
+
+        try:
+            with anyio.fail_after(deadline):
+                return await anyio.to_thread.run_sync(target, abandon_on_cancel=True)
+        except TimeoutError:
+            log.error("tool ABANDONED: %s still running after %ss", name, deadline)
+            return (
+                f"Error: tool '{name}' did not finish within {deadline}s and was abandoned. "
+                "The server is still responsive; try a narrower request."
+            )
+        except Exception:
+            log.exception("tool failed: %s", name)
+            raise
+
+    return wrapper
+
+
+def windows_server_mcp_tool():
+    """
+    Decorator to register a function as a Windows MCP tool.
+    """
+    def decorator(func):
+        registered_tools.append(func)
+        return func
+    return decorator
+
+def register_all_tools(mcp):
+    """
+    Imports all tool modules and registers them with the server instance
+    (``MCPServer`` on mcp 2.x, ``FastMCP`` on mcp 1.x).
+    """
+    import windows_server_mcp.tools.execute_powershell
+    import windows_server_mcp.tools.manage_registry
+    import windows_server_mcp.tools.manage_network
+    import windows_server_mcp.tools.task_manager
+    import windows_server_mcp.tools.software_audit
+    import windows_server_mcp.tools.storage_analysis
+    import windows_server_mcp.tools.system_info
+    import windows_server_mcp.tools.process_management
+    import windows_server_mcp.tools.optimization
+    import windows_server_mcp.tools.services
+    import windows_server_mcp.tools.hardware_drivers
+    import windows_server_mcp.tools.media_management
+    import windows_server_mcp.tools.advanced_process
+    import windows_server_mcp.tools.window_management
+    import windows_server_mcp.tools.startup_tasks
+    import windows_server_mcp.tools.event_diagnostics
+    import windows_server_mcp.tools.network_diagnostics
+    import windows_server_mcp.tools.security_updates
+    import windows_server_mcp.tools.power_hardware
+    import windows_server_mcp.tools.safe_file_operations
+    import windows_server_mcp.tools.developer_environment
+    import windows_server_mcp.tools.shell_helpers
+    import windows_server_mcp.tools.disk_health
+    import windows_server_mcp.tools.driver_maintenance
+    import windows_server_mcp.tools.software_maintenance
+    import windows_server_mcp.tools.peripherals
+    import windows_server_mcp.tools.virtualization
+    import windows_server_mcp.tools.restore_update_controls
+    import windows_server_mcp.tools.text_files
+
+    for func in registered_tools:
+        mcp.tool()(_run_in_thread(func))

windows_server_mcp/server.py

@@ -0,0 +1,116 @@
+"""Entry point for the Windows Management MCP server.
+
+This module works with both generations of the official MCP Python SDK:
+
+* ``mcp >= 2.0``  -> ``MCPServer`` (``mcp.server.mcpserver``).
+  In v2 the old ``FastMCP`` class was renamed to ``MCPServer`` and the
+  ``mcp.server.fastmcp`` module was removed without a deprecation shim.
+* ``mcp 1.x``     -> ``FastMCP`` (``mcp.server.fastmcp``).
+
+Migration guide:
+https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver
+"""
+
+import logging
+import logging.handlers
+import os
+import sys
+import tempfile
+from importlib.metadata import PackageNotFoundError, version as _dist_version
+
+from windows_server_mcp.registry import register_all_tools
+
+try:  # mcp 2.x
+    from mcp.server.mcpserver import MCPServer as _Server
+
+    _SDK_GENERATION = 2
+except ImportError:  # mcp 1.x
+    from mcp.server.fastmcp import FastMCP as _Server
+
+    _SDK_GENERATION = 1
+
+SERVER_NAME = "Windows Management"
+
+
+def _package_version() -> str:
+    try:
+        return _dist_version("windows-server-mcp")
+    except PackageNotFoundError:  # running from a source checkout
+        return "0.0.0+local"
+
+
+def create_server():
+    """Build the MCP server and register every Windows tool on it."""
+    if _SDK_GENERATION == 2:
+        # In v2 only `name` is positional-safe: pass everything else by keyword.
+        server = _Server(SERVER_NAME, version=_package_version())
+    else:
+        server = _Server(SERVER_NAME)
+    register_all_tools(server)
+    return server
+
+
+mcp = create_server()
+
+
+def _log_dir() -> str:
+    base = os.environ.get("LOCALAPPDATA") or tempfile.gettempdir()
+    return os.path.join(base, "windows-server-mcp")
+
+
+def _harden_stdio() -> None:
+    """Make sure logging can never block the server.
+
+    When the server is started with ``pythonw.exe`` by a bridge/launcher,
+    ``stderr`` is often a pipe nobody reads.  Once ~64 KB of log lines fill it,
+    the next ``write`` blocks forever and every tool call "hangs" until the
+    process is killed.  We send our own logs and ``stderr`` to files instead.
+    ``stdout`` is left alone: it carries the MCP protocol.
+    """
+    try:
+        directory = _log_dir()
+        os.makedirs(directory, exist_ok=True)
+        log_file = os.path.join(directory, "server.log")
+        err_file = os.path.join(directory, "stderr.log")
+
+        handler = logging.handlers.RotatingFileHandler(
+            log_file, maxBytes=1_000_000, backupCount=2, encoding="utf-8"
+        )
+        handler.setFormatter(logging.Formatter("%(asctime)s %(threadName)s %(levelname)s %(message)s"))
+        package_logger = logging.getLogger("windows_server_mcp")
+        package_logger.setLevel(logging.INFO)
+        package_logger.addHandler(handler)
+        package_logger.propagate = False
+
+        if os.path.exists(err_file) and os.path.getsize(err_file) > 5_000_000:
+            os.remove(err_file)
+        err_stream = open(err_file, "a", buffering=1, encoding="utf-8", errors="replace")
+        previous_stderr = sys.stderr
+        sys.stderr = err_stream
+        loggers = [logging.getLogger()] + [
+            lg for lg in logging.root.manager.loggerDict.values() if isinstance(lg, logging.Logger)
+        ]
+        for lg in loggers:
+            for existing in lg.handlers:
+                # Only re-point handlers that write to the old stderr; leave
+                # foreign handlers (e.g. pytest's capture handlers) untouched.
+                if (
+                    isinstance(existing, logging.StreamHandler)
+                    and not isinstance(existing, logging.FileHandler)
+                    and getattr(existing, "stream", None) in (previous_stderr, sys.__stderr__)
+                ):
+                    existing.setStream(err_stream)
+        package_logger.info("server starting (python %s, sdk generation %s)", sys.executable, _SDK_GENERATION)
+    except Exception:
+        # Never let logging setup prevent the server from starting.
+        pass
+
+
+def main():
+    """Run the server over stdio (the default transport)."""
+    _harden_stdio()
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

windows_server_mcp/shell.py

@@ -0,0 +1,200 @@
+"""Safe subprocess helpers shared by every tool.
+
+Why this module exists
+----------------------
+The MCP server talks to the client over stdio.  A child process that
+
+* inherits the server's ``stdin`` (the MCP channel) can block waiting for input
+  (``pause``, installers, ``Read-Host``...), and
+* has no ``timeout`` never returns if PowerShell hangs (``Get-Counter``,
+  Windows Update COM calls, a UAC prompt nobody can see...).
+
+When that happens the tool call never completes and the MCP client eventually
+gives up with its own timeout.  Every external command should go through
+:func:`run` / :func:`run_powershell` so it always has a deadline, never reads
+from the MCP channel, never pops a console window and is killed together with
+all of its children when the deadline expires.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from typing import Any, Sequence
+
+#: Used when a caller does not pass an explicit ``timeout``.
+DEFAULT_TIMEOUT = 60
+
+#: Exit code reported when a command was killed because it timed out
+#: (same convention as GNU ``timeout``).
+TIMEOUT_RETURNCODE = 124
+
+_IS_WINDOWS = sys.platform == "win32"
+_CREATE_NO_WINDOW = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+_CREATE_NEW_PROCESS_GROUP = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+
+
+#: Prepended to every PowerShell ``-Command`` script.  Windows PowerShell 5.1
+#: writes to a pipe using the console's OEM code page (cp437/cp850...), which
+#: turns accents and emojis into garbage ("é", "?", Chinese-looking text) once
+#: Python decodes it.  Forcing UTF-8 (without BOM) on both sides fixes that.
+UTF8_PREAMBLE = (
+    "try { [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false) } catch {}; "
+    "try { [Console]::InputEncoding = New-Object System.Text.UTF8Encoding($false) } catch {}; "
+    "$OutputEncoding = New-Object System.Text.UTF8Encoding($false); "
+)
+
+
+def _is_powershell_command(args: Any) -> bool:
+    if isinstance(args, (str, bytes)) or not args:
+        return False
+    exe = os.path.basename(str(args[0])).lower()
+    if exe not in ("powershell", "powershell.exe", "pwsh", "pwsh.exe"):
+        return False
+    return any(str(a).lower() in ("-command", "-c") for a in args[:-1])
+
+
+def with_utf8_preamble(args: Sequence[str]) -> list[str]:
+    """Return *args* with the UTF-8 preamble added to the PowerShell script."""
+    argv = list(args)
+    for index, value in enumerate(argv[:-1]):
+        if str(value).lower() in ("-command", "-c") and not argv[index + 1].startswith(UTF8_PREAMBLE):
+            argv[index + 1] = UTF8_PREAMBLE + argv[index + 1]
+            break
+    return argv
+
+
+def powershell_command(script: str, *, non_interactive: bool = True) -> list[str]:
+    """Build the argv used to run *script* with Windows PowerShell."""
+    argv = ["powershell", "-NoProfile"]
+    if non_interactive:
+        argv.append("-NonInteractive")
+    argv += ["-Command", UTF8_PREAMBLE + script]
+    return argv
+
+
+def kill_process_tree(proc: subprocess.Popen) -> None:
+    """Kill *proc* and every process it spawned."""
+    try:
+        if _IS_WINDOWS:
+            subprocess.run(
+                ["taskkill", "/PID", str(proc.pid), "/T", "/F"],
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=10,
+                creationflags=_CREATE_NO_WINDOW,
+            )
+        else:  # pragma: no cover - only used when developing on Linux/macOS
+            import signal
+
+            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+    except Exception:
+        pass
+    try:
+        proc.kill()
+    except Exception:
+        pass
+
+
+def _timeout_message(args: Any, timeout: float) -> str:
+    return (
+        f"Command timed out after {timeout:g}s and was terminated. "
+        "Try a narrower query, or raise the timeout if the task is expected to be slow."
+    )
+
+
+def run(
+    args: Sequence[str] | str,
+    *,
+    timeout: float | None = DEFAULT_TIMEOUT,
+    capture_output: bool = True,
+    text: bool = True,
+    check: bool = False,
+    **kwargs: Any,
+) -> subprocess.CompletedProcess:
+    """Drop-in replacement for :func:`subprocess.run` that cannot hang.
+
+    Differences from ``subprocess.run``:
+
+    * ``timeout`` defaults to :data:`DEFAULT_TIMEOUT`.  Pass ``None`` only if
+      you really want to wait forever.
+    * ``stdin`` is always closed (``DEVNULL``) so the child can never read from
+      the MCP stdio channel.
+    * No console window is created on Windows.
+    * On timeout the whole process tree is killed and a ``CompletedProcess``
+      with ``returncode == 124`` is *returned* (not raised).  ``stderr``
+      contains an explanatory message, so the existing
+      ``if result.returncode != 0: return result.stderr`` code paths report the
+      timeout to the model instead of blowing up.
+    """
+    kwargs.pop("stdin", None)
+    if _is_powershell_command(args):
+        args = with_utf8_preamble(args)
+        if text:
+            kwargs.setdefault("encoding", "utf-8")
+    if capture_output:
+        kwargs.setdefault("stdout", subprocess.PIPE)
+        kwargs.setdefault("stderr", subprocess.PIPE)
+    if text:
+        kwargs.setdefault("errors", "replace")
+    flags = kwargs.pop("creationflags", 0) | _CREATE_NO_WINDOW
+    if not _IS_WINDOWS:  # pragma: no cover
+        kwargs.setdefault("start_new_session", True)
+        flags = 0
+    else:
+        flags |= _CREATE_NEW_PROCESS_GROUP
+
+    proc = subprocess.Popen(
+        args,
+        stdin=subprocess.DEVNULL,
+        text=text,
+        creationflags=flags,
+        **kwargs,
+    )
+    try:
+        stdout, stderr = proc.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        kill_process_tree(proc)
+        try:
+            stdout, stderr = proc.communicate(timeout=5)
+        except Exception:
+            stdout, stderr = ("" if text else b""), ("" if text else b"")
+        message = _timeout_message(args, timeout or 0)
+        if text:
+            stderr = f"{(stderr or '').rstrip()}\n{message}".strip()
+        else:
+            stderr = (stderr or b"") + b"\n" + message.encode()
+        return subprocess.CompletedProcess(args, TIMEOUT_RETURNCODE, stdout, stderr)
+    except BaseException:
+        kill_process_tree(proc)
+        raise
+
+    result = subprocess.CompletedProcess(args, proc.returncode, stdout, stderr)
+    if check and result.returncode != 0:
+        raise subprocess.CalledProcessError(
+            result.returncode, args, output=stdout, stderr=stderr
+        )
+    return result
+
+
+def run_powershell(
+    script: str,
+    *,
+    timeout: float | None = DEFAULT_TIMEOUT,
+    non_interactive: bool = True,
+) -> subprocess.CompletedProcess:
+    """Run a PowerShell script with a deadline and a closed stdin."""
+    return run(powershell_command(script, non_interactive=non_interactive), timeout=timeout)
+
+
+def spawn_detached(args: Sequence[str]) -> subprocess.Popen:
+    """Start a GUI program (e.g. Explorer) without waiting for it or sharing stdio."""
+    return subprocess.Popen(
+        args,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        creationflags=_CREATE_NO_WINDOW if _IS_WINDOWS else 0,
+    )

windows_server_mcp/tools/__init__.py

@@ -0,0 +1 @@
+# Tools package

windows_server_mcp/tools/advanced_process.py

@@ -0,0 +1,184 @@
+import datetime
+import os
+import sys
+from windows_server_mcp.shell import TIMEOUT_RETURNCODE, run
+from typing import Optional
+
+import psutil
+
+from windows_server_mcp.registry import windows_server_mcp_tool
+
+
+def _format_time(timestamp: float) -> str:
+    return datetime.datetime.fromtimestamp(timestamp).strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _signature_status(exe_path: Optional[str]) -> str:
+    if not exe_path or not os.path.exists(exe_path):
+        return "Unknown"
+
+    escaped_path = exe_path.replace("'", "''")
+    ps_cmd = (
+        "Get-AuthenticodeSignature -LiteralPath "
+        f"'{escaped_path}' | "
+        "Select-Object Status,SignerCertificate | ConvertTo-Json -Depth 3"
+    )
+    try:
+        result = run(
+            ["powershell", "-NoProfile", "-Command", ps_cmd],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode != 0 or not result.stdout.strip():
+            return "Unknown"
+        return result.stdout.strip()
+    except Exception:
+        return "Unknown"
+
+
+@windows_server_mcp_tool()
+def get_process_details(pid: int) -> str:
+    """
+    Return detailed process metadata for a PID, including command line, parent,
+    executable path, resource usage, open files, network connections, and signature status.
+    """
+    try:
+        proc = psutil.Process(pid)
+        with proc.oneshot():
+            parent = proc.parent()
+            memory = proc.memory_info()
+            cpu_times = proc.cpu_times()
+            exe_path = proc.exe() if proc.exe else ""
+            lines = [
+                f"Name: {proc.name()}",
+                f"PID: {proc.pid}",
+                f"Status: {proc.status()}",
+                f"User: {proc.username()}",
+                f"Created: {_format_time(proc.create_time())}",
+                f"Parent: {parent.name()} (PID: {parent.pid})" if parent else "Parent: None",
+                f"Executable: {exe_path}",
+                f"Command Line: {' '.join(proc.cmdline())}",
+                f"Working Directory: {proc.cwd()}",
+                f"Threads: {proc.num_threads()}",
+                f"Handles: {proc.num_handles() if hasattr(proc, 'num_handles') else 'Unknown'}",
+                f"CPU Time: user={cpu_times.user:.2f}s system={cpu_times.system:.2f}s",
+                f"Memory RSS: {memory.rss / (1024 ** 2):.2f} MB",
+                f"Memory VMS: {memory.vms / (1024 ** 2):.2f} MB",
+                f"Signature: {_signature_status(exe_path)}",
+            ]
+
+            try:
+                open_files = proc.open_files()
+                lines.append("\nOpen Files:")
+                lines.extend(f"  {file.path}" for file in open_files[:20])
+                if len(open_files) > 20:
+                    lines.append(f"  ... and {len(open_files) - 20} more")
+            except Exception as exc:
+                lines.append(f"\nOpen Files: unavailable ({exc})")
+
+            try:
+                connections = proc.net_connections(kind="inet")
+                lines.append("\nNetwork Connections:")
+                for conn in connections[:20]:
+                    laddr = f"{conn.laddr.ip}:{conn.laddr.port}" if conn.laddr else ""
+                    raddr = f"{conn.raddr.ip}:{conn.raddr.port}" if conn.raddr else ""
+                    lines.append(f"  {laddr} -> {raddr} [{conn.status}]")
+                if len(connections) > 20:
+                    lines.append(f"  ... and {len(connections) - 20} more")
+            except Exception as exc:
+                lines.append(f"\nNetwork Connections: unavailable ({exc})")
+
+            return "\n".join(lines)
+    except psutil.NoSuchProcess:
+        return f"Error: No process found with PID {pid}."
+    except psutil.AccessDenied:
+        return f"Error: Access denied reading process PID {pid}."
+    except Exception as exc:
+        return f"Error getting process details: {exc}"
+
+
+@windows_server_mcp_tool()
+def get_process_tree(pid: int = 0) -> str:
+    """
+    Show parent-child process relationships.
+    Args:
+        pid: Root PID to inspect. Use 0 to show top-level process trees.
+    """
+    try:
+        processes = {proc.pid: proc for proc in psutil.process_iter(["pid", "name", "ppid"])}
+        children: dict[int, list[psutil.Process]] = {}
+        for proc in processes.values():
+            try:
+                children.setdefault(proc.ppid(), []).append(proc)
+            except (psutil.NoSuchProcess, psutil.AccessDenied):
+                continue
+
+        roots = [processes[pid]] if pid else [
+            proc for proc in processes.values() if proc.ppid() not in processes
+        ]
+
+        lines: list[str] = []
+
+        def walk(proc: psutil.Process, depth: int) -> None:
+            try:
+                indent = "  " * depth
+                lines.append(f"{indent}- {proc.name()} (PID: {proc.pid})")
+                for child in sorted(children.get(proc.pid, []), key=lambda item: item.name().lower()):
+                    walk(child, depth + 1)
+            except (psutil.NoSuchProcess, psutil.AccessDenied):
+                return
+
+        for root in sorted(roots, key=lambda item: item.name().lower()):
+            walk(root, 0)
+
+        return "\n".join(lines[:500]) if lines else "No process tree data found."
+    except KeyError:
+        return f"Error: No process found with PID {pid}."
+    except Exception as exc:
+        return f"Error building process tree: {exc}"
+
+
+_LOCK_SCAN_CODE = r"""
+import os, sys, psutil
+target = os.path.abspath(sys.argv[1]).lower()
+for proc in psutil.process_iter(["pid", "name"]):
+    try:
+        for f in proc.open_files():
+            if os.path.abspath(f.path).lower() == target:
+                print(f"PID: {proc.pid} | Name: {proc.name()} | Path: {f.path}", flush=True)
+                break
+    except Exception:
+        continue
+"""
+
+
+def _console_python() -> str:
+    """Return python.exe even when the server itself runs under pythonw.exe."""
+    exe = sys.executable
+    if os.path.basename(exe).lower() == "pythonw.exe":
+        candidate = os.path.join(os.path.dirname(exe), "python.exe")
+        if os.path.exists(candidate):
+            return candidate
+    return exe
+
+
+@windows_server_mcp_tool()
+def find_process_locking_file(file_path: str) -> str:
+    """
+    Identify processes that appear to have a file open.
+    Note: Windows may hide some handles without Administrator privileges.
+    The scan runs in a separate process with a 45s limit, because
+    psutil's open_files() can block forever on some Windows handles.
+    """
+    result = run([_console_python(), "-c", _LOCK_SCAN_CODE, file_path], timeout=45)
+    matches = [line for line in (result.stdout or "").splitlines() if line.startswith("PID:")]
+    if matches:
+        return "\n".join(matches)
+    if result.returncode == TIMEOUT_RETURNCODE:
+        return (
+            "The handle scan timed out (some process handle blocked it). "
+            f"No match found before the limit for '{file_path}'. "
+            "Try PowerShell/handle.exe or Resource Monitor as an alternative."
+        )
+    return f"No visible process handles found for '{file_path}'. Try running as Administrator for deeper handle visibility."