内容
# 诺马德
[中文说明](README.zh-CN.md)
诺马德是一款用于代理远程开发的本地MCP服务器。
它帮助AI编码代理与远程机器协同工作，同时在本地工作站上保留真实源代码：通过`rsync`同步代码，在SSH上运行短命令，在远程`tmux`会话中管理长时间运行的作业，诊断网络问题，并将生成的工件拉回本地项目。
任何支持MCP的代理环境，只要能启动带有命令和参数的标准输入/输出服务器，就可以与诺马德一起使用。
## 功能特点
- 每个本地项目支持多个远程工作区。
- 项目本地`.nomad.json`配置，带有通过MCP公开的模式提示。
- SSH预检和只读网络诊断。
- 增量`rsync`推送，带有`.gitignore`转换和`--delete`干预保护。
- 将远程工件拉入项目拥有的本地目录。
- 运行带有输出截断的短远程命令。
- 通过`tmux`管理长时间运行的远程任务。
- 可选的持久反向SSH隧道，用于与远程作业共享本地代理。
- 路径防护、危险命令检查和机密信息隐藏，以实现更安全的代理工作流程。
## 系统要求
- Python 3.11+
- `ssh`
- `rsync`
- 在使用长时间运行任务的远程机器上使用`tmux`
- 基于密钥的SSH访问您的远程目标
## 安装
直接使用`uvx`运行：
```bash
uvx nomad-mcp
```
或使用`pipx`将其安装为隔离的全局命令：
```bash
pipx install nomad-mcp
```
## MCP客户端配置
将诺马德用作标准输入/输出MCP服务器。确切的配置文件取决于您的客户端。
推荐的无需安装的配置：
```json
{
"mcpServers": {
"nomad": {
"command": "uvx",
"args": ["nomad-mcp"]
}
}
}
```
适用于基于TOML的客户端：
```toml
[mcp_servers.nomad]
command = "uvx"
args = ["nomad-mcp"]
startup_timeout_sec = 120
```
如果您使用`pipx`安装，请使用已安装的命令：
```json
{
"mcpServers": {
"nomad": {
"command": "nomad",
"args": []
}
}
}
```
您还可以通过以下方式打印配置片段：
```bash
nomad client-config
nomad client-config --runner nomad --format toml
```
## 快速入门
1. 在本地项目目录中打开支持MCP的代理。
2. 让它调用`init_discover`。
3. 选择SSH目标和远程工作区路径。
4. 让它使用`init_save_config`保存`.nomad.json`配置。
5. 使用`sync_push`推送代码。
6. 使用`run_remote`运行短命令。
7. 使用`task_start`运行长时间作业，然后使用`task_status`或`task_list`监控它们。
8. 使用`sync_pull`拉取远程工件。
## `.nomad.json`示例
```json
{
"project_name": "my_project",
"mode": "remote",
"default_target": "devbox",
"targets": {
"devbox": {
"description": "主要远程开发机器",
"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`使用`limits.command_timeout_seconds`。对于下载、构建、训练、模糊测试和其他缓慢工作，首选`task_start`，以便作业在远程`tmux`会话中运行，可以稍后检查。
## 工具
- `init_discover`：检查本地工作区、SSH别名和代理设置。
- `init_verify_and_probe`：验证SSH可达性并探测远程硬件/运行时。
- `init_save_config`：验证并保存`.nomad.json`。
- `init_probe_target`：刷新目标的硬件/运行时信息。
- `sync_push`：将本地代码推送到远程工作区。
- `sync_pull`：将远程文件或目录拉入本地`remote_artifacts/`。
- `run_remote`：在远程工作区运行短命令。
- `task_start`：启动长时间运行的`tmux`任务。
- `task_status`：检查一个任务并返回日志尾部。
- `task_list`：列出目标上的项目拥有的任务。
- `task_kill`：停止任务但不删除其日志。
- `net_diagnose`：运行只读SSH/网络诊断。
- `tunnel_start`、`tunnel_status`、`tunnel_stop`：管理持久反向隧道。
## 安全注意事项
诺马德可以通过SSH执行命令并使用`rsync`同步文件。请仅与受信任的本地项目和受信任的远程机器一起使用。
服务器包含防护措施，例如本地/远程路径检查、危险命令阻止、`.nomad.json`同步排除、机密信息隐藏、输出截断和`rsync --delete`干预保护。这些防护措施降低了风险，但它们并不能将不受信任的代理或远程机器变成受信任的机器。
## 开发
```bash
python -m pip install -e .[dev]
nomad --version
nomad doctor
python -m pytest
python -m compileall -q src tests
```
## 许可证
MIT
