Launch the server via mcp-remote to fix OAuth connection

[simoncoombes]

Why

Installing the extension and signing in currently leaves the server Disconnected. Gemini CLI reports Successfully authenticated then Failed to refresh auth token, and /mcp shows transform - Disconnected (OAuth not authenticated).

Root cause is upstream: google-gemini/gemini-cli#27745. Gemini CLI's native remote-OAuth path does not attach the token it just acquired on the request following sign-in for servers that use Dynamic Client Registration / auto-discovered OAuth (which the Transform server does). The server completes the token exchange and returns valid tokens; the CLI drops them. It affects every DCR-based HTTP MCP server, not just this one, and is unfixed as of 0.50.

What

Launch the transform server through npx -y mcp-remote <url> instead of the native httpUrl transport. mcp-remote performs the OAuth flow correctly and caches the token, so sign-in is a one-time browser step. This is the same OAuth approach our Cline integration already uses. Cost is a Node.js 18+ / npx runtime requirement, now documented in the README.

• gemini-extension.json: httpUrl -> command/args, version 0.1.0 -> 0.2.0
• README.md: install/auth steps updated (one-time browser sign-in on first use; Node/npx requirement)
• AGENTS.md: re-auth guidance made client-agnostic (was /mcp auth transform)
• CONTRIBUTING.md: new Transport section explaining the choice and how to revert to native once #27745 ships
• scripts/validate.sh: reads the canonical URL from args now; mutation-tested that the mismatch guards still fire

Verification

Tested the whole chain on Gemini CLI 0.50.0: gemini extensions install from the repo, one-time browser OAuth via mcp-remote (token cached under ~/.mcp-auth), /mcp shows transform Connected with 4 tools, and a real HTML file parsed to markdown end-to-end (headings + table preserved). ./scripts/validate.sh passes.

---

Summary by cubic

Fixes OAuth sign-in for the transform MCP server by launching it via mcp-remote instead of the native httpUrl transport. Users now complete a one-time browser sign-in; the token is cached and the server connects reliably.

• Bug Fixes

  • Route the server through npx -y mcp-remote https://mcp.transform.unstructured.io in gemini-extension.json (version bumped to 0.2.0) to work around the Gemini CLI remote‑OAuth bug.
  • Update docs: install/auth flow and transport rationale (README.md, CONTRIBUTING.md), and client-agnostic re-auth guidance (AGENTS.md).
  • Update scripts/validate.sh to read the canonical URL from args and retain mismatch checks.

• Migration

  • Requires Node.js 18+ with npx on PATH.
  • Restart the session to trigger the browser sign-in once; tokens are cached.

^{Written for commit f452f46. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 5 files

_{Re-trigger cubic}