# Jules MCP Gateway

An independent, self-hostable remote MCP gateway for one Google Jules account. It targets Cloudflare Workers **Free**, with a small authentication KV namespace and no task database or always-on server.

**Validation status:** all 13 tools are implemented. Real dependencies are installed and locked; formatting, policy lint, full TypeScript checking, unit/contract tests, Worker-runtime OAuth/MCP integration, schema checks, dependency audit and both Wrangler dry runs pass locally. **Not deployed or verified in ChatGPT.** See [implementation status](docs/implementation-status.md) for exact evidence and remaining live gates.

## What it does

A trusted MCP client can start work on `acme/widgets`; another authorised client can inspect that session, send feedback or approve its plan. Clients have independent credentials but share the deployment’s Jules account. Revoking a credential is not tenant isolation. A control credential has all implemented Jules control authority, without a gateway action-approval queue. Your MCP host may still request confirmations.

The gateway lists/gets connected sources, resolves exact `owner/repo` addresses, creates/lists/gets/deletes sessions, sends messages, approves plans, lists/gets activities and returns bounded selected change sets. It does not connect repositories to Jules, invent cancellation, merge PRs, execute a remote shell or supervise tasks after a chat ends.

## Architecture

Hosted clients use OAuth with S256 PKCE; compatible machine clients use independently revocable bearer credentials. Both reach the same authenticated HTTPS `/mcp` endpoint in a stateless Worker, which calls the fixed Jules API origin. KV holds authentication records only.

The official MCP SDK and Cloudflare’s stateless `createMcpHandler` own transport and negotiation. Cloudflare’s maintained OAuth provider owns OAuth token/grant mechanics. A small GitHub identity flow admits only the configured stable GitHub user ID, without requesting repository scopes. Dynamic registration and CIMD are off; OAuth clients are pre-registered through a separate owner-operated bootstrap credential. The application stores no Jules sessions or repository cache.

## First checks without installing dependencies

With Node 22.16 or newer:

```sh
node scripts/run-core-tests.mjs
node scripts/lint.mjs
node scripts/scan-public.mjs
node --experimental-strip-types scripts/check-schema.mjs
```

These checks do **not** establish MCP transport, OAuth-provider compatibility, Cloudflare CPU usage or hosted-client support.

For the complete validation gate, use pnpm and a network-enabled environment:

```sh
npm install --global pnpm@10.13.1
pnpm install --frozen-lockfile
pnpm check
```

The checked-in lockfile is generated by pnpm 10.13.1. Use that version for local and CI validation. The historical bootstrap command remains available for intentional dependency refreshes, not normal installation.

## Ordinary ChatGPT chat: an explicit feasibility gate

A service-token-only endpoint is not enough to establish hosted ChatGPT compatibility. Deploy the separate `src/feasibility.ts` entrypoint with the same OAuth stack, connect it in the actual ChatGPT web account, perform authenticated discovery/read/benign write, refresh/reconnect and revoke the grant. The diagnostic writes only a random expiring nonce; it never calls Jules and needs no Jules key.

Current OpenAI developer and Help Center pages disagree about Pro write access. This repository does not claim the actual account has passed or failed. ChatGPT web, Android, Codex cloud, Grokbot and consumer Grok are distinct client surfaces. See [client compatibility](docs/client-compatibility.md) and [Stage-0 runbook](docs/feasibility.md).

## Documentation

[Deployment](docs/deployment.md) · [Authentication](docs/authentication.md) · [Architecture](docs/architecture.md) · [API coverage](docs/api-coverage.md) · [Operations](docs/operations.md) · [Threat model](docs/threat-model.md) · [Security](SECURITY.md) · [Contributing](CONTRIBUTING.md).

## How this differs from Google’s package

Google Labs’ `@google/jules-mcp` offers a local process, orchestration/review tools and a local cache, under Apache-2.0, and describes itself as not officially supported by Google. This project instead implements a small remote, authenticated, Worker-oriented adapter to the documented Jules API. It does not copy or import the local cache architecture. It reuses maintained protocol/authentication libraries rather than reimplementing OAuth.

Original code is MIT. Dependency licences remain their own. This is not an officially supported Google, Cloudflare or OpenAI product.