[chenchenSimular]

Closes #16

Why

The add-mcp spike (#14, closed; decision in #15 (comment)) showed that Gemini CLI reads a plain mcpServers entry and signs in with OAuth by itself. Box can support it with our existing JSON writer and no new dependency. The spike also found two first-run gaps that don't need add-mcp; this PR carries those over too.

What

• Gemini CLI (--client gemini-cli, alias gemini), on json-client.js. It writes mcpServers.box = {"type": "http", "url": "https://relay.simular.cloud/mcp"} into ~/.gemini/settings.json, keeping comments and other settings. doctor and remove work as for the other JSON clients: only an entry that points at box is ours, a backup is kept, and old box-control entries are removed. A foreign box given as httpUrl is recognised too.
  • How it signs in (checked in the 0.66.0 bundle):
    • type: "http" makes Gemini CLI use streamable HTTP (url without a type would fall back to SSE on errors).
    • On a 401 it marks the server as needing OAuth and tells the user to run /mcp auth box.
    • /mcp auth finds the sign-in from the WWW-Authenticate header, with no oauth block needed. Without oauth.enabled, Gemini doesn't open a browser at every start; that matches the explicit sign-in step we use for the other clients.
  • Trusted folders: Gemini CLI loads MCP servers only in a trusted folder, so the hint says so.
• Permission errors. When a config can't be changed (EACCES/EPERM, or EBUSY on Windows), connect names the client's config and says the file or its folder may belong to another user, or the app may hold it open. For Codex it also prints the Codex app steps, for when the app holds the file: Settings → MCP servers → Add server, name it box, Streamable HTTP, paste the URL, Save, restart, Authenticate.
• Codex sign-in hint. With no codex on PATH (the Codex app alone), the hint points at the app's Settings → Authenticate instead of codex mcp login box.
• CI: gemini-cli (@google/gemini-cli@0.66.0) joins the real-client install matrix on Linux, macOS and Windows. The matrix seeds another server, runs connect, checks that gemini mcp list shows box: … (http), re-runs connect (no change), runs doctor, removes, and checks that the other server survived. The smoke dry run includes it.
• READMEs and package keywords list Gemini CLI.

Tests

• Unit:
  • Gemini round trip: comments and settings kept, idempotent, one backup, remove.
  • Foreign httpUrl box left alone.
  • Gemini added to the foreign-box and dry-run sweeps.
  • EACCES on Codex's config prints the app steps.
  • Codex hint without the CLI.
• Install matrix run locally on macOS: gemini-cli, codex and opencode all OK. All three OSes run in CI on this PR.

Review

An independent review (simular-code-review plus secure-coding invariant review) found nothing blocking.

• Gemini entry: checked against the 0.66.0 bundle and the live relay. It covers streamable HTTP, the 401 auth-required path, and /mcp auth discovery with DCR and iss.
• Fixed in the second commit: the permission message printed err.path, which can be a temp file or a file whose folder is the real problem, so it now names the config. EBUSY is now covered.
• Not verified: the Codex app's "Add server" when ~/.codex belongs to root. The app likely writes the same file, so the steps are worded for the case where the app holds the file. The interactive Gemini browser sign-in was not run end to end.

🤖 Generated with Claude Code