nomad-mcp 0.1.0__tar.gz

nomad_mcp-0.1.0/LICENSE

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

nomad_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: nomad-mcp
+Version: 0.1.0
+Summary: Local MCP Server to manage remote development execution, sync, and tasks.
+Author: Tsunam1
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+# nomad
+
+[中文说明](README.zh-CN.md)
+
+nomad is a local MCP server for agentic remote development.
+
+It helps an AI coding agent work with a remote machine while keeping the source
+of truth on your local workstation: sync code with `rsync`, run short commands
+over SSH, manage long-running jobs in remote `tmux` sessions, diagnose network
+issues, and pull generated artifacts back into the local project.
+
+nomad is not tied to a specific MCP client. Any agent environment that can start
+a stdio MCP server with a command and arguments can use it.
+
+## Features
+
+- Multi-target remote workspaces per local project.
+- Project-local `.nomad.json` configuration with schema hints exposed through MCP.
+- SSH preflight checks and read-only network diagnostics.
+- Incremental `rsync` push with `.gitignore` conversion and `--delete` dry-run protection.
+- Remote artifact pull into project-owned local directories.
+- Short remote command execution with output truncation.
+- Long-running remote task management through `tmux`.
+- Optional persistent reverse SSH tunnel for sharing a local proxy with remote jobs.
+- Path guards, dangerous-command checks, and secret redaction for safer agent workflows.
+
+## Requirements
+
+- Python 3.11+
+- `ssh`
+- `rsync`
+- `tmux` on remote machines when using long-running tasks
+- Key-based SSH access to your remote targets
+
+## Installation
+
+Run directly with `uvx`:
+
+```bash
+uvx nomad-mcp
+```
+
+Or install it as an isolated global command with `pipx`:
+
+```bash
+pipx install nomad-mcp
+```
+
+## MCP Client Configuration
+
+Use nomad as a stdio MCP server. The exact config file depends on your client.
+
+Recommended no-install configuration:
+
+```json
+{
+  "mcpServers": {
+    "nomad": {
+      "command": "uvx",
+      "args": ["nomad-mcp"]
+    }
+  }
+}
+```
+
+For TOML-based clients:
+
+```toml
+[mcp_servers.nomad]
+command = "uvx"
+args = ["nomad-mcp"]
+startup_timeout_sec = 120
+```
+
+If you installed with `pipx`, use the installed command instead:
+
+```json
+{
+  "mcpServers": {
+    "nomad": {
+      "command": "nomad",
+      "args": []
+    }
+  }
+}
+```
+
+You can also print config snippets with:
+
+```bash
+nomad client-config
+nomad client-config --runner nomad --format toml
+```
+
+## Quick Start
+
+1. Open an MCP-enabled agent in your local project directory.
+2. Ask it to call `init_discover`.
+3. Choose an SSH target and remote workspace path.
+4. Ask it to save a `.nomad.json` config with `init_save_config`.
+5. Push code with `sync_push`.
+6. Run short commands with `run_remote`.
+7. Run long jobs with `task_start`, then monitor them with `task_status` or `task_list`.
+8. Pull remote artifacts with `sync_pull`.
+
+## Example `.nomad.json`
+
+```json
+{
+  "project_name": "my_project",
+  "mode": "remote",
+  "default_target": "devbox",
+  "targets": {
+    "devbox": {
+      "description": "Primary remote development machine",
+      "ssh_host": "devbox",
+      "remote_path": "/data/my_project",
+      "local_subpath": null,
+      "auto_create_remote_path": true,
+      "network": {
+        "use_proxy_for_ssh": false,
+        "jump_host": null,
+        "reverse_tunnel": {
+          "enabled": false,
+          "proxy_scheme": "socks5"
+        }
+      },
+      "sync": {
+        "respect_gitignore": true,
+        "extra_excludes": []
+      },
+      "runtime": {
+        "interpreter": null,
+        "extra_env": {}
+      },
+      "limits": {
+        "command_timeout_seconds": 60,
+        "max_output_lines": 200,
+        "max_output_bytes": 10240
+      }
+    }
+  }
+}
+```
+
+`run_remote` uses `limits.command_timeout_seconds`. For downloads, builds,
+training, fuzzing, and other slow work, prefer `task_start` so the job runs in a
+remote tmux session and can be checked later.
+
+## Tools
+
+- `init_discover`: inspect the local workspace, SSH aliases, and proxy settings.
+- `init_verify_and_probe`: verify SSH reachability and probe remote hardware/runtimes.
+- `init_save_config`: validate and save `.nomad.json`.
+- `init_probe_target`: refresh hardware/runtime information for a target.
+- `sync_push`: push local code to the remote workspace.
+- `sync_pull`: pull a remote file or directory into local `remote_artifacts/`.
+- `run_remote`: run a short command in the remote workspace.
+- `task_start`: start a long-running tmux task.
+- `task_status`: inspect one task and return a log tail.
+- `task_list`: list project-owned tasks across targets.
+- `task_kill`: stop a task without deleting its logs.
+- `net_diagnose`: run read-only SSH/network diagnostics.
+- `tunnel_start`, `tunnel_status`, `tunnel_stop`: manage persistent reverse tunnels.
+
+## Safety Notes
+
+nomad can execute commands over SSH and synchronize files with `rsync`. Use it
+only with trusted local projects and trusted remote machines.
+
+The server includes guardrails such as local/remote path checks, dangerous-command
+blocking, `.nomad.json` sync exclusion, secret redaction, output truncation, and
+`rsync --delete` dry-run protection. These guardrails reduce risk, but they do not
+turn an untrusted agent or remote machine into a trusted one.
+
+## Development
+
+```bash
+python -m pip install -e .[dev]
+nomad --version
+nomad doctor
+python -m pytest
+python -m compileall -q src tests
+```
+
+## License
+
+MIT

nomad_mcp-0.1.0/README.md

@@ -0,0 +1,188 @@
+# nomad
+
+[中文说明](README.zh-CN.md)
+
+nomad is a local MCP server for agentic remote development.
+
+It helps an AI coding agent work with a remote machine while keeping the source
+of truth on your local workstation: sync code with `rsync`, run short commands
+over SSH, manage long-running jobs in remote `tmux` sessions, diagnose network
+issues, and pull generated artifacts back into the local project.
+
+nomad is not tied to a specific MCP client. Any agent environment that can start
+a stdio MCP server with a command and arguments can use it.
+
+## Features
+
+- Multi-target remote workspaces per local project.
+- Project-local `.nomad.json` configuration with schema hints exposed through MCP.
+- SSH preflight checks and read-only network diagnostics.
+- Incremental `rsync` push with `.gitignore` conversion and `--delete` dry-run protection.
+- Remote artifact pull into project-owned local directories.
+- Short remote command execution with output truncation.
+- Long-running remote task management through `tmux`.
+- Optional persistent reverse SSH tunnel for sharing a local proxy with remote jobs.
+- Path guards, dangerous-command checks, and secret redaction for safer agent workflows.
+
+## Requirements
+
+- Python 3.11+
+- `ssh`
+- `rsync`
+- `tmux` on remote machines when using long-running tasks
+- Key-based SSH access to your remote targets
+
+## Installation
+
+Run directly with `uvx`:
+
+```bash
+uvx nomad-mcp
+```
+
+Or install it as an isolated global command with `pipx`:
+
+```bash
+pipx install nomad-mcp
+```
+
+## MCP Client Configuration
+
+Use nomad as a stdio MCP server. The exact config file depends on your client.
+
+Recommended no-install configuration:
+
+```json
+{
+  "mcpServers": {
+    "nomad": {
+      "command": "uvx",
+      "args": ["nomad-mcp"]
+    }
+  }
+}
+```
+
+For TOML-based clients:
+
+```toml
+[mcp_servers.nomad]
+command = "uvx"
+args = ["nomad-mcp"]
+startup_timeout_sec = 120
+```
+
+If you installed with `pipx`, use the installed command instead:
+
+```json
+{
+  "mcpServers": {
+    "nomad": {
+      "command": "nomad",
+      "args": []
+    }
+  }
+}
+```
+
+You can also print config snippets with:
+
+```bash
+nomad client-config
+nomad client-config --runner nomad --format toml
+```
+
+## Quick Start
+
+1. Open an MCP-enabled agent in your local project directory.
+2. Ask it to call `init_discover`.
+3. Choose an SSH target and remote workspace path.
+4. Ask it to save a `.nomad.json` config with `init_save_config`.
+5. Push code with `sync_push`.
+6. Run short commands with `run_remote`.
+7. Run long jobs with `task_start`, then monitor them with `task_status` or `task_list`.
+8. Pull remote artifacts with `sync_pull`.
+
+## Example `.nomad.json`
+
+```json
+{
+  "project_name": "my_project",
+  "mode": "remote",
+  "default_target": "devbox",
+  "targets": {
+    "devbox": {
+      "description": "Primary remote development machine",
+      "ssh_host": "devbox",
+      "remote_path": "/data/my_project",
+      "local_subpath": null,
+      "auto_create_remote_path": true,
+      "network": {
+        "use_proxy_for_ssh": false,
+        "jump_host": null,
+        "reverse_tunnel": {
+          "enabled": false,
+          "proxy_scheme": "socks5"
+        }
+      },
+      "sync": {
+        "respect_gitignore": true,
+        "extra_excludes": []
+      },
+      "runtime": {
+        "interpreter": null,
+        "extra_env": {}
+      },
+      "limits": {
+        "command_timeout_seconds": 60,
+        "max_output_lines": 200,
+        "max_output_bytes": 10240
+      }
+    }
+  }
+}
+```
+
+`run_remote` uses `limits.command_timeout_seconds`. For downloads, builds,
+training, fuzzing, and other slow work, prefer `task_start` so the job runs in a
+remote tmux session and can be checked later.
+
+## Tools
+
+- `init_discover`: inspect the local workspace, SSH aliases, and proxy settings.
+- `init_verify_and_probe`: verify SSH reachability and probe remote hardware/runtimes.
+- `init_save_config`: validate and save `.nomad.json`.
+- `init_probe_target`: refresh hardware/runtime information for a target.
+- `sync_push`: push local code to the remote workspace.
+- `sync_pull`: pull a remote file or directory into local `remote_artifacts/`.
+- `run_remote`: run a short command in the remote workspace.
+- `task_start`: start a long-running tmux task.
+- `task_status`: inspect one task and return a log tail.
+- `task_list`: list project-owned tasks across targets.
+- `task_kill`: stop a task without deleting its logs.
+- `net_diagnose`: run read-only SSH/network diagnostics.
+- `tunnel_start`, `tunnel_status`, `tunnel_stop`: manage persistent reverse tunnels.
+
+## Safety Notes
+
+nomad can execute commands over SSH and synchronize files with `rsync`. Use it
+only with trusted local projects and trusted remote machines.
+
+The server includes guardrails such as local/remote path checks, dangerous-command
+blocking, `.nomad.json` sync exclusion, secret redaction, output truncation, and
+`rsync --delete` dry-run protection. These guardrails reduce risk, but they do not
+turn an untrusted agent or remote machine into a trusted one.
+
+## Development
+
+```bash
+python -m pip install -e .[dev]
+nomad --version
+nomad doctor
+python -m pytest
+python -m compileall -q src tests
+```
+
+## License
+
+MIT

nomad_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nomad-mcp"
+version = "0.1.0"
+description = "Local MCP Server to manage remote development execution, sync, and tasks."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Tsunam1" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "mcp>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-mock>=3.0.0",
+]
+
+[project.scripts]
+nomad = "nomad.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.setuptools.packages.find]
+where = ["src"]

nomad_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nomad_mcp-0.1.0/src/nomad/__init__.py

@@ -0,0 +1,2 @@
+# nomad package
+__version__ = "0.1.0"

nomad_mcp-0.1.0/src/nomad/cli.py

@@ -0,0 +1,124 @@
+"""
+Command line entry point for nomad.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from importlib.util import find_spec
+
+from nomad import __version__
+from nomad.schema import get_config_schema_hints
+
+
+PACKAGE_NAME = "nomad-mcp"
+
+
+def main(argv: list[str] | None = None) -> int | None:
+    """Runs helper CLI commands, or starts the MCP server when no args are given."""
+    args_list = list(sys.argv[1:] if argv is None else argv)
+    if not args_list:
+        from nomad.server import main as server_main
+
+        server_main()
+        return None
+
+    parser = _build_parser()
+    args = parser.parse_args(args_list)
+
+    if args.version:
+        print(__version__)
+        return 0
+
+    if args.command == "doctor":
+        return _doctor()
+    if args.command == "schema":
+        print(json.dumps(get_config_schema_hints(), indent=2))
+        return 0
+    if args.command == "client-config":
+        print(_client_config(args.runner, args.format))
+        return 0
+
+    parser.print_help()
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nomad",
+        description="Local MCP server for agentic remote development.",
+    )
+    parser.add_argument("--version", action="store_true", help="Print nomad version.")
+
+    subparsers = parser.add_subparsers(dest="command")
+    subparsers.add_parser("doctor", help="Check local runtime dependencies.")
+    subparsers.add_parser("schema", help="Print .nomad.json schema hints as JSON.")
+
+    config_parser = subparsers.add_parser(
+        "client-config", help="Print an MCP client configuration snippet."
+    )
+    config_parser.add_argument(
+        "--runner",
+        choices=("uvx", "nomad"),
+        default="uvx",
+        help="Use uvx package execution or an already-installed nomad command.",
+    )
+    config_parser.add_argument(
+        "--format",
+        choices=("json", "toml"),
+        default="json",
+        help="Output config format.",
+    )
+    return parser
+
+
+def _doctor() -> int:
+    checks = [
+        ("python>=3.11", sys.version_info >= (3, 11), sys.version.split()[0]),
+        ("mcp package", find_spec("mcp") is not None, "import mcp"),
+        ("ssh", shutil.which("ssh") is not None, shutil.which("ssh") or "missing"),
+        ("rsync", shutil.which("rsync") is not None, shutil.which("rsync") or "missing"),
+    ]
+    ok = True
+    for name, passed, detail in checks:
+        ok = ok and passed
+        mark = "ok" if passed else "missing"
+        print(f"{mark:7} {name}: {detail}")
+    print("note    remote tmux is required only when using task_start/task_status.")
+    return 0 if ok else 1
+
+
+def _client_config(runner: str, output_format: str) -> str:
+    if runner == "uvx":
+        command = "uvx"
+        args = [PACKAGE_NAME]
+    else:
+        command = "nomad"
+        args = []
+
+    if output_format == "toml":
+        rendered_args = ", ".join(json.dumps(arg) for arg in args)
+        return (
+            "[mcp_servers.nomad]\n"
+            f"command = {json.dumps(command)}\n"
+            f"args = [{rendered_args}]\n"
+            "startup_timeout_sec = 120"
+        )
+
+    return json.dumps(
+        {
+            "mcpServers": {
+                "nomad": {
+                    "command": command,
+                    "args": args,
+                }
+            }
+        },
+        indent=2,
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())