@myspec/mcp-server 0.2.0-next.79 → 0.2.0-next.80

package/README.md

@@ -58,6 +58,92 @@ value, including the dot** and paste it back into the terminal. Two traps:
 > keeping access until you run `logout`. The CLI prints the same warning with
 > the actual port, before the URL.
 
+### API tokens (unattended setup)
+
+`login` is interactive — it opens a browser. For anything that has to start
+without a person present (a server, a container, a CI job, a shared machine),
+use an API token instead.
+
+**1. Create the token.** In the MySpec webapp, open the avatar menu → **API
+tokens** → **Create token**. Choose the organization it should act in, whether
+it may write or only read, and an expiry. The token is shown **once**; it
+cannot be retrieved afterwards.
+
+**2. Configure it.** Credentials live in two files under `~/.myspec/`, both of
+which the server needs:
+
+`~/.myspec/oauth_creds.json` — the secret, **mode 0600** (the store refuses any
+file readable by group or other):
+
+```json
+{ "apiToken": "msp_pat_…" }
+```
+
+`~/.myspec/settings.json` — which auth server to talk to:
+
+```json
+{ "userAuthUrl": "https://auth.myspec.dev" }
+```
+
+```bash
+chmod 600 ~/.myspec/oauth_creds.json
+```
+
+`accessToken`, `expiresAt` and the discovered service URLs are filled in
+automatically on first use, and an API-token credential needs no `user` block —
+the owner is resolved server-side at exchange.
+
+There is **no environment variable for an API token** — these files are the
+only way to configure one.
+
+**3. Verify it.** The token is exchanged for a short-lived access token on
+every run, so a token that works here works in the server:
+
+```bash
+curl -sS -X POST "https://auth.myspec.dev/api/auth/token/exchange" \
+  -H "x-api-key: msp_pat_…" -w '\n%{http_code}\n'
+```
+
+`200` with an `accessToken` in the body means it is good. Otherwise:
+
+| Status | Meaning |
+|---|---|
+| `401` | Unknown, revoked or expired token — deliberately indistinguishable. Create a new one. |
+| `403` | The token's organization is gone, or its owner is no longer a member of it. Create a token for an organization you belong to. |
+| `429` | Rate limited. `Retry-After` says how long to wait; the body's `scope` says whether the limit was per-address or per-token. |
+
+#### How it differs from `login`
+
+|  | `login` | API token |
+|---|---|---|
+| Needs a browser | Yes | No |
+| Credential rotates | Yes, on every refresh | No |
+| Survives a missed write | No | Yes |
+| Scope | Whatever the session can reach | One organization, fixed at creation |
+| Access | Full | Read-only or read-write, fixed at creation |
+
+An API token's organization and access mode cannot be changed after creation —
+create a new token instead. Expiry *can* be extended, from the same page, and
+doing so does not change the token value, so nothing needs reconfiguring.
+
+#### Rolling back to a refresh token
+
+If a token does not work and you need the deployment running again now:
+
+1. **Delete the `apiToken` field** from `~/.myspec/oauth_creds.json`. Emptying
+   it is not enough and neither is adding a refresh token alongside it: when an
+   `apiToken` is present it is used exclusively, and a rejected one fails the
+   run rather than falling back — silently downgrading to a different identity
+   would be worse than stopping.
+2. Restore the previous credential — restore a backup of the credentials file
+   if you took one, or run `login` again.
+
+Do **not** use `logout` to roll back. It deletes the whole credentials file,
+API token included.
+
+Migrating an existing install off `MYSPEC_REFRESH_TOKEN`? See the
+[migration runbook](../../docs/runbooks/mcp-api-token-migration.md).
+
 ### Active organization
 
 Every MySpec access token carries the slug of one **active organization**, and
@@ -136,7 +222,6 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 | Variable | Purpose |
 |---|---|
 | `MYSPEC_USER_AUTH_URL` | user-auth base URL (default `https://auth.myspec.dev`). The webapp URL is derived from it; the platform / ai-agent URLs are discovered via the webapp. |
-| `MYSPEC_REFRESH_TOKEN` | Skip file-based credentials; the server mints a fresh access token on first use via this refresh token. The supported way to wire the MCP server up without running `npx @myspec/mcp-server login`. |
 | `MYSPEC_DOWNLOAD_ROOT` | Absolute path used by `read_spec_file` as its on-disk cache root (default: `~/.myspec`). Tools never write outside this root. |
 | `MYSPEC_AI_AGENT_WS_URL` | ai-agent WebSocket URL for `reverse`; skips the webapp discovery call |
 

package/dist/index.js

@@ -29,11 +29,13 @@ var HttpStatusError = class extends Error {
 };
 var BEARER_PATTERN = /Bearer\s+[A-Za-z0-9._\-+/=]+/g;
 var REFRESH_TOKEN_PATTERN = /"refreshToken"\s*:\s*"[^"]+"/g;
+var API_TOKEN_PATTERN = /"apiToken"\s*:\s*"[^"]+"/g;
+var API_TOKEN_VALUE_PATTERN = /\bmsp_pat_[A-Za-z0-9]+/g;
 var ACCESS_TOKEN_PATTERN = /"accessToken"\s*:\s*"[^"]+"/g;
 var SNAKE_TOKEN_PATTERN = /"(access_token|refresh_token|id_token)"\s*:\s*"[^"]+"/g;
 var JWT_PATTERN = /\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
 function redactSensitive(value) {
-  return value.replace(BEARER_PATTERN, "Bearer [REDACTED]").replace(REFRESH_TOKEN_PATTERN, '"refreshToken":"[REDACTED]"').replace(ACCESS_TOKEN_PATTERN, '"accessToken":"[REDACTED]"').replace(SNAKE_TOKEN_PATTERN, (_match, key) => `"${key}":"[REDACTED]"`).replace(JWT_PATTERN, "[REDACTED_JWT]");
+  return value.replace(BEARER_PATTERN, "Bearer [REDACTED]").replace(REFRESH_TOKEN_PATTERN, '"refreshToken":"[REDACTED]"').replace(API_TOKEN_PATTERN, '"apiToken":"[REDACTED]"').replace(API_TOKEN_VALUE_PATTERN, "[REDACTED_API_TOKEN]").replace(ACCESS_TOKEN_PATTERN, '"accessToken":"[REDACTED]"').replace(SNAKE_TOKEN_PATTERN, (_match, key) => `"${key}":"[REDACTED]"`).replace(JWT_PATTERN, "[REDACTED_JWT]");
 }
 var ConfigError = class extends Error {
   constructor(message) {
@@ -284,6 +286,7 @@ function createFileCredentialsStore(paths = {}) {
       return {
         accessToken: oauth.accessToken,
         refreshToken: oauth.refreshToken,
+        apiToken: oauth.apiToken,
         expiresAt: oauth.expiresAt,
         userAuthUrl: settings.userAuthUrl,
         platformUrl: settings.platformUrl,
@@ -308,6 +311,10 @@ function createFileCredentialsStore(paths = {}) {
         {
           accessToken: creds.accessToken,
           refreshToken: creds.refreshToken,
+          // Carried through every save. Omitting it would delete a configured
+          // API token on the first successful exchange, since save rewrites
+          // the whole file.
+          apiToken: creds.apiToken,
           expiresAt: creds.expiresAt,
           user: creds.user
         },
@@ -369,64 +376,39 @@ async function unlinkIfExists(target) {
     }
   }
 }
-var DEFAULT_USER_AUTH_URL = "https://auth.myspec.dev";
-function readEnvRefreshConfig(env = process.env) {
-  if (env.MYSPEC_ACCESS_TOKEN || env.MYSPEC_ACCESS_TOKEN_EXPIRES_AT) {
-    throw new ConfigError(
-      "MYSPEC_ACCESS_TOKEN / MYSPEC_ACCESS_TOKEN_EXPIRES_AT are not supported. The MCP server mints a fresh access token via MYSPEC_REFRESH_TOKEN; unset MYSPEC_ACCESS_TOKEN (and MYSPEC_ACCESS_TOKEN_EXPIRES_AT if set) and provide only MYSPEC_REFRESH_TOKEN."
+function assertNoEnvAccessToken(env = process.env) {
+  if (env.MYSPEC_REFRESH_TOKEN) {
+    process.stderr.write(
+      "myspec-mcp: MYSPEC_REFRESH_TOKEN is set but no longer supported and is being ignored. Set an `apiToken` in ~/.myspec/oauth_creds.json, or run `npx @myspec/mcp-server login`. See docs/runbooks/mcp-api-token-migration.md\n"
     );
   }
-  if (!env.MYSPEC_REFRESH_TOKEN) {
-    return null;
+  if (!env.MYSPEC_ACCESS_TOKEN && !env.MYSPEC_ACCESS_TOKEN_EXPIRES_AT) {
+    return;
   }
-  return {
-    refreshToken: env.MYSPEC_REFRESH_TOKEN,
-    userAuthUrl: env.MYSPEC_USER_AUTH_URL ?? DEFAULT_USER_AUTH_URL
-  };
-}
-function createCompositeCredentialsStore(opts) {
-  const { fileStore, envConfig } = opts;
-  const envRefreshToken = envConfig?.refreshToken;
-  const envUserAuthUrl = envConfig?.userAuthUrl ?? DEFAULT_USER_AUTH_URL;
-  return {
-    path: () => fileStore.path(),
-    async load() {
-      const fromFile = await fileStore.load();
-      if (fromFile) {
-        return fromFile;
-      }
-      if (!envRefreshToken) {
-        return null;
-      }
-      return {
-        accessToken: "",
-        refreshToken: envRefreshToken,
-        expiresAt: 0,
-        userAuthUrl: envUserAuthUrl,
-        user: { id: "env", email: "env@mcp" }
-      };
-    },
-    save(creds) {
-      return fileStore.save(creds);
-    },
-    clear() {
-      return fileStore.clear();
-    },
-    envRefreshToken: () => envRefreshToken,
-    envUserAuthUrl: () => envUserAuthUrl
-  };
+  throw new ConfigError(
+    "MYSPEC_ACCESS_TOKEN / MYSPEC_ACCESS_TOKEN_EXPIRES_AT are not supported. Run `npx @myspec/mcp-server login`, or put a long-lived API token in the `apiToken` field of your credentials file, and unset these variables."
+  );
 }
 function parseOauthCreds(value) {
   if (typeof value !== "object" || value === null) {
     throw new Error("oauth_creds.json is malformed (not an object)");
   }
   const v = value;
-  const accessToken = requireString(v, "accessToken");
-  const refreshToken = requireString(v, "refreshToken");
-  const expiresAt = requireNumber(v, "expiresAt");
+  const refreshToken = optionalString(v, "refreshToken");
+  const apiToken = optionalString(v, "apiToken");
+  if (!refreshToken && !apiToken) {
+    throw new NeedsLoginError(
+      "oauth_creds.json has no apiToken or refreshToken. Run `npx @myspec/mcp-server login` to sign in, or provision an API token."
+    );
+  }
+  const accessToken = optionalString(v, "accessToken") ?? "";
+  const expiresAt = v.expiresAt === void 0 ? 0 : requireNumber(v, "expiresAt");
   const userRaw = v.user;
   if (typeof userRaw !== "object" || userRaw === null) {
-    throw new Error("oauth_creds.json is malformed (missing user)");
+    if (!apiToken) {
+      throw new Error("oauth_creds.json is malformed (missing user)");
+    }
+    return { accessToken, refreshToken, apiToken, expiresAt };
   }
   const userObj = userRaw;
   const user = {
@@ -434,7 +416,17 @@ function parseOauthCreds(value) {
     email: requireString(userObj, "email"),
     name: typeof userObj.name === "string" ? userObj.name : void 0
   };
-  return { accessToken, refreshToken, expiresAt, user };
+  return { accessToken, refreshToken, apiToken, expiresAt, user };
+}
+function optionalString(v, key) {
+  const raw = v[key];
+  if (raw === void 0 || raw === null) {
+    return void 0;
+  }
+  if (typeof raw !== "string") {
+    throw new Error(`Credentials file is malformed (invalid ${key})`);
+  }
+  return raw.length === 0 ? void 0 : raw;
 }
 function parseSettings(value) {
   if (typeof value !== "object" || value === null) {
@@ -471,14 +463,21 @@ var TokenManager = class {
   store;
   fetchImpl;
   now;
-  envFallback;
   cached = null;
   refreshInFlight = null;
+  /**
+   * Set once the exchange endpoint rejects the API token outright.
+   *
+   * The rejection deliberately does not wipe the credential, so without this
+   * every subsequent tool call would re-POST a known-bad token to the endpoint
+   * the server rate-limits as its brute-force control. Latching turns a loop
+   * into one failed request.
+   */
+  apiTokenRejection = null;
   constructor(deps) {
     this.store = deps.store;
     this.fetchImpl = deps.fetchImpl ?? fetch;
     this.now = deps.now ?? Date.now;
-    this.envFallback = deps.envFallback ?? null;
   }
   async getValidAccessToken() {
     const creds = await this.ensureLoaded();
@@ -521,27 +520,20 @@ var TokenManager = class {
     return this.refreshInFlight;
   }
   async doRefresh(creds) {
+    if (creds.apiToken) {
+      if (this.apiTokenRejection) {
+        throw this.apiTokenRejection;
+      }
+      return this.performExchange(creds, creds.apiToken);
+    }
+    if (!creds.refreshToken) {
+      throw new NeedsLoginError(
+        "No credential is configured. Either run `npx @myspec/mcp-server login` to sign in interactively, or add a long-lived API token to the `apiToken` field of your credentials file \u2014 create one in the MySpec webapp under the avatar menu, API tokens."
+      );
+    }
     try {
       return await this.performRefresh(creds);
     } catch (err) {
-      if (err instanceof RefreshRejectedError && this.envFallback && this.envFallback.refreshToken !== creds.refreshToken) {
-        const bootstrap = {
-          accessToken: "",
-          refreshToken: this.envFallback.refreshToken,
-          expiresAt: 0,
-          userAuthUrl: this.envFallback.userAuthUrl,
-          platformUrl: creds.platformUrl,
-          webappUrl: creds.webappUrl,
-          aiAgentMcpReverseUrl: creds.aiAgentMcpReverseUrl,
-          user: creds.user
-        };
-        try {
-          return await this.performRefresh(bootstrap);
-        } catch (retryErr) {
-          await this.invalidateOnAuthFailure(retryErr);
-          throw retryErr;
-        }
-      }
       await this.invalidateOnAuthFailure(err);
       throw err;
     }
@@ -552,6 +544,52 @@ var TokenManager = class {
       await this.store.clear();
     }
   }
+  /**
+   * Trades the long-lived API token for a short-lived access token.
+   *
+   * Unlike refresh, nothing here is persisted except the new access token and
+   * its expiry — the API token is unchanged by the exchange, so re-saving it
+   * would be a no-op and expecting a rotated value back would be wrong.
+   */
+  async performExchange(creds, apiToken) {
+    const url = `${creds.userAuthUrl}/api/auth/token/exchange`;
+    const response = await this.fetchImpl(url, {
+      method: "POST",
+      headers: { "x-api-key": apiToken }
+    });
+    if (response.status === 401 || response.status === 403) {
+      const reason = response.status === 403 ? "the token owner no longer has access to its organization" : "the token is invalid, disabled, or expired";
+      const rejection = new ApiTokenRejectedError(
+        `API token exchange failed: ${reason}. Create a new API token in MySpec and write it to the apiToken field of your credentials file.`
+      );
+      this.apiTokenRejection = rejection;
+      throw rejection;
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new HttpStatusError(
+        response.status,
+        body,
+        `Token exchange failed: HTTP ${String(response.status)}`
+      );
+    }
+    const payload = await response.json().catch(() => null);
+    if (!payload || typeof payload.accessToken !== "string" || typeof payload.expiresIn !== "number") {
+      throw new HttpStatusError(
+        response.status,
+        "",
+        "Token exchange response was malformed."
+      );
+    }
+    const next = {
+      ...creds,
+      accessToken: payload.accessToken,
+      expiresAt: this.now() + payload.expiresIn * 1e3
+    };
+    this.cached = next;
+    await this.store.save(next);
+    return next;
+  }
   async performRefresh(creds) {
     const url = `${creds.userAuthUrl}/api/auth/token/refresh`;
     const response = await this.fetchImpl(url, {
@@ -587,6 +625,8 @@ var TokenManager = class {
 };
 var RefreshRejectedError = class extends NeedsLoginError {
 };
+var ApiTokenRejectedError = class extends ConfigError {
+};
 
 // src/auth/organization.ts
 import readline2 from "readline";
@@ -797,11 +837,11 @@ async function discoverConfig(opts) {
   } catch {
     throw discoveryError(endpoint, "response is not valid JSON", hint);
   }
-  const platformUrl = optionalString(body.platformUrl);
+  const platformUrl = optionalString2(body.platformUrl);
   if (platformUrl !== void 0) {
     assertHttpUrl(platformUrl, endpoint, hint);
   }
-  const aiAgentMcpReverseUrl = optionalString(body.aiAgentMcpReverseUrl);
+  const aiAgentMcpReverseUrl = optionalString2(body.aiAgentMcpReverseUrl);
   if (aiAgentMcpReverseUrl !== void 0) {
     assertWebSocketUrl(aiAgentMcpReverseUrl, endpoint, hint);
   }
@@ -827,7 +867,7 @@ function fetchConfig(endpoint, token, fetchImpl) {
     headers: { Authorization: `Bearer ${token}` }
   });
 }
-function optionalString(value) {
+function optionalString2(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
 function assertHttpUrl(value, endpoint, hint) {
@@ -887,11 +927,13 @@ async function runLogin(options, deps = {}) {
     webappUrl: config.webappUrl
   });
   const enriched = await discoverAfterLogin(credentials, config.webappUrl, deps.discover, log);
-  await store.save(enriched);
-  log(`Signed in as ${enriched.user.email}.`);
+  const prior = await store.load().catch(() => null);
+  const preserved = prior?.apiToken === void 0 ? enriched : { ...enriched, apiToken: prior.apiToken };
+  await store.save(preserved);
+  log(`Signed in as ${enriched.user?.email ?? "unknown"}.`);
   log(`Credentials saved to ${store.path()}`);
   await ensureActiveOrganization({
-    credentials: enriched,
+    credentials: preserved,
     webappUrl: config.webappUrl,
     requestedSlug: options.org,
     store,
@@ -1024,11 +1066,31 @@ async function runLogout() {
         "Content-Type": "application/json",
         Authorization: `Bearer ${existing.accessToken}`
       },
-      body: JSON.stringify({ refreshToken: existing.refreshToken }),
+      // Only session-derived credentials have a server-side session to end.
+      // An API-token credential has none, so there is nothing to revoke here —
+      // revoking the token itself is done from the MySpec web UI.
+      body: JSON.stringify(
+        existing.refreshToken ? { refreshToken: existing.refreshToken } : {}
+      ),
       signal: AbortSignal.timeout(5e3)
     });
   } catch {
   }
+  if (existing.apiToken) {
+    await store.save({
+      apiToken: existing.apiToken,
+      accessToken: "",
+      expiresAt: 0,
+      userAuthUrl: existing.userAuthUrl,
+      ...existing.platformUrl ? { platformUrl: existing.platformUrl } : {},
+      ...existing.webappUrl ? { webappUrl: existing.webappUrl } : {},
+      ...existing.aiAgentMcpReverseUrl ? { aiAgentMcpReverseUrl: existing.aiAgentMcpReverseUrl } : {}
+    });
+    process.stderr.write(
+      "Signed out. The configured API token was kept \u2014 delete the `apiToken` field in ~/.myspec/oauth_creds.json to remove it.\n"
+    );
+    return;
+  }
   await store.clear();
   process.stderr.write("Signed out and cleared local credentials.\n");
 }
@@ -4713,7 +4775,7 @@ Press Ctrl-C to stop. Auto-reconnect enabled.
       const message = err instanceof Error ? err.message : String(err);
       process.stderr.write(
         `myspec-mcp reverse: cannot obtain access token: ${message}
-Run \`npx @myspec/mcp-server login\` (or set MYSPEC_REFRESH_TOKEN) and try again.
+Run \`npx @myspec/mcp-server login\`, or configure an API token, and try again.
 `
       );
       return;
@@ -5015,10 +5077,7 @@ function printHelp() {
     "",
     "Environment:",
     "  MYSPEC_USER_AUTH_URL    user-auth base URL (default https://auth.myspec.dev)",
-    "  MYSPEC_AI_AGENT_WS_URL  ai-agent WebSocket URL for `reverse` (skips discovery)",
-    "  MYSPEC_REFRESH_TOKEN    Skip file-based credentials; the server mints a",
-    "                          fresh access token on first use via this refresh",
-    "                          token."
+    "  MYSPEC_AI_AGENT_WS_URL  ai-agent WebSocket URL for `reverse` (skips discovery)"
   ];
   process.stderr.write(lines.join("\n") + "\n");
 }
@@ -5126,12 +5185,9 @@ async function runReverseCommand(flags) {
     loadStored = () => Promise.resolve(null);
     persist = void 0;
   } else {
-    const envConfig = readEnvRefreshConfig();
-    const store = createCompositeCredentialsStore({
-      fileStore: createFileCredentialsStore(),
-      envConfig
-    });
-    const tokenManager = new TokenManager({ store, envFallback: envConfig });
+    assertNoEnvAccessToken();
+    const store = createFileCredentialsStore();
+    const tokenManager = new TokenManager({ store });
     getAccessToken = () => tokenManager.getValidAccessToken();
     onAuthFailed = async () => {
       await tokenManager.forceRefresh();
@@ -5198,25 +5254,19 @@ function createPlatformUrlResolver(deps) {
   };
 }
 async function runServe(flags) {
-  const envConfig = readEnvRefreshConfig();
-  const store = createCompositeCredentialsStore({
-    fileStore: createFileCredentialsStore(),
-    envConfig
-  });
+  assertNoEnvAccessToken();
+  const store = createFileCredentialsStore();
   const initial = await store.load();
   if (!initial) {
     process.stderr.write(
-      "myspec-mcp: starting unauthenticated. Run `npx @myspec/mcp-server login` (or set MYSPEC_REFRESH_TOKEN) to enable tools.\n"
+      "myspec-mcp: starting unauthenticated. Run `npx @myspec/mcp-server login`, or configure an API token, to enable tools.\n"
     );
   }
   const config = resolveConfig({
     cliUserAuthUrl: flagString(flags, "user-auth-url"),
     storedUserAuthUrl: initial?.userAuthUrl
   });
-  const tokenManager = new TokenManager({
-    store,
-    envFallback: envConfig
-  });
+  const tokenManager = new TokenManager({ store });
   const client = new PlatformClient({
     resolveBaseUrl: createPlatformUrlResolver({
       store,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myspec/mcp-server",
-  "version": "0.2.0-next.79",
+  "version": "0.2.0-next.80",
   "description": "MySpec MCP server — exposes MySpec platform projects, files and attachments to MCP-aware clients via OAuth-authenticated access tokens.",
   "type": "module",
   "repository": {