@loopops/mcp-server 1.0.0 → 2.0.0

package/dist/api-client.d.ts

@@ -1,38 +1,52 @@
 /**
- * tRPC client for connecting to the hosted Loop Operations API.
- * Used when the MCP server runs in API mode (API_URL + API_KEY set).
+ * tRPC client for the hosted Loop Operations API. Authenticated with
+ * short-lived Okta access tokens minted from a cached refresh token.
+ *
+ * The MCP subprocess is spawned by Claude Desktop / Claude Code with
+ * these env vars (written to ~/.mcp.json by `@loopops/mcp-cli`):
+ *   - API_URL
+ *   - OKTA_ISSUER
+ *   - OKTA_CLIENT_ID
+ *   - OKTA_REFRESH_TOKEN   (initial; may be rotated on refresh)
+ *
+ * Token lifecycle:
+ *   - On startup we have the refresh token from env. No access token yet.
+ *   - First tRPC call triggers `acquireAccessToken()` which hits Okta's
+ *     /token endpoint, caches the access_token + expiry in memory.
+ *   - Subsequent calls reuse the cached access_token until expiry (1h).
+ *   - On 401, we refresh once and retry (covers token lifetime edge).
+ *   - If Okta rotates the refresh_token (our policy says "rotate on every
+ *     use"), we persist the new one back to ~/.mcp.json via the shared
+ *     updater helper, and also keep the latest rotated token in memory
+ *     in case Claude Desktop doesn't restart before next use.
  */
 export declare function isApiMode(): boolean;
 export declare function getApiUrl(): string;
-export declare function getApiKey(): string;
 /** Base class so callers can distinguish API errors from unexpected errors. */
 export declare class ApiError extends Error {
     constructor(message: string);
 }
-/** The request took longer than the configured timeout. */
 export declare class ApiTimeoutError extends ApiError {
     readonly timeoutMs: number;
     constructor(timeoutMs: number);
 }
-/** fetch() itself failed (DNS, TCP reset, etc.) — no HTTP response received. */
 export declare class ApiNetworkError extends ApiError {
     constructor(cause: unknown);
 }
-/** API returned a non-2xx HTTP status. */
 export declare class ApiHttpError extends ApiError {
     readonly status: number;
     readonly body: string;
     constructor(status: number, body: string);
 }
-/** API returned 401/403 — API key missing, expired, or lacks permission. */
 export declare class ApiAuthError extends ApiError {
     readonly status: number;
     readonly body: string;
-    /** The tRPC error's `message` field if parseable, else null. */
     readonly serverMessage: string | null;
     constructor(status: number, body: string);
 }
-/** Make a tRPC query call to the hosted API. Retries once on timeout/network/5xx. */
+/** The refresh token itself was rejected by Okta — user must re-auth. */
+export declare class OktaRefreshError extends ApiError {
+    constructor(message: string);
+}
 export declare function trpcQuery<T = unknown>(path: string, input?: Record<string, unknown>): Promise<T>;
-/** Make a tRPC mutation call to the hosted API. Does NOT retry (non-idempotent). */
 export declare function trpcMutation<T = unknown>(path: string, input: Record<string, unknown>): Promise<T>;

package/dist/api-client.js

@@ -1,23 +1,48 @@
 /**
- * tRPC client for connecting to the hosted Loop Operations API.
- * Used when the MCP server runs in API mode (API_URL + API_KEY set).
+ * tRPC client for the hosted Loop Operations API. Authenticated with
+ * short-lived Okta access tokens minted from a cached refresh token.
+ *
+ * The MCP subprocess is spawned by Claude Desktop / Claude Code with
+ * these env vars (written to ~/.mcp.json by `@loopops/mcp-cli`):
+ *   - API_URL
+ *   - OKTA_ISSUER
+ *   - OKTA_CLIENT_ID
+ *   - OKTA_REFRESH_TOKEN   (initial; may be rotated on refresh)
+ *
+ * Token lifecycle:
+ *   - On startup we have the refresh token from env. No access token yet.
+ *   - First tRPC call triggers `acquireAccessToken()` which hits Okta's
+ *     /token endpoint, caches the access_token + expiry in memory.
+ *   - Subsequent calls reuse the cached access_token until expiry (1h).
+ *   - On 401, we refresh once and retry (covers token lifetime edge).
+ *   - If Okta rotates the refresh_token (our policy says "rotate on every
+ *     use"), we persist the new one back to ~/.mcp.json via the shared
+ *     updater helper, and also keep the latest rotated token in memory
+ *     in case Claude Desktop doesn't restart before next use.
  */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 const apiUrl = process.env.API_URL;
-const apiKey = process.env.API_KEY;
+const oktaIssuer = process.env.OKTA_ISSUER;
+const oktaClientId = process.env.OKTA_CLIENT_ID;
+// Mutable — may be updated in-memory when Okta rotates the refresh token.
+let refreshToken = process.env.OKTA_REFRESH_TOKEN;
+// Access token cache (in-memory, subprocess-lifetime).
+let cachedAccessToken = null;
+let cachedAccessTokenExpiresAt = 0; // epoch ms
 const DEFAULT_TIMEOUT_MS = Number(process.env.API_TIMEOUT_MS || 30_000);
+const SERVER_NAME = "loop-operations";
+// Refresh a little early so requests don't race token expiry at the edge.
+const ACCESS_TOKEN_EARLY_REFRESH_MS = 60 * 1000; // 1 minute
 export function isApiMode() {
-    return !!apiUrl;
+    return !!apiUrl && !!oktaIssuer && !!oktaClientId && !!refreshToken;
 }
 export function getApiUrl() {
     if (!apiUrl)
         throw new Error("API_URL not set");
     return apiUrl;
 }
-export function getApiKey() {
-    if (!apiKey)
-        throw new Error("API_KEY not set");
-    return apiKey;
-}
 /** Base class so callers can distinguish API errors from unexpected errors. */
 export class ApiError extends Error {
     constructor(message) {
@@ -25,7 +50,6 @@ export class ApiError extends Error {
         this.name = "ApiError";
     }
 }
-/** The request took longer than the configured timeout. */
 export class ApiTimeoutError extends ApiError {
     timeoutMs;
     constructor(timeoutMs) {
@@ -34,7 +58,6 @@ export class ApiTimeoutError extends ApiError {
         this.name = "ApiTimeoutError";
     }
 }
-/** fetch() itself failed (DNS, TCP reset, etc.) — no HTTP response received. */
 export class ApiNetworkError extends ApiError {
     constructor(cause) {
         super(`Loop API network error: ${cause instanceof Error ? cause.message : String(cause)}`);
@@ -42,7 +65,6 @@ export class ApiNetworkError extends ApiError {
         this.cause = cause;
     }
 }
-/** API returned a non-2xx HTTP status. */
 export class ApiHttpError extends ApiError {
     status;
     body;
@@ -53,11 +75,9 @@ export class ApiHttpError extends ApiError {
         this.name = "ApiHttpError";
     }
 }
-/** API returned 401/403 — API key missing, expired, or lacks permission. */
 export class ApiAuthError extends ApiError {
     status;
     body;
-    /** The tRPC error's `message` field if parseable, else null. */
     serverMessage;
     constructor(status, body) {
         super(`Loop API auth error (${status}): ${body.slice(0, 300)}`);
@@ -67,14 +87,13 @@ export class ApiAuthError extends ApiError {
         this.serverMessage = extractTrpcMessage(body);
     }
 }
-/**
- * tRPC returns errors wrapped in an envelope. Extract the `message`
- * field so MCP tools can surface the server's actionable text verbatim
- * instead of our generic fallback.
- *
- * Shape (tRPC fetch adapter, HTTP error): [{ error: { json: { message } } }]
- *   or { error: { json: { message } } }
- */
+/** The refresh token itself was rejected by Okta — user must re-auth. */
+export class OktaRefreshError extends ApiError {
+    constructor(message) {
+        super(message);
+        this.name = "OktaRefreshError";
+    }
+}
 function extractTrpcMessage(body) {
     try {
         const parsed = JSON.parse(body);
@@ -90,7 +109,6 @@ function extractTrpcMessage(body) {
                     if (typeof msg === "string" && msg.trim().length > 0)
                         return msg;
                 }
-                // Older/simpler shape: error.message at the top level
                 const flat = errorNode.message;
                 if (typeof flat === "string" && flat.trim().length > 0)
                     return flat;
@@ -98,7 +116,7 @@ function extractTrpcMessage(body) {
         }
     }
     catch {
-        // Body wasn't JSON; fall through.
+        // not JSON
     }
     return null;
 }
@@ -134,25 +152,111 @@ function isRetryable(err) {
         return true;
     return false;
 }
-/** Make a tRPC query call to the hosted API. Retries once on timeout/network/5xx. */
-export async function trpcQuery(path, input) {
+/**
+ * Persist a rotated refresh token back to ~/.mcp.json. Best-effort — if
+ * the write fails, we still keep the new token in-memory so the current
+ * subprocess keeps working. Claude Desktop's next spawn will need the
+ * disk value though.
+ */
+function persistRotatedRefreshToken(newToken) {
+    try {
+        const path = join(homedir(), ".mcp.json");
+        if (!existsSync(path))
+            return;
+        const raw = readFileSync(path, "utf-8");
+        const data = JSON.parse(raw);
+        const stanza = data.mcpServers?.[SERVER_NAME];
+        if (!stanza?.env)
+            return;
+        stanza.env.OKTA_REFRESH_TOKEN = newToken;
+        writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
+        try {
+            chmodSync(path, 0o600);
+        }
+        catch {
+            // ok on platforms where this is a no-op
+        }
+    }
+    catch (err) {
+        // Log to stderr (visible in Claude Desktop logs) but don't fail the request.
+        console.error("[MCP] Could not persist rotated refresh token to ~/.mcp.json:", err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * Mint a fresh access token via Okta's /token endpoint. Updates the
+ * in-memory cache AND (if Okta rotated the refresh token) persists the
+ * new refresh token to ~/.mcp.json.
+ */
+async function refreshAccessTokenOnce() {
+    if (!oktaIssuer || !oktaClientId || !refreshToken) {
+        throw new OktaRefreshError("Missing OKTA_ISSUER / OKTA_CLIENT_ID / OKTA_REFRESH_TOKEN. Re-run `npx @loopops/mcp-cli login`.");
+    }
+    const response = await doFetch(`${oktaIssuer}/v1/token`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "refresh_token",
+            client_id: oktaClientId,
+            refresh_token: refreshToken,
+        }),
+    }, DEFAULT_TIMEOUT_MS);
+    if (!response.ok) {
+        const body = await response.text().catch(() => "<unreadable>");
+        throw new OktaRefreshError(`Okta refresh failed (HTTP ${response.status}). Your refresh token may be revoked or idle-expired. Re-run \`npx @loopops/mcp-cli login\`. Detail: ${body.slice(0, 300)}`);
+    }
+    const tokens = (await response.json());
+    cachedAccessToken = tokens.access_token;
+    cachedAccessTokenExpiresAt = Date.now() + tokens.expires_in * 1000;
+    // Handle rotation (our Okta policy rotates on every use).
+    if (tokens.refresh_token && tokens.refresh_token !== refreshToken) {
+        refreshToken = tokens.refresh_token;
+        persistRotatedRefreshToken(tokens.refresh_token);
+    }
+    return cachedAccessToken;
+}
+async function acquireAccessToken(forceRefresh = false) {
+    if (!forceRefresh &&
+        cachedAccessToken &&
+        Date.now() + ACCESS_TOKEN_EARLY_REFRESH_MS < cachedAccessTokenExpiresAt) {
+        return cachedAccessToken;
+    }
+    return await refreshAccessTokenOnce();
+}
+/** Shared tRPC call plumbing — one place handles auth headers + retry. */
+async function callTrpc(args) {
     const url = new URL(getApiUrl());
-    url.pathname = url.pathname.replace(/\/$/, "") + "/" + path;
-    if (input !== undefined) {
-        url.searchParams.set("input", JSON.stringify({ json: input }));
-    }
-    const init = {
-        method: "GET",
-        redirect: "follow",
-        headers: {
-            Authorization: `Bearer ${getApiKey()}`,
-            "Content-Type": "application/json",
-        },
-    };
+    url.pathname = url.pathname.replace(/\/$/, "") + "/" + args.path;
+    if (args.method === "GET" && args.input !== undefined) {
+        url.searchParams.set("input", JSON.stringify({ json: args.input }));
+    }
+    // Up to 2 tries when allowed for transient errors, plus 1 extra try
+    // dedicated to re-auth after 401.
+    const maxNetAttempts = args.retryOnNetwork ? 2 : 1;
     let lastErr;
-    for (let attempt = 0; attempt < 2; attempt++) {
+    let reauthed = false;
+    // Outer retry loop: network/5xx (GET only) + one re-auth retry.
+    for (let attempt = 0; attempt < maxNetAttempts + 1; attempt++) {
         try {
+            const accessToken = await acquireAccessToken();
+            const init = {
+                method: args.method,
+                redirect: "follow",
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                    "Content-Type": "application/json",
+                },
+            };
+            if (args.method === "POST") {
+                init.body = JSON.stringify({ json: args.input ?? {} });
+            }
             const response = await doFetch(url.toString(), init, DEFAULT_TIMEOUT_MS);
+            if (response.status === 401 && !reauthed) {
+                // Access token may have expired between cache check + request.
+                // Force-refresh once and retry.
+                reauthed = true;
+                await acquireAccessToken(/* forceRefresh */ true);
+                continue;
+            }
             if (!response.ok)
                 await readAndThrow(response);
             const data = (await response.json());
@@ -160,29 +264,20 @@ export async function trpcQuery(path, input) {
         }
         catch (err) {
             lastErr = err;
+            if (err instanceof OktaRefreshError)
+                throw err;
             if (!isRetryable(err))
                 throw err;
-            if (attempt === 0)
+            if (attempt < maxNetAttempts)
                 continue;
+            throw err;
         }
     }
     throw lastErr;
 }
-/** Make a tRPC mutation call to the hosted API. Does NOT retry (non-idempotent). */
+export async function trpcQuery(path, input) {
+    return callTrpc({ method: "GET", path, input, retryOnNetwork: true });
+}
 export async function trpcMutation(path, input) {
-    const url = new URL(getApiUrl());
-    url.pathname = url.pathname.replace(/\/$/, "") + "/" + path;
-    const response = await doFetch(url.toString(), {
-        method: "POST",
-        redirect: "follow",
-        headers: {
-            Authorization: `Bearer ${getApiKey()}`,
-            "Content-Type": "application/json",
-        },
-        body: JSON.stringify({ json: input }),
-    }, DEFAULT_TIMEOUT_MS);
-    if (!response.ok)
-        await readAndThrow(response);
-    const data = (await response.json());
-    return data.result?.data?.json;
+    return callTrpc({ method: "POST", path, input, retryOnNetwork: false });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopops/mcp-server",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Loop Operations MCP Server — AI skills for RevOps",
   "license": "UNLICENSED",
   "type": "module",