Jules Manager（TypeScript）（服务器版本2.0.0）

一个MCP服务器实现，用于将Google Jules编排为来自本地编码代理的远程编码代理。该系统处理整个生命周期：任务分解、基于API的Jules调度、异步状态监视、干预处理、代码审查和PR合并。

核心原则

本地代理不得在活动轮询中浪费上下文窗口令牌。 解耦监控机制独立处理轮询，仅在需要人工输入或最终审查时触发本地代理。

后台监控执行：定期轮询 scripts/jules_monitor.ts 只能打电话 jules_check_jules （紧凑型 Q/C/F/N 答复）。监视器不呼叫 jules_get_session 在投票期间。详细的会话检索保留用于可操作事件后的后续处理。

概述

Jules MCP服务器充当本地编码环境和Google Jules API之间的桥梁。它使您能够：

直接从您的开发环境创建和管理Jules编码会话。
在后台自动监视会话进度。
使用事件监视器处理人工输入请求（如计划批准或澄清）。
直接从已完成的会话中提取拉取请求信息。

快速启动/安装

先决条件

Node.js 20+
JULES_API_KEY Jules API密钥的环境变量集

再进行

npm install

启动系统

该系统由三个运行进程组成，以实现全部功能：

# Terminal 1: Build the TypeScript project
npm run build

# Terminal 2: Start the background monitor
node build/scripts/jules_monitor.js --config config.json

# Terminal 3: Start the event watcher
node build/scripts/jules_event_watcher.js --command "node build/scripts/event_handler.js"

命令行用法

jules_cli（友好的cli）

从命令行与Jules交互的最简单方法是 jules_cli 包装：

npm run jules --  [options]

命令：

命令	描述	选项
`create`	创建新的Jules会话	`--owner`, `--repo`, `--branch`, `--prompt`, `--title`, `--require-approval`, `--automation-mode`
`get`	获取会话详细信息	`--session-id`
`list`	列出所有会话	（无）
`approve`	批准会议计划	`--session-id`
`monitor`	轮询会话，直到其完成/失败	`--session-id`, `--interval` （秒，默认120）

示例：

# Create a session
npm run jules -- create --owner my-org --repo my-repo --branch main --prompt "Refactor the login module"

# List sessions
npm run jules -- list

# Get a specific session
npm run jules -- get --session-id 12345

# Approve a plan
npm run jules -- approve --session-id 12345

# Monitor a session (polls every 60s)
npm run jules -- monitor --session-id 12345 --interval 60

mcp客户端（原始mcp工具调用）

对于直接MCP工具调用（可用于脚本编写或调试），请使用通用MCP客户端：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool  --arguments ''

MCP工具

Jules MCP服务器公开了以下14个工具来管理Jules会话的生命周期。

`jules_create_session`

为GitHub存储库创建一个新的Jules编码会话。

重要提示： 始终使用存储库的默认分支(main 或 master)作为起始分支。Jules会自动为每个会话创建自己的功能分支。

参数：

owner （string，必填）：GitHub存储库所有者。
repo （string，必填）：GitHub存储库名称。
branch （字符串，必填）：起始分支名称。 必须是默认分支(main 或 master) -Jules将创建自己的功能分支。
prompt （string，必填）：Jules的任务描述。
title （字符串，可选）：可选会话标题。
requirePlanApproval （布尔值，可选）：执行前是否需要计划审批。
automationMode （字符串，可选）：自动化模式。默认为 "AUTO_CREATE_PR" （Jules在成功完成后自动发布拉取请求）。传递空字符串或替代模式将覆盖此设置。

使用示例：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_create_session --arguments '{"owner": "my-org", "repo": "my-repo", "branch": "main", "prompt": "Refactor the login module", "requirePlanApproval": true}'

`jules_get_session`

获取会话元数据、状态和输出。

参数：

session_id （string，必填）：Jules会话ID。

使用示例：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_get_session --arguments '{"session_id": "sessions/12345"}'

`jules_check_jules`

用于定期轮询的令牌保存状态检查。返回一个字符代码，以最小化响应大小和上下文使用：

Q：会议需要澄清/批准(AWAITING_USER_FEEDBACK 或 AWAITING_PLAN_APPROVAL)
C：会话已完成
F：会话失败
N：无需操作（正在进行、未知或未找到会话）

您可以提供特定的 session_id，或 owner + repo （可选 branch)以解决当前项目的最新会话。

参数：

session_id （字符串，可选）：要检查的特定会话。
owner （字符串，可选）：GitHub存储库所有者（当 session_id 未提供）。
repo （字符串，可选）：GitHub存储库名称（当 session_id 未提供）。
branch （string，可选）：按项目检查时可选的分支过滤器。

使用示例（项目范围）：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_check_jules --arguments '{"owner": "mikbin", "repo": "jules-mcp", "branch": "main"}'

用法示例（会话范围）：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_check_jules --arguments '{"session_id": "sessions/12345"}'

`jules_list_sessions`

列出Jules的会议。

参数：

pageSize （number，可选）：要返回的最大会话数。
pageToken （字符串，可选）：分页的页面标记。

使用示例：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_list_sessions --arguments '{"pageSize": 10}'

`jules_delete_session`

删除Jules会话。

参数：

session_id （string，必填）：Jules会话ID。

使用示例：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_delete_session --arguments '{"session_id": "sessions/12345"}'

`jules_send_message`

向Jules会议发送澄清或指示。

参数：

session_id （string，必填）：Jules会话ID。
message （字符串，必填）：要发送的消息文本。

使用示例：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_send_message --arguments '{"session_id": "sessions/12345", "message": "Please make sure to also update the unit tests."}'

`jules_approve_plan`

批准等待计划批准的会话计划。

参数：

session_id （string，必填）：Jules会话ID。

使用示例：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_approve_plan --arguments '{"session_id": "sessions/12345"}'

`jules_list_activities`

列出Jules会议的活动。

参数：

session_id （string，必填）：Jules会话ID。
pageSize （number，可选）：要返回的最大活动数。
pageToken （字符串，可选）：分页的页面标记。

使用示例：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_list_activities --arguments '{"session_id": "sessions/12345", "pageSize": 5}'

`jules_get_activity`

按ID获取Jules会话的单个活动。

参数：

session_id （string，必填）：Jules会话ID。
activity_id （字符串，必填）：活动ID。

使用示例：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_get_activity --arguments '{"session_id": "sessions/12345", "activity_id": "activities/67890"}'

`jules_list_sources`

列出可用的源代码（GitHub存储库）。

参数：

pageSize （number，可选）：要返回的最大源数。
pageToken （字符串，可选）：分页的页面标记。

使用示例：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_list_sources --arguments '{}'

`jules_get_source`

获取特定来源的详细信息。

参数：

source_id （字符串，必填）：源ID。

使用示例：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_get_source --arguments '{"source_id": "sources/github/my-org/my-repo"}'

`jules_extract_pr_from_session`

从已完成的Jules会话输出中提取拉取请求信息。

参数：

session_id （string，必填）：已完成的Jules会话ID。

使用示例：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_extract_pr_from_session --arguments '{"session_id": "sessions/12345"}'

`jules_wait`

暂停执行指定秒数（最多600秒）。在轮询调用之间使用以保存上下文窗口令牌，而不需要单独的睡眠MCP服务器。

参数：

seconds （数字，必填）：等待时间（秒）（最多600）。

使用示例：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_wait --arguments '{"seconds": 120}'

`jules_monitor_session`

使用实时MCP进度通知监控Jules会话。轮询会话，直到它达到终端状态(COMPLETED 或 FAILED)，发送 notifications/progress 向客户端返回带有最新活动描述的消息。如果会话进入 AWAITING_USER_FEEDBACK，工具会提前返回，以便调用者可以回复 jules_approve_plan 或 jules_send_message 然后恢复监视。

参数：

session_id （string，必填）：要监视的Jules会话ID。
poll_interval_seconds （数字，可选）：轮询间隔（秒）（默认值：60，最大值：300）。

使用示例：

npm run mcp-client -- --command node build/mcp-server/jules_mcp_server.js --tool jules_monitor_session --arguments '{"session_id": "sessions/12345", "poll_interval_seconds": 10}'

注：进度通知需要支持MCP的客户端 notifications/progress 方法（大多数兼容MCP的IDE都是这样做的）。通知包括 message 字段中包含当前会话状态和最新活动描述，允许客户端显示实时状态更新，而无需消耗额外的上下文窗口令牌。

配置和环境变量

环境变量

变量	必填	描述
`JULES_API_KEY`	Jules API身份验证没有\*	API密钥。
`JULES_API_BASE`	否	Jules API的基本URL（默认值：https://jules.googleapis.com/v1alpha)
`JULES_CONFIG`	否	指向config.json的路径（默认：config.json）

*\*如果未通过提供，则需要 mcp_config.json.*

MCP配置文件（推荐）

Jules MCP可以从Antigravity或Cline等工具使用的标准MCP配置文件中自动发现您的API密钥。它寻找 JULES_API_KEY 在 env 部分 jules-mcp-server 进入：

~/.gemini/antigravity/mcp_config.json
~/.cline/mcp_config.json

示例 mcp_config.json 条目：

{
  "mcpServers": {
    "jules-mcp-server": {
      "command": "node",
      "args": ["/path/to/jules-mcp/build/mcp-server/jules_mcp_server.js"],
      "env": {
        "JULES_API_KEY": "your-api-key-here"
      }
    }
  }
}

JSON配置

后台进程的共享配置存储在 config.json。有关所有可用设置，请参阅文件：

{
  "jobs_path": "jobs.jsonl",
  "events_path": "events.jsonl",
  "monitor_state_path": ".monitor_state.json",
  "watcher_state_path": ".watcher_state.json",
  "monitor_poll_seconds": 45,
  "watcher_poll_seconds": 1,
  "stuck_minutes": 20,
  "api_base": "https://jules.googleapis.com/v1alpha",
  "mcp_command": ["node", "build/mcp-server/jules_mcp_server.js"],
  "event_command": ["node", "build/scripts/event_handler.js"],
  "auto_approve_plans": false
}

配置详细信息：

auto_approve_plans （布尔值）：如果 true，the event_handler 将自动呼叫 jules_approve_plan 每当会话进入 AWAITING_USER_FEEDBACK 申请批准计划。
mcp_command （string\[\]）：必填项 jules_monitor监视器使用此命令调用MCP工具 jules_check_jules 用于所有定期轮询检查。

测试

使用以下命令运行测试套件维测试:

npm test

项目结构

jules-mcp/
├── README.md                    # This file
├── config.json                  # Shared configuration
├── jobs.jsonl                   # Active jobs registry
├── events.jsonl                 # Actionable event queue
├── docs/
│   └── architecture.md          # Detailed architecture documentation
├── mcp-server/
│   ├── jules_mcp_server.ts      # MCP server implementation
│   └── README.md                # MCP server docs
├── src/
│   ├── mcp_client.ts            # Generic MCP client (raw tool invocation)
│   └── utils.ts                 # Shared utilities (e.g. formatTimestamp)
├── scripts/
│   ├── jules_cli.ts             # Friendly CLI wrapper (npm run jules)
│   ├── jules_monitor.ts         # Background poller
│   ├── jules_event_watcher.ts   # Event queue watcher
│   └── event_handler.ts         # Event handler
└── tests/
    ├── mcp_server.test.ts       # MCP server tests
    ├── monitor.test.ts          # Monitor tests
    ├── event_handler.test.ts    # Event handler tests
    └── utils.test.ts            # Utility tests

与AI编码工具集成

项目建成后(npm run build)，您可以将Jules MCP服务器与支持MCP stdio协议的任何AI编码工具（如Amp、Cline、Kilo Code、Windsurf等）一起使用。

有关AI代理和更容易发现的信息，请参阅 llms-installation.md.

先决条件 - 跑 npm run build 在项目根目录中 - 有你的 JULES_API_KEY 准备好了（从 jules.google.com/settings)

使用标准stdio传输配置服务器：

命令: node
参数: /absolute/path/to/jules-mcp/build/mcp-server/jules_mcp_server.js
环境: JULES_API_KEY = ``

放大器（VS代码扩展）

将以下内容添加到您的VS代码中 settings.json 在...之下 amp.mcpServers:

{
  "amp.mcpServers": {
    "jules-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/jules-mcp/build/mcp-server/jules_mcp_server.js"],
      "env": {
        "JULES_API_KEY": ""
      }
    }
  }
}

或者，通过npx全局安装（无需克隆仓库）：

{
  "amp.mcpServers": {
    "jules-mcp": {
      "command": "npx",
      "args": ["-y", "jules-mcp-ts"],
      "env": {
        "JULES_API_KEY": ""
      }
    }
  }
}

更新Amp的设置后，重新加载VS Code窗口以获取新的MCP服务器。

代理发现和API可见性

当Jules MCP服务器作为MCP服务器安装时，用于以下工具 克莱恩, Kilo Code, 安培，或 帆板运动那些特工确实如此不嵌入任何Jules API证书。相反，他们：

查找标准MCP配置文件(~/.gemini/antigravity/mcp_config.json 或 ~/.cline/mcp_config.json).
如果文件包含以下项 jules-mcp-server，the env 部分被合并到流程环境中，公开 JULES_API_KEY 并且可选 JULES_API_BASE.
如果找不到配置文件，代理将回退到环境变量 JULES_API_KEY / JULES_API_BASE 在启动服务器之前，您可以在shell中导出。

因为提供了凭据 运行时，它们从未被纳入生产捆绑包(build/…).捆绑包仅包含与Jules API对话的已编译JavaScript代码；实际的API密钥位于存储库之外，因此可以安全地共享构建的工件而不会泄露机密。

能见度

存储库内部 –README和 config.json 记录所需的环境变量和可选的 auto_approve_plans 旗帜。
存储库外部 –运行MCP服务器的任何进程（包括第三方代理）都可以通过上述MCP配置机制发现凭据。不需要额外的网络请求；在服务器启动之前，在本地读取密钥。

此设计确保API信息 任何兼容MCP的客户端都可以发现 同时保持 私有的 到主机环境。

Jules Mpc

快速接入

详细介绍

Jules Manager（TypeScript）（服务器版本2.0.0）

核心原则

概述

快速启动/安装

先决条件

再进行

启动系统

命令行用法

jules_cli（友好的cli）

mcp客户端（原始mcp工具调用）

MCP工具

jules_create_session

jules_get_session

jules_check_jules

jules_list_sessions

jules_delete_session

jules_send_message

jules_approve_plan

jules_list_activities

jules_get_activity

jules_list_sources

jules_get_source

jules_extract_pr_from_session

jules_wait

jules_monitor_session

配置和环境变量

环境变量

MCP配置文件（推荐）

JSON配置

测试

项目结构

与AI编码工具集成

放大器（VS代码扩展）

代理发现和API可见性

能见度

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`jules_create_session`

`jules_get_session`

`jules_check_jules`

`jules_list_sessions`

`jules_delete_session`

`jules_send_message`

`jules_approve_plan`

`jules_list_activities`

`jules_get_activity`

`jules_list_sources`

`jules_get_source`

`jules_extract_pr_from_session`

`jules_wait`

`jules_monitor_session`