Jules MCP Server (jules-mcp)

Note

本项目是 mcp-gateway (MCP 聚合网关) 的子项目之一，旨在提供 Jules AI 代理的 MCP 封装服务。

Jules MCP 服务是一个基于 FastMCP 框架，封装了 Google Jules Agent 操作的 MCP 服务。

通过此服务器，支持 MCP 协议的客户端（及 Python 代码）可以调用官方 jules-agent-sdk 来列出 Jules Source、创建并管理 Session，以及监控 Activity。

• 服务器框架: FastMCP
• SDK: jules-agent-sdk
• Python 版本: 3.13+
• 许可协议: Apache-2.0

参考：

"jules-mcp": { "command": "d:/jules-mcp-server/.venv/Scripts/python.exe", "args": [ "-m", "jules_mcp" ], "cwd": "d:/jules-mcp-server", "env": { "JULES_API_KEY": "xxx" } }

功能特性

通过本 MCP 服务器暴露的工具（按领域分组）：

• Sources (资源)
  • get_source(source_id): 获取单个资源
  • list_sources(filter_str, page_size, page_token): 分页列出资源
  • get_all_sources(filter_str): 获取所有资源（自动分页）
• Sessions (会话)
  • create_session(prompt, source, ...): 创建新的 Jules 会话
  • get_session(session_id): 获取会话详情
  • list_sessions(page_size, page_token): 分页列出会话
  • approve_session_plan(session_id): 批准待处理的任务计划
  • send_session_message(session_id, prompt): 向现有会话发送消息
  • wait_for_session_completion(session_id, ...): 轮询直到会话完成或失败
• Activities (活动)
  • get_activity(session_id, activity_id): 获取单项活动
  • list_activities(session_id, ...): 分页列出会话关联的活动
  • list_all_activities(session_id): 列出所有活动（自动分页）

详细参数签名及说明请参见 jules_mcp/jules_mcp.py 中的代码注释。

安装指南

方案 A：从本地源码安装

# 在项目根目录下执行
pip install -e .

方案 B：使用 uv 安装（推荐用于开发）

# 在项目根目录下执行
# 将自动创建 .venv 并安装依赖 (包含 Python 3.13+)
uv sync

该项目目标运行环境为 Python 3.13+。

环境配置

请通过环境变量设置您的 Jules API Key：

• Windows PowerShell

  $Env:JULES_API_KEY = "<your_api_key_here>"

• Unix Shell (bash/zsh)

  export JULES_API_KEY="<your_api_key_here>"

如果未显式提供 API Key，SDK 将自动尝试从 JULES_API_KEY 环境变量中读取。

运行 MCP 服务器

主要有两种运行方式：

1. 编程式运行 (FastMCP Client) —— 适用于测试或嵌入式调用：

import asyncio
from fastmcp import Client
from jules_mcp import mcp

async def main():
    async with Client(mcp) as client:
        # 示例：获取所有资源（自动分页）
        result = await client.call_tool("get_all_sources")
        print(result)

asyncio.run(main())

2. 作为独立可执行程序 —— 适用于外部 MCP 客户端：

• 使用 uv 直接运行

  uv run fastmcp run jules_mcp/jules_mcp.py:mcp

  这将通过 stdio 启动 MCP 服务器。

• 使用配置文件

  • MCP.json: 用于 MCP 托管主机的示例配置。
  • fastmcp.json: FastMCP 运行时及环境配置。

如果您的安装路径不同，请相应调整 MCP.json 中的路径。

也可以通过模块入口点运行：

python -m jules_mcp

🐳 Docker 部署

我们提供了官方构建的 Docker 镜像，支持 amd64 和 arm64 架构。

1. 本地构建运行

如果您需要修改代码或使用未发布的版本：

# 1. 构建镜像
docker build -t jules-mcp .

# 2. 运行容器
docker run -i --rm \
  -e JULES_API_KEY="<your_api_key>" \
  jules-mcp

2. MCP 客户端配置示例 (Claude Desktop)

将以下配置添加到您的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "jules-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "JULES_API_KEY=<your_api_key>",
        "jules-mcp"
      ]
    }
  }
}

使用示例

列出并过滤资源

import asyncio
from fastmcp import Client
from jules_mcp import mcp

async def main():
    async with Client(mcp) as client:
        # 过滤语法遵循 Jules 支持的 AIP-160 规则
        res = await client.call_tool(
            "list_sources",
            {"filter_str": "name=sources/source1 OR name=sources/source2", "page_size": 10}
        )
        print(res)

asyncio.run(main())

创建会话并等待完成

import asyncio
from fastmcp import Client
from jules_mcp import mcp

async def run_session():
    async with Client(mcp) as client:
        session = await client.call_tool(
            "create_session",
            {
                "prompt": "Analyze the repository and propose improvements",
                "source": "sources/abc123",
                "require_plan_approval": True,
            },
        )

        # (可选) 批准执行计划
        await client.call_tool("approve_session_plan", {"session_id": session["name"]})

        # 等待完成
        final = await client.call_tool(
            "wait_for_session_completion",
            {"session_id": session["name"], "poll_interval": 5, "timeout": 600}
        )
        print(final)

asyncio.run(run_session())

查看活动

import asyncio
from fastmcp import Client
from jules_mcp import mcp

async def list_acts(session_id: str):
    async with Client(mcp) as client:
        acts = await client.call_tool("list_all_activities", {"session_id": session_id})
        for a in acts:
            print(a)

asyncio.run(list_acts("sessions/abc123"))

开发与测试

• 创建虚拟环境并安装开发依赖

  uv pip install -e .
  
  uv sync
  # 尽量使用uv 可以使用pip 安装uv
  # 或者: pip install -e .[dev]

• 运行测试 (注：部分工具会调用 Jules API，需设置 JULES_API_KEY)

  uv run pytest -q

项目元数据

• 包名: jules-mcp
• 版本: 0.1.6
• 入口点:
  • Python 模块: python -m jules_mcp
  • FastMCP 源: jules_mcp/jules_mcp.py:mcp

Agent Intelligence

本仓库包含专门的 .agent 目录，通过项目特定的知识资产赋能 AI 协作助手：

• Rules (规则)：架构约束与编码标准（如 FastAPI、全栈安全规范）。
• Skills (技能)：特定任务的专家级指令（如 MCP 开发、Jules SDK 集成规范）。
• Workflows (工作流)：常见操作的标准流程（如 API 变更维护、Bug 构建与定位）。

这些资产确保 AI 助手能够以极高的精准度和一致性维护本仓库。

许可协议

Apache License 2.0. 详见 LICENSE 文件。