Nomad MCP

NomadMCP

MCP服务器和CLI工具，用于使用OpenCode/CodeNomad自动执行任务，具有并行执行、git工作树和PR管理功能。

概述

NomadMCP是一个MCP（模型上下文协议）服务器和CLI工具，通过以下方式自动化编码任务：

1. 为每个任务创建独立的工作区（git工作树或分支）
2. 生成OpenCode服务器会话
3. 将任务发送给AI代理
4. 等待代理创建拉取请求
5. 轮询PR以获取审核反馈
6. 自动迭代反馈，直到合并PR
7. 完成后清理工作区

主要特点

✨ 并行任务执行 -以可配置的限制同时运行多个任务 🌳 Git工作树 -使用工作树进行真正的并行工作，没有冲突 🐳 Docker支持 -使用Docker和Docker Compose实现完全容器化 🖥️ CLI工具 -用于在CodeNomad中运行任务和查看进度的独立CLI ⚙️ 灵活的配置 -通过env变量、JSON文件或默认值进行配置 🔄 自动PR迭代 -持续处理审核反馈，直到合并

建筑

系统通过以下组件管理整个生命周期：

• Git 管理器：存储库验证、分支/工作树操作
• 进程管理器：生成和管理OpenCode服务器进程
• 客户经理：用于OpenCode API通信的HTTP客户端
• 会话管理器：管理OpenCode会话生命周期
• PR经理：GitHub公关运营通过 gh 命令行界面
• 任务编排器：协调整个工作流程
• 任务队列：使用可配置的限制管理并行执行
• CLI工具：任务执行的独立界面

需求

• python：3.10或更高
• OpenCode命令行界面：安装 npm install -g @opencode/cli
• GitHub 命令行界面：安装 brew install gh （macOS）或查看
• Git仓库：工作目录必须是git存储库
• GitHub身份验证：运行 gh auth login 鉴定

安装

选项1：标准安装

1. 克隆存储库：

git clone https://github.com/doryashar/NomadMCP.git
cd NomadMCP

1. 运行安装脚本：

./install.sh

或手动安装：

pip install -r requirements.txt

1. 安装CLI工具（可选）：

pip install -e .

选项2：Docker安装

docker-compose build
docker-compose up -d

看 了解详细的Docker说明。

配置

通过环境变量进行配置或 config.json:

# Parallel execution
export NOMAD_MCP_MAX_PARALLEL_TASKS=5

# Use git worktrees (recommended for parallel tasks)
export NOMAD_MCP_USE_WORKTREES=true

# Task settings
export NOMAD_MCP_DEFAULT_TIMEOUT=60
export NOMAD_MCP_BRANCH_PREFIX=task

# Logging
export NOMAD_MCP_LOG_LEVEL=INFO

或创建 config.json （参见 config.example.json)

用法

选项1:MCP服务器（通过克劳德代码）

在Claude Code设置中配置MCP服务器：

{
  "mcpServers": {
    "nomad-mcp": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/NomadMCP"
    }
  }
}

然后使用 execute_task 工具：

参数：

• task_description （string，必填）：要完成的任务的描述
• working_directory （string，可选）：git存储库的绝对路径（默认为当前目录）
• branch_name （字符串，可选）：自定义分支名称（如果未提供，则自动生成）
• timeout_minutes （数字，可选）：等待PR合并的最长时间（默认值：60）

选项2:CLI工具（独立）

直接从命令行运行任务：

# Single task
nomad-cli -d "Add dark mode toggle to settings"

# Multiple tasks in parallel
nomad-cli -d "Add dark mode" -d "Fix login bug" -d "Update docs"

# Tasks from JSON file
nomad-cli --tasks-file tasks.json

# Specify working directory
nomad-cli -d "Add feature" --dir /path/to/repo

# Don't open CodeNomad GUI
nomad-cli -d "Add feature" --no-gui

任务文件格式 (tasks.json):

[
  {
    "id": "task-1",
    "description": "Add dark mode toggle",
    "branch_name": "feature/dark-mode",
    "timeout_minutes": 60
  },
  {
    "id": "task-2",
    "description": "Fix authentication bug",
    "working_directory": "/path/to/other/repo"
  }
]

CLI会自动执行以下操作：

• 打开CodeNomad GUI以显示所有活动会话
• 列出手动连接的服务器端口
• 并行运行任务（遵守max_paralog_tasks配置）
• 以JSON格式输出结果（带 --output 旗帜）

例子：

Use the execute_task tool to add a new feature to my project:

Task: "Add a dark mode toggle to the settings page with persistence"
Working Directory: /Users/username/projects/my-app
Branch Name: feature/dark-mode

工作流程：

1. ✓ 验证目录是否为git存储库
2. ✓ 创建分支 feature/dark-mode
3. ✓ 启动该目录中的OpenCode服务器
4. ✓ 创建新会话
5. ✓ 向AI代理发送任务提示
6. ✓ Agent实现该功能并创建PR
7. ✓ 监控PR的合并或审查意见
8. ✓ 如果存在评论，请将其发送回代理
9. ✓ 代理处理反馈并更新PR
10. ✓ 重复步骤7-9，直到合并PR
11. ✓ 删除分支并清理会话

运作原理

任务执行流程

User → MCP Tool/CLI → Task Queue → Task Orchestrator
  ↓
  1. Git validation (error if not a repo)
  2. Create worktree (or branch if worktrees disabled)
  3. Spawn OpenCode server in worktree directory
  4. Create session via API
  5. Send task prompt
  ↓
  6. Poll for PR creation (check messages)
  7. Extract PR URL and number
  ↓
  8. Poll PR status every 30s
  ↓
  9. If merged:
     - Remove worktree/delete branch
     - Close session
     - Kill server
     - Return success
  ↓
  10. If review comments:
      - Format comments
      - Send to session
      - Wait for agent to update PR
      - Go to step 8
  ↓
  11. If timeout:
      - Return timeout status
      - Leave PR open for manual review

并行执行和Git工作树

为什么选择Worktrees？

在同一存储库上并行运行多个任务时，传统分支可能会导致冲突：

• 无法同时结账不同的分行
• 一个任务的文件更改会影响其他任务
• 代理可能会覆盖彼此的工作

Git工作树 通过创建单独的工作目录来解决这个问题：

repo/
├── .git/
├── main-code/          # Main worktree
└── .git/worktrees_nomad/
    ├── task_abc123/    # Task 1's isolated workspace
    └── task_def456/    # Task 2's isolated workspace

每台工作台：

• 有自己的分行结账了吗
• 具有完全独立的文件
• 可以同时进行
• 共享同一个git数据库

配置：

# Enable worktrees (default: true)
export NOMAD_MCP_USE_WORKTREES=true

# Set max parallel tasks
export NOMAD_MCP_MAX_PARALLEL_TASKS=5

何时改用分支：

• 单任务执行
• 顺序工作流
• 更简单的心智模型
• 集 NOMAD_MCP_USE_WORKTREES=false

OpenCode与CodeNomad

OpenCode 是执行AI编码工作的底层CLI/服务器：

• 运行为 opencode serve
• 公开HTTP API
• 管理会话和消息

Codenomad 是一个桌面GUI（Electron应用程序），它：

• 生成OpenCode服务器
• 提供可视化界面
• 管理多个实例

NomadMCP 执行与CodeNomad相同的操作，但采用编程方式：

• 直接生成OpenCode服务器
• 通过HTTP API连接
• 无需GUI
• 自动化的理想选择

在CodeNomad中查看会话

由于NomadMCP直接生成OpenCode服务器，您可以将CodeNomad连接到这些服务器以查看会话：

1. 使用NomadMCP启动一个任务（这会在随机端口上生成一个OpenCode服务器）
2. 打开CodeNomad桌面应用程序
3. 添加指向的新实例 `http://localhost:

`

1. 实时查看会话

服务器启动时，端口会显示在日志中。

项目结构

NomadMCP/
├── src/
│   ├── __init__.py           # Package init
│   ├── __main__.py           # Entry point
│   ├── server.py             # MCP server implementation
│   ├── types.py              # Data models and types
│   ├── git_manager.py        # Git operations
│   ├── process_manager.py    # OpenCode process management
│   ├── client_manager.py     # OpenCode API client
│   ├── session_manager.py    # Session lifecycle
│   ├── pr_manager.py         # GitHub PR operations
│   └── task_orchestrator.py  # Main orchestration logic
├── pyproject.toml            # Project metadata
├── requirements.txt          # Python dependencies
└── README.md                 # This file

错误处理

服务器处理各种错误情况：

• 不是git仓库：立即返回错误
• 分支存在：返回错误以避免冲突
• 未安装OpenCode：清除带有安装说明的错误消息
• GitHub CLI未通过身份验证：身份验证指令错误
• 服务器生成失败：清理和详细错误
• 会话创建失败：清理并重试逻辑
• PR超时：返回超时状态，保持PR打开
• 服务器崩溃：检测和优雅的清理

发展

运行测试

pytest

代码格式化

black src/
ruff check src/

局限性

• 需要手动GitHub身份验证(gh auth login)
• PR轮询间隔固定为30秒
• 每个OpenCode服务器实例一个任务
• 无持久性-如果MCP服务器重新启动，活动任务将丢失

未来的增强功能

• \[\]在重启过程中持续跟踪任务
• \[\]具有资源限制的并行任务执行
• \[\]可配置的轮询间隔
• \[\]支持其他git托管平台（GitLab、Bitbucket）
• \[\]WebSocket支持实时更新
• \[\]任务队列管理
• \[\]与CodeNomad的桌面应用程序集成，实现自动实例注册

许可证

麻省理工学院

贡献

欢迎投稿！请打开问题或提交拉取请求。

支持

对于问题或疑问，请在GitHub上打开问题。