朱尔斯_mcp

Name: 朱尔斯_mcp
Author: GatienBoquet

作者：GatienBoquet5 星标更新：2025-11-02

安装使用来源：spider==github.com

项目介绍

非官方 Jules MCP 服务器

jules-mcp-server 将您的 AI 编码助手（如 Claude、Cursor 或 Copilot）连接到 Jules API，使您能够直接从 IDE 进行自主编码会话。它作为模型上下文协议（MCP）服务器运行，赋予您的 AI 助手创建编码会话、管理任务以及与 Jules 代理进行交互的能力，以实现自动化软件开发。

变更日志 | 故障排除

主要功能

自主编码会话：直接从您的 AI 助手创建和管理 Jules 编码会话。
GitHub 集成：通过 Jules 源连接到您的 GitHub 存储库。
计划审批工作流：在 Jules 执行更改之前审查并批准执行计划。
实时活动跟踪：监控会话进度并查看详细的活动日志。
类型安全验证：使用 Zod 的运行时验证确保所有输入在 API 调用之前都经过验证。
可流式传输的 HTTP 传输：使用 MCP 可流式传输的 HTTP 规范进行可靠通信。

声明

jules-mcp-server 提供您的 MCP 客户端访问权限，以便在连接的 GitHub 存储库中创建和管理编码会话。请确保在执行之前审查并批准计划，特别是在生产存储库中。该服务器需要一个具有适当权限的有效 Jules API 密钥。

要求

Node.js v18 或更高版本
具有 API 密钥的 Jules API 账户
npm

开始使用

1. 克隆并安装

git clone https://github.com/yourusername/jules-mcp-server.git
cd jules-mcp-server
npm install

2. 配置环境

cp .env.example .env
# 编辑 .env 并添加您的 JULES_API_KEY

您的 .env 文件应包含：

JULES_API_KEY=your_api_key_here
PORT=3323
HOST=127.0.0.1

3. 启动服务器

npm run dev
# 服务器启动于 http://127..0.0.1:3323/mcp

对于生产环境：

npm run build
npm run start:node

4. 配置您的 MCP 客户端

向您的 MCP 客户端添加以下配置：

{
  "mcpServers": {
    "jules": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3323/mcp"
    }
  }
}

[!IMPORTANT] Jules MCP 服务器使用 可流式传输的 HTTP 传输，并且必须在连接您的 MCP 客户端之前运行。与基于 stdio 的服务器不同，此服务器作为一个持久的 HTTP 服务运行。

MCP 客户端配置

<details> <summary>Claude Desktop</summary>

编辑您的 Claude Desktop 配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

添加 Jules 服务器配置：

{
  "mcpServers": {
    "jules": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3323/mcp"
    }
  }
}

保存配置后重启 Claude Desktop。

</details> <details> <summary>Cursor</summary>

手动安装：

前往 Cursor 设置 → 功能 → MCP
点击 添加新的全局 MCP 服务器
添加配置：

{
  "mcpServers": {
    "jules": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3323/mcp"
    }
  }
}

重启 Cursor

[!NOTE] 确保在启动 Cursor 之前 Jules MCP 服务器正在运行。服务器使用无状态模式以优化与 Cursor 的兼容性。

</details> <details> <summary>VS Code / Copilot</summary>

按照 MCP 安装指南并使用上述提供的配置。

[!NOTE] 对于 MCP 客户端版本，可流式传输的 HTTP 支持可能有所不同。确保您使用的是支持 streamable-http 传输类型的最新版本。

</details> <details> <summary>其他 MCP 客户端</summary>

对于支持可流式传输的 HTTP 传输的其他 MCP 客户端，请使用上述提供的配置。确保客户端支持：

MCP 协议版本 2024-11-05 或更高版本
可流式传输的 HTTP 传输（type: "streamable-http"）
无状态模式（无需会话管理）

</details>

您的第一个提示

在您的 MCP 客户端中输入以下提示以验证设置：

列出我的 Jules 源

您的 MCP 客户端应调用 jules_list_sources 工具并显示您的连接的 GitHub 存储库。

要创建一个编码会话：

为 sources/github/owner/repo 创建一个 Jules 会话，提示为“添加一个 README 文件”

[!TIP] 在创建会话时使用 requirePlanApproval: true 以在 Jules 执行更改之前审查更改。

工具

所有工具均包括使用 Zod 的运行时验证，以确保类型安全并提供清晰的错误消息。

会话管理 (3 个工具)
- jules_create_session - 创建一个新的 Jules 编码会话
- jules_list_sessions - 列出所有 Jules 会话
- jules_send_message - 向活跃的 Jules 代理发送消息
计划审批 (1 个工具)
- jules_approve_plan - 批准会话的执行计划
监控 (2 个工具)
- jules_list_sources - 列出您的连接的 GitHub 源
- jules_list_activities - 列出会话的活动

工具详情

`jules_list_sources`

列出您的连接的 GitHub 源。

参数：

pageSize (可选)：每页的项目数 (1-100)
pageToken (可选)：分页标记

`jules_create_session`

创建一个新的 Jules 编码会话。

参数：

prompt (必需)：Jules 的任务提示 (1-10000 字符)
source (必需)：源路径，例如 sources/github/owner/repo
title (可选)：会话标题 (1-200 字符)
startingBranch (可选)：开始的 Git 分支 (默认：main)
requirePlanApproval (可选)：是否在执行前需要计划审批 (默认：false)

`jules_list_sessions`

列出所有 Jules 会话。

参数：

pageSize (可选)：每页的项目数 (1-100)
pageToken (可选)：分页标记

`jules_approve_plan`

批准会话的执行计划。

参数：

sessionId (必需)：要批准的会话 ID，格式：sessions/{id}

`jules_send_message`

向活跃的 Jules 代理发送消息。

参数：

sessionId (必需)：会话 ID，格式：sessions/{id}
prompt (必需)：要发送的消息 (1-10000 字符)

`jules_list_activities`

列出会话的活动。

参数：

sessionId (必需)：会话 ID，格式：sessions/{id}
pageSize (可选)：每页的项目数 (1-100)
pageToken (可选)：分页标记

资源

服务器提供了两个 MCP 资源以提供更多上下文：

jules://sources - 您连接的 GitHub 源
jules://sessions/{id}/activities - 特定会话的最新活动

资源可以直接由 MCP 客户端访问以收集上下文信息。

配置

Jules MCP 服务器支持以下环境变量：

JULES_API_KEY (必需) 您的 Jules API 密钥用于身份验证。
- 类型：字符串
PORT HTTP 服务器的端口号。
- 类型：数字
- 默认值：3323
HOST 绑定服务器的主机地址。
- 类型：字符串
- 默认值：127.0.0.1
ALLOWED_ORIGINS CORS 允许的来源的逗号分隔列表。
- 类型：字符串
- 默认值：null,http://localhost

在您的 .env 文件中配置这些变量：

JULES_API_KEY=your_api_key_here
PORT=3323
HOST=127.0.0.1
ALLOWED_ORIGINS=null,http://localhost

架构

无状态模式

服务器以 无状态模式（不进行会话管理）运行，以优化与 MCP 客户端（如 Cursor）的兼容性。每个请求都是独立的，不需要会话 ID 标头。

传输

使用 MCP 可流式传输的 HTTP 传输规范，包括：

启用 JSON 响应 (enableJsonResponse: true)
不进行会话管理 (sessionIdGenerator: undefined)
使用可配置来源的 CORS 保护
请求/响应日志记录以调试

验证

所有工具输入在进行 API 调用之前都会使用 Zod 模式进行验证：

防止无效请求到达 Jules API
提供清晰的操作错误消息
通过早期捕获错误节省 API 配额
确保整个请求管道中的类型安全

参见 VALIDATION_EXAMPLES.md 以获取详细的验证规则和示例。

故障排除

服务器无法启动

问题：服务器无法启动或立即崩溃。

解决方案：

验证 .env 中已设置 JULES_API_KEY
检查端口 3323 是否已被占用：netstat -ano | findstr :3323 (Windows) 或 lsof -i :3323 (macOS/Linux)
确保 Node.js 版本是 18 或更高版本：node --version
查看服务器日志以获取特定的错误消息

Cursor 显示“没有工具”

问题：MCP 连接似乎正常，但没有列出任何工具。

解决方案：

验证服务器正在运行：curl http://127.0.0.1:3323/mcp 应不会返回连接错误
在进行配置更改后重启 Cursor
确保配置中的 URL 精确为 http://127.0.0.1:3323/mcp
确保服务器使用无状态模式（默认配置）
尝试重新启动服务器：停止它并再次运行 npm run dev

CORS/来源错误

问题：服务器返回 403 禁止来源错误。

解决方案：

在 .env 中为本地开发添加 null 到 ALLOWED_ORIGINS
对于自定义来源，更新 ALLOWED_ORIGINS：ALLOWED_ORIGINS=null,http://localhost,http://127.0.0.1
更改环境变量后重启服务器

验证错误

问题：工具调用因验证错误而失败。

解决方案：

检查错误消息以获取特定字段的要求
验证会话 ID 匹配格式 sessions/{id}
验证源路径匹配格式 sources/github/owner/repo
确保字符串长度在指定范围内
参见 VALIDATION_EXAMPLES.md 以获取正确的输入格式

API 认证错误

问题：工具因 401 未授权错误而失败。

解决方案：

验证您的 JULES_API_KEY 是有效的并且处于激活状态
检查 API 密钥是否具有必要的权限
确保 .env 文件位于项目根目录中
更新 API 密钥后重启服务器

连接超时

问题：对 Jules API 的请求超时或挂起。

解决方案：

检查您的互联网连接
在 status.jules.ai（如果可用）上验证 Jules API 的状态
如果处理大型存储库，请增加超时值
检查防火墙设置，可能会阻止外出的 HTTPS 请求

开发

从源构建

npm install
npm run build

src/ 目录中的 TypeScript 源代码编译到 dist/ 目录中的 JavaScript。

在开发模式下运行

npm run dev

这使用 tsx 直接运行 TypeScript 并启用热重载。

项目结构

jules-mcp-server/
├── src/
│   ├── server.ts           # 主服务器和 MCP 设置
│   ├── client/
│   │   └── jules-client.ts # Jules API 客户端
│   ├── tools/
│   │   ├── index.ts        # 工具注册表
│   │   ├── sources.ts      # 源管理工具
│   │   ├── sessions.ts     # 会话管理工具
│   │   └── activities.ts   # 活动监控工具
│   ├── schemas/
│   │   └── index.ts        # Zod 验证模式
│   ├── resources/
│   │   └── index.ts        # MCP 资源
│   └── types/
│       └── tool.ts         # 类型定义
├── dist/                   # 编译后的 JavaScript
├── .env                    # 环境配置
└── package.json

已知限制

可流式传输的 HTTP 客户端支持

并非所有 MCP 客户端完全支持可流式传输的 HTTP 传输。此服务器已测试过：

✅ Cursor（无状态模式）
✅ Claude Desktop（需手动配置）
⚠️ VS Code/Copilot（有限支持，检查版本）

会话管理

服务器使用无状态模式以优化兼容性。如果您需要有状态的会话管理，可以修改 src/server.ts 以启用 sessionIdGenerator，但这可能会破坏与某些客户端（如 Cursor）的兼容性。

仅限本地访问

默认情况下，服务器绑定到 127.0.0.1（仅限本地）以保证安全性。要允许远程访问，请更改 HOST 环境变量，但在生产环境中务必实施适当的认证并使用 HTTPS。

贡献

欢迎贡献！请：

分叉仓库
创建功能分支
在测试中进行更改
提交拉取请求

许可证

MIT 许可证 - 详见 LICENSE 文件。

支持

问题：GitHub 问题
Jules API：jules API
MCP 规范：modelcontextprotocol.io