@loopops/mcp-server 2.0.2 → 2.1.0

package/dist/api-client.js

@@ -23,6 +23,7 @@
 import { homedir, platform } from "node:os";
 import { join } from "node:path";
 import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { withRefreshLock } from "./token-lock.js";
 const apiUrl = process.env.API_URL;
 const oktaIssuer = process.env.OKTA_ISSUER;
 const oktaClientId = process.env.OKTA_CLIENT_ID;
@@ -178,29 +179,59 @@ function claudeDesktopConfigPath() {
     }
 }
 /**
- * Persist a rotated refresh token across every config location we know
- * users store MCP settings in:
- *   - ~/.mcp.json (CLI canonical, also legacy Claude Desktop path)
- *   - ~/.claude/settings.json (Claude Code)
- *   - OS-specific Claude Desktop config (macOS/Windows/Linux)
- *
- * We update whichever files have the loop-operations stanza. Missing
- * files are skipped silently. This mirrors @loopops/mcp-cli's
- * `updateRefreshToken` helper — keep the two in sync.
- *
- * Best-effort: if all writes fail, we still keep the new token
- * in-memory so the current subprocess keeps working. The next cold
- * spawn is the one that breaks.
+ * Every config path that might hold the loop-operations MCP stanza.
+ * Priority order matches `@loopops/mcp-cli`'s `getClaudeConfig`:
+ *   1. ~/.claude/settings.json (Claude Code)
+ *   2. ~/.mcp.json (CLI canonical, also legacy Claude Desktop path)
+ *   3. OS-specific Claude Desktop config
  */
-function persistRotatedRefreshToken(newToken) {
+function tokenConfigPaths() {
     const paths = [
-        join(homedir(), ".mcp.json"),
         join(homedir(), ".claude", "settings.json"),
+        join(homedir(), ".mcp.json"),
     ];
     const desktop = claudeDesktopConfigPath();
     if (desktop)
         paths.push(desktop);
-    for (const path of paths) {
+    return paths;
+}
+/**
+ * Read the current refresh token from disk, trying each config path
+ * in priority order. Returns the first token we find, or null if none
+ * of the files have the loop-operations stanza.
+ *
+ * Callers MUST hold the refresh lock before reading — otherwise another
+ * process may rotate between read and use.
+ */
+function readRefreshTokenFromDisk() {
+    for (const path of tokenConfigPaths()) {
+        try {
+            if (!existsSync(path))
+                continue;
+            const data = JSON.parse(readFileSync(path, "utf-8"));
+            const token = data.mcpServers?.[SERVER_NAME]?.env?.OKTA_REFRESH_TOKEN;
+            if (typeof token === "string" && token.length > 0)
+                return token;
+        }
+        catch {
+            // Try the next path.
+        }
+    }
+    return null;
+}
+/**
+ * Persist a rotated refresh token across every config location we know
+ * users store MCP settings in. We update whichever files have the
+ * loop-operations stanza. Missing files are skipped silently. This
+ * mirrors @loopops/mcp-cli's `updateRefreshToken` helper — keep the
+ * two in sync.
+ *
+ * Best-effort: if all writes fail, we still keep the new token
+ * in-memory so the current subprocess keeps working. The next cold
+ * spawn is the one that breaks.
+ */
+function persistRotatedRefreshToken(newToken) {
+    for (const path of tokenConfigPaths()) {
         try {
             if (!existsSync(path))
                 continue;
@@ -228,34 +259,57 @@ function persistRotatedRefreshToken(newToken) {
 /**
  * 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.
+ * new refresh token to every MCP config path.
+ *
+ * Serialised across processes with a lockfile. Our Okta policy rotates
+ * the refresh token on every use, so two processes hitting /token in
+ * parallel would race: one would succeed with the current token, the
+ * other would see invalid_grant (or bank a token that the first
+ * rotation has already superseded). The lock ensures only one /token
+ * call is in flight per machine; losers wait, then re-read the
+ * freshly-rotated token from disk and proceed.
  */
 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)}`);
+    if (!oktaIssuer || !oktaClientId) {
+        throw new OktaRefreshError("Missing OKTA_ISSUER / OKTA_CLIENT_ID. Re-run `npx @loopops/mcp-cli login`.");
     }
-    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;
+    return await withRefreshLock(async () => {
+        // Re-read from disk inside the lock. Our in-memory `refreshToken`
+        // may be stale because another process already rotated it and
+        // wrote the new value.
+        const diskToken = readRefreshTokenFromDisk();
+        const currentToken = diskToken ?? refreshToken;
+        if (!currentToken) {
+            throw new OktaRefreshError("Missing OKTA_REFRESH_TOKEN. Re-run `npx @loopops/mcp-cli login`.");
+        }
+        if (diskToken && diskToken !== refreshToken) {
+            // Pick up a newer token another process already rotated for us;
+            // sync in-memory to match disk.
+            refreshToken = diskToken;
+        }
+        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: currentToken,
+            }),
+        }, 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 !== currentToken) {
+            refreshToken = tokens.refresh_token;
+            persistRotatedRefreshToken(tokens.refresh_token);
+        }
+        return cachedAccessToken;
+    });
 }
 async function acquireAccessToken(forceRefresh = false) {
     if (!forceRefresh &&

package/dist/token-lock.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Cross-process exclusive lock for Okta refresh-token rotation.
+ *
+ * Our Okta policy rotates the refresh token on every use. When multiple
+ * processes hold the same refresh token (Claude Desktop + Claude Code +
+ * any other MCP host), each one independently calling Okta's /token
+ * endpoint races the rotation — one wins, the others get invalid_grant
+ * (or worse, bank a rotated token that's already been superseded).
+ *
+ * This lock serialises rotation across all processes on the machine, so
+ * only one /token call is in flight at a time. Every holder must:
+ *   1. Acquire the lock.
+ *   2. Re-read the refresh token from DISK (not memory — another
+ *      process may have just rotated it).
+ *   3. Call Okta.
+ *   4. Persist the new token before releasing.
+ *
+ * Implementation: atomic O_EXCL lockfile creation. Cross-platform
+ * (POSIX + Windows NTFS both honour it). If the holder crashes, the
+ * lockfile persists — we treat it as stale after LOCK_STALE_MS and
+ * reclaim it.
+ *
+ * NOTE: `@loopops/mcp-cli` ships a mirror of this file. They are
+ * separate published packages installed independently via npx. Keep
+ * both copies in sync.
+ */
+export declare function withRefreshLock<T>(fn: () => Promise<T>): Promise<T>;

package/dist/token-lock.js

@@ -0,0 +1,96 @@
+/**
+ * Cross-process exclusive lock for Okta refresh-token rotation.
+ *
+ * Our Okta policy rotates the refresh token on every use. When multiple
+ * processes hold the same refresh token (Claude Desktop + Claude Code +
+ * any other MCP host), each one independently calling Okta's /token
+ * endpoint races the rotation — one wins, the others get invalid_grant
+ * (or worse, bank a rotated token that's already been superseded).
+ *
+ * This lock serialises rotation across all processes on the machine, so
+ * only one /token call is in flight at a time. Every holder must:
+ *   1. Acquire the lock.
+ *   2. Re-read the refresh token from DISK (not memory — another
+ *      process may have just rotated it).
+ *   3. Call Okta.
+ *   4. Persist the new token before releasing.
+ *
+ * Implementation: atomic O_EXCL lockfile creation. Cross-platform
+ * (POSIX + Windows NTFS both honour it). If the holder crashes, the
+ * lockfile persists — we treat it as stale after LOCK_STALE_MS and
+ * reclaim it.
+ *
+ * NOTE: `@loopops/mcp-cli` ships a mirror of this file. They are
+ * separate published packages installed independently via npx. Keep
+ * both copies in sync.
+ */
+import { closeSync, openSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const LOCK_PATH = join(homedir(), ".loopops-refresh.lock");
+const LOCK_TIMEOUT_MS = 10_000;
+const LOCK_STALE_MS = 30_000;
+const POLL_INTERVAL_MS = 50;
+export async function withRefreshLock(fn) {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    let fd;
+    while (true) {
+        try {
+            fd = openSync(LOCK_PATH, "wx");
+            try {
+                writeSync(fd, `${process.pid}\n`);
+            }
+            catch {
+                // Writing PID is best-effort diagnostics; ignore failure.
+            }
+            break;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST")
+                throw err;
+            // Lock exists. Check if the holder crashed (stale lock).
+            try {
+                const age = Date.now() - statSync(LOCK_PATH).mtimeMs;
+                if (age > LOCK_STALE_MS) {
+                    try {
+                        unlinkSync(LOCK_PATH);
+                    }
+                    catch {
+                        // Raced another reclaimer; loop and retry.
+                    }
+                    continue;
+                }
+            }
+            catch {
+                // Lockfile vanished between EEXIST and stat; loop and retry.
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out after ${LOCK_TIMEOUT_MS}ms waiting for refresh lock ` +
+                    `at ${LOCK_PATH}. Another process may be holding it. If this ` +
+                    `persists, remove the file manually.`);
+            }
+            await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // best-effort
+            }
+        }
+        try {
+            unlinkSync(LOCK_PATH);
+        }
+        catch {
+            // best-effort
+        }
+    }
+}

package/dist/tools/config.js

@@ -107,6 +107,50 @@ export function registerConfigTools(server, allowed) {
             branch,
         })));
     }
+    if (allowed.has("compare_scenarios")) {
+        server.tool("compare_scenarios", "Run the Plan capacity model for two scenarios and render a side-by-side comparison per measure. For each (territory × measure) cell, shows A vs B capacity, target, gap, and the delta (B−A). Use when evaluating a stretch / conservative / hiring-delay scenario against `base` before deciding whether to promote. No writes — neither scenario's `active` status changes.", {
+            scenarioA: z
+                .string()
+                .describe("First scenario id (e.g. 'base'). Must exist in config/plan/scenarios/ and be complete."),
+            scenarioB: z
+                .string()
+                .describe("Second scenario id to compare against A (e.g. 'stretch'). Must exist and be complete."),
+            planYear: z
+                .number()
+                .int()
+                .optional()
+                .describe("Override the configured plan year for both runs. Defaults to capacity_config.planning.plan_year."),
+            measureIds: z
+                .array(z.string())
+                .optional()
+                .describe("Filter both reports to a subset of measures. Default: all target_settable measures."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Git branch to read configs from. Default: main."),
+        }, safeTool(async ({ scenarioA, scenarioB, planYear, measureIds, branch }) => trpcMutation("mcp.compareScenarios", {
+            scenarioA,
+            scenarioB,
+            planYear,
+            measureIds,
+            branch,
+        })));
+    }
+    if (allowed.has("promote_scenario")) {
+        server.tool("promote_scenario", "Promote a scenario to active by editing `active_scenario` in config/plan/capacity_config.yaml. Fails hard if the scenario doesn't resolve (missing or dangling components) — won't promote a broken plan. Dry-run by default — returns the diff; pass dryRun:false to commit the change.", {
+            scenarioId: z
+                .string()
+                .describe("Scenario id to promote (e.g. 'stretch'). Must exist in config/plan/scenarios/ and be complete."),
+            dryRun: z
+                .boolean()
+                .default(true)
+                .describe("When true (default), return the diff without writing. Pass dryRun:false to commit."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Git branch to read from and write back to. Default: main. Writing to main = live promotion."),
+        }, safeTool(async ({ scenarioId, dryRun, branch }) => trpcMutation("mcp.promoteScenario", { scenarioId, dryRun, branch })));
+    }
     if (allowed.has("preview_routing")) {
         server.tool("preview_routing", "Simulate Route loop resolution for a hypothetical lead. Walks config/route/rules.yaml, dispatches to territory/pool/queue/user/target_account handler, and returns the resolved owner + audit trail. Useful for testing rule changes before merging. Requires at least billing geography or email.", {
             email: z.string().optional().describe("Lead email — also extracts the domain for target_account lookup."),

package/package.json

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

package/dist/db.d.ts

@@ -1,3 +0,0 @@
-import pg from "pg";
-export type Db = pg.Pool;
-export declare function createDb(connectionString: string): Db;

package/dist/db.js

@@ -1,8 +0,0 @@
-import pg from "pg";
-export function createDb(connectionString) {
-    return new pg.Pool({
-        connectionString,
-        max: 3,
-        idleTimeoutMillis: 30000,
-    });
-}

package/dist/roles.d.ts

@@ -1 +0,0 @@
-export declare function loadSkillsForRole(roleName: string): Promise<Set<string>>;

package/dist/roles.js

@@ -1,33 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { parse } from "yaml";
-function resolveSkills(roles, roleName, visited = new Set()) {
-    if (visited.has(roleName))
-        return [];
-    visited.add(roleName);
-    const role = roles[roleName];
-    if (!role)
-        return [];
-    const inherited = role.inherits
-        ? resolveSkills(roles, role.inherits, visited)
-        : [];
-    return [...new Set([...inherited, ...role.skills])];
-}
-export async function loadSkillsForRole(roleName) {
-    // Look for skills.yaml relative to the project root
-    const __dirname = dirname(fileURLToPath(import.meta.url));
-    const configPath = resolve(__dirname, "../../../config/mcp/skills.yaml");
-    // Try project-relative path first, then fall back to cwd-based path
-    let raw;
-    try {
-        raw = await readFile(configPath, "utf-8");
-    }
-    catch {
-        const cwdPath = resolve(process.cwd(), "config/mcp/skills.yaml");
-        raw = await readFile(cwdPath, "utf-8");
-    }
-    const config = parse(raw);
-    const skills = resolveSkills(config.roles, roleName);
-    return new Set(skills);
-}