mcp-vm-shell 1.0.0__tar.gz

mcp_vm_shell-1.0.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agowa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_vm_shell-1.0.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: mcp-vm-shell
+Version: 1.0.0
+Summary: An MCP server that provides shell access to a VM.
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Dist: fastmcp
+Requires-Dist: tzlocal
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# mcp-vm-shell
+
+MCP plugin to grant access to a KVM VM with its TTY accessible through a unix socket.
+
+## Enter dev environment
+
+1. Install [nix](https://nixos.org/download/)
+2. Run `nix develop --impure --extra-experimental-features nix-command --extra-experimental-features flakes`
+
+Bulding the pip package using `uv sync; uv build`.
+Upload to pypi after configuring the API Token using `twine upload --verbose dist/*`
+

mcp_vm_shell-1.0.0/README.md

@@ -0,0 +1,12 @@
+# mcp-vm-shell
+
+MCP plugin to grant access to a KVM VM with its TTY accessible through a unix socket.
+
+## Enter dev environment
+
+1. Install [nix](https://nixos.org/download/)
+2. Run `nix develop --impure --extra-experimental-features nix-command --extra-experimental-features flakes`
+
+Bulding the pip package using `uv sync; uv build`.
+Upload to pypi after configuring the API Token using `twine upload --verbose dist/*`
+

mcp_vm_shell-1.0.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "mcp-vm-shell"
+version = "1.0.0"
+description = "An MCP server that provides shell access to a VM."
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE.md"]
+readme = "README.md"
+dependencies = [
+    "fastmcp",
+    "tzlocal",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.scripts]
+mcp-vm-shell = "mcp_vm_shell.server:main"
+
+[build-system]
+requires = ["uv_build >= 0.12.5, <0.13.0"]
+build-backend = "uv_build"

mcp_vm_shell-1.0.0/pyproject.toml.orig

@@ -0,0 +1,20 @@
+[project]
+name = "mcp-vm-shell"
+version = "1.0.0"
+description = "An MCP server that provides shell access to a VM."
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE.md"]
+readme = "README.md"
+dependencies = ["fastmcp", "tzlocal"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.scripts]
+mcp-vm-shell = "mcp_vm_shell.server:main"
+
+[build-system]
+requires = ["uv_build >= 0.12.5, <0.13.0"]
+build-backend = "uv_build"

mcp_vm_shell-1.0.0/src/mcp_vm_shell/server.py

@@ -0,0 +1,87 @@
+import argparse
+import socket
+import threading
+import uuid
+
+from mcp.server.fastmcp import FastMCP
+
+parser = argparse.ArgumentParser()
+parser.add_argument("socket_path", help="Path to the VM Unix socket")
+parser.add_argument("--timeout", type=float, default=30.0)
+args = parser.parse_args()
+
+mcp = FastMCP("vm-shell")
+
+def sock_connect():
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    sock.settimeout(30)
+    sock.connect(args.socket_path)
+    return sock
+
+# One command at a time; a terminal is a shared stateful session.
+lock = threading.Lock()
+MAX_OUTPUT = 1024 * 1024
+
+
+def read_until(marker: bytes, deadline: float, sock) -> bytes:
+    import time
+
+    output = bytearray()
+    while time.monotonic() < deadline:
+        try:
+            chunk = sock.recv(4096)
+        except socket.timeout:
+            continue
+
+        if not chunk:
+            raise RuntimeError("VM socket disconnected")
+
+        output.extend(chunk)
+
+        if marker in output:
+            return bytes(output[:output.index(marker)])
+
+        if len(output) > MAX_OUTPUT:
+            raise RuntimeError("Output limit exceeded; session may need reset")
+
+    raise TimeoutError("Command timed out; terminal state may be uncertain")
+
+
+@mcp.tool()
+def shell(command: str) -> str:
+    """Execute a command in the connected VM shell.
+
+    Requires an already authenticated interactive shell on the socket,
+    with terminal echo disabled (stty -echo).
+    Commands run in a persistent shell session.
+    """
+    if not command.strip():
+        return "Error: empty command"
+
+    marker = f"__MCP_DONE_{uuid.uuid4().hex}__".encode()
+
+    # The socket must already represent an authenticated shell.
+    # Capture the exit code and emit a unique completion marker.
+    payload = (
+        command
+        + f"\n__mcp_rc=$?; printf '\\n%s:%s\\n' "
+          f"'{marker.decode()}' \"$__mcp_rc\"\n"
+    ).encode()
+
+    with lock:
+        import time
+
+        sock = sock_connect()
+        with sock:
+            deadline = time.monotonic() + args.timeout
+            sock.sendall(payload)
+            result = read_until(marker, deadline, sock)
+            return result.decode(errors="replace").strip()
+
+
+if __name__ == "__main__":
+    #mcp.run(transport="stdio")
+    mcp.settings.host="127.0.0.1"
+    mcp.settings.port=1427
+    mcp.run(transport="streamable-http")
+