@myspec/mcp-server 1.1.1-next.156 → 1.1.1-next.157

package/README.md

@@ -19,13 +19,19 @@ Run with `npx @myspec/mcp-server [command]` (or `myspec-mcp [command]` when inst
 ```text
 (default)                 Start MCP server over stdio
 serve                     Start MCP server over stdio
-login                     Sign in via browser loopback OAuth
-login --paste             Same as login, but never auto-opens a browser
-login --org <slug>        Sign in and pin that organization
-logout                    Revoke refresh token and clear local credentials
+auth login                Sign in via browser loopback OAuth
+auth login --paste        Same as auth login, but never auto-opens a browser
+auth login --org <slug>   Sign in and pin that organization
+auth logout               Revoke refresh token and clear local credentials
+auth status               Show the sign-in: account email and active organization
+login, logout             Aliases for `auth login` and `auth logout`
 reverse --root <dir>      Connect to ai-agent and expose local_fs tools
 ```
 
+`login` and `logout` keep working exactly as before; they run `auth login` and
+`auth logout`. Add `--help` after any auth command to print the usage instead
+of running it.
+
 ### Signing in from another device (`--paste`)
 
 `login` opens a browser on this machine and catches the callback on a local
@@ -239,6 +245,45 @@ dev environment:
 npx -y @myspec/mcp-server login --user-auth-url https://dev-auth.myspec.dev
 ```
 
+### Checking your sign-in (`auth status`)
+
+```bash
+npx -y @myspec/mcp-server auth status
+```
+
+```text
+Signed in to https://auth.myspec.dev
+  Account:       jane@example.com
+  Organization:  Acme Inc (acme)
+  Credential:    login session (/home/jane/.myspec/oauth_creds.json)
+```
+
+It reports the credential `serve` would use, in the same precedence order
+(`MYSPEC_API_TOKEN` > file `apiToken` > the `login` session), and honours
+`--user-auth-url` the same way. The first line names the auth server, which is
+how you tell a dev sign-in from a production one.
+
+- **What is checked online.** The email and organization come from the saved
+  access token while it is still valid (they last 15 minutes); once it has
+  expired, `auth status` renews it first, like any other command. For a login
+  session it then looks the organization name up from user-auth, which also
+  confirms the session: one that was ended on the server is reported as signed
+  out. `MYSPEC_API_TOKEN` is exchanged on every run. A file `apiToken` whose
+  saved access token is still valid is not checked with the server, so a token
+  revoked in the webapp can still show as signed in for up to 15 minutes.
+- **API tokens show the organization slug only**, e.g.
+  `acme (API tokens do not include the organization name)`, plus the token's
+  access mode (`read-only` or `read-write`). user-auth has no endpoint that
+  returns the name for an API token.
+- **No active organization** prints `Organization: none` and how to pin one.
+- **If the name lookup fails** (the network, or a server error), the slug is
+  shown with the reason and the command still succeeds.
+- **Exit codes:** `0` when signed in; `2` when not signed in, when the
+  credential is rejected, or when an expired token could not be renewed — so
+  `auth status || auth login` works in a script. A problem with the
+  credentials file itself (wrong file mode, bad JSON) fails the same way
+  `serve` does. A failure never deletes the saved credentials.
+
 ### `reverse`
 
 `reverse` connects out to the ai-agent service over WebSocket and exposes a set

package/dist/index.js

@@ -319,6 +319,14 @@ function createFileCredentialsStore(paths = {}) {
     }
   };
 }
+function keepCredentialsOnFailure(store) {
+  return {
+    load: () => store.load(),
+    save: (creds) => store.save(creds),
+    clear: () => Promise.resolve(),
+    path: () => store.path()
+  };
+}
 async function writeSettingsFile(target, creds) {
   await writeJsonFile(
     target,
@@ -809,19 +817,36 @@ var ApiTokenRejectedError = class extends ConfigError {
 
 // src/auth/organization.ts
 import readline2 from "readline";
-function readOrgClaim(accessToken) {
+
+// src/auth/token-claims.ts
+function readTokenClaims(accessToken) {
   const payload = accessToken.split(".")[1];
   if (payload === void 0) {
-    return void 0;
+    return {};
   }
+  let claims;
   try {
-    const json = Buffer.from(payload, "base64url").toString("utf-8");
-    const claims = JSON.parse(json);
-    const org = claims.org;
-    return typeof org === "string" && org.length > 0 ? org : void 0;
+    claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf-8"));
   } catch {
-    return void 0;
+    return {};
+  }
+  if (typeof claims !== "object" || claims === null) {
+    return {};
   }
+  const record = claims;
+  return {
+    email: nonEmptyString(record.email),
+    org: nonEmptyString(record.org),
+    access: nonEmptyString(record.access)
+  };
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+
+// src/auth/organization.ts
+function readOrgClaim(accessToken) {
+  return readTokenClaims(accessToken).org;
 }
 var NO_ACTIVE_ORG_HINT = "Your CLI session has no active organization, so the access token is missing the `org` claim that the platform API and ai-agent require. Run `npx @myspec/mcp-server login --org <slug>` to pin one.";
 async function listOrganizations(opts) {
@@ -1199,14 +1224,6 @@ function defaultRefreshTokens(store) {
   const tokenManager = new TokenManager({ store: keepCredentialsOnFailure(store) });
   return tokenManager.forceRefresh();
 }
-function keepCredentialsOnFailure(store) {
-  return {
-    load: () => store.load(),
-    save: (creds) => store.save(creds),
-    clear: () => Promise.resolve(),
-    path: () => store.path()
-  };
-}
 function sameSlug(a, b) {
   return a.toLowerCase() === b.toLowerCase();
 }
@@ -1289,6 +1306,153 @@ async function runLogout(env = process.env) {
   }
 }
 
+// src/cli/auth-status.ts
+var NOT_SIGNED_IN = "Not signed in. Run `npx @myspec/mcp-server auth login` to sign in, or set MYSPEC_API_TOKEN to a MySpec API token.";
+var SESSION_REVOKED = "Your saved sign-in is no longer valid: the session was ended on the server. Run `npx @myspec/mcp-server auth login` to sign in again.";
+async function resolveAuthStatus(deps) {
+  const stored = await deps.store.load();
+  if (!stored) {
+    throw new NeedsLoginError(NOT_SIGNED_IN);
+  }
+  let accessToken;
+  try {
+    accessToken = await deps.getAccessToken();
+  } catch (err) {
+    throw describeTokenFailure(err, stored.userAuthUrl);
+  }
+  const claims = readTokenClaims(accessToken);
+  const kind = credentialKind(stored, deps.envApiTokenActive);
+  const status = {
+    userAuthUrl: stored.userAuthUrl,
+    credential: { kind, location: deps.store.path() },
+    // The saved user is the fallback only: an API-token record has none.
+    email: claims.email ?? stored.user?.email,
+    access: claims.access
+  };
+  const slug = claims.org;
+  if (slug === void 0) {
+    return status;
+  }
+  if (kind !== "login-session") {
+    return {
+      ...status,
+      organization: { slug },
+      orgNameNote: "API tokens do not include the organization name"
+    };
+  }
+  let organizations;
+  try {
+    organizations = await deps.listOrgs({
+      userAuthUrl: stored.userAuthUrl,
+      accessToken,
+      webappUrl: stored.webappUrl ?? deps.webappUrl
+    });
+  } catch (err) {
+    if (err instanceof HttpStatusError && err.status === 401) {
+      throw new NeedsLoginError(SESSION_REVOKED);
+    }
+    return {
+      ...status,
+      organization: { slug },
+      orgNameNote: `could not look up its name: ${errorMessage2(err)}`
+    };
+  }
+  const match = organizations.find((org) => org.slug.toLowerCase() === slug.toLowerCase());
+  if (!match) {
+    return {
+      ...status,
+      organization: { slug },
+      orgNameNote: "not among your organizations; it may have been deleted, or you were removed"
+    };
+  }
+  return { ...status, organization: { slug, name: match.name } };
+}
+function describeTokenFailure(err, userAuthUrl) {
+  if (err instanceof TypeError) {
+    return new ConfigError(
+      `Could not reach ${userAuthUrl} to check the sign-in: ${errorMessage2(err)}`
+    );
+  }
+  if (err instanceof HttpStatusError) {
+    return new ConfigError(
+      `Could not check the sign-in against ${userAuthUrl}: ${errorMessage2(err)}`
+    );
+  }
+  return err;
+}
+function credentialKind(stored, envApiTokenActive) {
+  if (stored.apiToken === void 0) {
+    return "login-session";
+  }
+  return envApiTokenActive ? "env-api-token" : "file-api-token";
+}
+function formatAuthStatus(status) {
+  const lines = [
+    `Signed in to ${status.userAuthUrl}`,
+    `  Account:       ${status.email ?? "unknown"}`,
+    `  Organization:  ${formatOrganization(status)}`,
+    `  Credential:    ${formatCredential(status)}`
+  ];
+  if (status.organization === void 0) {
+    lines.push("", `Warning: ${NO_ACTIVE_ORG_HINT}`);
+  }
+  return lines;
+}
+function formatOrganization(status) {
+  const org = status.organization;
+  if (org === void 0) {
+    return "none";
+  }
+  if (org.name !== void 0) {
+    return `${org.name} (${org.slug})`;
+  }
+  return status.orgNameNote === void 0 ? org.slug : `${org.slug} (${status.orgNameNote})`;
+}
+function formatCredential(status) {
+  const access = status.access === void 0 ? "" : ` (${formatAccess(status.access)})`;
+  switch (status.credential.kind) {
+    case "env-api-token":
+      return `API token from MYSPEC_API_TOKEN${access}`;
+    case "file-api-token":
+      return `API token in ${status.credential.location}${access}`;
+    case "login-session":
+      return `login session (${status.credential.location})`;
+  }
+}
+function formatAccess(access) {
+  if (access === "read") {
+    return "read-only";
+  }
+  if (access === "write") {
+    return "read-write";
+  }
+  return access;
+}
+function errorMessage2(err) {
+  return redactSensitive(err instanceof Error ? err.message : String(err));
+}
+async function runAuthStatus(options, deps = {}) {
+  const log = deps.log ?? ((message) => {
+    process.stderr.write(message + "\n");
+  });
+  const tokenManager = new TokenManager({
+    store: keepCredentialsOnFailure(options.store),
+    fetchImpl: deps.fetchImpl
+  });
+  const listOrgs = deps.listOrgs ?? ((opts) => listOrganizations({ ...opts, fetchImpl: deps.fetchImpl }));
+  const status = await resolveAuthStatus({
+    store: options.store,
+    getAccessToken: () => tokenManager.getValidAccessToken(),
+    listOrgs,
+    webappUrl: options.webappUrl,
+    envApiTokenActive: options.envApiTokenActive
+  });
+  for (const line of formatAuthStatus(status)) {
+    log(line);
+  }
+  return status;
+}
+
 // src/platform/client.ts
 import { createHash } from "crypto";
 
@@ -7328,7 +7492,7 @@ async function handleList(args, opts) {
   try {
     await walk(realPath, "");
   } catch (err) {
-    return structuredError("list_dir_failed", errorMessage2(err));
+    return structuredError("list_dir_failed", errorMessage3(err));
   }
   return structuredOk({ entries, truncated });
 }
@@ -7349,7 +7513,7 @@ async function handleRead(args, opts) {
   try {
     stat2 = await fs4.stat(realPath);
   } catch (err) {
-    return structuredError("stat_failed", errorMessage2(err));
+    return structuredError("stat_failed", errorMessage3(err));
   }
   if (!stat2.isFile()) {
     return structuredError("not_a_file", `Not a regular file: ${args.path}`);
@@ -7365,7 +7529,7 @@ async function handleRead(args, opts) {
   try {
     raw = await fs4.readFile(realPath);
   } catch (err) {
-    return structuredError("read_failed", errorMessage2(err));
+    return structuredError("read_failed", errorMessage3(err));
   }
   const probe = raw.subarray(0, Math.min(READ_FILE_BINARY_PROBE_BYTES, raw.length));
   if (probe.includes(0)) {
@@ -7572,7 +7736,7 @@ async function nodeGrep(searchRoot, realRoot, pattern, opts) {
   try {
     regex = opts.isRegex ? new RegExp(pattern, opts.caseSensitive ? "" : "i") : new RegExp(escapeRegExp(pattern), opts.caseSensitive ? "" : "i");
   } catch (err) {
-    throw new InvalidRegexError(errorMessage2(err));
+    throw new InvalidRegexError(errorMessage3(err));
   }
   const matches = [];
   let truncated = false;
@@ -7646,7 +7810,7 @@ async function nodeGrep(searchRoot, realRoot, pattern, opts) {
 function escapeRegExp(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function errorMessage2(err) {
+function errorMessage3(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function mapPathError(err) {
@@ -7659,7 +7823,7 @@ function mapPathError(err) {
   if (err.code === "ENOENT") {
     return structuredError("not_found", "Path does not exist");
   }
-  return structuredError("resolve_failed", errorMessage2(err));
+  return structuredError("resolve_failed", errorMessage3(err));
 }
 function mapPackError(err) {
   if (err instanceof PackCacheMissError) {
@@ -7674,7 +7838,7 @@ function mapPackError(err) {
   if (err instanceof AbsolutePathError || err instanceof PathOutsideRootError) {
     return mapPathError(err);
   }
-  return structuredError("pack_failed", errorMessage2(err));
+  return structuredError("pack_failed", errorMessage3(err));
 }
 function registerLocalFsTools(server, opts) {
   const packCache = new PackCache();
@@ -7753,7 +7917,7 @@ function registerLocalFsTools(server, opts) {
 `);
       return result;
     } catch (err) {
-      const msg = errorMessage2(err);
+      const msg = errorMessage3(err);
       const elapsedMs = Math.round(performance.now() - started);
       process.stdout.write(`[tool] ${name}  -> threw  ${String(elapsedMs)}ms  ${msg}
 `);
@@ -8114,20 +8278,49 @@ function createReverseMcpPresenceProbe(deps) {
 }
 
 // src/index.ts
+var AUTH_COMMANDS = ["login", "logout", "status"];
+function isAuthCommand(value) {
+  return AUTH_COMMANDS.includes(value);
+}
 function parseArgs(argv) {
   const [first, ...rest] = argv;
-  let command = "serve";
-  let flagArgs = argv;
-  if (first === "login" || first === "logout" || first === "serve" || first === "reverse" || first === "help" || first === "version") {
-    command = first;
-    flagArgs = rest;
-  } else if (first === "--help" || first === "-h") {
-    command = "help";
-    flagArgs = rest;
-  } else if (first === "--version" || first === "-v") {
-    command = "version";
-    flagArgs = rest;
+  if (first === "auth") {
+    const [sub, ...subRest] = rest;
+    if (sub === void 0 || sub === "help" || sub === "--help" || sub === "-h") {
+      return { command: "help", flags: /* @__PURE__ */ new Map() };
+    }
+    if (!isAuthCommand(sub)) {
+      throw new ConfigError(
+        `Unknown auth command: ${sub}. Expected one of: ${AUTH_COMMANDS.join(", ")}.`
+      );
+    }
+    return authArgs(sub, subRest);
+  }
+  if (first === "login" || first === "logout") {
+    return authArgs(first, rest);
+  }
+  if (first === "serve" || first === "reverse" || first === "help" || first === "version") {
+    return { command: first, flags: parseFlags(rest) };
+  }
+  if (first === "--help" || first === "-h") {
+    return { command: "help", flags: parseFlags(rest) };
+  }
+  if (first === "--version" || first === "-v") {
+    return { command: "version", flags: parseFlags(rest) };
+  }
+  return { command: "serve", flags: parseFlags(argv) };
+}
+function authArgs(authCommand, args) {
+  if (args.includes("-h")) {
+    return { command: "help", flags: /* @__PURE__ */ new Map() };
   }
+  const flags = parseFlags(args);
+  if (flags.has("help")) {
+    return { command: "help", flags };
+  }
+  return { command: "auth", authCommand, flags };
+}
+function parseFlags(flagArgs) {
   const flags = /* @__PURE__ */ new Map();
   const unknownPositional = [];
   for (let i = 0; i < flagArgs.length; i += 1) {
@@ -8157,7 +8350,7 @@ function parseArgs(argv) {
       `Unknown positional arguments: ${unknownPositional.join(", ")}. Run \`npx @myspec/mcp-server --help\` for usage.`
     );
   }
-  return { command, flags };
+  return flags;
 }
 function flagString(flags, key) {
   const value = flags.get(key);
@@ -8176,16 +8369,21 @@ function printHelp() {
     "Commands:",
     "  (default)               Start MCP server over stdio",
     "  serve                   Start MCP server over stdio",
-    "  login                   Sign in via browser (chooser page on the webapp)",
-    "  login --paste           Same as login, but never auto-opens a browser. Open",
-    "                          the printed URL yourself; if the page cannot reach this",
-    "                          CLI it shows a `<code>.<state>` token to paste back.",
-    "  login --org <slug>      Sign in and pin that organization. Tokens only work",
+    "  auth login              Sign in via browser (chooser page on the webapp)",
+    "  auth login --paste      Same as auth login, but never auto-opens a browser.",
+    "                          Open the printed URL yourself; if the page cannot reach",
+    "                          this CLI it shows a `<code>.<state>` token to paste back.",
+    "  auth login --org <slug> Sign in and pin that organization. Tokens only work",
     "                          when an organization is active; the CLI asks when you",
     "                          belong to several and this flag is not given.",
-    "  logout                  Sign out and clear the session credentials. A",
+    "  auth logout             Sign out and clear the session credentials. A",
     "                          configured apiToken is KEPT, so an unattended",
     "                          install keeps working.",
+    "  auth status             Show whether you are signed in, the account email and",
+    "                          the active organization. Renews an expired access",
+    "                          token first, as any command does. Exits 2 when not",
+    "                          signed in.",
+    "  login, logout           Aliases for `auth login` and `auth logout`.",
     "  reverse --root <dir>    Connect to ai-agent and expose local_fs tools.",
     "                          The agent WebSocket URL is discovered from the webapp",
     "                          (GET /api/v1/config) using your saved credentials;",
@@ -8238,14 +8436,28 @@ function assertOrgFlagHasValue(flags) {
   }
 }
 async function main(argv = process.argv.slice(2)) {
-  const { command, flags } = parseArgs(argv);
-  switch (command) {
+  const parsed = parseArgs(argv);
+  const { flags } = parsed;
+  switch (parsed.command) {
     case "help":
       printHelp();
       return;
     case "version":
       process.stderr.write(readVersion() + "\n");
       return;
+    case "auth":
+      await runAuthCommand(parsed.authCommand, flags);
+      return;
+    case "reverse":
+      await runReverseCommand(flags);
+      return;
+    case "serve":
+      await runServe(flags);
+      return;
+  }
+}
+async function runAuthCommand(authCommand, flags) {
+  switch (authCommand) {
     case "login":
       assertOrgFlagHasValue(flags);
       await runLogin({
@@ -8257,13 +8469,14 @@ async function main(argv = process.argv.slice(2)) {
     case "logout":
       await runLogout();
       return;
-    case "reverse":
-      await runReverseCommand(flags);
-      return;
-    case "serve":
-    default:
-      await runServe(flags);
+    case "status": {
+      assertNoEnvAccessToken();
+      const { store, config, envApiTokenActive } = await buildCredentialsStore({
+        cliUserAuthUrl: flagString(flags, "user-auth-url")
+      });
+      await runAuthStatus({ store, webappUrl: config.webappUrl, envApiTokenActive });
       return;
+    }
   }
 }
 var REVERSE_DISCOVERY_HINT = "Pass --agent-url <url>, set MYSPEC_AI_AGENT_WS_URL, or run `npx @myspec/mcp-server login` and retry.";
@@ -8353,17 +8566,12 @@ async function buildCredentialsStore(opts = {}) {
     // ConfigError exit — and one that never names the file it came from.
     storedUserAuthUrl: stored?.userAuthUrl ?? usableAuthUrl(fromSettings, settingsPath, warn)
   });
+  const envConfig = readEnvApiToken(config.userAuthUrl, env, warn);
   return {
-    store: createEnvApiTokenStore({
-      fileStore,
-      // `warn` rather than the default sink, so the "cannot be sent as a
-      // header" warning lands wherever the caller's other warnings do.
-      envConfig: readEnvApiToken(config.userAuthUrl, env, warn),
-      settingsPath,
-      warn
-    }),
+    store: createEnvApiTokenStore({ fileStore, envConfig, settingsPath, warn }),
     config,
-    usingEnvApiToken
+    usingEnvApiToken,
+    envApiTokenActive: envConfig !== null
   };
 }
 function warnIfStaticTokenShadowsApiToken(inlineToken, env = process.env, warn = (message) => {

package/package.json

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