Jules Orchestrator

Google Jules API v1alpha を GitHub Copilot で統合・制御するための MCP（Model Context Protocol）サーバー。

複数の自動化タスクを並列実行し、セッション単位で進捗・出力を管理します。

概要

GitHub Copilot Chat
       ↓ (MCP Protocol)
  Jules Orchestrator
       ↓ (REST API)
Google Jules API v1alpha

主な機能

✅ 複数セッション並列管理 — 複数タスクを同時に dispatch & monitor
✅ 状態推論 — session.state + activities 解析で信頼性の高い状態判定
✅ ブロッキングイベント検出 — プラン承認待ち・質問待ちを即座に通知
✅ 差分・PR 抽出 — artifacts から git patch, PR URL を自動抽出
✅ API-only — Jules CLI 不要
✅ 簡潔な設定 — API キーのみで動作

ファイル構成

mcp/jules/
├── design.md              ← 完全な技術仕様（要読）
├── SETUP.md               ← セットアップガイド
├── README.md              ← このファイル
├── package.json           ← Node.js 依存関係
├── tsconfig.json          ← TypeScript 設定
├── .env.example           ← 環境変数テンプレート
├── mcp.json               ← VS Code MCP 設定例
└── src/
    ├── index.ts           ← MCP サーバーエントリ
    ├── types/
    │   └── index.ts       ← 型定義（Session, Activity等）
    ├── client/
    │   └── julesApiClient.ts    ← REST API クライアント
    ├── cluster/
    │   └── sessionCluster.ts    ← セッションクラスター管理
    ├── inference/
    │   └── stateInference.ts    ← 状態推論ロジック
    └── tools/
        └── handlers.ts          ← MCP ツールハンドラー

クイックスタート

1. インストール

cd mcp/jules
npm install
npm run build

2. 環境変数設定

cp .env.example .env
# .env を編集し、JULES_API_KEY を設定

3. VS Code 登録

~/.config/Code/User/settings.json に追加：

{
  "modelContextProtocol.servers": {
    "jules-orchestrator": {
      "command": "node",
      "args": ["/full/path/to/mcp/jules/dist/index.js"],
      "env": {
        "JULES_API_KEY": "your_api_key"
      }
    }
  }
}

4. Copilot で利用

GitHub Copilot Chat で以下のように指示：

@jules-orchestrator dispatch_session
  prompt="Fix auth bug"
  source="sources/github/me/myrepo"
  requirePlanApproval=true

@jules-orchestrator wait_for_cluster_events

@jules-orchestrator resolve_interruption
  sessionId="..."
  action="approve_plan"

MCP ツール API

list_sources

接続済みソース一覧を取得。

// Input
{}

// Output
{
  sources: [
    {
      name: "sources/github/owner/repo",
      githubRepo: { owner: "owner", repo: "repo" }
    }
  ]
}

dispatch_session

新しい Jules セッションを作成・起動。

// Input
{
  prompt: "Fix auth bug",
  source: "sources/github/owner/repo",
  title?: "Auth Bug Fix",
  requirePlanApproval?: true
}

// Output
{
  sessionId: "...",
  state: "RUNNING",
  url: "https://jules.co/...",
  timestamp: "2025-11-26T..."
}

wait_for_cluster_events

クラスタ監視。ブロッキングイベント発生時に即座に返す。

// Input
{
  pollIntervalMs?: 3000,
  timeoutMs?: 600000,
  includeDetails?: true
}

// Output (ブロッキングイベント時)
{
  status: "INTERRUPTED",
  events: [
    {
      sessionId: "...",
      state: "AWAITING_PLAN_APPROVAL",
      context: "Plan description...",
      lastPlan: "...",
      lastQuestion: "..."
    }
  ]
}

// Output (全完了時)
{
  status: "ALL_COMPLETED",
  summary: {
    totalSessions: 2,
    completed: 2,
    failed: 0,
    patches: ["diff -u ..."],
    prUrls: ["https://github.com/.../pull/123"]
  }
}

resolve_interruption

ユーザー応答（承認またはメッセージ）を送信。

// Input
{
  sessionId: "...",
  action: "approve_plan" | "send_message",
  message?: "Proceed with plan"
}

// Output
{
  success: true,
  message: "Plan approved. Session resumed.",
  newState: "RUNNING"
}

get_session_details

セッション詳細を取得。

// Input
{
  sessionId: "...",
  includeActivities?: true,
  includePatches?: true
}

// Output
{
  session: { name: "...", state: "...", url: "..." },
  inferredState: { state: "RUNNING", context?: "..." },
  activities: [...],
  patches: ["diff -u ..."],
  lastQuestion?: "Which branch?",
  lastPlan?: "Plan description...",
  prUrl?: "https://github.com/.../pull/123"
}

cancel_session

セッションを停止・削除。

// Input
{
  sessionId: "..."
}

// Output
{
  success: true,
  message: "Session cancelled.",
  removedFromCluster: true
}

add_to_cluster

既存のJulesセッションをクラスターに追加してモニタリング対象にする。 dispatch_session 以外で作成されたセッションを管理したい場合に使用。

// Input
{
  sessionId: "2356450202027531703"
}

// Output
{
  success: true,
  message: "Session 2356450202027531703 added to cluster",
  sessionId: "2356450202027531703",
  title: "Fix ErrorBoundary",
  state: "AWAITING_USER_FEEDBACK",
  url: "https://jules.co/...",
  source: "sources/github/owner/repo"
}

get_cluster_status

MCPでdispatchしたセッションのみのクラスタ全体のステータス。 ※ Jules API の全セッションを見るには list_all_sessions を使用。

// Input
{}

// Output
{
  stats: {
    total: 3,
    running: 1,
    awaitingPlanApproval: 1,
    awaitingUserFeedback: 0,
    completed: 1,
    failed: 0
  },
  blockingSessions: [
    {
      sessionId: "...",
      state: "AWAITING_PLAN_APPROVAL",
      title: "Fix auth bug",
      url: "https://..."
    }
  ],
  note: "This shows only sessions dispatched via MCP dispatch_session. Use list_all_sessions for all Jules API sessions."
}

list_all_sessions

Jules API の全セッションを取得（MCP以外で作成されたセッションも含む）。

// Input
{
  limit?: 100,              // 最大取得数
  stateFilter?: ["COMPLETED", "IN_PROGRESS"]  // 状態でフィルタ
}

// Output
{
  sessions: [
    {
      id: "...",
      title: "Fix auth bug",
      state: "COMPLETED",
      url: "https://...",
      source: "sources/github/owner/repo",
      createTime: "2025-11-26T...",
      hasPullRequest: true,
      pullRequestUrl: "https://github.com/.../pull/123"
    }
  ],
  total: 10,
  allSessionsCount: 50,
  note: "This lists ALL sessions from Jules API, not just those dispatched via MCP."
}

list_sessions_by_source

特定のリポジトリに関連するセッションのみをフィルタリング取得。

// Input
{
  source: "sources/github/owner/repo",  // または "github/owner/repo"
  stateFilter?: ["IN_PROGRESS"],
  limit?: 100
}

// Output
{
  sessions: [
    {
      id: "...",
      title: "Fix auth bug",
      state: "IN_PROGRESS",
      source: "sources/github/owner/repo",
      startingBranch: "main",
      createTime: "2025-11-26T...",
      hasPullRequest: false
    }
  ],
  total: 3,
  sourceFilter: "sources/github/owner/repo"
}

状態遷移図

┌─────────────────┐
│   RUNNING       │ ← dispatch_session で開始
└────────┬────────┘
         ↓
    ┌─────────────────────────┐
    │ 複数の可能な分岐          │
    └─────┬───────┬───────┬───┘
          ↓       ↓       ↓
    ┌──PLAN┐  ┌─QUESTION  ┌──ERROR─┐
    │      │  │  ASKED   │        │
    └──┬───┘  └────┬─────┘        │
       │           │              │
       ↓ approve   ↓ respond      ↓
    RUNNING ←──────┘            FAILED
       ↓
    ┌──────────┐
    │ COMPLETED │
    └──────────┘

設定・認証

API キー取得

1. Google Cloud Console にアクセス
2. Jules API を有効化
3. API キーを作成（制限: Jules API のみ）
4. キーを .env または環境変数 JULES_API_KEY に設定

セキュリティ推奨事項

• API キーを環境変数で管理（コードにハードコード禁止）
• IP 制限を設定
• キーのローテーション定期実施
• .env を .gitignore に追加

トラブルシューティング

MCP サーバー起動エラー

Error: JULES_API_KEY is required

→ .env を確認、または環境変数を設定

401 Unauthorized

→ Jules API キーが無効（期限切れまたは権限不足）

セッション作成失敗

→ ソース名を list_sources で確認

参考資料

• 設計書: design.md（完全な技術仕様）
• セットアップ: SETUP.md（詳細な導入ガイド）
• Jules API リファレンス: https://developers.google.com/jules/api/reference/rest
• MCP プロトコル: https://modelcontextprotocol.io

ライセンス

MIT

更新履歴

| バージョン | 日付 | 内容 | | ---------- | ---------- | ------------------------------ | | 3.0.0 | 2025-11-26 | 完全設計実装 + ツール群実装完了 |

最終更新: 2025-11-26