@myspec/mcp-server 0.1.0-next.4 → 0.1.0-next.6

package/README.md

@@ -23,28 +23,40 @@ 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. |
 
 Local state is stored under `~/.myspec/` (alongside the on-disk cache root), split into two files:
 
-- `settings.json` — non-secret config: the auth-server and platform URLs you logged in with.
+- `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.
@@ -57,7 +69,8 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 | `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
   };
 }
@@ -313,13 +315,18 @@ function createFileCredentialsStore(paths = {}) {
         expiresAt: oauth.expiresAt,
         userAuthUrl: settings.userAuthUrl,
         platformUrl: settings.platformUrl,
+        webappUrl: settings.webappUrl,
         user: oauth.user
       };
     },
     async save(creds) {
       await writeJsonFile(
         settingsPath,
-        { userAuthUrl: creds.userAuthUrl, platformUrl: creds.platformUrl },
+        {
+          userAuthUrl: creds.userAuthUrl,
+          platformUrl: creds.platformUrl,
+          webappUrl: creds.webappUrl
+        },
         { secret: false }
       );
       await writeJsonFile(
@@ -462,7 +469,8 @@ function parseSettings(value) {
   const v = value;
   const userAuthUrl = requireString(v, "userAuthUrl");
   const platformUrl = typeof v.platformUrl === "string" ? v.platformUrl : void 0;
-  return { userAuthUrl, platformUrl };
+  const webappUrl = typeof v.webappUrl === "string" ? v.webappUrl : void 0;
+  return { userAuthUrl, platformUrl, webappUrl };
 }
 function requireString(obj, key) {
   const value = obj[key];
@@ -487,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");
@@ -651,6 +659,7 @@ var TokenManager = class {
           expiresAt: 0,
           userAuthUrl: this.envFallback.userAuthUrl,
           platformUrl: creds.platformUrl,
+          webappUrl: creds.webappUrl,
           user: creds.user
         };
         try {
@@ -1141,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: {
@@ -1235,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: {
@@ -1262,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: {
@@ -3446,6 +3461,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;
@@ -3512,22 +3585,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."
@@ -3578,16 +3656,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({
@@ -3599,10 +3696,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()
@@ -3624,7 +3737,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,
@@ -3662,5 +3776,6 @@ if (isCliEntry()) {
 }
 export {
   main,
+  resolveReverseAgentUrl,
   runServe
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myspec/mcp-server",
-  "version": "0.1.0-next.4",
+  "version": "0.1.0-next.6",
   "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",