@myspec/mcp-server 0.1.0-next.3 → 0.1.0-next.5

package/README.md

@@ -23,26 +23,43 @@ 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 (experimental)
+reverse --root <dir>      Connect to ai-agent and expose local_fs tools
 ```
 
-### `reverse` (experimental)
+### `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. This is an early spike.
+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 (default `ws://localhost:3001/mcp/reverse`). |
+| `--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. |
 
-Credentials are persisted at `$XDG_CONFIG_HOME/myspec/mcp-server.json` (POSIX) or `%APPDATA%\myspec\mcp-server.json` (Windows), mode `0600`.
+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
 
@@ -52,7 +69,8 @@ Credentials are persisted at `$XDG_CONFIG_HOME/myspec/mcp-server.json` (POSIX) o
 | `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 defaultOauthCredsPath() {
+  return path.join(myspecDir(), "oauth_creds.json");
 }
-function createFileCredentialsStore(filePath) {
-  const target = filePath ?? defaultCredentialsPath();
+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];
@@ -425,7 +495,7 @@ 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 ?? deriveWebappFromAuth(userAuthUrl);
+  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 {
@@ -3384,6 +3455,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 +3579,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://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 +3650,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 +3690,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 +3731,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 +3770,6 @@ if (isCliEntry()) {
 }
 export {
   main,
+  resolveReverseAgentUrl,
   runServe
 };

package/package.json

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