@ezmodo/mcp-server 0.13.5 → 0.14.1

package/lib/http-client.js

@@ -10,11 +10,13 @@ import { CONFIG } from '../config/index.js';
 import { MCP_VERSION } from './version.js';
 import { getLogger } from './logger.js';
 import { getApiUrl } from './env.js';
-// Not getApiKey() directly: over HTTP one process serves many callers, so the
-// credential belongs to the request in flight rather than the process (#2599).
-// Over stdio there is no request context and this resolves to the environment,
-// exactly as before.
-import { resolveApiKey } from './request-context.js';
+// Not getApiKey() directly. Two reasons, both about the credential belonging to
+// the CALL rather than the process: over HTTP one process serves many callers,
+// each with their own key (#2599); and over stdio the credential may be an
+// OAuth token this server obtained for itself, which can need refreshing before
+// use (#2631). lib/credentials.js owns the precedence between them.
+import { resolveCredential } from './credentials.js';
+import { NOT_AUTHENTICATED } from './auth-guidance.js';
 
 // API base URL is resolved per-request (see callZephlyAPI): getApiUrl() honors
 // the EZMODO_API_URL / ZEPHLY_API_URL override; CONFIG.apiUrl is the build-time
@@ -82,8 +84,19 @@ export async function callZephlyAPI(endpoint, data) {
   let url = `${apiUrl}/${route}`;
   let body = null;
 
+  // Resolved per call, and awaited: an expired OAuth token refreshes here.
+  const credential = await resolveCredential();
+  if (!credential) {
+    // Coded, not just worded: lib/create-server.js turns this into sign-in
+    // guidance for the agent, and matching on a message would break the first
+    // time someone reworded it.
+    const error = new Error('Not authenticated with EzModo.');
+    error.code = NOT_AUTHENTICATED;
+    throw error;
+  }
+
   const headers = {
-    'Authorization': `Bearer ${resolveApiKey()}`,
+    'Authorization': `Bearer ${credential.token}`,
     'Content-Type': 'application/json',
     'User-Agent': `ezmodo-mcp-server/${MCP_VERSION}`,
     'X-MCP-API-Version': 'v1',
@@ -150,6 +163,12 @@ export async function callZephlyAPI(endpoint, data) {
     // status and retryable let callers back off on a 503 instead of giving up
     // the way a 404 tells them to.
     thrown.status = response.status;
+    // A machine-readable code, when the API sent one. Carried so a caller can
+    // branch on the KIND of failure rather than on its prose — the no-organization
+    // 403 (#2639) is answered with specific guidance, and every other 403 is not.
+    if (typeof error.code === 'string' && error.code) {
+      thrown.code = error.code;
+    }
     if (typeof error.retryable === 'boolean') {
       thrown.retryable = error.retryable;
     }

package/lib/instructions.generated.js

@@ -0,0 +1,14 @@
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ *
+ * Extracted from plugins/ezmodo/skills/work-tracking/SKILL.md by
+ * scripts/build-instructions.mjs. Edit the SKILL, then run:
+ *
+ *   npm run generate:instructions --workspace=@ezmodo/mcp-server
+ *
+ * __tests__/instructions.test.js fails if this drifts from the skill.
+ */
+
+export const WORK_TRACKING_CORE = 'Work in this repository is tracked in EzModo, and the tools for it are on this\nMCP server. The contract, in short:\n\n1. **Create the task before you edit, not after.** A task written afterwards is\n   a changelog; a task written first is what the next session reads to find out\n   what you were doing and why.\n2. **Start the session by calling `get_current_project_context()`.** Cache the\n   `projectId`. It also returns the components, tags and `terminology` you need.\n   No `.ezmodo/config.json` means this repo is not tracked — say so rather than\n   guessing at a project.\n3. **Call `get_context` with a keyword query before creating anything.** Use\n   what comes back to write a task that names real files, endpoints and\n   patterns. A vague task is not worth the call that made it.\n4. **Name every component the work touches** via `componentIds`. A task spanning\n   web and api belongs to both. The list REPLACES the previous set on update.\n5. **Set `taskType`** — `feature` | `bug` | `testing` | `chore`. Not cosmetic:\n   `bug` feeds open-bug counts, milestone freezes gate on it, and estimation\n   weights past tasks of the same kind.\n6. **Toggle steps as you finish them**, not in a batch at the end\n   (`manage_task action:"update" toggleSteps:[...]`).\n7. **Capture knowledge the moment it happens**, not in a summary at the end:\n   `addKnowledge` with `fact` for a root cause, `decision` for a choice —\n   including what you rejected and why — `reference` for a key file or pattern,\n   `context` for progress. Be specific: file paths, function names, exact\n   errors. "Fixed a bug in the parser" helps nobody.\n8. **Already three edits in with no task?** Call `report_untracked_work` the\n   moment you notice, rather than continuing untracked.\n9. **Resuming?** `get_task` first, and read ALL of its knowledge items. That is\n   where the previous session\'s reasoning went — do not re-derive it.\n10. **Finish at `in_review`** with `completionNotes`, and do NOT call\n    `action:"complete"`. A human completes a task after verifying it.\n11. **Report what actually happened.** A task moved to `in_review` claiming work\n    that was not done is worse than no task, because the next session trusts it.\n\nRespect the project\'s `terminology`: a project can rename epics, tasks and\ncomponents, and a marketing project calls an epic a "Campaign". Write anything a\nhuman reads in those words; keep API field names (`epicId`, `taskId`) as they\nare.';
+
+export const WORK_TRACKING_LOCAL = 'Running against a local checkout, two more:\n\n12. **Link every commit**: `manage_task action:"link_commit"` with the full\n    40-character `sha` from `git rev-parse HEAD`. A short SHA is rejected, and\n    padding one is not a fix. Linking is also what derives component links from\n    the commit\'s files — do not link those by hand.\n13. **Pass `changedFiles`** when creating or updating a task, so the work\n    resolves to the components that own those paths.';

package/lib/instructions.js

@@ -0,0 +1,37 @@
+/**
+ * The MCP `instructions` string — what the server tells every client about how
+ * to work with it (#2633).
+ *
+ * WHY THIS MATTERS OUT OF PROPORTION TO ITS SIZE. The tools were always the
+ * easy half. What makes an agent actually TRACK work — create a task before you
+ * edit, tick steps off, capture knowledge, link the commit, finish at
+ * in_review — shipped only as Claude Code skills in plugins/ezmodo/skills/.
+ * Cursor, Codex, Zed and every other stdio MCP client got the tools and none of
+ * the discipline. The initialize result carries an instructions string that
+ * clients inject into system context, so this reaches all of them with no
+ * plugin, no per-editor packaging, and no install step.
+ *
+ * WHY IT IS SHORT. A skill is loaded on demand and can afford several hundred
+ * lines. Instructions are paid for on every session, so this is the irreducible
+ * core and nothing else. The full contract stays in the skill, and the two are
+ * the same words — see scripts/build-instructions.mjs for how, and why they are
+ * not two hand-maintained copies.
+ *
+ * WHY IT VARIES BY SURFACE. The remote connector serves no local-machine tools,
+ * so telling an agent there to link commits and pass changed files is advice it
+ * cannot follow — worse than silence, because an agent that tries will report a
+ * failure the user cannot act on. The local block is appended only for stdio,
+ * on the same `surface` parameter that filters the tool list.
+ */
+
+import { WORK_TRACKING_CORE, WORK_TRACKING_LOCAL } from './instructions.generated.js';
+
+/**
+ * @param {'local'|'remote'} [surface]
+ * @returns {string}
+ */
+export function getInstructions(surface = 'local') {
+  return surface === 'remote'
+    ? WORK_TRACKING_CORE
+    : `${WORK_TRACKING_CORE}\n\n${WORK_TRACKING_LOCAL}`;
+}

package/lib/oauth-config.js

@@ -0,0 +1,98 @@
+/**
+ * Keycloak OIDC configuration for the local (stdio) MCP server.
+ *
+ * WHY THE SERVER LOGS IN AT ALL. Installing used to be two steps, and the
+ * second one is the cumbersome one: install the server, then leave the agent,
+ * open the web UI, mint an API key, paste it into a shell profile, restart.
+ * That step is identical for Cursor, Codex, Zed or anything else speaking
+ * stdio MCP, and it is what makes people reach for the CLI. The server signs
+ * itself in instead, so installing IS the whole install (E-252 #2631).
+ *
+ * WHY `ezmodo-mcp` AND NOT `ezmodo-cli`. Both are public PKCE clients in the
+ * `ezmodo` realm and either would authenticate, since the API skips the
+ * audience check (KEYCLOAK_CLIENT_ID is deliberately empty in
+ * infra/cloud-run-api-ezmodo.tf). Three things decide it:
+ *
+ *   1. Redirect URIs. `ezmodo-cli` registers ONE fixed loopback,
+ *      http://localhost:19838/callback. A fixed port fails when it is already
+ *      taken — including by an `ezmodo auth login` running in another terminal,
+ *      which is exactly when a user is most likely to be signing in.
+ *      `ezmodo-mcp` registers http://localhost/* and http://127.0.0.1/*, which
+ *      matches ANY ephemeral port: Keycloak's RedirectUtils, on a failed match
+ *      for an http URI whose host is a loopback interface, rebuilds it with
+ *      port 80 and re-matches.
+ *   2. Consent. `ezmodo-mcp` sets consent_required. The whole argument for
+ *      preferring OAuth over a pasted key is that the user SEES what they are
+ *      granting; a client that skips the consent screen throws that away.
+ *   3. It is what this is. `ezmodo-mcp` is the MCP client, and the scopes a
+ *      human reads on the consent screen are attached to it.
+ *
+ * The client id is baked in, not pasted. That is why Keycloak's refusal of
+ * anonymous Dynamic Client Registration — the thing that makes a claude.ai
+ * connector user paste `ezmodo-mcp` by hand — does not touch a local install
+ * at all.
+ */
+
+import { CONFIG } from '../config/index.js';
+
+/**
+ * Keycloak per environment. Mirrors cli/src/lib/config.ts KEYCLOAK_CONFIG; the
+ * realm is `ezmodo` everywhere, including local, so a client that works on a
+ * laptop works in production.
+ */
+const KEYCLOAK = {
+  production: { url: 'https://auth.ezmodo.com', realm: 'ezmodo' },
+  staging: { url: 'https://auth.staging.ezmodo.com', realm: 'ezmodo' },
+  development: { url: 'http://localhost:7373', realm: 'ezmodo' },
+};
+
+/** The public PKCE client this server authenticates as. */
+export const OAUTH_CLIENT_ID = 'ezmodo-mcp';
+
+/**
+ * What we ask consent for, and deliberately NOT everything on offer.
+ *
+ * `ezmodo:delete` is a registered optional scope and is left out by default.
+ * Keycloak's consent screen is accept-or-decline over the whole requested set,
+ * so asking for it would make "permanently delete your tasks, documents, goals
+ * and projects" a condition of installing an MCP server — which is not a
+ * decision to bundle into a setup step someone is clicking through. The MCP
+ * tool surface is overwhelmingly create/update anyway; almost nothing here
+ * deletes.
+ *
+ * `offline_access` is what makes the refresh token outlive the short access
+ * token, i.e. what stops this asking for a browser every few minutes.
+ *
+ * Override with EZMODO_OAUTH_SCOPES (space-separated) to widen or narrow it —
+ * that is the escape hatch for someone who genuinely wants delete, without
+ * making it everyone's default.
+ */
+export const DEFAULT_SCOPES = 'openid email profile offline_access ezmodo:read ezmodo:write';
+
+/** The scopes to request, honouring the override. */
+export function getScopes() {
+  const override = process.env.EZMODO_OAUTH_SCOPES;
+  return override && override.trim() ? override.trim() : DEFAULT_SCOPES;
+}
+
+/**
+ * Keycloak endpoints for the environment this build targets.
+ *
+ * Falls back to production for an unrecognised environment for the same reason
+ * config/index.js defaults BUILD_ENV to production: the only caller that
+ * arrives here with nothing set is an installed copy on a real user's machine,
+ * and pointing that at localhost fails with an error saying nothing about why.
+ */
+export function getKeycloakEndpoints() {
+  const env = KEYCLOAK[CONFIG.environment] ? CONFIG.environment : 'production';
+  const { url, realm } = KEYCLOAK[env];
+  const base = `${url}/realms/${realm}/protocol/openid-connect`;
+  return {
+    environment: env,
+    issuer: `${url}/realms/${realm}`,
+    authorization: `${base}/auth`,
+    token: `${base}/token`,
+    logout: `${base}/logout`,
+    clientId: OAUTH_CLIENT_ID,
+  };
+}

package/lib/oauth.js

@@ -0,0 +1,353 @@
+/**
+ * Authorization Code + PKCE sign-in, run by the MCP server for itself (#2631).
+ *
+ * Ported from cli/src/lib/oauth-login.ts, oauth-callback-server.ts and
+ * token-refresh.ts rather than imported from them. This package is published to
+ * npm and launched with `npx @ezmodo/mcp-server`; it must not require the CLI
+ * to be installed. lib/cli-credential.js re-implements the CLI's credential
+ * read for the same reason, and records the same trade-off: when the CLI's
+ * formats move, a copy goes stale and stops working, which is the safe
+ * direction to fail in.
+ *
+ * WHAT IS DIFFERENT FROM THE CLI'S COPY, and why:
+ *
+ *   - An EPHEMERAL loopback port, not the CLI's fixed 19838. The `ezmodo-mcp`
+ *     client registers http://localhost/* and http://127.0.0.1/*, so any port
+ *     matches; a fixed port would collide with a concurrent `ezmodo auth
+ *     login`, which is precisely when someone is likely to be signing in.
+ *   - NOTHING is written to stdout. Over stdio, stdout IS the MCP protocol
+ *     channel — a stray console.log is a protocol violation that corrupts the
+ *     session. The CLI's copy prints progress freely because it owns its
+ *     terminal. Here, diagnostics go to the logger (stderr) and anything the
+ *     user must read is returned to the caller to surface (#2632).
+ *   - Refresh is single-flight. Tool calls run concurrently, so several can
+ *     find the same expired token at once; without this they would each burn a
+ *     refresh token and all but one would fail, because Keycloak rotates it.
+ */
+
+import { createHash, randomBytes } from 'crypto';
+import { createServer } from 'http';
+import fetch from 'node-fetch';
+import { getKeycloakEndpoints, getScopes } from './oauth-config.js';
+import { clearTokens, isExpired, readTokens, writeTokens } from './token-store.js';
+import { getLogger } from './logger.js';
+
+/** How long to wait for the user to finish in the browser before giving up. */
+const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000;
+
+// ============================================================
+// PKCE primitives (RFC 7636)
+// ============================================================
+
+function generateState() {
+  return randomBytes(32).toString('hex');
+}
+
+function generateCodeVerifier() {
+  return randomBytes(32)
+    .toString('base64url')
+    .replace(/[^a-zA-Z0-9\-._~]/g, '')
+    .substring(0, 128);
+}
+
+function generateCodeChallenge(verifier) {
+  return createHash('sha256').update(verifier).digest('base64url');
+}
+
+/**
+ * Read the `sub`, `email` and `exp` out of a JWT WITHOUT verifying it.
+ *
+ * Safe here, and only here: this token came from a TLS connection to the token
+ * endpoint moments ago, and nothing security-relevant is decided from these
+ * claims — they are stored so a human can be told which account is signed in.
+ * The API verifies the signature on every request, which is where that check
+ * belongs.
+ */
+function decodeJwtPayload(token) {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return {};
+    return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+// ============================================================
+// Loopback callback capture
+// ============================================================
+
+const DONE_PAGE = (heading, detail) => `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>EzModo</title>
+<style>
+ body{font-family:system-ui,-apple-system,"Segoe UI",sans-serif;background:#0f1115;color:#e8eaed;
+      display:flex;align-items:center;justify-content:center;height:100vh;margin:0}
+ main{text-align:center;max-width:26rem;padding:2rem}
+ h1{font-size:1.25rem;font-weight:600;margin:0 0 .5rem}
+ p{color:#9aa0a6;line-height:1.5;margin:0}
+</style></head>
+<body><main><h1>${heading}</h1><p>${detail}</p></main></body></html>`;
+
+/**
+ * Listen on an ephemeral loopback port for the authorization redirect.
+ *
+ * Resolves with the code once one arrives. The redirect URI is returned before
+ * the code is, because the caller needs the port to build the authorize URL —
+ * hence the two-stage shape rather than a single promise.
+ *
+ * @param {string} expectedState
+ * @returns {Promise<{ redirectUri: string, code: Promise<string>, close: () => void }>}
+ */
+function startCallbackServer(expectedState) {
+  return new Promise((resolveReady, rejectReady) => {
+    let settle;
+    const code = new Promise((resolve, reject) => {
+      settle = { resolve, reject };
+    });
+
+    let finished = false;
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      if (url.pathname === '/favicon.ico') {
+        res.writeHead(204).end();
+        return;
+      }
+
+      const fail = (message) => {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end(DONE_PAGE('Sign-in failed', message));
+        if (!finished) {
+          finished = true;
+          settle.reject(new Error(message));
+        }
+      };
+
+      const error = url.searchParams.get('error');
+      if (error) {
+        // Keycloak reports a refused consent here rather than by not
+        // redirecting, so this is the ordinary "user clicked Cancel" path.
+        const description = url.searchParams.get('error_description') || error;
+        fail(description);
+        return;
+      }
+
+      const received = url.searchParams.get('code');
+      const state = url.searchParams.get('state');
+      if (!received) {
+        fail('No authorization code in the callback.');
+        return;
+      }
+      if (state !== expectedState) {
+        // The CSRF check. A mismatch means this redirect was not the one we
+        // started, so the code must not be exchanged.
+        fail('State mismatch — this sign-in did not come from this request.');
+        return;
+      }
+
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(DONE_PAGE('You are signed in', 'You can close this tab and return to your editor.'));
+      if (!finished) {
+        finished = true;
+        settle.resolve(received);
+      }
+    });
+
+    server.on('error', (error) => {
+      if (!finished) {
+        finished = true;
+        settle.reject(error);
+      }
+      rejectReady(error);
+    });
+
+    const timer = setTimeout(() => {
+      if (!finished) {
+        finished = true;
+        settle.reject(new Error('Timed out waiting for the browser sign-in to complete.'));
+      }
+    }, CALLBACK_TIMEOUT_MS);
+    // Do not hold the process open purely to wait for a browser.
+    timer.unref?.();
+
+    const close = () => {
+      clearTimeout(timer);
+      server.close();
+    };
+    code.then(close, close);
+
+    // Port 0 = let the OS pick. 127.0.0.1 rather than a wildcard bind: this
+    // socket briefly accepts an authorization code, and it has no business
+    // being reachable from the network.
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      resolveReady({ redirectUri: `http://127.0.0.1:${port}/callback`, code, close });
+    });
+  });
+}
+
+// ============================================================
+// Token endpoint
+// ============================================================
+
+async function postToken(body) {
+  const endpoints = getKeycloakEndpoints();
+  const response = await fetch(endpoints.token, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(body).toString(),
+  });
+
+  const text = await response.text();
+  if (!response.ok) {
+    const error = new Error(`Token request failed (${response.status}): ${text}`);
+    error.status = response.status;
+    throw error;
+  }
+  return JSON.parse(text);
+}
+
+/** Turn a Keycloak token response into what the store holds. */
+function toStoredTokens(response) {
+  const claims = decodeJwtPayload(response.access_token);
+  return {
+    accessToken: response.access_token,
+    refreshToken: response.refresh_token,
+    expiresAt: new Date(Date.now() + (response.expires_in ?? 60) * 1000).toISOString(),
+    userId: claims.sub,
+    email: claims.email || claims.preferred_username,
+    scope: response.scope,
+    issuer: getKeycloakEndpoints().issuer,
+  };
+}
+
+// ============================================================
+// Sign-in
+// ============================================================
+
+/**
+ * Build the authorize URL and start listening for its redirect.
+ *
+ * Split from the wait deliberately: the caller needs the URL to hand to the
+ * user (in a tool result, or a browser it opened) BEFORE anyone can complete
+ * the flow. Returning both at once would mean the URL only became available
+ * after it was already too late to show it.
+ *
+ * @returns {Promise<{ authUrl: string, complete: () => Promise<StoredTokens>, cancel: () => void }>}
+ */
+export async function beginLogin() {
+  const endpoints = getKeycloakEndpoints();
+  const state = generateState();
+  const verifier = generateCodeVerifier();
+  const challenge = generateCodeChallenge(verifier);
+
+  const { redirectUri, code, close } = await startCallbackServer(state);
+
+  const authUrl = new URL(endpoints.authorization);
+  authUrl.searchParams.set('response_type', 'code');
+  authUrl.searchParams.set('client_id', endpoints.clientId);
+  authUrl.searchParams.set('redirect_uri', redirectUri);
+  authUrl.searchParams.set('scope', getScopes());
+  authUrl.searchParams.set('state', state);
+  authUrl.searchParams.set('code_challenge', challenge);
+  authUrl.searchParams.set('code_challenge_method', 'S256');
+
+  getLogger().debug('OAuth sign-in started', { redirectUri, environment: endpoints.environment });
+
+  const complete = async () => {
+    const authorizationCode = await code;
+    const response = await postToken({
+      grant_type: 'authorization_code',
+      client_id: endpoints.clientId,
+      code: authorizationCode,
+      redirect_uri: redirectUri,
+      code_verifier: verifier,
+    });
+    const tokens = toStoredTokens(response);
+    writeTokens(tokens);
+    getLogger().info('OAuth sign-in complete', { email: tokens.email });
+    return tokens;
+  };
+
+  return { authUrl: authUrl.toString(), complete, cancel: close };
+}
+
+// ============================================================
+// Refresh
+// ============================================================
+
+/**
+ * In-flight refresh, shared by every caller that arrives while it runs.
+ *
+ * Keycloak ROTATES refresh tokens: the old one dies the moment the new one is
+ * issued. Two concurrent refreshes therefore do not merely waste a round trip,
+ * they race to invalidate each other, and the loser signs the user out. One
+ * promise, awaited by all.
+ */
+let refreshInFlight = null;
+
+async function refreshTokens(tokens) {
+  const endpoints = getKeycloakEndpoints();
+  try {
+    const response = await postToken({
+      grant_type: 'refresh_token',
+      client_id: endpoints.clientId,
+      refresh_token: tokens.refreshToken,
+    });
+    const refreshed = toStoredTokens(response);
+    // Keycloak may omit a new refresh token; keep the old one when it does,
+    // or the next refresh has nothing to present.
+    if (!refreshed.refreshToken) refreshed.refreshToken = tokens.refreshToken;
+    writeTokens(refreshed);
+    return refreshed;
+  } catch (error) {
+    // 400 from the token endpoint on a refresh means the grant is dead —
+    // expired, revoked, or already rotated. Keeping it would retry forever
+    // against something that can never succeed, so drop it and let the caller
+    // ask for a fresh sign-in.
+    if (error.status === 400) {
+      getLogger().info('Refresh token no longer valid; signing out', { error: error.message });
+      clearTokens();
+      return null;
+    }
+    // Anything else (network, 5xx) is plausibly transient. Leave the stored
+    // tokens alone so a later call can try again.
+    getLogger().warn('Token refresh failed', { error: error.message });
+    return null;
+  }
+}
+
+/**
+ * A usable access token, refreshing if needed, or null when a sign-in is due.
+ *
+ * Null is the ONLY failure mode: every caller is on the path of a tool call,
+ * and "you need to sign in" is a message the agent can act on, whereas a thrown
+ * error is one it cannot.
+ *
+ * @returns {Promise<string|null>}
+ */
+export async function getAccessToken() {
+  const tokens = readTokens();
+  if (!tokens) return null;
+  if (!isExpired(tokens)) return tokens.accessToken;
+  if (!tokens.refreshToken) return null;
+
+  if (!refreshInFlight) {
+    refreshInFlight = refreshTokens(tokens).finally(() => {
+      refreshInFlight = null;
+    });
+  }
+  const refreshed = await refreshInFlight;
+  return refreshed?.accessToken ?? null;
+}
+
+/** Who is signed in, for diagnostics. Null when nobody is. */
+export function getSignedInIdentity() {
+  const tokens = readTokens();
+  if (!tokens) return null;
+  return { email: tokens.email, userId: tokens.userId, scope: tokens.scope };
+}
+
+/** Forget the stored tokens. */
+export function signOut() {
+  return clearTokens();
+}

package/lib/remote-tools.js

@@ -41,6 +41,12 @@
 
 /** Tools that operate on the local machine and are never served remotely. */
 export const LOCAL_ONLY_TOOLS = Object.freeze([
+  // Not a filesystem tool, but local for the same reason: over the connector
+  // Claude completes its own OAuth before any tool call, so a second sign-in
+  // offered there would be inert and confusing (#2632). It also opens a
+  // browser and binds a loopback port, neither of which means anything in a
+  // container.
+  'authenticate',
   'detect_git_repository',
   'get_current_project_context',
   'initialize_project_context',