@sutraspaces/mcp-server 1.1.1 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Sutra MCP Server
 
-An [MCP](https://modelcontextprotocol.io) server that connects AI agents to the [Sutra Admin API](https://sutra.co). Manage spaces, members, contacts, content, discussions, surveys, plans, broadcasts, and more — all through your AI tools.
+An MCP server that connects AI agents to the Sutra Admin API. Manage spaces, members, contacts, content, discussions, surveys, plans, broadcasts, and more — all through your AI tools. See the [Sutra developer docs](https://sutra.co/developers/docs) for API documentation.
 
 ## Quick Start
 
@@ -11,16 +11,45 @@ npm install -g @sutraspaces/mcp-server
 Or run directly with npx:
 
 ```bash
+# OAuth — opens your browser to log in on first run (recommended)
+npx -y @sutraspaces/mcp-server
+
+# Or with an API token (no browser)
 SUTRA_API_TOKEN="sutra_live_sk_..." npx -y @sutraspaces/mcp-server
 ```
 
-You can get an API token from your Sutra account settings or by contacting support@sutra.co.
+There are two ways to authenticate:
+
+- **OAuth (recommended)** — run the server with no token. It opens your browser, you log in to Sutra and approve access, and the token is cached locally (`~/.sutra/credentials.json`) and refreshed automatically. No copy-pasting keys.
+- **API token** — set `SUTRA_API_TOKEN`. Best for headless/server environments. Get a token from your Sutra account settings (**Settings → Sutra API**) or by contacting support@sutra.co.
+
+If `SUTRA_API_TOKEN` is set, the server uses it and skips OAuth.
+
+### Managing OAuth login
+
+```bash
+npx -y @sutraspaces/mcp-server login    # log in / re-authorize without starting the server
+npx -y @sutraspaces/mcp-server logout   # clear cached credentials
+```
 
 ## Usage
 
 ### Claude Desktop
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`. With OAuth, no token is embedded — the server opens your browser the first time it runs:
+
+```json
+{
+  "mcpServers": {
+    "sutra": {
+      "command": "npx",
+      "args": ["-y", "@sutraspaces/mcp-server"]
+    }
+  }
+}
+```
+
+To use an API token instead, add it under `env`:
 
 ```json
 {
@@ -36,22 +65,33 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
+If your client doesn't surface the login prompt on first start, run `npx -y @sutraspaces/mcp-server login` once in a terminal, then start the client.
+
 ### Claude Code
 
 ```bash
+# OAuth (opens browser on first run)
+claude mcp add sutra -- npx -y @sutraspaces/mcp-server
+
+# Or with an API token
 claude mcp add sutra -- env SUTRA_API_TOKEN=sutra_live_sk_... npx -y @sutraspaces/mcp-server
 ```
 
 ### Cursor / Windsurf / Other MCP Clients
 
-Point your MCP client at `npx -y @sutraspaces/mcp-server` with the `SUTRA_API_TOKEN` environment variable set. The server communicates over stdio.
+Point your MCP client at `npx -y @sutraspaces/mcp-server`. The server communicates over stdio. Leave the environment empty to authenticate with OAuth, or set `SUTRA_API_TOKEN` to use a token.
 
 ## Configuration
 
 | Variable | Required | Description |
 |---|---|---|
-| `SUTRA_API_TOKEN` | Yes | Your Sutra Admin API token (`sutra_live_sk_...`) |
+| `SUTRA_API_TOKEN` | No* | Your Sutra Admin API token (`sutra_live_sk_...`). *Required only if not using OAuth. When set, OAuth is skipped. |
+| `SUTRA_OAUTH_ISSUER` | No | OAuth issuer base URL (default: `https://sutra.co`). Must be `https://` (only loopback hosts may use `http://`). Separate from the Admin API URL. |
+| `SUTRA_SCOPES` | No | Space-separated scopes to request during OAuth login (default: all scopes your account can authorize) |
+| `SUTRA_CONFIG_DIR` | No | Directory for cached OAuth credentials (default: `~/.sutra`) |
 | `SUTRA_BASE_URL` | No | Override the API URL (default: `https://api.sutra.co/api/admin/v1`) |
+| `SUTRA_HELP_CENTER_TOKEN` | No | Internal scoped admin key (`sutra_admin_...`) for Lotus Help Center tools |
+| `SUTRA_HELP_CENTER_BASE_URL` | No | Override the Help Center API URL (default: `https://api.sutra.co/api/v4/lotus/help`) |
 
 ## Available Tools
 
@@ -64,10 +104,16 @@ Point your MCP client at `npx -y @sutraspaces/mcp-server` with the `SUTRA_API_TO
 - **get_space** — Get details for a single space
 - **list_child_spaces** — List direct child spaces
 - **create_space** — Create a new space (top-level or child)
+- **create_child_space** — Create a child space and make it visible through placement
+- **attach_child_space** — Attach an existing space under a parent and make it visible
+- **update_child_space_placement** — Move or repair a child space display
+- **detach_child_space** — Detach a child from one parent without deleting it
 - **update_space** — Update space name, description, type, privacy, or state
 - **delete_space** — Delete/archive a space
 - **reorder_child_spaces** — Reorder children within a parent
 
+Use `sp_...` IDs, not slugs. For normal course and section pages, use `placement.surface = "auto"`.
+
 ### Members
 - **list_members** — List space members with optional email, user_id, search, role, state, and custom property filtering
 - **get_member** — Get member details
@@ -86,8 +132,27 @@ Point your MCP client at `npx -y @sutraspaces/mcp-server` with the `SUTRA_API_TO
 - **bulk_update_contact_property_values** — Set or clear property values for up to 100 contacts at once
 
 ### Content & Discussions
-- **list_content** / **get_content_block** / **create_content** / **update_content** / **delete_content** — Manage content blocks
+- **get_document_capabilities** / **get_document** — Read document editing rules and the visible Tiptap document
+- **replace_document** / **insert_document_nodes** / **update_document_node** / **delete_document_node** / **move_document_node** — Edit visible document content by Tiptap node UID
+- **list_content** / **get_content_block** / **create_content** / **update_content** / **delete_content** — Legacy content-block mirror tools
 - **reorder_content** — Reorder content blocks within a space
+
+### Media Uploads
+- **create_media_upload** — Create a server-mediated direct-to-S3 upload session
+- **complete_media_upload** — Verify the uploaded object and queue video processing
+- **get_media_upload** — Read upload and processing status
+- **cancel_media_upload** — Abandon a pending upload
+- **create_media_reference** — Insert a Loom, YouTube, or Vimeo embed without uploading a file
+
+### Design Tools
+
+- **get_design_capabilities** — Read Sutra's renderer-aware design manifest
+- **get_space_design** — Read current page-design nodes and digest for a space
+- **validate_space_design** — Validate proposed page-design nodes
+- **create_or_update_design_draft** — Create or update a digest-guarded design draft
+- **publish_design_draft** — Publish a draft with conflict and destructive-omission protection
+- **restore_design_draft** — Restore the pre-publish backup for a published design draft
+- **import_design_asset** — Re-host an external image URL and return the canonical Sutra URL
 - **list_messages** / **get_message** / **create_message** / **update_message** / **delete_message** — Manage discussion messages
 - **list_reflections** / **get_reflection** / **create_reflection** / **update_reflection** / **delete_reflection** — Manage threaded replies
 
@@ -120,12 +185,24 @@ Point your MCP client at `npx -y @sutraspaces/mcp-server` with the `SUTRA_API_TO
 - **send_broadcast** — Send a broadcast to space members
 - **get_broadcast_delivery_status** — Check delivery progress
 
+### Help Center
+These tools are available only when `SUTRA_HELP_CENTER_TOKEN` is set.
+
+- **help_list_articles** / **help_get_article** — Read Lotus Help Center articles, metadata, and version history
+- **help_create_article** / **help_update_article** — Human/admin-style create and update through Lotus
+- **help_propose_article** — Submit an AI-authored draft as `ai_cobolt` and mark it pending human review
+- **help_propose_article_update** — Submit AI-authored changes to an existing article without publishing them
+- **help_review_article** — Approve or reject a pending article version
+- **help_publish_article** — Explicitly publish an article version
+- **help_list_collections** / **help_create_collection** / **help_update_collection** / **help_delete_collection** — Manage Help Center collections
+
 ## Available Resources
 
 - **sutra://admin-api/overview** — Core Admin API concepts, public ID prefixes, scopes, pagination, and filtering
 - **sutra://admin-api/membership-spaces** — Difference between admin-manageable spaces and limited membership-space inventory
 - **sutra://admin-api/contacts-properties** — Contact listing and member/contact property value workflows
 - **sutra://admin-api/people-filtering** — Member and contact search, email, state, role, and custom property filtering
+- **sutra://design/capabilities** — Renderer-aware design rules and supported fonts for Sutra page-design tools
 
 ## API Concepts
 
@@ -161,4 +238,4 @@ Point your MCP client at `npx -y @sutraspaces/mcp-server` with the `SUTRA_API_TO
 AI Agent → MCP Protocol (stdio) → sutra-mcp → Sutra Admin API → Sutra Platform
 ```
 
-The server is a thin, stateless wrapper. All data flows through the Sutra Admin API with Bearer token authentication. No data is cached or stored locally.
+The server is a thin, stateless wrapper. All data flows through the Sutra Admin API with Bearer token authentication. No Sutra customer data is cached or stored locally. The only thing written to disk is your OAuth credential cache at `~/.sutra/credentials.json` (file mode `600`), used to keep you logged in between runs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sutraspaces/mcp-server",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "MCP server for the Sutra Admin API — manage spaces, members, contacts, content, and more via AI agents",
   "type": "module",
   "main": "src/index.js",
@@ -12,7 +12,8 @@
     "README.md"
   ],
   "scripts": {
-    "start": "node src/index.js"
+    "start": "node src/index.js",
+    "test": "node --test"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
@@ -33,12 +34,12 @@
   ],
   "author": "Sutra <support@sutra.co> (https://sutra.co)",
   "license": "MIT",
-  "homepage": "https://github.com/joinsutra/mcp-server",
+  "homepage": "https://github.com/lorenzsell/sutra-mcp",
   "repository": {
     "type": "git",
-    "url": "https://github.com/joinsutra/mcp-server.git"
+    "url": "https://github.com/lorenzsell/sutra-mcp.git"
   },
   "bugs": {
-    "url": "https://github.com/joinsutra/mcp-server/issues"
+    "url": "https://github.com/lorenzsell/sutra-mcp/issues"
   }
 }

package/src/auth/oauth.js

@@ -0,0 +1,470 @@
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { generateCodeVerifier, generateCodeChallenge, generateState } from "./pkce.js";
+import { load, save, clear } from "./store.js";
+
+const LOGIN_TIMEOUT_MS = 300_000; // 5 minutes
+
+// ---------------------------------------------------------------------------
+// URL safety
+// ---------------------------------------------------------------------------
+
+const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+
+/**
+ * Require a URL to be HTTPS (or HTTP only for loopback dev hosts). This is the
+ * boundary that prevents the PKCE verifier, authorization code, and refresh
+ * token from ever being POSTed over plaintext to an attacker.
+ * @param {string} urlString
+ * @param {string} label
+ * @returns {URL}
+ */
+function assertHttpsOrLoopback(urlString, label) {
+  let u;
+  try {
+    u = new URL(urlString);
+  } catch {
+    throw new Error(`${label} is not a valid URL`);
+  }
+  const loopback = LOOPBACK_HOSTNAMES.has(u.hostname);
+  if (u.protocol !== "https:" && !(u.protocol === "http:" && loopback)) {
+    throw new Error(
+      `${label} must use HTTPS (got ${u.protocol}//${u.host}). ` +
+      `Set SUTRA_OAUTH_ISSUER to an https:// URL.`
+    );
+  }
+  return u;
+}
+
+/**
+ * Require an OAuth endpoint to be HTTPS/loopback AND same-origin as the issuer.
+ * Same-origin blocks a tampered or hijacked metadata document from redirecting
+ * the token exchange (and thus the verifier/refresh token) to another host.
+ * @param {string} urlString
+ * @param {string} issuerOrigin
+ * @param {string} label
+ */
+function assertEndpointSafe(urlString, issuerOrigin, label) {
+  const u = assertHttpsOrLoopback(urlString, label);
+  if (u.origin !== issuerOrigin) {
+    throw new Error(
+      `${label} (${u.origin}) is not on the same origin as the issuer ` +
+      `(${issuerOrigin}); refusing to use it.`
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Discovery
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch OAuth server metadata from the well-known endpoint.
+ * Falls back to conventional paths if discovery fails.
+ * @param {string} issuer
+ * @returns {Promise<{ authorization_endpoint: string, token_endpoint: string }>}
+ */
+export async function discoverMetadata(issuer) {
+  const issuerOrigin = assertHttpsOrLoopback(issuer, "SUTRA_OAUTH_ISSUER").origin;
+
+  const validate = (md) => {
+    assertEndpointSafe(md.authorization_endpoint, issuerOrigin, "authorization_endpoint");
+    assertEndpointSafe(md.token_endpoint, issuerOrigin, "token_endpoint");
+    return md;
+  };
+
+  const wellKnown = `${issuer}/.well-known/oauth-authorization-server`;
+  try {
+    const res = await fetch(wellKnown, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (res.ok) {
+      const ct = res.headers.get("content-type") ?? "";
+      if (ct.includes("json")) {
+        const data = await res.json();
+        if (data.authorization_endpoint && data.token_endpoint) {
+          return validate(data);
+        }
+      }
+    }
+  } catch (err) {
+    // A validation failure (untrusted endpoint) must propagate, not silently
+    // fall back. Only swallow network/timeout/parse errors.
+    if (err instanceof TypeError === false && /must use HTTPS|same origin/.test(err.message)) {
+      throw err;
+    }
+    // network error or timeout — fall through to defaults
+  }
+  // Fallback to conventional paths (same origin as issuer by construction).
+  return validate({
+    authorization_endpoint: `${issuer}/oauth/authorize`,
+    token_endpoint: `${issuer}/oauth/token`,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Browser opener
+// ---------------------------------------------------------------------------
+
+/**
+ * Open a URL in the system browser. Never throws.
+ * @param {string} url
+ */
+function openBrowser(url) {
+  try {
+    const cmd =
+      process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+        ? "start"
+        : "xdg-open";
+    // On win32 'start' is a shell built-in; needs shell:true
+    spawn(cmd, [url], {
+      detached: true,
+      stdio: "ignore",
+      shell: process.platform === "win32",
+    }).unref();
+  } catch {
+    // Swallow — we still print the URL to stderr
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Loopback HTTP server helpers
+// ---------------------------------------------------------------------------
+
+const SUCCESS_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8">
+<title>Sutra Login</title>
+<style>body{font-family:sans-serif;max-width:480px;margin:80px auto;text-align:center}
+h1{color:#1a7f5a}.check{font-size:64px}</style></head><body>
+<div class="check">&#10003;</div>
+<h1>You are logged in to Sutra</h1>
+<p>You can close this tab and return to your terminal.</p>
+</body></html>`;
+
+const ERROR_HTML = (msg) =>
+  `<!DOCTYPE html><html><head><meta charset="utf-8">
+<title>Sutra Login Error</title>
+<style>body{font-family:sans-serif;max-width:480px;margin:80px auto;text-align:center}
+h1{color:#c0392b}</style></head><body>
+<h1>Login failed</h1>
+<p>${escapeHtml(msg)}</p>
+<p>You can close this tab and check your terminal for details.</p>
+</body></html>`;
+
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Start an ephemeral loopback HTTP server on 127.0.0.1.
+ * Returns the server and its port.
+ * @returns {Promise<{ server: import("node:http").Server, port: number }>}
+ */
+function startCallbackServer() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (!addr || typeof addr === "string") {
+        reject(new Error("Failed to bind loopback server"));
+        return;
+      }
+      resolve({ server, port: addr.port });
+    });
+    server.on("error", reject);
+  });
+}
+
+/**
+ * Wait for the OAuth callback on the given server.
+ * Resolves with { code, state } or rejects with an Error.
+ * Sends a friendly HTML response to the browser.
+ * @param {import("node:http").Server} server
+ * @param {string} expectedState
+ * @param {number} timeoutMs
+ * @returns {Promise<{ code: string, state: string }>}
+ */
+function waitForCallback(server, expectedState, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      server.close();
+      reject(new Error("Login timed out — no callback received within 5 minutes"));
+    }, timeoutMs);
+
+    server.on("request", (req, res) => {
+      if (settled) {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      // Only handle /callback
+      const url = new URL(req.url, "http://127.0.0.1");
+      if (url.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+
+      const error = url.searchParams.get("error");
+      const errorDesc =
+        url.searchParams.get("error_description") ?? error ?? "Unknown error";
+      const code = url.searchParams.get("code");
+      const returnedState = url.searchParams.get("state");
+
+      if (error) {
+        settled = true;
+        clearTimeout(timer);
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(ERROR_HTML(errorDesc));
+        server.close();
+        reject(new Error(`OAuth error: ${errorDesc}`));
+        return;
+      }
+
+      if (returnedState !== expectedState) {
+        settled = true;
+        clearTimeout(timer);
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(ERROR_HTML("State mismatch — possible CSRF attempt. Please try again."));
+        server.close();
+        reject(new Error("OAuth state mismatch (CSRF check failed)"));
+        return;
+      }
+
+      if (!code) {
+        settled = true;
+        clearTimeout(timer);
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(ERROR_HTML("No authorization code received"));
+        server.close();
+        reject(new Error("OAuth callback missing authorization code"));
+        return;
+      }
+
+      // Success
+      settled = true;
+      clearTimeout(timer);
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(SUCCESS_HTML);
+      server.close();
+      resolve({ code, state: returnedState });
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Token exchange helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * POST to the token endpoint with application/x-www-form-urlencoded body.
+ * Returns the parsed JSON response or throws.
+ * @param {string} tokenEndpoint
+ * @param {Record<string, string>} params
+ * @returns {Promise<{ access_token: string, token_type: string, expires_in: number, refresh_token?: string, scope?: string }>}
+ */
+async function postToken(tokenEndpoint, params) {
+  const body = new URLSearchParams(params).toString();
+  const res = await fetch(tokenEndpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json",
+    },
+    body,
+    signal: AbortSignal.timeout(30_000),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Token endpoint error ${res.status}: ${safeErrorDetail(text)}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`Token endpoint returned a non-JSON response (status ${res.status})`);
+  }
+}
+
+/**
+ * Extract only the OAuth `error`/`error_description` fields from a token-endpoint
+ * body. Never returns the raw body, which on a misbehaving or hostile endpoint
+ * could contain an access_token / refresh_token that would then land in logs.
+ * @param {string} text
+ * @returns {string}
+ */
+function safeErrorDetail(text) {
+  try {
+    const j = JSON.parse(text);
+    const detail = [j.error, j.error_description].filter(Boolean).join(": ");
+    return detail ? detail.slice(0, 200) : "unrecognized error response";
+  } catch {
+    return "unrecognized error response";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the full Authorization-Code + PKCE login flow.
+ * Opens a browser, waits for the callback, exchanges the code, saves creds.
+ *
+ * @param {{ issuer: string, interactive?: boolean }} options
+ * @returns {Promise<{ access_token: string, refresh_token?: string, expires_at: number, scope?: string, token_endpoint: string }>}
+ */
+export async function login({ issuer, interactive = true }) {
+  const metadata = await discoverMetadata(issuer);
+  const { authorization_endpoint, token_endpoint, scopes_supported } = metadata;
+
+  const verifier = generateCodeVerifier();
+  const challenge = generateCodeChallenge(verifier);
+  const state = generateState();
+
+  const { server, port } = await startCallbackServer();
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+  const authorizeUrl = new URL(authorization_endpoint);
+  authorizeUrl.searchParams.set("response_type", "code");
+  authorizeUrl.searchParams.set("client_id", "sutra-mcp");
+  authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+  authorizeUrl.searchParams.set("state", state);
+  authorizeUrl.searchParams.set("code_challenge", challenge);
+  authorizeUrl.searchParams.set("code_challenge_method", "S256");
+  // Request scopes explicitly. SUTRA_SCOPES narrows the grant; otherwise default
+  // to the full set the server advertises (scopes_supported) so the MCP tools
+  // keep working. We always send an explicit scope when one is known rather than
+  // relying on the server's blank-scope default (which is read-only) — this
+  // keeps the grant visible on the consent screen and least-privilege-friendly.
+  const requestedScopes =
+    process.env.SUTRA_SCOPES?.trim() ||
+    (Array.isArray(scopes_supported) ? scopes_supported.join(" ") : "");
+  if (requestedScopes) {
+    authorizeUrl.searchParams.set("scope", requestedScopes);
+  } else {
+    // No SUTRA_SCOPES, and discovery didn't advertise scopes_supported (a
+    // degraded/fallback metadata fetch). Without a scope param the server grants
+    // its read-only default — and that token gets cached and silently reused. Make
+    // the downgrade visible so the user can re-run with SUTRA_SCOPES for writes.
+    process.stderr.write(
+      "\nWarning: the server did not advertise its available scopes (metadata " +
+      "discovery may have failed); requesting the server default, which is " +
+      "read-only. If you need write tools, set SUTRA_SCOPES and log in again.\n"
+    );
+  }
+
+  const urlString = authorizeUrl.toString();
+
+  process.stderr.write(
+    `\nOpen this URL to log in to Sutra:\n\n  ${urlString}\n\n` +
+    `Waiting for browser callback (5 min timeout)...\n`
+  );
+
+  if (interactive) {
+    openBrowser(urlString);
+  }
+
+  // Wait for callback — server is closed inside waitForCallback
+  const { code } = await waitForCallback(server, state, LOGIN_TIMEOUT_MS);
+
+  process.stderr.write("Authorization code received — exchanging for tokens...\n");
+
+  const tokenData = await postToken(token_endpoint, {
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    client_id: "sutra-mcp",
+    code_verifier: verifier,
+  });
+
+  const creds = {
+    access_token: tokenData.access_token,
+    refresh_token: tokenData.refresh_token ?? null,
+    expires_at: Date.now() + (tokenData.expires_in ?? 3600) * 1000,
+    scope: tokenData.scope ?? null,
+    token_endpoint,
+  };
+
+  save(issuer, creds);
+  process.stderr.write("Login successful. Credentials cached.\n");
+  return creds;
+}
+
+/**
+ * Refresh an access token using the stored refresh_token.
+ * Saves rotated credentials on success. Clears and throws on failure.
+ *
+ * @param {{ issuer: string, creds: object }} options
+ * @returns {Promise<object>} updated creds
+ */
+export async function refresh({ issuer, creds }) {
+  if (!creds.refresh_token) {
+    clear(issuer);
+    throw new Error("No refresh token available — please log in again");
+  }
+
+  try {
+    const tokenData = await postToken(creds.token_endpoint, {
+      grant_type: "refresh_token",
+      refresh_token: creds.refresh_token,
+      client_id: "sutra-mcp",
+    });
+
+    const updated = {
+      access_token: tokenData.access_token,
+      refresh_token: tokenData.refresh_token ?? creds.refresh_token,
+      expires_at: Date.now() + (tokenData.expires_in ?? 3600) * 1000,
+      scope: tokenData.scope ?? creds.scope,
+      token_endpoint: creds.token_endpoint,
+    };
+
+    save(issuer, updated);
+    return updated;
+  } catch (err) {
+    clear(issuer);
+    throw new Error(`Token refresh failed (${err.message}) — please log in again`);
+  }
+}
+
+/**
+ * Return a valid access token, refreshing or re-logging-in as needed.
+ * This is the main entry point called by the client bootstrap.
+ *
+ * @param {{ issuer: string }} options
+ * @returns {Promise<string>} a valid access token
+ */
+export async function getValidAccessToken({ issuer }) {
+  let creds = load(issuer);
+
+  if (creds) {
+    // Token still valid (with 60s buffer)
+    if (creds.expires_at - 60_000 > Date.now()) {
+      return creds.access_token;
+    }
+    // Expired but we have a refresh token
+    if (creds.refresh_token) {
+      try {
+        const updated = await refresh({ issuer, creds });
+        return updated.access_token;
+      } catch (err) {
+        process.stderr.write(`Refresh failed: ${err.message}\n`);
+        // Fall through to full login
+      }
+    }
+  }
+
+  // No valid creds — run full login
+  const freshCreds = await login({ issuer });
+  return freshCreds.access_token;
+}