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

package/README.md

@@ -20,12 +20,44 @@ Run with `npx @myspec/mcp-server [command]` (or `myspec-mcp [command]` when inst
 (default)                 Start MCP server over stdio
 serve                     Start MCP server over stdio
 login                     Sign in via browser loopback OAuth
-login --paste             Sign in by pasting a one-time code
+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
 reverse --root <dir>      Connect to ai-agent and expose local_fs tools
 ```
 
+### Signing in from another device (`--paste`)
+
+`login` opens a browser on this machine and catches the callback on a local
+loopback port. When the browser lives somewhere else — a remote dev box, a
+container, a phone — use `--paste`: the same flow, minus the auto-open.
+
+```bash
+npx -y @myspec/mcp-server login --paste
+```
+
+Open the printed URL wherever you can. If the page cannot reach this CLI, it
+shows a token in a box that looks like `<code>.<state>`. Copy **the whole
+value, including the dot** and paste it back into the terminal. Two traps:
+
+- The page's copy button is labelled "Copy code" and the page URL contains a
+  bare `?code=`. Neither of those bare values works — the CLI rejects them with
+  `Pasted token is missing a state suffix`.
+- The code expires **60 seconds after you finish signing in** — not 60 seconds
+  after the token appears. user-auth starts that clock before redirecting to
+  the page, and the page then spends part of it trying to reach this CLI
+  (instant if the port refuses the connection, but up to the browser's connect
+  timeout if it is filtered). So paste it the moment it appears; a stale one
+  fails with `OAuth code exchange failed: HTTP 401`. The CLI's own deadline is
+  minutes long, which is time to *reach* the token, not to use it.
+
+> **Do not open the sign-in URL on a machine where you do not trust everything
+> else running on it.** The page attempts a callback to `127.0.0.1:<port>` on
+> whichever machine opens the URL, and anything listening on that port can take
+> the one-time code and exchange it for an access **and** refresh token —
+> keeping access until you run `logout`. The CLI prints the same warning with
+> the actual port, before the URL.
+
 ### Active organization
 
 Every MySpec access token carries the slug of one **active organization**, and

package/dist/index.js

@@ -44,6 +44,13 @@ var ConfigError = class extends Error {
 
 // src/auth/oauth-loopback.ts
 var DEFAULT_TIMEOUT_MS = 5 * 6e4;
+function callbackWarning(callbackBase) {
+  return `Note: the sign-in page will try to call back to ${callbackBase}
+on whichever machine opens that URL. Do not open it on a machine where you
+do not trust everything else running on it \u2014 anything listening on that port
+can take the one-time code and exchange it for an access *and* refresh token,
+keeping access until you run \`myspec-mcp logout\`.`;
+}
 var SUCCESS_HTML = "<!doctype html><html><body><h1>Sign-in complete</h1><p>You may close this tab and return to your terminal.</p></body></html>";
 var ERROR_HTML = "<!doctype html><html><body><h1>Sign-in failed</h1><p>Return to your terminal for details.</p></body></html>";
 async function loopbackLogin(opts) {
@@ -67,17 +74,29 @@ async function loopbackLogin(opts) {
       const webappLogin = new URL(`${opts.webappUrl.replace(/\/$/, "")}/auth/cli`);
       webappLogin.searchParams.set("target", loopbackTarget);
       const signInUrl = webappLogin.toString();
+      const remoteBrowser = opts.remoteBrowser ?? !opts.openBrowser;
+      if (remoteBrowser) {
+        logger(callbackWarning(callbackBase));
+      }
       logger(`Open this URL in your browser to sign in:
   ${signInUrl}`);
       if (!opts.disablePasteFallback) {
+        const lead = remoteBrowser ? "Sign in there. If the page shows a token box, copy the whole value" : "If the browser cannot reach this CLI directly, copy the whole token";
         logger(
-          "If the browser cannot reach this CLI directly, paste the code shown on the\n/auth/cli page here and press Enter."
+          `${lead}
+shown in the box \u2014 it looks like \`<code>.<state>\` \u2014 and paste it here,
+then press Enter. (Not the \`code=\` value from the URL.) The code expires
+60 seconds after you finish signing in, and the page spends part of that
+trying to reach this CLI, so paste it the moment it appears.`
         );
       }
       if (opts.openBrowser) {
         opts.openBrowser(signInUrl).catch((err) => {
           const message = err instanceof Error ? err.message : String(err);
           logger(`Failed to open browser automatically: ${message}`);
+          if (!remoteBrowser) {
+            logger(callbackWarning(callbackBase));
+          }
         });
       }
     }
@@ -233,51 +252,6 @@ async function exchangeCode(userAuthUrl, code, fetchImpl) {
   return await response.json();
 }
 
-// src/auth/oauth-paste.ts
-import readline2 from "readline/promises";
-async function pasteLogin(opts) {
-  const fetchImpl = opts.fetchImpl ?? fetch;
-  const now = opts.now ?? Date.now;
-  const logger = opts.logger ?? ((m) => {
-    process.stderr.write(m + "\n");
-  });
-  const signInUrl = `${opts.webappUrl.replace(/\/$/, "")}/auth/cli`;
-  logger("Open this URL in your browser, sign in, and copy the one-time code shown:");
-  logger(`  ${signInUrl}`);
-  const ask = opts.prompt ?? defaultPrompt;
-  const raw = await ask("Paste the one-time code: ");
-  const code = raw.trim();
-  if (!code) {
-    throw new Error("No code provided.");
-  }
-  const response = await fetchImpl(`${opts.userAuthUrl}/api/auth/oauth/exchange`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ code })
-  });
-  if (!response.ok) {
-    const body = await response.text().catch(() => "");
-    throw new HttpStatusError(response.status, body, `OAuth code exchange failed: HTTP ${String(response.status)}`);
-  }
-  const exchanged = await response.json();
-  return {
-    accessToken: exchanged.accessToken,
-    refreshToken: exchanged.refreshToken,
-    expiresAt: now() + exchanged.expiresIn * 1e3,
-    userAuthUrl: opts.userAuthUrl,
-    webappUrl: opts.webappUrl,
-    user: exchanged.user
-  };
-}
-async function defaultPrompt(question) {
-  const rl = readline2.createInterface({ input: process.stdin, output: process.stderr });
-  try {
-    return await rl.question(question);
-  } finally {
-    rl.close();
-  }
-}
-
 // src/auth/credentials-store.ts
 import { promises as fs } from "fs";
 import os from "os";
@@ -615,7 +589,7 @@ var RefreshRejectedError = class extends NeedsLoginError {
 };
 
 // src/auth/organization.ts
-import readline3 from "readline";
+import readline2 from "readline";
 function readOrgClaim(accessToken) {
   const payload = accessToken.split(".")[1];
   if (payload === void 0) {
@@ -716,7 +690,7 @@ async function promptForOrganization(organizations, deps = {}) {
     output.write(`  ${String(index + 1)}) ${org.name} (${org.slug})
 `);
   });
-  const rl = readline3.createInterface({ input, output });
+  const rl = readline2.createInterface({ input, output });
   try {
     for (; ; ) {
       const answer = await new Promise((resolve3) => {
@@ -891,19 +865,23 @@ function discoveryError(endpoint, reason, hint) {
 }
 
 // src/cli/login.ts
+var PASTE_TIMEOUT_MS = 15 * 6e4;
 async function runLogin(options, deps = {}) {
   const config = resolveConfig({ cliUserAuthUrl: options.userAuthUrl });
   const store = deps.store ?? createFileCredentialsStore();
   const log = deps.log ?? ((message) => {
     process.stderr.write(message + "\n");
   });
-  const doLogin = deps.doLogin ?? ((cfg) => options.paste ? pasteLogin(cfg) : loopbackLogin({
-    ...cfg,
-    openBrowser: async (url) => {
-      const mod = await import("open");
-      await mod.default(url);
-    }
-  }));
+  const openBrowser = async (url) => {
+    const mod = await import("open");
+    await mod.default(url);
+  };
+  const loopback = deps.loopback ?? loopbackLogin;
+  const doLogin = deps.doLogin ?? ((cfg) => {
+    return loopback(
+      options.paste ? { ...cfg, remoteBrowser: true, timeoutMs: PASTE_TIMEOUT_MS } : { ...cfg, openBrowser }
+    );
+  });
   const credentials = await doLogin({
     userAuthUrl: config.userAuthUrl,
     webappUrl: config.webappUrl
@@ -5011,7 +4989,9 @@ function printHelp() {
     "  (default)               Start MCP server over stdio",
     "  serve                   Start MCP server over stdio",
     "  login                   Sign in via browser (chooser page on the webapp)",
-    "  login --paste           Sign in by pasting a one-time code",
+    "  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",
     "                          when an organization is active; the CLI asks when you",
     "                          belong to several and this flag is not given.",

package/package.json

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