Jules API v1alpha MCP Server for GitHub Copilot orchestration
npm install jules-manage-mcp
GitHub Copilot Chat
↓ (MCP Protocol)
Jules Orchestrator
↓ (REST API)
Google Jules API v1alpha
`
$3
✅ 複数セッション並列管理 — 複数タスクを同時に 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 ツールハンドラー
`
---
クイックスタート
$3
`bash
cd mcp/jules
npm install
npm run build
`
$3
`bash
cp .env.example .env
.env を編集し、JULES_API_KEY を設定
`
$3
~/.config/Code/User/settings.json に追加：
`json
{
"modelContextProtocol.servers": {
"jules-orchestrator": {
"command": "node",
"args": ["/full/path/to/mcp/jules/dist/index.js"],
"env": {
"JULES_API_KEY": "your_api_key"
}
}
}
}
`
$3
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
$3
接続済みソース一覧を取得。
`typescript
// Input
{}
// Output
{
sources: [
{
name: "sources/github/owner/repo",
githubRepo: { owner: "owner", repo: "repo" }
}
]
}
`
$3
新しい Jules セッションを作成・起動。
`typescript
// 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..."
}
`
$3
クラスタ監視。ブロッキングイベント発生時に即座に返す。
`typescript
// 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"]
}
}
`
$3
ユーザー応答（承認またはメッセージ）を送信。
`typescript
// Input
{
sessionId: "...",
action: "approve_plan" | "send_message",
message?: "Proceed with plan"
}
// Output
{
success: true,
message: "Plan approved. Session resumed.",
newState: "RUNNING"
}
`
$3
セッション詳細を取得。
`typescript
// 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"
}
`
$3
セッションを停止・削除。
`typescript
// Input
{
sessionId: "..."
}
// Output
{
success: true,
message: "Session cancelled.",
removedFromCluster: true
}
`
$3
既存のJulesセッションをクラスターに追加してモニタリング対象にする。
dispatch_session 以外で作成されたセッションを管理したい場合に使用。
`typescript
// 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"
}
`
$3
MCPでdispatchしたセッションのみのクラスタ全体のステータス。
※ Jules API の全セッションを見るには list_all_sessions を使用。
`typescript
// 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."
}
`
$3
Jules API の全セッションを取得（MCP以外で作成されたセッションも含む）。
`typescript
// 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."
}
`
$3
特定のリポジトリに関連するセッションのみをフィルタリング取得。
`typescript
// 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 │
└──────────┘
`
---
設定・認証
$3
1. Google Cloud Console にアクセス
2. Jules API を有効化
3. API キーを作成（制限: Jules API のみ）
4. キーを .env または環境変数 JULES_API_KEY に設定
$3
- API キーを環境変数で管理（コードにハードコード禁止）
- IP 制限を設定
- キーのローテーション定期実施
- .env を .gitignore に追加
---
トラブルシューティング
$3
`
Error: JULES_API_KEY is required
`
→ .env を確認、または環境変数を設定
$3
→ Jules API キーが無効（期限切れまたは権限不足）
$3
→ ソース名を list_sources で確認
---
参考資料
- 設計書: design.md（完全な技術仕様）
- セットアップ: SETUP.md`（詳細な導入ガイド）