jules-mcp-server

# 朱尔斯 MCP 服务器 一个**纯标准库 Python MCP 服务器**，它公开了 [Google 朱尔斯](https://jules.google) 自动编码代理作为 **10 个原生 MCP 工具**，因此任何支持 MCP 的代理主机（Hermes Agent、Claude Desktop、Claude Code、n8n、自定义客户端）都可以创建朱尔斯编码会话、控制其计划、跟踪进度并发布/合并生成的拉取请求 — 完全自动化。 **零外部依赖。** 无需 `pip install` — 服务器使用仅 `json` + `urllib` 的 MCP stdio 协议（Content-Length 分帧 JSON-RPC）。这很重要，因为官方 `mcp` Python SDK 依赖于 `pydantic-core`（Rust），它在 Python 3.14.x 上无法构建。此服务器可在任何 Python 3.8+ 上运行。 --- ## 目录 - [什么是朱尔斯？](#what-is-jules) - [架构](#architecture) - [10 个工具](#the-10-tools) - [实际工作流程（编排循环）](#actual-workflow-the-orchestration-loop) - [设置](#setup) - [步骤 1 — 先决条件](#step-1--prerequisites) - [步骤 2 — 获取朱尔斯 API 密钥](#step-2--get-a-jules-api-key) - [步骤 3 — 配置凭证](#step-3--configure-credentials) - [步骤 4 — 在 MCP 客户端中注册服务器](#step-4--register-the-server-in-your-mcp-client) - [步骤 5 — 验证](#step-5--verify) - [HTTP 流式桥接（n8n 和 HTTP 客户端）](#http-streamable-bridge-n8n--http-clients) - [朱尔斯编排器技能](#the-jules-orchestrator-skill) - [会话状态](#session-states) - [存储库布局](#repo-layout) - [故障排除](#troubleshooting) - [注意事项](#caveats) - [许可证](#license) --- ## 什么是朱尔斯？ [朱尔斯](https://jules.google) 是谷歌的异步编码代理。你指向它一个 GitHub 仓库和一个任务提示；它克隆仓库到一个云 VM，提出计划，编写代码，并打开一个拉取请求。谷歌通过 `https://jules.googleapis.com/v1alpha` 的 REST API 公开它，包含三种资源类型： | 资源 | 含义 | |----------|---------| | **源** | 连接到您的朱尔斯账户的 GitHub 仓库，例如 `sources/github/owner/repo` | | **会话** | 一个工作单元（`prompt` + `sourceContext`）；可以自动打开一个 PR 并自动批准计划 | | **活动** | 会话中的计划/进度/问题/完成事件 | 该服务器包装了该 API，以便您的代理可以使用工具调用驱动朱尔斯，而不是您点击 Web UI。 ## 架构 ``` ┌─────────────────────┐ stdio (JSON-RPC, ┌──────────────────────┐ HTTPS (X-Goog-Api-Key) ┌─────────────────────┐ │ MCP 客户端/代理 │ 内容长度 │ jules_mcp_server.py │ ─────────────────────────► │ 朱尔斯 REST API │ │ （Hermes、Claude、 │ ◄───帧─────────► │ （纯标准库） │ │ v1alpha │ │ 自定义主机,...） │ │ │ HTTPS (Bearer PAT) ├─────────────────────┤ └─────────────────────┘ │ 10 个 jules_* 工具 │ ─────────────────────────► │ GitHub REST API │ └──────────────────────┘ （仅 jules_publish_pr） │ （PR 合并） │ ┌─────────────────────┐ HTTP 流式 ▲ └─────────────────────┘ │ n8n MCP 客户端工具 │ POST /mcp ┌─────────┴────────────┐ │ （或任何 HTTP 主机） │ ◄──────────────────► │ jules_mcp_http_bridge│ └─────────────────────┘ │ （包装相同的 handle()）│ └──────────────────────┘ ``` - **`jules_mcp_server.py`** — stdio MCP 服务器。处理 `initialize` / `tools/list` / `tools/call`，将每个工具映射到朱尔斯 REST 调用。错误始终作为 `isError: true` 工具结果返回 — 进程永远不会因错误调用而崩溃。 - **`jules_mcp_http_bridge.py`** — 可选的 HTTP 流式传输包装器，适用于使用 HTTP 而不是 stdio 的客户端（n8n 内置的 MCP 客户端工具，远程主机）。 - **GitHub 集成** — `jules_publish_pr` 直接通过 GitHub REST API 合并朱尔斯的 PR，无需额外的 GitHub MCP 服务器。 ## 10 个工具 | # | 工具 | REST 映射 | 功能 | |---|------|--------------|--------------| | 1 | `jules_list_sources` | `GET /sources` | 列出连接到您的朱尔斯账户的 GitHub 仓库。返回诸如 `sources/github/owner/repo` 的源名称 — `jules_create_session` 需要。 | | 2 | `jules_create_session` | `POST /sessions` | 创建 **并** 分配一个编码会话：提示 + 源（+ 可选 `starting_branch`、`title`）。默认值：`automationMode=AUTO_CREATE_PR`，`requirePlanApproval=false`（完全自主）。设置 `require_plan_approval=true` 以控制计划。 | | 3 | `jules_list_sessions` | `GET /sessions` | 列出您的会话，最近的优先（`page_size`，默认为 10）。 | | 4 | `jules_get_session` | `GET /sessions/{id}` | 一个会话的完整状态 — 包括 `outputs[].pullRequest.url` 一旦朱尔斯完成。 | | 5 | `jules_approve_plan` | `POST /sessions/{id}:approvePlan` | 批准待定的计划（仅当会话创建时需要 `require_plan_approval=true`）。 | | 6 | `jules_send_message` | `POST /sessions/{id}:sendMessage` | 发送后续提示：回答朱尔斯的澄清问题，发送修复指令。 | | 7 | `jules_list_activities` | `GET /sessions/{id}/activities` | 会话的事件日志 — 计划、进度更新、问题、完成。轮询此以跟踪状态。 | | 8 | `jules_get_plan` | *(包装器)* | 读取活动，找到最新的 `planGenerated` 事件，并返回计划为 **可读文本** （计划 ID + 编号步骤，含标题/描述）。朱尔斯 API 没有计划读取端点 — 此工具合成一个。 | | 9 | `jules_update_plan` | *(包装器)* | 请求计划更改。API 没有计划编辑端点 — 此工具读取当前计划以获取上下文，格式化您的 `feedback` 为结构化更正消息，并通过 `sendMessage` 发送。朱尔斯重新生成计划；轮询 `jules_get_plan` 以查看修订。 | | 10 | `jules_publish_pr` | *(包装器 → GitHub API)* | “接受朱尔斯的 PR” 操作：从会话的输出中读取 PR URL，解析 `owner/repo/pull/N`，并通过 `PUT /repos/{owner}/{repo}/pulls/{n}/merge` 合并（默认 `squash`；也可 `merge` / `rebase`，可选 `commit_title`）。 | ### 工具参数快速参考 ```jsonc jules_create_session { "prompt": "修复登录错误并添加测试", // 必需 "source": "sources/github/owner/repo", // 必需 — 包括 `sources/` 前缀的全 ID！ "starting_branch": "main", // 可选，默认为 "main" "automation_mode": "AUTO_CREATE_PR", // 可选，默认为 AUTO_CREATE_PR "require_plan_approval": true, // 可选，默认为 false "title": "登录错误修复" // 可选 } jules_update_plan { "session_id": "1234567890", "feedback": "删除步骤 3（CSS 更改）— 超出范围。添加一个步骤来为身份验证处理程序编写测试。" } jules_publish_pr { "session_id": "1234567890", "merge_method": "squash", // "merge" | "squash" | "rebase" "commit_title": "feat: 登录修复" // 可选 } ``` > ⚠️ **常见错误：** `source` 参数必须是 `jules_list_sources` 返回的 **完整** ID，**包括 `sources/` 前缀** （`sources/github/owner/repo`）。传递 `github/owner/repo` 会导致 `INVALID_ARGUMENT` 错误。 ## 实际工作流程（编排循环） 有两种方法可以通过此服务器运行朱尔斯： ### 模式 A — 完全自主（“发射并忘记”） ``` jules_list_sources → jules_create_session { prompt, source } # 默认值：自动批准计划，自动创建 PR → 轮询 jules_get_session / jules_list_activities # 直到状态 = COMPLETED → jules_get_session # 读取 outputs[].pullRequest.url → 自身审查 PR → jules_publish_pr { session_id } # 合并它 ``` 朱尔斯计划、编码并打开 PR，零交互。适用于小范围、定义良好的任务。 ### 模式 B — 受控（推荐，编排器技能使用） ``` 1. 范围 编写一个封闭的规格：目标、涉及的文件、超出范围、可检查的验收标准。 2. 创建 jules_create_session { prompt: <规格>, source, require_plan_approval: true } 3. 控制 等待状态 AWAITING_PLAN_APPROVAL，然后： jules_get_plan { session_id } # 读取计划 ├─ 计划匹配规格 → jules_approve_plan └─ 计划漂移 → jules_update_plan { feedback } → 重新读取 → 批准 4. 等待 轮询 jules_get_session（状态）+ jules_list_activities（事件）。 如果朱尔斯提出澄清问题 → jules_send_message 回答。 5. PR 完成时，PR 存在（AUTO_CREATE_PR）。从 jules_get_session 获取其 URL。 6. 审查 自身阅读差异（gh pr diff / GitHub MCP）。记录具体发现。 7. 决定 清洁 → 步骤 8。问题 → 步骤 9。 8. 发布 jules_publish_pr { session_id } # squash-merge 9. 迭代 jules_send_message { fix-it prompt with file:line findings } → 回到 4。 10. 停止 在迭代上限（默认为 4）、 recurring issues 或 Jules 无法做出的决定。 ``` 完整的攻略 — 包括角色分工（编排器审查，朱尔斯实现）、提示模板、代码审查标准和每个任务的状态文件 — 位于捆绑的 [`skills/jules-orchestrator/`](skills/jules-orchestrator/) 技能中。 ## 设置 ### 步骤 1 — 先决条件 1. **Python 3.8+** (`python3 --version`). 无需安装包。 2. **朱尔斯账户** — 在 [jules.google.com](https://jules.google.com) 使用您的谷歌账户登录。 3. **安装朱尔斯 GitHub 应用** 并在朱尔斯 Web UI 中连接您的仓库。**API 无法使用仓库，直到 GitHub 应用安装在其中** — 必须在浏览器中完成此操作。 4. *(仅限 `jules_publish_pr`)* **GitHub 个人访问令牌**，具有 `repo` 作用域，以便服务器可以合并 PR。 ### 步骤 2 — 获取朱尔斯 API 密钥 1. 前往 **[jules.google.com/settings#api](https://jules.google.com/settings#api)**。 2. 创建 API 密钥（每个账户最多 3 个密钥）。 3. 复制它 — 您将在下一步中存储它。 ### 步骤 3 — 配置凭证 服务器首先读取 **环境变量**，然后回落到 env 文件（默认为 `~/.hermes/.env`，覆盖 `JULES_ENV_FILE`）。 ```bash # 选项 A：env 文件（默认位置） mkdir -p ~/.hermes cat >> ~/.hermes/.env <<'EOF' JULES_API_KEY=your_jules_api_key_here GITHUB_TOKEN=github_pat_xxx # 仅需用于 jules_publish_pr EOF chmod 600 ~/.hermes/.env # 选项 B：纯环境变量（在 MCP 客户端配置中设置） export JULES_API_KEY=your_jules_api_key_here export GITHUB_TOKEN=github_pat_xxx ``` GitHub 令牌解析顺序，用于 `jules_publish_pr`： `GITHUB_TOKEN` 环境变量 → `GITHUB_PERSONAL_ACCESS_TOKEN` 环境变量 → env 文件（任一名称）→ `mcp_servers.github.env.GITHUB_PERSONAL_ACCESS_TOKEN` 在 `~/.hermes/config.yaml`（如果您已经在 Hermes 下运行 GitHub MCP 服务器，则自动重用 PAT`在 `~/.hermes/config.yaml`中（因此，如果您已经运行 Hermes 下的 GitHub MCP 服务器，则 PAT 会自动重用）。 ### 步骤 4 — 在 MCP 客户端中注册服务器 首先将仓库克隆到一个稳定的位置： ```bash git clone https://github.com/Rahul7562/jules-mcp-server.git cd jules-mcp-server ``` **Hermes Agent** (`~/.hermes/config.yaml`): ```yaml mcp_servers: jules: command: python3 args: - /绝对路径/jules-mcp-server/jules_mcp_server.py ``` 重启 Hermes；`jules_*` 工具将出现在代理的工具集中。 **Claude Desktop** (`claude_desktop_config.json` — macOS: `~/Library/Application Support/Claude/`，Windows: `%APPDATA%\Claude\`): ```json { "mcpServers": { "jules": { "command": "python3", "args": ["/绝对路径/jules-mcp-server/jules_mcp_server.py"], "env": { "JULES_API_KEY": "your_key", "GITHUB_TOKEN": "github_pat_xxx" } } } } ``` **Claude Code**: ```bash claude mcp add jules -e JULES_API_KEY=your_key -e GITHUB_TOKEN=github_pat_xxx \ -- python3 /绝对路径/jules-mcp-server/jules_mcp_server.py ``` **任何其他 stdio MCP 客户端** — 以 `python3 jules_mcp_server.py` 作为服务器命令运行；它实现了 `2024-11-05` 版本的协议，包含 `tools` 功能。 ### 步骤 5 — 验证 运行捆绑的烟雾测试（不需要 **API 密钥** — 它验证协议层和干净的错误路径）： ```bash python3 test_jules_mcp.py ``` 预期输出以以下内容结尾： ``` TOOLS/LIST -> 10 tools: - jules_list_sources - jules_create_session ... RESULT: PASS — 10 tools incl jules_publish_pr ``` 然后从您的代理执行实时端到端检查：调用 `jules_list_sources`. 如果它打印您的连接的 GitHub 仓库，则整个链（密钥 → 环境变量 → 配置 → 服务器 → 实时 API）已证明有效。 ## HTTP 流式桥接（n8n 和 HTTP 客户端） 一些主机（特别是 **n8n 内置的 MCP 客户端工具**，它使用官方的 `@modelcontextprotocol/sdk`）通过 HTTP 而不是 stdio 进行 MCP 操作。`jules_mcp_http_bridge.py` 在相同的服务器上包装 **MCP 流式 HTTP** 传输： ```bash python3 jules_mcp_http_bridge.py # [jules-bridge] Listening on http://0.0.0.0:9673/mcp ``` | 路由 | 行为 | |-------|----------| | `POST /mcp` | JSON-RPC 请求 → JSON 响应 (`Content-Type: application/json`) | | `GET /mcp` | `405` — 告诉 SDK “无 SSE 流，使用 POST” | | `DELETE /mcp` | `200` — 会话拆除 | | 通知 | `202`, 无正文 | 通过环境变量配置：`JULES_BRIDGE_PORT`（默认为 `9673`），`JULES_BRIDGE_HOST`（默认为 `0.0.0.0`）。将您的 n8n MCP 客户端工具指向 `http://localhost:9673/mcp`。 > 桥接器设置了宽容的 CORS 标头，并且其自身没有身份验证 — 如果机器被共享，请将其绑定到 localhost 或将其放在反向代理后面。 ## 朱尔斯编排器技能 此仓库捆绑了 **[`jules-orchestrator`](skills/jules-orchestrator/SKILL.md)** 代理技能 — 一个完整的攻略，用于使用规则运行受控循环（模式 B）。它编码： - **角色分工** — 编排器模型范围、控制、审查和合并；朱尔斯仅实现。朱尔斯从不审查自己的工作，编排器从不手动编辑代码。 - **10 步循环**，每步有确切的工具调用。 - **停止条件** — 迭代上限（默认为 4）、重复问题（规范问题，而不是实现问题）和朱尔斯无法做出的决定。 捆绑文件： | 文件 | 用途 | |------|---------| | [`SKILL.md`](skills/jules-orchestrator/SKILL.md) | 主要攻略 — 角色分工、10 步循环、停止条件 | | [`references/jules-mcp-tools.md`](skills/jules-orchestrator/references/jules-mcp-tools.md) | 每个工具的深入参考：参数、返回值、哪些循环步骤使用它、陷阱 | | [`references/code-review-rubric.md`](skills/jules-orchestrator/references/code-review-rubric.md) | 审查步骤针对每个差异运行的检查清单（正确性、边缘情况、错误处理、安全、集成、测试、性能） | | [`references/lessons-learned.md`](skills/jules-orchestrator/references/lessons-learned.md) | 实际运行笔记：提供者怪癖、审查步骤中发现的边界条件 FPGA 错误、轮询频率、分支清理 | | [`assets/prompt-templates.md`](skills/jules-orchestrator/assets/prompt-templates.md) | 范围模板、初始会话提示、修复提示 | | [`assets/state-template.md`](skills/jules-orchestrator/assets/state-template.md) | 每个任务的 YAML 状态文件（会话 ID、迭代次数、PR 号码、合并状态、审查日志） | **安装**（适用于 Hermes Agent / Claude Code 等支持技能的主机）：将目录复制到您的技能文件夹中，例如 ```bash cp -r skills/jules-orchestrator ~/.hermes/skills/autonomous-ai-agents/ # Hermes # 或 cp -r skills/jules-orchestrator ~/.claude/skills/ # Claude Code ``` 还应在目标仓库的 `AGENTS.md` 中添加一个简短的“使用编排器工作”部分（参见技能以获取确切的片段）。 ## 会话状态 ``` QUEUED → PLANNING → AWAITING_PLAN_APPROVAL → IN_PROGRESS → COMPLETED → FAILED ↗ AWAITING_USER_FEEDBACK （可以在会话中间发生） ↗ PAUSED ``` - `AWAITING_PLAN_APPROVAL` 仅在 `require_plan_approval=true` 时发生。 - `jules_get_plan` 如果状态仍为 `PLANNING`，则错误为“找不到计划” — 轮询 `jules_get_session` 直到 `AWAITING_PLAN_APPROVAL` 为止。 - 每 10-30 秒轮询一次；朱尔斯会话通常需要几分钟。 - 完整的 REST 参考（端点、活动类型、工件架构）在 [`docs/jules-api-reference.md`](docs/jules-api-reference.md) 中。 ## 存储库布局 ``` jules-mcp-server/ ├── jules_mcp_server.py # MCP 服务器（stdio 传输）— 主要制品 ├── jules_mcp_http_bridge.py # 可选的 HTTP 流式传输桥接器（端口 9673） ├── test_jules_mcp.py # 烟雾测试：辅助单元 + 完整的 MCP 握手（无需 API 密钥） ├── docs/ │ └── jules-api-reference.md # 朱尔斯 v1alpha REST 参考 ├── skills/ │ └── jules-orchestrator/ # 捆绑的编排技能（参见上文） ├── LICENSE # MIT └── README.md ``` ## 故障排除 | 症状 | 原因/修复 | |---------|-------------| | `ERROR: JULES_API_KEY not set` | 密钥在环境变量和 env 文件中均未设置。添加 `JULES_API_KEY=...` 到 `~/.hermes/.env`（或设置 `JULES_ENV_FILE` 到您的文件路径，或在客户端的 `env` 块中导出变量）。 | | `jules_list_sources` 返回空值 | 朱尔斯 GitHub 应用未安装在任何仓库上。在朱尔斯 Web UI 中连接仓库。 | | `jules_list_sources` 返回空值 | 您传递了 `github/owner/repo` 作为源。使用 `jules_list_sources` 返回的 **完整** ID `sources/github/owner/repo`。 | | `No plan found in session ...` 来自 `jules_get_plan` | 会话仍处于 `PLANNING` 状态，或创建时自动批准（无计划门控）。轮询 `jules_get_session` 获取状态。 | | `Session ... has no pull request yet` 来自 `jules_publish_pr` | 会话仍在运行中，或 `automation_mode` 为空（无自动 PR）。通过 `jules_list_activities` 确认 `COMPLETED`。 | | `No GitHub token available` | 设置 `GITHUB_TOKEN` 或 `GITHUB_PERSONAL_ACCESS_TOKEN`（环境变量或 env 文件）。仅需用于 `jules_publish_pr`。 | | GitHub 合并 HTTP 405/409 | PR 不可合并 — 分支冲突、检查失败或分支保护。在 GitHub 上解决后重试。 | | 官方 `mcp` SDK 在 Python 3.14 上安装失败 | 这就是此服务器存在的原因 — 它不需要 SDK。直接运行 `jules_mcp_server.py` 即可。 | | n8n 无法连接 | 使用 HTTP 桥接器 (`jules_mcp_http_bridge.py`)，端点 `http://localhost:9673/mcp`，而不是 stdio 服务器。 | ## 注意事项 - 朱尔斯 API 是 **v1alpha** — 端点、字段和键可能会更改；无稳定性保证。 - 会话是 **仓库作用域** 的，而不是人作用域的：”分配“工作 = 将会话指向仓库 + 提示。 - 自动创建的 PRs 落在 **您的** GitHub 账户上 — 始终审查生成的 PRs，然后再合并（这是编排循环的重点）。 - 使用可能会消耗朱尔斯/Gemini 配额；适用速率限制。每个账户最多 3 个 API 密钥。 - `jules_publish_pr` **合并** PR（终端“接受”操作）。如果您想要发布-无需合并的语义，请从 `jules_get_session` 读取 PR URL，并单独处理合并。 ## 许可证 [MIT](LICENSE)