@myspec/mcp-server 0.1.0 → 0.1.1-next.16

package/README.md

@@ -26,6 +26,18 @@ logout                    Revoke refresh token and clear local credentials
 reverse --root <dir>      Connect to ai-agent and expose local_fs tools
 ```
 
+The only URL option is `--user-auth-url <url>` (default `https://auth.myspec.dev`),
+accepted by every command. The webapp URL is derived from it (`auth.` → `app.`,
+`dev-auth.` → `dev-app.`, `localhost:8787` → `localhost:5173`), and the remaining
+endpoints — the platform API base URL and the ai-agent WebSocket URL — are
+discovered after login from the webapp's authenticated `GET /api/v1/config`,
+then saved to `~/.myspec/settings.json` for subsequent runs. Example against the
+dev environment:
+
+```bash
+npx -y @myspec/mcp-server login --user-auth-url https://dev-auth.myspec.dev
+```
+
 ### `reverse`
 
 `reverse` connects out to the ai-agent service over WebSocket and exposes a set
@@ -33,30 +45,31 @@ 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
+npx @myspec/mcp-server 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
+A successful discovery refreshes the URLs saved in `~/.myspec/settings.json`;
+if discovery fails, `reverse` falls back to the agent URL saved by a previous
+successful discovery, and otherwise 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
+npx @myspec/mcp-server 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.
+- `settings.json` — non-secret config: the auth-server URL you logged in with, plus the derived webapp URL and the discovered platform / ai-agent URLs (refreshed on every successful discovery).
 - `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.
@@ -65,11 +78,9 @@ 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`) |
-| `MYSPEC_PLATFORM_URL` | platform API base URL (default `https://platform.myspec.dev`) |
+| `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_file` as its on-disk cache root (default: `~/.myspec`). Tools never write outside this root. |
-| `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

@@ -89,7 +89,6 @@ async function loopbackLogin(opts) {
     refreshToken: exchanged.refreshToken,
     expiresAt: now() + exchanged.expiresIn * 1e3,
     userAuthUrl: opts.userAuthUrl,
-    platformUrl: opts.platformUrl,
     webappUrl: opts.webappUrl,
     user: exchanged.user
   };
@@ -266,7 +265,6 @@ async function pasteLogin(opts) {
     refreshToken: exchanged.refreshToken,
     expiresAt: now() + exchanged.expiresIn * 1e3,
     userAuthUrl: opts.userAuthUrl,
-    platformUrl: opts.platformUrl,
     webappUrl: opts.webappUrl,
     user: exchanged.user
   };
@@ -316,6 +314,7 @@ function createFileCredentialsStore(paths = {}) {
         userAuthUrl: settings.userAuthUrl,
         platformUrl: settings.platformUrl,
         webappUrl: settings.webappUrl,
+        aiAgentMcpReverseUrl: settings.aiAgentMcpReverseUrl,
         user: oauth.user
       };
     },
@@ -325,7 +324,8 @@ function createFileCredentialsStore(paths = {}) {
         {
           userAuthUrl: creds.userAuthUrl,
           platformUrl: creds.platformUrl,
-          webappUrl: creds.webappUrl
+          webappUrl: creds.webappUrl,
+          aiAgentMcpReverseUrl: creds.aiAgentMcpReverseUrl
         },
         { secret: false }
       );
@@ -470,7 +470,8 @@ function parseSettings(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 };
+  const aiAgentMcpReverseUrl = typeof v.aiAgentMcpReverseUrl === "string" ? v.aiAgentMcpReverseUrl : void 0;
+  return { userAuthUrl, platformUrl, webappUrl, aiAgentMcpReverseUrl };
 }
 function requireString(obj, key) {
   const value = obj[key];
@@ -494,14 +495,11 @@ 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://platform.myspec.dev";
-  const webappUrl = sources.cliWebappUrl ?? env.MYSPEC_WEBAPP_URL ?? sources.storedWebappUrl ?? deriveWebappFromAuth(userAuthUrl);
+  const webappUrl = deriveWebappFromAuth(userAuthUrl);
   validateUrl(userAuthUrl, "user-auth URL");
-  validateUrl(platformUrl, "platform URL");
   validateUrl(webappUrl, "webapp URL");
   return {
     userAuthUrl: stripTrailingSlash(userAuthUrl),
-    platformUrl: stripTrailingSlash(platformUrl),
     webappUrl: stripTrailingSlash(webappUrl)
   };
 }
@@ -540,32 +538,136 @@ function stripTrailingSlash(value) {
   return value.endsWith("/") ? value.slice(0, -1) : value;
 }
 
+// src/discovery.ts
+var DEFAULT_ERROR_HINT = "Run `npx @myspec/mcp-server login` and retry.";
+async function discoverConfig(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const endpoint = configEndpoint(opts.webappUrl);
+  const hint = opts.errorHint ?? DEFAULT_ERROR_HINT;
+  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, hint);
+  }
+  if (!response.ok) {
+    throw discoveryError(endpoint, `HTTP ${String(response.status)}`, hint);
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw discoveryError(endpoint, "response is not valid JSON", hint);
+  }
+  const platformUrl = optionalString(body.platformUrl);
+  if (platformUrl !== void 0) {
+    assertHttpUrl(platformUrl, endpoint, hint);
+  }
+  const aiAgentMcpReverseUrl = optionalString(body.aiAgentMcpReverseUrl);
+  if (aiAgentMcpReverseUrl !== void 0) {
+    assertWebSocketUrl(aiAgentMcpReverseUrl, endpoint, hint);
+  }
+  return {
+    platformUrl: platformUrl ? stripTrailingSlash2(platformUrl) : void 0,
+    aiAgentMcpReverseUrl
+  };
+}
+function configEndpoint(webappUrl) {
+  return `${webappUrl}/api/v1/config`;
+}
+function applyDiscoveredUrls(creds, webappUrl, discovered) {
+  return {
+    ...creds,
+    webappUrl,
+    platformUrl: discovered.platformUrl ?? creds.platformUrl,
+    aiAgentMcpReverseUrl: discovered.aiAgentMcpReverseUrl ?? creds.aiAgentMcpReverseUrl
+  };
+}
+function fetchConfig(endpoint, token, fetchImpl) {
+  return fetchImpl(endpoint, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${token}` }
+  });
+}
+function optionalString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function assertHttpUrl(value, endpoint, hint) {
+  const parsed = parseUrl(value, endpoint, hint);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw discoveryError(
+      endpoint,
+      `returned a non-HTTP platformUrl (${value}); expected http:// or https://`,
+      hint
+    );
+  }
+}
+function assertWebSocketUrl(value, endpoint, hint) {
+  const parsed = parseUrl(value, endpoint, hint);
+  if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
+    throw discoveryError(
+      endpoint,
+      `returned a non-WebSocket URL (${value}); expected ws:// or wss://`,
+      hint
+    );
+  }
+}
+function parseUrl(value, endpoint, hint) {
+  try {
+    return new URL(value);
+  } catch {
+    throw discoveryError(endpoint, `returned an invalid URL: ${value}`, hint);
+  }
+}
+function stripTrailingSlash2(value) {
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+function discoveryError(endpoint, reason, hint) {
+  return new ConfigError(`Could not discover endpoints from ${endpoint} (${reason}). ${hint}`);
+}
+
 // src/cli/login.ts
-async function runLogin(options) {
-  const config = resolveConfig({
-    cliUserAuthUrl: options.userAuthUrl,
-    cliPlatformUrl: options.platformUrl,
-    cliWebappUrl: options.webappUrl
+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 store = createFileCredentialsStore();
-  const credentials = options.paste ? await pasteLogin({
-    userAuthUrl: config.userAuthUrl,
-    platformUrl: config.platformUrl,
-    webappUrl: config.webappUrl
-  }) : await loopbackLogin({
-    userAuthUrl: config.userAuthUrl,
-    platformUrl: config.platformUrl,
-    webappUrl: config.webappUrl,
+  const doLogin = deps.doLogin ?? ((cfg) => options.paste ? pasteLogin(cfg) : loopbackLogin({
+    ...cfg,
     openBrowser: async (url) => {
       const mod = await import("open");
       await mod.default(url);
     }
+  }));
+  const credentials = await doLogin({
+    userAuthUrl: config.userAuthUrl,
+    webappUrl: config.webappUrl
   });
-  await store.save(credentials);
-  process.stderr.write(`Signed in as ${credentials.user.email}.
-`);
-  process.stderr.write(`Credentials saved to ${store.path()}
-`);
+  const enriched = await discoverAfterLogin(credentials, config.webappUrl, deps.discover, log);
+  await store.save(enriched);
+  log(`Signed in as ${enriched.user.email}.`);
+  log(`Credentials saved to ${store.path()}`);
+}
+async function discoverAfterLogin(credentials, webappUrl, discover = discoverConfig, log = () => void 0) {
+  try {
+    const discovered = await discover({
+      webappUrl,
+      getAccessToken: () => Promise.resolve(credentials.accessToken),
+      errorHint: "The endpoints will be discovered on first use."
+    });
+    return applyDiscoveredUrls(credentials, webappUrl, discovered);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log(`Warning: ${message}`);
+    return credentials;
+  }
 }
 
 // src/cli/logout.ts
@@ -660,6 +762,7 @@ var TokenManager = class {
           userAuthUrl: this.envFallback.userAuthUrl,
           platformUrl: creds.platformUrl,
           webappUrl: creds.webappUrl,
+          aiAgentMcpReverseUrl: creds.aiAgentMcpReverseUrl,
           user: creds.user
         };
         try {
@@ -1587,38 +1690,37 @@ var silentLogger = {
 };
 var PlatformClient = class {
   tokenManager;
-  project;
-  session;
-  file;
-  attachment;
-  baseUrl;
+  resolveBaseUrl;
+  clientsPromise = null;
   constructor(deps) {
     this.tokenManager = deps.tokenManager;
-    this.baseUrl = deps.baseUrl.replace(/\/$/, "");
-    const httpClient = new BaseHttpClient({ baseUrl: this.baseUrl, logger: silentLogger });
-    this.project = new HttpProjectClient(httpClient);
-    this.session = new HttpSpecSessionClient(httpClient);
-    this.file = new HttpFileClient(httpClient);
-    this.attachment = new HttpAttachmentClient(httpClient);
+    if (deps.baseUrl !== void 0) {
+      const fixed = deps.baseUrl.replace(/\/$/, "");
+      this.resolveBaseUrl = () => Promise.resolve(fixed);
+    } else if (deps.resolveBaseUrl) {
+      this.resolveBaseUrl = deps.resolveBaseUrl;
+    } else {
+      throw new Error("PlatformClient requires either baseUrl or resolveBaseUrl");
+    }
   }
   async listProjects(opts = {}) {
-    return this.withTokenRetry((jwt) => this.project.listProjects(jwt, opts));
+    return this.withTokenRetry((jwt, c) => c.project.listProjects(jwt, opts));
   }
   async getProject(projectId) {
-    return this.withTokenRetry((jwt) => this.project.getProject(projectId, jwt));
+    return this.withTokenRetry((jwt, c) => c.project.getProject(projectId, jwt));
   }
   async listProjectSessions(projectId, opts = {}) {
     const merged = {
       archiveFilter: opts.archiveFilter ?? "active",
       ...opts
     };
-    return this.withTokenRetry((jwt) => this.session.listSpecSessions(projectId, jwt, merged));
+    return this.withTokenRetry((jwt, c) => c.session.listSpecSessions(projectId, jwt, merged));
   }
   async listFiles(projectId, opts = {}) {
-    return this.withTokenRetry((jwt) => this.file.listFiles(projectId, jwt, opts));
+    return this.withTokenRetry((jwt, c) => c.file.listFiles(projectId, jwt, opts));
   }
   async getFileMetadata(fileId) {
-    return this.withTokenRetry((jwt) => this.file.getFile(fileId, jwt));
+    return this.withTokenRetry((jwt, c) => c.file.getFile(fileId, jwt));
   }
   async getAccessTokenWithExpiry() {
     const accessToken = await this.tokenManager.getValidAccessToken();
@@ -1626,29 +1728,29 @@ var PlatformClient = class {
     return { accessToken, expiresAt: creds.expiresAt };
   }
   async getFileDownloadUrl(fileId) {
-    return this.withTokenRetry((jwt) => this.file.getDownloadUrl(fileId, jwt));
+    return this.withTokenRetry((jwt, c) => c.file.getDownloadUrl(fileId, jwt));
   }
   async getRevisionDownloadUrl(fileId, revisionNumber) {
     return this.withTokenRetry(
-      (jwt) => this.file.getRevisionDownloadUrl(fileId, revisionNumber, jwt)
+      (jwt, c) => c.file.getRevisionDownloadUrl(fileId, revisionNumber, jwt)
     );
   }
   async getAttachmentDownloadUrl(attachmentId) {
-    return this.withTokenRetry((jwt) => this.attachment.getDownloadUrl(attachmentId, jwt));
+    return this.withTokenRetry((jwt, c) => c.attachment.getDownloadUrl(attachmentId, jwt));
   }
   async downloadFile(fileId, revision) {
     if (revision !== void 0) {
       const bytes2 = await this.withTokenRetry(
-        (jwt) => this.file.downloadRevision(fileId, revision, jwt)
+        (jwt, c) => c.file.downloadRevision(fileId, revision, jwt)
       );
       return { bytes: bytes2, revisionNumber: revision };
     }
-    const bytes = await this.withTokenRetry((jwt) => this.file.downloadContent(fileId, jwt));
+    const bytes = await this.withTokenRetry((jwt, c) => c.file.downloadContent(fileId, jwt));
     const meta = await this.getFileMetadata(fileId);
     return { bytes, revisionNumber: meta.revisionCount };
   }
   async listAttachments(projectId) {
-    return this.withTokenRetry((jwt) => this.attachment.listByProject(projectId, jwt));
+    return this.withTokenRetry((jwt, c) => c.attachment.listByProject(projectId, jwt));
   }
   /**
    * Fetch a single attachment's metadata by id. Returns null on a 404 so callers
@@ -1659,7 +1761,7 @@ var PlatformClient = class {
    */
   async getAttachmentMetadata(attachmentId) {
     try {
-      return await this.withTokenRetry((jwt) => this.attachment.getById(attachmentId, jwt));
+      return await this.withTokenRetry((jwt, c) => c.attachment.getById(attachmentId, jwt));
     } catch (err) {
       if (statusOf(err) === 404) {
         return null;
@@ -1668,7 +1770,7 @@ var PlatformClient = class {
     }
   }
   async downloadAttachment(attachmentId) {
-    return this.withTokenRetry((jwt) => this.attachment.downloadContent(attachmentId, jwt));
+    return this.withTokenRetry((jwt, c) => c.attachment.downloadContent(attachmentId, jwt));
   }
   /**
    * Soft-deletes an attachment by id. The server hides it from subsequent
@@ -1677,7 +1779,7 @@ var PlatformClient = class {
    * is set and an attachment with the same filename already exists.
    */
   async deleteAttachment(attachmentId) {
-    await this.withTokenRetry((jwt) => this.attachment.deleteById(attachmentId, jwt));
+    await this.withTokenRetry((jwt, c) => c.attachment.deleteById(attachmentId, jwt));
   }
   /**
    * Two-phase attachment upload. Reserves an attachment id (Phase 1), then
@@ -1687,7 +1789,7 @@ var PlatformClient = class {
    */
   async uploadAttachment(args) {
     const initiated = await this.withTokenRetry(
-      (jwt) => this.attachment.initiateUpload(
+      (jwt, c) => c.attachment.initiateUpload(
         {
           projectId: args.projectId,
           fileName: args.fileName,
@@ -1699,21 +1801,44 @@ var PlatformClient = class {
       )
     );
     const uploaded = await this.withTokenRetry(
-      (jwt) => this.attachment.uploadContent(initiated.attachmentId, args.content, jwt)
+      (jwt, c) => c.attachment.uploadContent(initiated.attachmentId, args.content, jwt)
     );
     return {
       attachmentId: uploaded.attachmentId,
       fileUri: uploaded.fileUri
     };
   }
+  /**
+   * Builds the HTTP clients on first use, resolving the base URL lazily. A
+   * successful build is cached for the process lifetime; a failed resolution
+   * (e.g. discovery before login) is dropped so the next call retries.
+   */
+  clients() {
+    this.clientsPromise ??= this.buildClients().catch((err) => {
+      this.clientsPromise = null;
+      throw err;
+    });
+    return this.clientsPromise;
+  }
+  async buildClients() {
+    const baseUrl = (await this.resolveBaseUrl()).replace(/\/$/, "");
+    const httpClient = new BaseHttpClient({ baseUrl, logger: silentLogger });
+    return {
+      project: new HttpProjectClient(httpClient),
+      session: new HttpSpecSessionClient(httpClient),
+      file: new HttpFileClient(httpClient),
+      attachment: new HttpAttachmentClient(httpClient)
+    };
+  }
   async withTokenRetry(call) {
+    const clients = await this.clients();
     const jwt = await this.tokenManager.getValidAccessToken();
     try {
-      return await call(jwt);
+      return await call(jwt, clients);
     } catch (err) {
       if (statusOf(err) === 401) {
         const refreshed = await this.tokenManager.forceRefresh();
-        return await call(refreshed);
+        return await call(refreshed, clients);
       }
       throw err;
     }
@@ -3468,64 +3593,6 @@ 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;
@@ -3602,16 +3669,15 @@ function printHelp() {
     "  --version               Print version",
     "  --help                  Print this help",
     "",
-    "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 (login: hosts the /auth/cli page;",
-    "                          reverse: hosts the /api/v1/config discovery endpoint)",
+    "Flags:",
+    "  --user-auth-url <url>   user-auth base URL (overrides env / saved settings;",
+    "                          default https://auth.myspec.dev). The webapp URL is",
+    "                          derived from it, and the remaining endpoints",
+    "                          (platform API, ai-agent WebSocket) are discovered",
+    "                          via the webapp and saved to ~/.myspec/settings.json.",
     "",
     "Environment:",
     "  MYSPEC_USER_AUTH_URL    user-auth base URL (default https://auth.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",
@@ -3646,9 +3712,7 @@ async function main(argv = process.argv.slice(2)) {
     case "login":
       await runLogin({
         paste: flagBool(flags, "paste"),
-        userAuthUrl: flagString(flags, "user-auth-url"),
-        platformUrl: flagString(flags, "platform-url"),
-        webappUrl: flagString(flags, "webapp-url")
+        userAuthUrl: flagString(flags, "user-auth-url")
       });
       return;
     case "logout":
@@ -3663,21 +3727,43 @@ async function main(argv = process.argv.slice(2)) {
       return;
   }
 }
+var REVERSE_DISCOVERY_HINT = "Pass --agent-url <url>, set MYSPEC_AI_AGENT_WS_URL, or run `npx @myspec/mcp-server login` and retry.";
 async function resolveReverseAgentUrl(sources) {
   const env = sources.env ?? process.env;
+  const warn = sources.warn ?? ((message) => {
+    process.stderr.write(message + "\n");
+  });
   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` };
+  const config = resolveConfig({ env, storedUserAuthUrl: stored?.userAuthUrl });
+  const endpoint = configEndpoint(config.webappUrl);
+  try {
+    const discovered = await sources.discover(config.webappUrl);
+    if (!discovered.aiAgentMcpReverseUrl) {
+      throw new ConfigError(
+        `Could not discover endpoints from ${endpoint} (response is missing aiAgentMcpReverseUrl). ${REVERSE_DISCOVERY_HINT}`
+      );
+    }
+    if (stored && sources.persist) {
+      await sources.persist(applyDiscoveredUrls(stored, config.webappUrl, discovered)).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        warn(`myspec-mcp reverse: could not save discovered URLs (${message})`);
+      });
+    }
+    return { agentUrl: discovered.aiAgentMcpReverseUrl, discoveredVia: endpoint };
+  } catch (err) {
+    if (stored?.aiAgentMcpReverseUrl) {
+      const message = err instanceof Error ? err.message : String(err);
+      warn(
+        `myspec-mcp reverse: discovery failed (${message}); using the agent URL saved in settings.json`
+      );
+      return { agentUrl: stored.aiAgentMcpReverseUrl };
+    }
+    throw err;
+  }
 }
 async function runReverseCommand(flags) {
   const root = flagString(flags, "root") ?? process.cwd();
@@ -3686,12 +3772,14 @@ async function runReverseCommand(flags) {
   let onAuthFailed;
   let forceRefresh;
   let loadStored;
+  let persist;
   if (inlineToken) {
     const staticToken = inlineToken;
     getAccessToken = () => Promise.resolve(staticToken);
     onAuthFailed = void 0;
     forceRefresh = void 0;
     loadStored = () => Promise.resolve(null);
+    persist = void 0;
   } else {
     const envConfig = readEnvRefreshConfig();
     const store = createCompositeCredentialsStore({
@@ -3705,13 +3793,19 @@ async function runReverseCommand(flags) {
     };
     forceRefresh = () => tokenManager.forceRefresh();
     loadStored = () => store.load();
+    persist = (creds) => store.save(creds);
   }
   const resolved = await resolveReverseAgentUrl({
     flagAgentUrl: flagString(flags, "agent-url"),
-    cliWebappUrl: flagString(flags, "webapp-url"),
     loadStored,
+    persist,
     discover: (webappUrl) => {
-      return discoverAgentUrl({ webappUrl, getAccessToken, forceRefresh });
+      return discoverConfig({
+        webappUrl,
+        getAccessToken,
+        forceRefresh,
+        errorHint: REVERSE_DISCOVERY_HINT
+      });
     }
   });
   if (resolved.discoveredVia) {
@@ -3728,6 +3822,36 @@ async function runReverseCommand(flags) {
     version: readVersion()
   });
 }
+function createPlatformUrlResolver(deps) {
+  const discover = deps.discover ?? discoverConfig;
+  const warn = deps.warn ?? ((message) => {
+    process.stderr.write(message + "\n");
+  });
+  return async () => {
+    const stored = await deps.store.load().catch(() => null);
+    if (stored?.platformUrl && stored.userAuthUrl === deps.userAuthUrl) {
+      return stored.platformUrl;
+    }
+    const discovered = await discover({
+      webappUrl: deps.webappUrl,
+      getAccessToken: () => deps.tokenManager.getValidAccessToken(),
+      forceRefresh: () => deps.tokenManager.forceRefresh()
+    });
+    if (!discovered.platformUrl) {
+      throw new ConfigError(
+        `Could not discover endpoints from ${configEndpoint(deps.webappUrl)} (response is missing platformUrl). Run \`npx @myspec/mcp-server login\` and retry.`
+      );
+    }
+    const creds = await deps.tokenManager.getCredentials().catch(() => null);
+    if (creds) {
+      await deps.store.save(applyDiscoveredUrls(creds, deps.webappUrl, discovered)).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        warn(`myspec-mcp: could not save discovered URLs (${message})`);
+      });
+    }
+    return discovered.platformUrl;
+  };
+}
 async function runServe(flags) {
   const envConfig = readEnvRefreshConfig();
   const store = createCompositeCredentialsStore({
@@ -3742,16 +3866,21 @@ async function runServe(flags) {
   }
   const config = resolveConfig({
     cliUserAuthUrl: flagString(flags, "user-auth-url"),
-    cliPlatformUrl: flagString(flags, "platform-url"),
-    storedUserAuthUrl: initial?.userAuthUrl,
-    storedPlatformUrl: initial?.platformUrl,
-    storedWebappUrl: initial?.webappUrl
+    storedUserAuthUrl: initial?.userAuthUrl
   });
   const tokenManager = new TokenManager({
     store,
     envFallback: envConfig
   });
-  const client = new PlatformClient({ baseUrl: config.platformUrl, tokenManager });
+  const client = new PlatformClient({
+    resolveBaseUrl: createPlatformUrlResolver({
+      store,
+      tokenManager,
+      userAuthUrl: config.userAuthUrl,
+      webappUrl: config.webappUrl
+    }),
+    tokenManager
+  });
   await startStdioServer({ client, version: readVersion() });
 }
 function isCliEntry() {
@@ -3782,6 +3911,8 @@ if (isCliEntry()) {
   });
 }
 export {
+  REVERSE_DISCOVERY_HINT,
+  createPlatformUrlResolver,
   main,
   resolveReverseAgentUrl,
   runServe

package/package.json

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