universal-host-manager-mcp 0.1.0__tar.gz

universal_host_manager_mcp-0.1.0/.env.example

@@ -0,0 +1,20 @@
+# Bind to loopback when a reverse proxy or tunnel runs on the same host.
+HOST=127.0.0.1
+PORT=8765
+MCP_BASE_URL=https://mcp.example.com
+MCP_WORKSPACE_DIR=/home/youruser/workspace
+
+MAX_OUTPUT_CHARS=64000
+DEFAULT_CMD_TIMEOUT=300
+MAX_CMD_TIMEOUT=1800
+MAX_READ_BYTES=5000000
+MAX_WRITE_BYTES=5000000
+LOG_LEVEL=INFO
+
+AUTH0_DOMAIN=your-tenant.eu.auth0.com
+AUTH0_CLIENT_ID=replace_me
+AUTH0_CLIENT_SECRET=replace_me
+AUTH0_AUDIENCE=https://mcp.example.com/
+
+# Local development only. Never enable on a publicly reachable endpoint.
+ALLOW_INSECURE_NO_AUTH=false

universal_host_manager_mcp-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+.env
+.env.*
+!.env.example
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.idea/
+.vscode/

universal_host_manager_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmet Baktiaya
+
+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.

universal_host_manager_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.5
+Name: universal-host-manager-mcp
+Version: 0.1.0
+Summary: Cross-platform FastMCP server for authenticated remote Linux/macOS host administration
+Project-URL: Homepage, https://github.com/Abktya/universal-host-manager-mcp
+Project-URL: Repository, https://github.com/Abktya/universal-host-manager-mcp
+Project-URL: Issues, https://github.com/Abktya/universal-host-manager-mcp/issues
+Project-URL: Security, https://github.com/Abktya/universal-host-manager-mcp/blob/main/SECURITY.md
+Author: Ahmet Baktiaya
+License: MIT License
+        
+        Copyright (c) 2026 Ahmet Baktiaya
+        
+        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.
+License-File: LICENSE
+Keywords: chatgpt,claude,devops,mcp,model-context-protocol,remote-shell,sysadmin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: fastmcp<5,>=2.13
+Requires-Dist: python-dotenv<2,>=1.0
+Description-Content-Type: text/markdown
+
+# Universal Host Manager MCP
+
+A cross-platform [Model Context Protocol](https://modelcontextprotocol.io/) server for administering a Linux or macOS host through MCP clients such as ChatGPT and Claude.
+
+It uses [FastMCP](https://gofastmcp.com/) Streamable HTTP transport, Auth0 OAuth, bounded file tools, output limits and command timeouts.
+
+> [!CAUTION]
+> This project exposes arbitrary shell execution. Authentication decides who may use it; it does not make commands harmless. Read [SECURITY.md](SECURITY.md) before deploying it.
+
+## Features
+
+- Linux and macOS support
+- Streamable HTTP endpoint
+- Auth0 OAuth integration
+- File reads, writes and directory listings constrained to `MCP_WORKSPACE_DIR`
+- Configurable command timeouts and output truncation
+- File-size limits and decoding fallback
+- Fail-closed startup when authentication is not configured
+- Example systemd and launchd services
+
+## Tools
+
+| Tool | Parameters | Purpose |
+| --- | --- | --- |
+| `run_command` | `command: str`, `timeout: int` | Runs an arbitrary shell command with the workspace as its working directory |
+| `read_file` | `path: str` | Reads a text file inside the workspace |
+| `write_file` | `path: str`, `content: str` | Writes UTF-8 text inside the workspace |
+| `list_dir` | `path: str = "."` | Lists a directory inside the workspace |
+| `system_metrics` | none | Reports disk, memory and top-process information |
+
+The workspace boundary applies to the file tools. It does **not** sandbox `run_command`; commands retain all permissions of the service's OS user.
+
+## Requirements
+
+- Python 3.10+
+- Linux or macOS
+- Auth0 account for remote use
+- HTTPS endpoint for remote MCP clients
+
+## Install
+
+```bash
+git clone https://github.com/Abktya/universal-host-manager-mcp.git
+cd universal-host-manager-mcp
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+cp .env.example .env
+```
+
+Edit `.env` and use an explicitly restricted workspace:
+
+```dotenv
+HOST=127.0.0.1
+PORT=8765
+MCP_BASE_URL=https://mcp.example.com
+MCP_WORKSPACE_DIR=/home/youruser/workspace
+
+AUTH0_DOMAIN=your-tenant.eu.auth0.com
+AUTH0_CLIENT_ID=replace_me
+AUTH0_CLIENT_SECRET=replace_me
+AUTH0_AUDIENCE=https://mcp.example.com/
+```
+
+Never commit `.env`.
+
+## Auth0 setup
+
+This project uses FastMCP's `Auth0Provider` fixed-client OAuth integration.
+
+1. In Auth0, create an API.
+2. Use your public MCP URL as its identifier/audience, for example `https://mcp.example.com/`.
+3. Create a Regular Web Application.
+4. Put its domain, client ID and client secret in `.env`.
+5. Add only the callback URLs required by your MCP clients to the Auth0 application's allowed callback URLs.
+6. Set the application's allowed web origins and logout URLs as required by your clients.
+7. Keep RS256 signing enabled.
+
+FastMCP also supports an Auth0 MCP-native/DCR path through `Auth0MCPProvider`. This repository currently uses the manually managed, fixed-client `Auth0Provider` path.
+
+## Install
+
+From PyPI (recommended):
+
+```bash
+pip install universal-host-manager-mcp
+```
+
+Or with [uv](https://docs.astral.sh/uv/) / [pipx](https://pipx.pypa.io/), without polluting a project environment:
+
+```bash
+uvx universal-host-manager-mcp
+```
+
+From source (for development):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Run
+
+```bash
+universal-host-manager-mcp
+```
+
+(Running from a source checkout with the `.venv` activated works the same way — the console script is installed by `pip install -e .`.)
+
+With the default port, the Streamable HTTP endpoint is:
+
+```text
+http://127.0.0.1:8765/mcp
+```
+
+For an intentional local-only test without Auth0:
+
+```bash
+ALLOW_INSECURE_NO_AUTH=true universal-host-manager-mcp
+```
+
+Do not use insecure mode on a publicly reachable endpoint.
+
+## Cloudflare Tunnel
+
+Install `cloudflared`, authenticate it and create a named tunnel:
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create universal-host-manager-mcp
+cloudflared tunnel route dns universal-host-manager-mcp mcp.example.com
+```
+
+Create `~/.cloudflared/config.yml`:
+
+```yaml
+tunnel: YOUR_TUNNEL_ID
+credentials-file: /home/youruser/.cloudflared/YOUR_TUNNEL_ID.json
+
+ingress:
+  - hostname: mcp.example.com
+    service: http://127.0.0.1:8765
+  - service: http_status:404
+```
+
+Validate and run it:
+
+```bash
+cloudflared tunnel ingress validate
+cloudflared tunnel run universal-host-manager-mcp
+```
+
+Your remote MCP URL will be:
+
+```text
+https://mcp.example.com/mcp
+```
+
+Set `MCP_BASE_URL=https://mcp.example.com`; do not include `/mcp` in `MCP_BASE_URL`.
+
+## ChatGPT and Claude
+
+Add the public Streamable HTTP URL to the client's MCP/connector configuration:
+
+```text
+https://mcp.example.com/mcp
+```
+
+Complete the Auth0 sign-in when the client opens the authorization flow. The exact settings screens and supported connector options can change, so follow the current client documentation rather than using legacy SSE instructions.
+
+Multiple clients can connect to the same running HTTP server. Each client authenticates independently; no separate server process or port is required.
+
+## Background service
+
+### Linux systemd
+
+Copy and edit the included unit:
+
+```bash
+sudo cp examples/mcp-manager.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now mcp-manager
+sudo systemctl status mcp-manager --no-pager
+```
+
+The example uses systemd hardening directives. Adjust `ReadWritePaths`, `ProtectHome`, the user, paths and permissions to match the resources the MCP server genuinely needs.
+
+### macOS launchd
+
+Edit paths in `examples/com.user.mcpmanager.plist`, then:
+
+```bash
+cp examples/com.user.mcpmanager.plist ~/Library/LaunchAgents/
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.user.mcpmanager.plist
+launchctl kickstart -k gui/$(id -u)/com.user.mcpmanager
+```
+
+## Configuration
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `HOST` | `127.0.0.1` | Listen address |
+| `PORT` | `8765` | Listen port |
+| `MCP_BASE_URL` | local URL | Public OAuth base URL, without `/mcp` |
+| `MCP_WORKSPACE_DIR` | user home | Boundary for file tools and command working directory |
+| `MAX_OUTPUT_CHARS` | `64000` | Maximum returned tool-output characters |
+| `DEFAULT_CMD_TIMEOUT` | `300` | Default command timeout in seconds |
+| `MAX_CMD_TIMEOUT` | `1800` | Maximum accepted command timeout |
+| `MAX_READ_BYTES` | `5000000` | Maximum file size read by `read_file` |
+| `MAX_WRITE_BYTES` | `5000000` | Maximum content size written by `write_file` |
+| `LOG_LEVEL` | `INFO` | Python log level |
+| `ALLOW_INSECURE_NO_AUTH` | `false` | Explicit local-development authentication bypass |
+
+## Download
+
+Clone with Git:
+
+```bash
+git clone https://github.com/Abktya/universal-host-manager-mcp.git
+```
+
+Or use **Code → Download ZIP** on GitHub.
+
+## License
+
+[MIT](LICENSE)

universal_host_manager_mcp-0.1.0/README.md

@@ -0,0 +1,228 @@
+# Universal Host Manager MCP
+
+A cross-platform [Model Context Protocol](https://modelcontextprotocol.io/) server for administering a Linux or macOS host through MCP clients such as ChatGPT and Claude.
+
+It uses [FastMCP](https://gofastmcp.com/) Streamable HTTP transport, Auth0 OAuth, bounded file tools, output limits and command timeouts.
+
+> [!CAUTION]
+> This project exposes arbitrary shell execution. Authentication decides who may use it; it does not make commands harmless. Read [SECURITY.md](SECURITY.md) before deploying it.
+
+## Features
+
+- Linux and macOS support
+- Streamable HTTP endpoint
+- Auth0 OAuth integration
+- File reads, writes and directory listings constrained to `MCP_WORKSPACE_DIR`
+- Configurable command timeouts and output truncation
+- File-size limits and decoding fallback
+- Fail-closed startup when authentication is not configured
+- Example systemd and launchd services
+
+## Tools
+
+| Tool | Parameters | Purpose |
+| --- | --- | --- |
+| `run_command` | `command: str`, `timeout: int` | Runs an arbitrary shell command with the workspace as its working directory |
+| `read_file` | `path: str` | Reads a text file inside the workspace |
+| `write_file` | `path: str`, `content: str` | Writes UTF-8 text inside the workspace |
+| `list_dir` | `path: str = "."` | Lists a directory inside the workspace |
+| `system_metrics` | none | Reports disk, memory and top-process information |
+
+The workspace boundary applies to the file tools. It does **not** sandbox `run_command`; commands retain all permissions of the service's OS user.
+
+## Requirements
+
+- Python 3.10+
+- Linux or macOS
+- Auth0 account for remote use
+- HTTPS endpoint for remote MCP clients
+
+## Install
+
+```bash
+git clone https://github.com/Abktya/universal-host-manager-mcp.git
+cd universal-host-manager-mcp
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+cp .env.example .env
+```
+
+Edit `.env` and use an explicitly restricted workspace:
+
+```dotenv
+HOST=127.0.0.1
+PORT=8765
+MCP_BASE_URL=https://mcp.example.com
+MCP_WORKSPACE_DIR=/home/youruser/workspace
+
+AUTH0_DOMAIN=your-tenant.eu.auth0.com
+AUTH0_CLIENT_ID=replace_me
+AUTH0_CLIENT_SECRET=replace_me
+AUTH0_AUDIENCE=https://mcp.example.com/
+```
+
+Never commit `.env`.
+
+## Auth0 setup
+
+This project uses FastMCP's `Auth0Provider` fixed-client OAuth integration.
+
+1. In Auth0, create an API.
+2. Use your public MCP URL as its identifier/audience, for example `https://mcp.example.com/`.
+3. Create a Regular Web Application.
+4. Put its domain, client ID and client secret in `.env`.
+5. Add only the callback URLs required by your MCP clients to the Auth0 application's allowed callback URLs.
+6. Set the application's allowed web origins and logout URLs as required by your clients.
+7. Keep RS256 signing enabled.
+
+FastMCP also supports an Auth0 MCP-native/DCR path through `Auth0MCPProvider`. This repository currently uses the manually managed, fixed-client `Auth0Provider` path.
+
+## Install
+
+From PyPI (recommended):
+
+```bash
+pip install universal-host-manager-mcp
+```
+
+Or with [uv](https://docs.astral.sh/uv/) / [pipx](https://pipx.pypa.io/), without polluting a project environment:
+
+```bash
+uvx universal-host-manager-mcp
+```
+
+From source (for development):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Run
+
+```bash
+universal-host-manager-mcp
+```
+
+(Running from a source checkout with the `.venv` activated works the same way — the console script is installed by `pip install -e .`.)
+
+With the default port, the Streamable HTTP endpoint is:
+
+```text
+http://127.0.0.1:8765/mcp
+```
+
+For an intentional local-only test without Auth0:
+
+```bash
+ALLOW_INSECURE_NO_AUTH=true universal-host-manager-mcp
+```
+
+Do not use insecure mode on a publicly reachable endpoint.
+
+## Cloudflare Tunnel
+
+Install `cloudflared`, authenticate it and create a named tunnel:
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create universal-host-manager-mcp
+cloudflared tunnel route dns universal-host-manager-mcp mcp.example.com
+```
+
+Create `~/.cloudflared/config.yml`:
+
+```yaml
+tunnel: YOUR_TUNNEL_ID
+credentials-file: /home/youruser/.cloudflared/YOUR_TUNNEL_ID.json
+
+ingress:
+  - hostname: mcp.example.com
+    service: http://127.0.0.1:8765
+  - service: http_status:404
+```
+
+Validate and run it:
+
+```bash
+cloudflared tunnel ingress validate
+cloudflared tunnel run universal-host-manager-mcp
+```
+
+Your remote MCP URL will be:
+
+```text
+https://mcp.example.com/mcp
+```
+
+Set `MCP_BASE_URL=https://mcp.example.com`; do not include `/mcp` in `MCP_BASE_URL`.
+
+## ChatGPT and Claude
+
+Add the public Streamable HTTP URL to the client's MCP/connector configuration:
+
+```text
+https://mcp.example.com/mcp
+```
+
+Complete the Auth0 sign-in when the client opens the authorization flow. The exact settings screens and supported connector options can change, so follow the current client documentation rather than using legacy SSE instructions.
+
+Multiple clients can connect to the same running HTTP server. Each client authenticates independently; no separate server process or port is required.
+
+## Background service
+
+### Linux systemd
+
+Copy and edit the included unit:
+
+```bash
+sudo cp examples/mcp-manager.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now mcp-manager
+sudo systemctl status mcp-manager --no-pager
+```
+
+The example uses systemd hardening directives. Adjust `ReadWritePaths`, `ProtectHome`, the user, paths and permissions to match the resources the MCP server genuinely needs.
+
+### macOS launchd
+
+Edit paths in `examples/com.user.mcpmanager.plist`, then:
+
+```bash
+cp examples/com.user.mcpmanager.plist ~/Library/LaunchAgents/
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.user.mcpmanager.plist
+launchctl kickstart -k gui/$(id -u)/com.user.mcpmanager
+```
+
+## Configuration
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `HOST` | `127.0.0.1` | Listen address |
+| `PORT` | `8765` | Listen port |
+| `MCP_BASE_URL` | local URL | Public OAuth base URL, without `/mcp` |
+| `MCP_WORKSPACE_DIR` | user home | Boundary for file tools and command working directory |
+| `MAX_OUTPUT_CHARS` | `64000` | Maximum returned tool-output characters |
+| `DEFAULT_CMD_TIMEOUT` | `300` | Default command timeout in seconds |
+| `MAX_CMD_TIMEOUT` | `1800` | Maximum accepted command timeout |
+| `MAX_READ_BYTES` | `5000000` | Maximum file size read by `read_file` |
+| `MAX_WRITE_BYTES` | `5000000` | Maximum content size written by `write_file` |
+| `LOG_LEVEL` | `INFO` | Python log level |
+| `ALLOW_INSECURE_NO_AUTH` | `false` | Explicit local-development authentication bypass |
+
+## Download
+
+Clone with Git:
+
+```bash
+git clone https://github.com/Abktya/universal-host-manager-mcp.git
+```
+
+Or use **Code → Download ZIP** on GitHub.
+
+## License
+
+[MIT](LICENSE)

universal_host_manager_mcp-0.1.0/SECURITY.md

@@ -0,0 +1,28 @@
+# Security policy
+
+## Important security model
+
+This server intentionally exposes arbitrary shell execution and file-writing
+capabilities. Authentication controls who can call the tools; it does not make
+shell commands safe.
+
+`MCP_WORKSPACE_DIR` constrains the built-in file tools and sets the command
+working directory. It is **not** an operating-system sandbox for `run_command`.
+A command can use absolute paths or access any resource permitted to the OS user.
+
+## Safe deployment checklist
+
+- Run the service as a dedicated, unprivileged OS user.
+- Grant that user access only to the directories and services it must manage.
+- Set `MCP_WORKSPACE_DIR` explicitly.
+- Keep Auth0 enabled on every remotely reachable deployment.
+- Bind to `127.0.0.1` behind a TLS reverse proxy or Cloudflare Tunnel.
+- Never commit `.env`, tokens, client secrets, SSH keys or tunnel credentials.
+- Do not grant passwordless unrestricted `sudo`.
+- Review logs and rotate credentials if an MCP client or account is compromised.
+- For stronger isolation, run the service inside a locked-down container or VM.
+
+## Reporting a vulnerability
+
+Please do not disclose credentials or exploitable deployment details in a public
+issue. Contact the repository owner privately through GitHub.

universal_host_manager_mcp-0.1.0/examples/com.user.mcpmanager.plist

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.user.mcpmanager</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/path/to/universal-host-manager-mcp/.venv/bin/universal-host-manager-mcp</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>/path/to/universal-host-manager-mcp</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin</string>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>/tmp/universal-host-manager-mcp.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/universal-host-manager-mcp.error.log</string>
+    <key>KeepAlive</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>

universal_host_manager_mcp-0.1.0/examples/mcp-manager.service

@@ -0,0 +1,22 @@
+[Unit]
+Description=Universal Host Manager MCP Server
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=youruser
+Group=youruser
+WorkingDirectory=/opt/universal-host-manager-mcp
+EnvironmentFile=/opt/universal-host-manager-mcp/.env
+ExecStart=/opt/universal-host-manager-mcp/.venv/bin/universal-host-manager-mcp
+Restart=on-failure
+RestartSec=5
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=/home/youruser/workspace
+
+[Install]
+WantedBy=multi-user.target

universal_host_manager_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "universal-host-manager-mcp"
+version = "0.1.0"
+description = "Cross-platform FastMCP server for authenticated remote Linux/macOS host administration"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Ahmet Baktiaya" },
+]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "chatgpt",
+    "remote-shell",
+    "devops",
+    "sysadmin",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "fastmcp>=2.13,<5",
+    "python-dotenv>=1.0,<2",
+]
+
+[project.urls]
+Homepage = "https://github.com/Abktya/universal-host-manager-mcp"
+Repository = "https://github.com/Abktya/universal-host-manager-mcp"
+Issues = "https://github.com/Abktya/universal-host-manager-mcp/issues"
+Security = "https://github.com/Abktya/universal-host-manager-mcp/blob/main/SECURITY.md"
+
+[project.scripts]
+universal-host-manager-mcp = "universal_host_manager_mcp:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/universal_host_manager_mcp"]

universal_host_manager_mcp-0.1.0/requirements.txt

@@ -0,0 +1,2 @@
+fastmcp>=2.13,<5
+python-dotenv>=1.0,<2

universal_host_manager_mcp-0.1.0/src/universal_host_manager_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Universal Host Manager MCP Server package."""
+
+from .server import main
+
+__all__ = ["main"]

universal_host_manager_mcp-0.1.0/src/universal_host_manager_mcp/server.py

@@ -0,0 +1,259 @@
+"""Universal Host Manager MCP Server.
+
+A cross-platform (Linux/macOS) FastMCP server for authenticated remote host
+administration. This server exposes powerful shell and file-management tools;
+read SECURITY.md and run it only as an unprivileged, dedicated OS user.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import signal
+import subprocess
+from functools import wraps
+from pathlib import Path
+from typing import Callable, ParamSpec, TypeVar
+
+from dotenv import load_dotenv
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.auth0 import Auth0Provider
+
+load_dotenv()
+
+logging.basicConfig(
+    level=os.getenv("LOG_LEVEL", "INFO").upper(),
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+logger = logging.getLogger("universal-host-manager")
+
+HOST = os.getenv("HOST", "127.0.0.1")
+PORT = int(os.getenv("PORT", "8765"))
+BASE_URL = os.getenv("MCP_BASE_URL", f"http://localhost:{PORT}").rstrip("/")
+WORKSPACE_ROOT = Path(os.getenv("MCP_WORKSPACE_DIR", Path.home())).expanduser().resolve()
+
+MAX_OUTPUT_CHARS = int(os.getenv("MAX_OUTPUT_CHARS", "64000"))
+DEFAULT_CMD_TIMEOUT = int(os.getenv("DEFAULT_CMD_TIMEOUT", "300"))
+MAX_CMD_TIMEOUT = int(os.getenv("MAX_CMD_TIMEOUT", "1800"))
+MAX_READ_BYTES = int(os.getenv("MAX_READ_BYTES", "5000000"))
+MAX_WRITE_BYTES = int(os.getenv("MAX_WRITE_BYTES", "5000000"))
+ALLOW_INSECURE_NO_AUTH = os.getenv("ALLOW_INSECURE_NO_AUTH", "false").lower() in {
+    "1", "true", "yes",
+}
+
+AUTH0_DOMAIN = os.getenv("AUTH0_DOMAIN")
+AUTH0_CLIENT_ID = os.getenv("AUTH0_CLIENT_ID")
+AUTH0_CLIENT_SECRET = os.getenv("AUTH0_CLIENT_SECRET")
+AUTH0_AUDIENCE = os.getenv("AUTH0_AUDIENCE")
+
+auth_values = [AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_AUDIENCE]
+if all(auth_values):
+    auth = Auth0Provider(
+        config_url=f"https://{AUTH0_DOMAIN}/.well-known/openid-configuration",
+        client_id=AUTH0_CLIENT_ID,
+        client_secret=AUTH0_CLIENT_SECRET,
+        audience=AUTH0_AUDIENCE,
+        base_url=BASE_URL,
+        allowed_client_redirect_uris=[
+            "https://claude.ai/api/mcp/auth_callback",
+            "https://claude.com/api/mcp/auth_callback",
+            "https://chatgpt.com/connector/oauth/*",
+            "https://antigravity.google/oauth-callback",
+            "http://localhost:*",
+            "http://127.0.0.1:*",
+        ],
+    )
+elif any(auth_values):
+    raise RuntimeError(
+        "Incomplete Auth0 configuration. Set AUTH0_DOMAIN, AUTH0_CLIENT_ID, "
+        "AUTH0_CLIENT_SECRET and AUTH0_AUDIENCE."
+    )
+elif ALLOW_INSECURE_NO_AUTH:
+    auth = None
+    logger.warning("Authentication is disabled by ALLOW_INSECURE_NO_AUTH=true.")
+else:
+    raise RuntimeError(
+        "Auth0 configuration is missing. Refusing to start without authentication. "
+        "For local-only development, explicitly set ALLOW_INSECURE_NO_AUTH=true."
+    )
+
+mcp = FastMCP("Universal Host Manager", auth=auth)
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def _truncate(text: str, limit: int = MAX_OUTPUT_CHARS) -> str:
+    if len(text) <= limit:
+        return text
+    half = limit // 2
+    omitted = len(text) - (half * 2)
+    return f"{text[:half]}\n\n... [truncated {omitted} chars] ...\n\n{text[-half:]}"
+
+
+def _validate_path(target_path: str) -> Path:
+    candidate = Path(target_path).expanduser()
+    if not candidate.is_absolute():
+        candidate = WORKSPACE_ROOT / candidate
+    resolved = candidate.resolve()
+    if resolved != WORKSPACE_ROOT and WORKSPACE_ROOT not in resolved.parents:
+        raise PermissionError(f"Path must be inside {WORKSPACE_ROOT}")
+    return resolved
+
+
+def _run(command: str, timeout: int = DEFAULT_CMD_TIMEOUT) -> str:
+    """Run ``command`` in a shell, killing the whole process group on timeout.
+
+    ``subprocess.run(..., shell=True)`` only terminates the immediate shell
+    process on timeout; any children it spawned (background jobs, piped
+    processes, ``nohup``'d commands, etc.) are left running. Starting the
+    shell in its own session (``start_new_session=True``) lets us send the
+    kill signal to the whole process group via ``os.killpg`` instead.
+    """
+    timeout = max(1, min(timeout, MAX_CMD_TIMEOUT))
+    process = subprocess.Popen(
+        command,
+        shell=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        cwd=WORKSPACE_ROOT,
+        errors="replace",
+        start_new_session=True,  # own process group -> can kill children too
+    )
+    try:
+        stdout, stderr = process.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        stdout, stderr = process.communicate()
+        return _truncate(
+            f"[ERROR] Command timed out after {timeout}s and was killed "
+            f"(including any child processes)\n"
+            f"--- partial output ---\n{(stdout + stderr).strip() or '(none)'}"
+        )
+    except Exception as exc:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        logger.exception("Command execution failed")
+        return f"[ERROR] Execution failed: {type(exc).__name__}: {exc}"
+
+    output = (stdout + stderr).strip() or "(no output)"
+    if process.returncode:
+        output = f"[exit={process.returncode}]\n{output}"
+    return _truncate(output)
+
+
+def safe_tool(fn: Callable[P, R]) -> Callable[P, R | str]:
+    @wraps(fn)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R | str:
+        try:
+            return fn(*args, **kwargs)
+        except Exception as exc:
+            logger.exception("Tool execution failed: %s", fn.__name__)
+            return f"[ERROR] {fn.__name__} failed: {type(exc).__name__}: {exc}"
+
+    return wrapper
+
+
+@mcp.tool()
+@safe_tool
+def run_command(command: str, timeout: int = DEFAULT_CMD_TIMEOUT) -> str:
+    """Run an arbitrary shell command with WORKSPACE_ROOT as its working directory.
+
+    Warning: the working directory is not an OS sandbox. Absolute paths, shell
+    redirection and invoked programs may access anything permitted to the server's
+    OS user.
+    """
+    logger.info("[TOOL] run_command timeout=%ss command=%r", timeout, command[:150])
+    return _run(command, timeout)
+
+
+@mcp.tool()
+@safe_tool
+def read_file(path: str) -> str:
+    """Read a text file located inside the configured workspace."""
+    target = _validate_path(path)
+    if not target.exists():
+        return f"[ERROR] File not found: {path}"
+    if not target.is_file():
+        return f"[ERROR] Not a regular file: {path}"
+    if target.stat().st_size > MAX_READ_BYTES:
+        return f"[ERROR] File exceeds MAX_READ_BYTES ({MAX_READ_BYTES})."
+
+    raw = target.read_bytes()
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        text = raw.decode("latin-1", errors="replace")
+    return _truncate(text)
+
+
+@mcp.tool()
+@safe_tool
+def write_file(path: str, content: str) -> str:
+    """Write UTF-8 text inside the configured workspace."""
+    encoded = content.encode("utf-8")
+    if len(encoded) > MAX_WRITE_BYTES:
+        return f"[ERROR] Content exceeds MAX_WRITE_BYTES ({MAX_WRITE_BYTES})."
+    target = _validate_path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8")
+    return f"Wrote {len(encoded)} bytes to {target}"
+
+
+@mcp.tool()
+@safe_tool
+def list_dir(path: str = ".") -> str:
+    """List a directory located inside the configured workspace."""
+    target = _validate_path(path)
+    if not target.exists():
+        return f"[ERROR] Path not found: {path}"
+    if not target.is_dir():
+        return f"[ERROR] Not a directory: {path}"
+    entries = sorted(item.name + ("/" if item.is_dir() else "") for item in target.iterdir())
+    return _truncate("\n".join(entries) or "(empty directory)")
+
+
+@mcp.tool()
+@safe_tool
+def system_metrics() -> str:
+    """Return disk, memory and top-process information for Linux or macOS."""
+    current_os = platform.system().lower()
+    disk = _run("df -h .")
+    if current_os == "darwin":
+        memory = _run("vm_stat | head -10")
+        processes = _run("ps -A -o %cpu,%mem,comm | sort -nr | head -n 10")
+    elif current_os == "linux":
+        memory = _run("free -h")
+        processes = _run("ps aux --sort=-%mem | head -15")
+    else:
+        return f"[ERROR] Unsupported operating system: {platform.system()}"
+
+    return (
+        f"--- DISK USAGE ---\n{disk}\n\n"
+        f"--- MEMORY STATUS ---\n{memory}\n\n"
+        f"--- TOP PROCESSES ---\n{processes}"
+    )
+
+
+def main() -> None:
+    """Entry point used by the ``universal-host-manager-mcp`` console script."""
+    logger.info(
+        "Starting Universal Host Manager on %s:%s (OS=%s, workspace=%s)",
+        HOST,
+        PORT,
+        platform.system(),
+        WORKSPACE_ROOT,
+    )
+    mcp.run(transport="streamable-http", host=HOST, port=PORT)
+
+
+if __name__ == "__main__":
+    main()