@myspec/mcp-server 0.1.0-next.1 → 0.1.0-next.11

package/README.md

@@ -23,19 +23,54 @@ login                     Sign in via browser loopback OAuth
 login --paste             Sign in by pasting a one-time code
 login --provider <google|github|gitlab|linear|atlassian>
 logout                    Revoke refresh token and clear local credentials
+reverse --root <dir>      Connect to ai-agent and expose local_fs tools
 ```
 
-Credentials are persisted at `$XDG_CONFIG_HOME/myspec/mcp-server.json` (POSIX) or `%APPDATA%\myspec\mcp-server.json` (Windows), mode `0600`.
+### `reverse`
+
+`reverse` connects out to the ai-agent service over WebSocket and exposes a set
+of `local_fs` tools scoped to a single local directory, so a cloud agent can
+read files from your machine.
+
+```bash
+npx @myspec/mcp-server@next reverse --root /path/to/project
+```
+
+The ai-agent WebSocket URL is **discovered at startup** from the webapp's
+authenticated `GET /api/v1/config` endpoint using your saved credentials, so
+the agent domain is never hardcoded in the CLI and can change server-side.
+If discovery fails, `reverse` exits with an actionable error instead of
+guessing — pass `--agent-url` or set `MYSPEC_AI_AGENT_WS_URL` to skip
+discovery (e.g. against a local ai-agent):
+
+```bash
+npx @myspec/mcp-server@next reverse --root . --agent-url ws://localhost:3001/mcp/reverse
+```
+
+| Flag / env | Purpose |
+|---|---|
+| `--root <dir>` | Directory to grant read access to (default: current working directory). All tool paths resolve relative to this root; nothing outside it is reachable. |
+| `--agent-url <url>` / `MYSPEC_AI_AGENT_WS_URL` | ai-agent WebSocket URL override; skips webapp discovery entirely. |
+| `--webapp-url <url>` | Webapp base URL used for discovery (default: the URL stored at login, else derived from the auth host). |
+| `--access-token <jwt>` / `MYSPEC_ACCESS_TOKEN` | Use a static access token for local testing instead of the saved credentials. Otherwise `reverse` uses the refresh token from `npx @myspec/mcp-server login` and auto-refreshes. |
+
+Local state is stored under `~/.myspec/` (alongside the on-disk cache root), split into two files:
+
+- `settings.json` — non-secret config: the auth-server, platform, and webapp URLs you logged in with.
+- `oauth_creds.json` — the OAuth tokens (access/refresh/expiry) and your user identity, written mode `0600`.
+
+`logout` removes `oauth_creds.json`; `settings.json` is left in place.
 
 ## Environment variables
 
 | Variable | Purpose |
 |---|---|
 | `MYSPEC_USER_AUTH_URL` | user-auth base URL (default `https://auth.myspec.dev`) |
-| `MYSPEC_PLATFORM_URL` | platform API base URL (default `https://api.myspec.dev`) |
+| `MYSPEC_PLATFORM_URL` | platform API base URL (default `https://platform.myspec.dev`) |
 | `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_file` as its on-disk cache root (default: `~/.myspec`). Tools never write outside this root. |
-| `MYSPEC_WEBAPP_URL` | Webapp base URL used by `login --paste` to display the OAuth callback URL (default: derived from `MYSPEC_USER_AUTH_URL`) |
+| `MYSPEC_WEBAPP_URL` | Webapp base URL used by `login` (the `/auth/cli` page) and by `reverse` discovery (default: the URL stored at login, else derived from `MYSPEC_USER_AUTH_URL`) |
+| `MYSPEC_AI_AGENT_WS_URL` | ai-agent WebSocket URL for `reverse`; skips the webapp discovery call |
 
 ## Tools
 

package/dist/index.js

@@ -90,6 +90,7 @@ async function loopbackLogin(opts) {
     expiresAt: now() + exchanged.expiresIn * 1e3,
     userAuthUrl: opts.userAuthUrl,
     platformUrl: opts.platformUrl,
+    webappUrl: opts.webappUrl,
     user: exchanged.user
   };
 }
@@ -266,6 +267,7 @@ async function pasteLogin(opts) {
     expiresAt: now() + exchanged.expiresIn * 1e3,
     userAuthUrl: opts.userAuthUrl,
     platformUrl: opts.platformUrl,
+    webappUrl: opts.webappUrl,
     user: exchanged.user
   };
 }
@@ -282,57 +284,117 @@ async function defaultPrompt(question) {
 import { promises as fs } from "fs";
 import os from "os";
 import path from "path";
-function defaultCredentialsPath(env = process.env) {
-  if (process.platform === "win32") {
-    const appData = env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
-    return path.join(appData, "myspec", "mcp-server.json");
-  }
-  const xdg = env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
-  return path.join(xdg, "myspec", "mcp-server.json");
+function myspecDir() {
+  return path.join(os.homedir(), ".myspec");
+}
+function defaultSettingsPath() {
+  return path.join(myspecDir(), "settings.json");
 }
-function createFileCredentialsStore(filePath) {
-  const target = filePath ?? defaultCredentialsPath();
+function defaultOauthCredsPath() {
+  return path.join(myspecDir(), "oauth_creds.json");
+}
+function createFileCredentialsStore(paths = {}) {
+  const settingsPath = paths.settingsPath ?? defaultSettingsPath();
+  const oauthCredsPath = paths.oauthCredsPath ?? defaultOauthCredsPath();
   return {
-    path: () => target,
+    // The secret bundle is the credential file users care about (`login`
+    // prints this); settings.json sits next to it.
+    path: () => oauthCredsPath,
     async load() {
-      try {
-        if (process.platform !== "win32") {
-          const stat = await fs.stat(target);
-          if ((stat.mode & 63) !== 0) {
-            throw new Error(
-              `Refusing to load credentials from ${target}: file mode is too permissive (${(stat.mode & 511).toString(8)}). Run \`chmod 600 ${target}\` and retry.`
-            );
-          }
-        }
-        const raw = await fs.readFile(target, "utf-8");
-        const parsed = JSON.parse(raw);
-        return parseCredentials(parsed);
-      } catch (err) {
-        if (isFsNotFound(err)) {
-          return null;
-        }
-        throw err;
+      const oauth = await loadOauthCreds(oauthCredsPath);
+      if (!oauth) {
+        return null;
+      }
+      const settings = await loadSettings(settingsPath);
+      if (!settings) {
+        return null;
       }
+      return {
+        accessToken: oauth.accessToken,
+        refreshToken: oauth.refreshToken,
+        expiresAt: oauth.expiresAt,
+        userAuthUrl: settings.userAuthUrl,
+        platformUrl: settings.platformUrl,
+        webappUrl: settings.webappUrl,
+        user: oauth.user
+      };
     },
     async save(creds) {
-      const dir = path.dirname(target);
-      await fs.mkdir(dir, { recursive: true, mode: 448 });
-      await fs.writeFile(target, JSON.stringify(creds, null, 2), { mode: 384 });
-      if (process.platform !== "win32") {
-        await fs.chmod(target, 384);
-      }
+      await writeJsonFile(
+        settingsPath,
+        {
+          userAuthUrl: creds.userAuthUrl,
+          platformUrl: creds.platformUrl,
+          webappUrl: creds.webappUrl
+        },
+        { secret: false }
+      );
+      await writeJsonFile(
+        oauthCredsPath,
+        {
+          accessToken: creds.accessToken,
+          refreshToken: creds.refreshToken,
+          expiresAt: creds.expiresAt,
+          user: creds.user
+        },
+        { secret: true }
+      );
     },
     async clear() {
-      try {
-        await fs.unlink(target);
-      } catch (err) {
-        if (!isFsNotFound(err)) {
-          throw err;
-        }
-      }
+      await unlinkIfExists(oauthCredsPath);
     }
   };
 }
+async function loadOauthCreds(target) {
+  try {
+    if (process.platform !== "win32") {
+      const stat = await fs.stat(target);
+      if ((stat.mode & 63) !== 0) {
+        throw new Error(
+          `Refusing to load credentials from ${target}: file mode is too permissive (${(stat.mode & 511).toString(8)}). Run \`chmod 600 ${target}\` and retry.`
+        );
+      }
+    }
+    const raw = await fs.readFile(target, "utf-8");
+    return parseOauthCreds(JSON.parse(raw));
+  } catch (err) {
+    if (isFsNotFound(err)) {
+      return null;
+    }
+    throw err;
+  }
+}
+async function loadSettings(target) {
+  try {
+    const raw = await fs.readFile(target, "utf-8");
+    return parseSettings(JSON.parse(raw));
+  } catch (err) {
+    if (isFsNotFound(err)) {
+      return null;
+    }
+    throw err;
+  }
+}
+async function writeJsonFile(target, data, opts) {
+  const dir = path.dirname(target);
+  await fs.mkdir(dir, { recursive: true, mode: 448 });
+  if (process.platform !== "win32") {
+    await fs.chmod(dir, 448);
+  }
+  await fs.writeFile(target, JSON.stringify(data, null, 2), { mode: 384 });
+  if (opts.secret && process.platform !== "win32") {
+    await fs.chmod(target, 384);
+  }
+}
+async function unlinkIfExists(target) {
+  try {
+    await fs.unlink(target);
+  } catch (err) {
+    if (!isFsNotFound(err)) {
+      throw err;
+    }
+  }
+}
 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) {
@@ -380,19 +442,17 @@ function createCompositeCredentialsStore(opts) {
     envUserAuthUrl: () => envUserAuthUrl
   };
 }
-function parseCredentials(value) {
+function parseOauthCreds(value) {
   if (typeof value !== "object" || value === null) {
-    throw new Error("Credentials file is malformed (not an object)");
+    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 userAuthUrl = requireString(v, "userAuthUrl");
-  const platformUrl = typeof v.platformUrl === "string" ? v.platformUrl : void 0;
   const userRaw = v.user;
   if (typeof userRaw !== "object" || userRaw === null) {
-    throw new Error("Credentials file is malformed (missing user)");
+    throw new Error("oauth_creds.json is malformed (missing user)");
   }
   const userObj = userRaw;
   const user = {
@@ -400,7 +460,17 @@ function parseCredentials(value) {
     email: requireString(userObj, "email"),
     name: typeof userObj.name === "string" ? userObj.name : void 0
   };
-  return { accessToken, refreshToken, expiresAt, userAuthUrl, platformUrl, user };
+  return { accessToken, refreshToken, expiresAt, user };
+}
+function parseSettings(value) {
+  if (typeof value !== "object" || value === null) {
+    throw new Error("settings.json is malformed (not an object)");
+  }
+  const v = value;
+  const userAuthUrl = requireString(v, "userAuthUrl");
+  const platformUrl = typeof v.platformUrl === "string" ? v.platformUrl : void 0;
+  const webappUrl = typeof v.webappUrl === "string" ? v.webappUrl : void 0;
+  return { userAuthUrl, platformUrl, webappUrl };
 }
 function requireString(obj, key) {
   const value = obj[key];
@@ -424,8 +494,8 @@ function isFsNotFound(err) {
 function resolveConfig(sources = {}) {
   const env = sources.env ?? process.env;
   const userAuthUrl = sources.cliUserAuthUrl ?? env.MYSPEC_USER_AUTH_URL ?? sources.storedUserAuthUrl ?? "https://auth.myspec.dev";
-  const platformUrl = sources.cliPlatformUrl ?? env.MYSPEC_PLATFORM_URL ?? sources.storedPlatformUrl ?? "https://api.myspec.dev";
-  const webappUrl = sources.cliWebappUrl ?? env.MYSPEC_WEBAPP_URL ?? deriveWebappFromAuth(userAuthUrl);
+  const platformUrl = sources.cliPlatformUrl ?? env.MYSPEC_PLATFORM_URL ?? sources.storedPlatformUrl ?? "https://platform.myspec.dev";
+  const webappUrl = sources.cliWebappUrl ?? env.MYSPEC_WEBAPP_URL ?? sources.storedWebappUrl ?? deriveWebappFromAuth(userAuthUrl);
   validateUrl(userAuthUrl, "user-auth URL");
   validateUrl(platformUrl, "platform URL");
   validateUrl(webappUrl, "webapp URL");
@@ -589,6 +659,7 @@ var TokenManager = class {
           expiresAt: 0,
           userAuthUrl: this.envFallback.userAuthUrl,
           platformUrl: creds.platformUrl,
+          webappUrl: creds.webappUrl,
           user: creds.user
         };
         try {
@@ -1079,7 +1150,9 @@ var HttpAttachmentClient = class {
     const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
     const url = `${baseUrl}/project/v1/attachments/${attachmentId}/content`;
     const attempt = async () => {
-      const blob = new Blob([content], { type: "application/octet-stream" });
+      const blob = new Blob([content], {
+        type: "application/octet-stream"
+      });
       const response = await fetch(url, {
         method: "PUT",
         headers: {
@@ -1173,7 +1246,9 @@ var HttpFileClient = class {
   async uploadContent(fileId, content, jwtToken) {
     const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
     const url = `${baseUrl}/project/v1/files/${fileId}/content`;
-    const blob = new Blob([content], { type: "application/octet-stream" });
+    const blob = new Blob([content], {
+      type: "application/octet-stream"
+    });
     const response = await fetch(url, {
       method: "PUT",
       headers: {
@@ -1200,7 +1275,9 @@ var HttpFileClient = class {
   async saveManualRevision(fileId, content, jwtToken) {
     const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
     const url = `${baseUrl}/project/v1/files/${fileId}/revisions`;
-    const blob = new Blob([content], { type: "application/octet-stream" });
+    const blob = new Blob([content], {
+      type: "application/octet-stream"
+    });
     const response = await fetch(url, {
       method: "POST",
       headers: {
@@ -1245,6 +1322,17 @@ var HttpFileClient = class {
       expiresAt: new Date(response.expires_at)
     };
   }
+  async getRevisionDownloadUrl(fileId, revisionNumber, jwtToken) {
+    const response = await this.httpClient.get(
+      `/project/v1/files/${fileId}/revisions/${revisionNumber}`,
+      jwtToken,
+      { headers: { Accept: "application/json" } }
+    );
+    return {
+      signedUrl: response.signed_url,
+      expiresAt: new Date(response.expires_at)
+    };
+  }
   async downloadContent(fileId, jwtToken) {
     const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
     const url = `${baseUrl}/project/v1/files/${fileId}`;
@@ -1538,6 +1626,11 @@ var PlatformClient = class {
   async getFileDownloadUrl(fileId) {
     return this.withTokenRetry((jwt) => this.file.getDownloadUrl(fileId, jwt));
   }
+  async getRevisionDownloadUrl(fileId, revisionNumber) {
+    return this.withTokenRetry(
+      (jwt) => this.file.getRevisionDownloadUrl(fileId, revisionNumber, jwt)
+    );
+  }
   async getAttachmentDownloadUrl(attachmentId) {
     return this.withTokenRetry((jwt) => this.attachment.getDownloadUrl(attachmentId, jwt));
   }
@@ -1692,12 +1785,12 @@ import { z as z2 } from "zod";
 var inputSchema2 = {
   file_id: z2.string().min(1).describe("UUID of the file"),
   include_download_url: z2.number().int().nonnegative().optional().describe(
-    "Revision number to include a download URL for. Pass `revision_count` for the latest (signed URL); pass an older revision to get a URL plus `download_headers` carrying a short-lived bearer token. Omit or 0 to skip."
+    "Revision number to include a download URL for. Returns a signed, time-limited URL for that revision (latest or historical) that needs no credentials. Omit or 0 to skip."
   )
 };
 var getFileTool = {
   name: "get_file",
-  description: "Get file metadata. With `include_download_url=N`, also returns a download URL for revision N: latest returns a signed URL; older revisions return a URL plus `download_headers` containing a short-lived bearer token (treat as sensitive).",
+  description: "Get file metadata. With `include_download_url=N`, also returns a signed, time-limited download URL for revision N (latest or historical). The URL is self-authenticating, so no credentials are returned.",
   inputSchema: inputSchema2,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
@@ -1723,24 +1816,12 @@ var getFileTool = {
       );
     }
     const isLatest = requested === meta.revisionCount;
-    let downloadBlock;
-    if (isLatest) {
-      const signed = await ctx.client.getFileDownloadUrl(meta.id);
-      downloadBlock = {
-        download_url: signed.signedUrl,
-        download_revision: meta.revisionCount,
-        expires_at: signed.expiresAt.toISOString()
-      };
-    } else {
-      const url = `${ctx.client.baseUrl}/project/v1/files/${encodeURIComponent(meta.id)}/revisions/${String(requested)}`;
-      const token = await ctx.client.getAccessTokenWithExpiry();
-      downloadBlock = {
-        download_url: url,
-        download_revision: requested,
-        expires_at: new Date(token.expiresAt).toISOString(),
-        download_headers: [`Authorization: Bearer ${token.accessToken}`]
-      };
-    }
+    const signed = isLatest ? await ctx.client.getFileDownloadUrl(meta.id) : await ctx.client.getRevisionDownloadUrl(meta.id, requested);
+    const downloadBlock = {
+      download_url: signed.signedUrl,
+      download_revision: requested,
+      expires_at: signed.expiresAt.toISOString()
+    };
     return jsonResult({ ...base, ...downloadBlock });
   }
 };
@@ -3300,7 +3381,8 @@ async function runOneConnection(opts) {
     headers: {
       Authorization: `Bearer ${opts.accessToken}`,
       "X-Mcp-Client": `myspec-mcp-server/${opts.version}`,
-      "X-Mcp-Root-Label": opts.rootLabel
+      "X-Mcp-Root-Label": opts.rootLabel,
+      "X-Client-Type": "mcp-server"
     }
   });
   await waitForOpen(ws);
@@ -3384,6 +3466,64 @@ function sleep2(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
+// src/reverse/discover.ts
+async function discoverAgentUrl(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const endpoint = `${opts.webappUrl}/api/v1/config`;
+  let response;
+  try {
+    const token = await opts.getAccessToken();
+    response = await fetchConfig(endpoint, token, fetchImpl);
+    if (response.status === 401 && opts.forceRefresh) {
+      const refreshed = await opts.forceRefresh();
+      response = await fetchConfig(endpoint, refreshed, fetchImpl);
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw discoveryError(endpoint, message);
+  }
+  if (!response.ok) {
+    throw discoveryError(endpoint, `HTTP ${String(response.status)}`);
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw discoveryError(endpoint, "response is not valid JSON");
+  }
+  const agentUrl = body.aiAgentMcpReverseUrl;
+  if (typeof agentUrl !== "string" || agentUrl.length === 0) {
+    throw discoveryError(endpoint, "response is missing aiAgentMcpReverseUrl");
+  }
+  assertWebSocketUrl(agentUrl, endpoint);
+  return agentUrl;
+}
+function fetchConfig(endpoint, token, fetchImpl) {
+  return fetchImpl(endpoint, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${token}` }
+  });
+}
+function assertWebSocketUrl(value, endpoint) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw discoveryError(endpoint, `returned an invalid URL: ${value}`);
+  }
+  if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
+    throw discoveryError(
+      endpoint,
+      `returned a non-WebSocket URL (${value}); expected ws:// or wss://`
+    );
+  }
+}
+function discoveryError(endpoint, reason) {
+  return new ConfigError(
+    `Could not discover the ai-agent URL from ${endpoint} (${reason}). Pass --agent-url <url>, set MYSPEC_AI_AGENT_WS_URL, or run \`npx @myspec/mcp-server login\` and retry.`
+  );
+}
+
 // src/index.ts
 function parseArgs(argv) {
   const [first, ...rest] = argv;
@@ -3450,22 +3590,27 @@ function printHelp() {
     "  login                   Sign in via browser (chooser page on the webapp)",
     "  login --paste           Sign in by pasting a one-time code",
     "  logout                  Revoke refresh token and clear local credentials",
-    "  reverse --root <dir>    Connect to ai-agent and expose local_fs tools (spike).",
+    "  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;",
+    "                          override with --agent-url <url> or MYSPEC_AI_AGENT_WS_URL.",
     "                          Uses the saved refresh_token from `npx @myspec/mcp-server login`",
     "                          to obtain & auto-refresh access tokens. Override with",
     "                          --access-token <jwt> or MYSPEC_ACCESS_TOKEN for local testing.",
     "  --version               Print version",
     "  --help                  Print this help",
     "",
-    "Login flags:",
+    "Login / reverse flags:",
     "  --user-auth-url <url>   user-auth base URL (overrides env / defaults)",
     "  --platform-url <url>    platform API base URL",
-    "  --webapp-url <url>      webapp base URL hosting the /auth/cli page",
+    "  --webapp-url <url>      webapp base URL (login: hosts the /auth/cli page;",
+    "                          reverse: hosts the /api/v1/config discovery endpoint)",
     "",
     "Environment:",
     "  MYSPEC_USER_AUTH_URL    user-auth base URL (default https://auth.myspec.dev)",
-    "  MYSPEC_PLATFORM_URL     platform API base URL (default https://api.myspec.dev)",
+    "  MYSPEC_PLATFORM_URL     platform API base URL (default https://platform.myspec.dev)",
     "  MYSPEC_WEBAPP_URL       webapp base URL (default derived from user-auth host)",
+    "  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."
@@ -3516,16 +3661,35 @@ async function main(argv = process.argv.slice(2)) {
       return;
   }
 }
+async function resolveReverseAgentUrl(sources) {
+  const env = sources.env ?? process.env;
+  const explicitAgentUrl = sources.flagAgentUrl ?? env.MYSPEC_AI_AGENT_WS_URL;
+  if (explicitAgentUrl) {
+    return { agentUrl: explicitAgentUrl };
+  }
+  const stored = await sources.loadStored().catch(() => null);
+  const config = resolveConfig({
+    env,
+    cliWebappUrl: sources.cliWebappUrl,
+    storedUserAuthUrl: stored?.userAuthUrl,
+    storedWebappUrl: stored?.webappUrl
+  });
+  const agentUrl = await sources.discover(config.webappUrl);
+  return { agentUrl, discoveredVia: `${config.webappUrl}/api/v1/config` };
+}
 async function runReverseCommand(flags) {
   const root = flagString(flags, "root") ?? process.cwd();
-  const agentUrl = flagString(flags, "agent-url") ?? process.env.MYSPEC_AI_AGENT_WS_URL ?? "ws://localhost:3001/mcp/reverse";
   const inlineToken = flagString(flags, "access-token") ?? process.env.MYSPEC_ACCESS_TOKEN;
   let getAccessToken;
   let onAuthFailed;
+  let forceRefresh;
+  let loadStored;
   if (inlineToken) {
     const staticToken = inlineToken;
     getAccessToken = () => Promise.resolve(staticToken);
     onAuthFailed = void 0;
+    forceRefresh = void 0;
+    loadStored = () => Promise.resolve(null);
   } else {
     const envConfig = readEnvRefreshConfig();
     const store = createCompositeCredentialsStore({
@@ -3537,10 +3701,26 @@ async function runReverseCommand(flags) {
     onAuthFailed = async () => {
       await tokenManager.forceRefresh();
     };
+    forceRefresh = () => tokenManager.forceRefresh();
+    loadStored = () => store.load();
+  }
+  const resolved = await resolveReverseAgentUrl({
+    flagAgentUrl: flagString(flags, "agent-url"),
+    cliWebappUrl: flagString(flags, "webapp-url"),
+    loadStored,
+    discover: (webappUrl) => {
+      return discoverAgentUrl({ webappUrl, getAccessToken, forceRefresh });
+    }
+  });
+  if (resolved.discoveredVia) {
+    process.stderr.write(
+      `myspec-mcp reverse: discovered agent URL via ${resolved.discoveredVia}
+`
+    );
   }
   await runReverse({
     root,
-    agentUrl,
+    agentUrl: resolved.agentUrl,
     getAccessToken,
     onAuthFailed,
     version: readVersion()
@@ -3562,7 +3742,8 @@ async function runServe(flags) {
     cliUserAuthUrl: flagString(flags, "user-auth-url"),
     cliPlatformUrl: flagString(flags, "platform-url"),
     storedUserAuthUrl: initial?.userAuthUrl,
-    storedPlatformUrl: initial?.platformUrl
+    storedPlatformUrl: initial?.platformUrl,
+    storedWebappUrl: initial?.webappUrl
   });
   const tokenManager = new TokenManager({
     store,
@@ -3600,5 +3781,6 @@ if (isCliEntry()) {
 }
 export {
   main,
+  resolveReverseAgentUrl,
   runServe
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myspec/mcp-server",
-  "version": "0.1.0-next.1",
+  "version": "0.1.0-next.11",
   "description": "MySpec MCP server — exposes MySpec platform projects, files and attachments to MCP-aware clients via OAuth-authenticated access tokens.",
   "type": "module",
   "repository": {
@@ -50,7 +50,7 @@
     "@eslint/js": "^10.0.1",
     "@myspec/platform-client": "file:../../packages/platform-client",
     "@myspec/shared": "file:../../packages/shared",
-    "@types/node": "^22.10.0",
+    "@types/node": "^25.9.1",
     "@types/ws": "^8.18.1",
     "eslint": "^10.4.1",
     "tsup": "^8.3.5",