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

package/README.md

@@ -23,16 +23,38 @@ 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)
 ```
 
-Credentials are persisted at `$XDG_CONFIG_HOME/myspec/mcp-server.json` (POSIX) or `%APPDATA%\myspec\mcp-server.json` (Windows), mode `0600`.
+### `reverse` (experimental)
+
+`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.
+
+```bash
+npx @myspec/mcp-server@next reverse --root /path/to/project
+```
+
+| 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`). |
+| `--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.
+- `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`) |

package/dist/index.js

@@ -282,57 +282,112 @@ 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,
+        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 },
+        { 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 +435,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 +453,16 @@ 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;
+  return { userAuthUrl, platformUrl };
 }
 function requireString(obj, key) {
   const value = obj[key];
@@ -424,7 +486,7 @@ 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 platformUrl = sources.cliPlatformUrl ?? env.MYSPEC_PLATFORM_URL ?? sources.storedPlatformUrl ?? "https://platform.myspec.dev";
   const webappUrl = sources.cliWebappUrl ?? env.MYSPEC_WEBAPP_URL ?? deriveWebappFromAuth(userAuthUrl);
   validateUrl(userAuthUrl, "user-auth URL");
   validateUrl(platformUrl, "platform URL");
@@ -3464,7 +3526,7 @@ function printHelp() {
     "",
     "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_REFRESH_TOKEN    Skip file-based credentials; the server mints a",
     "                          fresh access token on first use via this refresh",

package/package.json

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