# Jules MCP Server (`jules-mcp`)

Universal Model Context Protocol (MCP) server for Google Jules Cloud Agent with 100% native REST API coverage, multi-account pooling, automated load balancing, 24-hour rolling quota ledger, container test runner auto-injection, standardized chore recipes, persistent quota queuing, file collision locks, exponential backoff retries, semantic conflict resolution, preflight conflict dry-runs, and multi-session 3-way consolidation.

### Key Capabilities:
1. **Parallel Cloud Dispatching**: Fire multiple chores on the same repo or across repos concurrently.
2. **Local 3-Way Patch Reconciliation (`jules_consolidate_sessions`)**: Fetches unidiff patches from all completed sessions, applies them sequentially with `git apply --3way` and semantic fallback for non-overlapping imports/functions, runs project test suites, and opens **1 clean consolidated GitHub PR**—eliminating PR collisions and branch drift completely.
3. **Preflight Dry-Run Conflict Check (`jules_verify_patch`)**: Evaluates a completed session's unidiff patch against a local workspace using `git apply --check --3way` before modifying any files or branches.
4. **Persistent Quota Task Queue (`jules_queue_status` / `jules_drain_queue`)**: Holds tasks in `~/.config/jules/queue.json` when the rolling 24-hour pool quota is saturated and drains them automatically as slots open up.
5. **In-Flight File Locks (`jules_inspect_locks`)**: Tracks active tasks per file in `~/.config/jules/locks.json` to prevent concurrent colliding modifications to the same file.
6. **Exponential Backoff & Network Jitter**: Retries transient Google Jules API drops (500/502/503/504, network drops, timeouts) with randomized exponential delay.
7. **Standardized Chore Recipes (`jules_recipe_dispatch`)**: High-efficiency blueprints for recurring grunt work (`scaffold-unit-test`, `add-strict-types`, `document-endpoints`, `clean-dead-code`, `refactor-isolated-helper`).
8. **Rolling 24-Hour Quota Ledger (`jules_pool_status`)**: Tracks timestamps for every dispatch across all 3 accounts in `~/.config/jules/usage.json`, ensuring guaranteed quota and predicting reset minutes with zero silent 429 errors.
9. **Container Test Runner Auto-Injection**: Detects repository stack (Python/FastAPI vs Next.js/TypeScript) and injects explicit container sandbox test instructions (`pytest` / `npm run build && npm test`) into Jules's execution prompt.
10. **Automated Remote PR Rebase (`jules_rebase_pr`)**: Rebases outdated cloud PRs against the latest `main` branch locally and force-pushes with lease.
11. **Zero Freeze Pauses**: Autonomous unblocking directives, auto-plan approvals, and `jules_auto_nudge_all`.

---

## Complete MCP Tool Reference (34 Tools)

### 1. Harness Intelligence, Queue & Multi-Session Consolidation
- **`jules_consolidate_sessions`** — Reconcile and merge multiple concurrent Jules sessions on the SAME repository into a single clean local branch or unified PR. Uses 3-way unidiff application and semantic conflict resolution to resolve cloud branch drift automatically, runs tests, and creates 1 clean PR.
- **`jules_verify_patch`** — Dry-run preflight check: inspects a completed session's git patch and runs `git apply --check --3way` against a local workspace to verify whether the patch will apply cleanly with 0 conflicts before creating branches or writing files.
- **`jules_recipe_dispatch`** — Dispatch a standardized, high-efficiency chore recipe with pre-tested prompt blueprints (`scaffold-unit-test`, `add-strict-types`, `document-endpoints`, `clean-dead-code`, `refactor-isolated-helper`).
- **`jules_queue_status`** — Inspect persistent task queue (`~/.config/jules/queue.json`), queued backlog depth, available pool slots, and countdown to earliest slot reset.
- **`jules_drain_queue`** — Drain and dispatch queued tasks to Google Jules accounts with newly available 24h rolling quota slots.
- **`jules_inspect_locks`** — List active in-flight file locks across repositories to monitor parallel task partitioning and prevent file collisions.
- **`jules_rebase_pr`** — Rebases an existing Jules PR against latest `main` branch locally and force-pushes with lease, eliminating GitHub out-of-date branch warnings.
- **`jules_check_events`** — Real-time event monitor for the entire multi-account pool: detects stuck tasks, plans needing approval, completed tasks, and failures.
- **`jules_auto_nudge_all`** — Pool-wide autonomous unblocker: unblocks all sessions paused in `AWAITING_USER_FEEDBACK` with standard execution directives.
- **`jules_wait_for_task`** — Synchronously blocks/polls for a session until completion or input request with automatic plan approval and auto-unblocking.
- **`jules_dispatch_and_wait`** — Single-call chore execution: decorates prompt with architectural guardrails, dispatches to least-loaded account, and waits.
- **`jules_queue_tasks`** — Sequentially executes a pipeline of chores on the same repo (waits for Task N before launching Task N+1).
- **`jules_stream_progress`** — Generates a structured markdown execution timeline: step-by-step plan checklist `[x]`, internal thought reasoning trail, files modified, and sandbox bash commands.

### 2. Local Git & GitHub PR Automation
- **`jules_apply_patch`** — Fetches clean unidiff patches from completed sessions and applies them directly into a local git repository, creates fix branches, executes test suites (`npm test` / `pytest`), and auto-commits.
- **`jules_review_pr`** — Inspects GitHub Pull Requests opened by Jules (diff stats, review comments, CI status checks) via `gh`.
- **`jules_merge_pr`** — Safely squash-merges verified GitHub PRs and cleans up remote branches.
- **`jules_sync_prs`** — Local PR sync runner: applies patches, verifies locally with tests, and creates GitHub PRs.

### 3. Task Dispatching & Multi-Account Load Balancing
- **`jules_create_task`** — Dispatches tasks with architectural invariant decoration, container test directives, anti-pause directives, target branches, custom working branch, automated PR creation (`AUTO_CREATE_PR`), and plan approval mode.
- **`jules_batch_dispatch`** — Launches multiple tasks across repositories simultaneously with multi-account load balancing.
- **`jules_pool_status`** — Live status of all configured Google accounts (quotas, 24h rolling usage ledger, active in-flight count, completed count, next reset minutes).

### 4. Source & Repository Discovery
- **`jules_list_sources`** — Lists connected GitHub repositories across all accounts with branch metadata, default branches, and AIP-160 filter support.
- **`jules_get_source`** — Inspects repository details and all branches for a target repo.

### 5. Interactive Feedback & Plan Approvals
- **`jules_get_plan`** — Extracts structured step-by-step plans generated by Jules.
- **`jules_approve_plan`** — Approves a plan to unblock code implementation.
- **`jules_reply_feedback`** — Sends messages and instructions directly to Jules when paused in `AWAITING_USER_FEEDBACK`.

### 6. Artifacts, Terminal Logs & Outputs
- **`jules_get_session`** — Retrieves full session details, PR URL, git patch, and execution timeline.
- **`jules_get_patch`** — Extracts clean git unidiff patches and suggested commit messages.
- **`jules_inspect_bash_logs`** — Extracts all terminal shell commands executed inside Google's cloud sandbox with exit codes and stdout/stderr output.
- **`jules_get_media_artifacts`** — Extracts visual media (screenshots, diagrams, test failure images) generated in the container.
- **`jules_list_activities`** — Streams granular activity trails with pagination.
- **`jules_get_activity`** — Retrieves a single activity event payload.

### 7. Session Lifecycle
- **`jules_list_sessions`** — Filters sessions across accounts by state, repository, or AIP-160 filter.
- **`jules_archive_session`** — Archives or unarchives sessions.
- **`jules_delete_session`** — Permanently deletes a session across accounts.

---

## Configuration

### Multi-Account Pool (`~/.config/jules/keys.json`)
```json
{
  "accounts": [
    { "name": "Primary", "email": "yasser040503@gmail.com", "key": "[REDACTED]" },
    { "name": "Secondary", "email": "bousrihyasser@gmail.com", "key": "[REDACTED]" },
    { "name": "Tertiary", "email": "yasserbousrih0405@gmail.com", "key": "[REDACTED]" }
  ]
}
```

### Build & Run
```bash
npm run build
npm test
```