@myspec/mcp-server 0.2.0-next.80 → 0.2.0-next.82

package/README.md

@@ -64,6 +64,10 @@ value, including the dot** and paste it back into the terminal. Two traps:
 without a person present (a server, a container, a CI job, a shared machine),
 use an API token instead.
 
+> Needs **`@myspec/mcp-server` 0.2.0 or newer** (`npm view @myspec/mcp-server
+> version`). Earlier builds ignore the `apiToken` field and report that they are
+> not signed in, without mentioning the version.
+
 **1. Create the token.** In the MySpec webapp, open the avatar menu → **API
 tokens** → **Create token**. Choose the organization it should act in, whether
 it may write or only read, and an expiry. The token is shown **once**; it
@@ -233,13 +237,46 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 | `get_project` | `project_id` | Project + active sessions + files + attachments |
 | `get_spec_file` | `file_id`, optional `include_download_url` | File metadata, including `content_version` (see [Concurrent edits](#concurrent-edits-content_version)); with `include_download_url=N` also returns a download URL targeting revision `N` |
 | `read_spec_file` | `file_id`, optional `revision` | UTF-8 content of the file, plus `content_version` when reading the latest revision (errors for binary or files > 1 MiB — use `download_spec_file` for those). Cached on disk under `MYSPEC_DOWNLOAD_ROOT` |
-| `download_spec_file` | `file_id`, `destination_path`, optional `revision`, optional `overwrite` | Downloads the file's raw bytes to `destination_path` (absolute or cwd-relative; an existing directory gets the basename appended). Handles binary files and files up to 50 MiB. Refuses to replace an existing file unless `overwrite=true`. Returns only metadata (`saved_path`, `bytes_written`, `revision_number`) — **not** the content, so a large file can be saved locally and read in chunks |
+| `download_spec_file` | `file_id`, optional `destination_path`, optional `revision`, optional `overwrite` | Downloads the file's raw bytes to a local file — by default under `.specs/` in the working directory (see [Download destinations](#download-destinations)). Handles binary files and files up to 50 MiB. Refuses to replace an existing file unless `overwrite=true`. Returns only metadata (`saved_path`, `bytes_written`, `revision_number`, `destination_source`) — **not** the content, so a large file can be saved locally and read in chunks |
 | `list_spec_file` | `project_id`, optional `path`, optional `trashed` | Lists a project's spec files (`file_id`, `file_path`, `file_type`, `file_size_bytes`, `revision_count`, `session_id`, `updated_at`). Filter to a directory with `path` (exact file or everything under it; `""`/`"/"`/omit = all). `trashed=true` lists the Trash Bin instead of live files |
 | `move_spec_file_to_trash` | `file_id` | Moves a spec file to the Trash Bin (recoverable — hidden from listings and AI-agent tools, restorable indefinitely). Not a permanent delete |
 | `restore_spec_file_from_trash` | `file_id` | Restores a trashed spec file back to the active file list, reversing `move_spec_file_to_trash` |
 | `get_attachment` | `attachment_id`, optional `include_download_url` | Attachment metadata (looked up org-scoped by id); with `include_download_url>0` also returns a signed download URL |
 | `upload_attachment` | `project_id`, `file_path` (absolute), optional `file_name`, optional `mime_type`, optional `override` | Uploads the local file as a new attachment on the project. Returns `attachment_id`, `file_name` (the **effective** name the platform stored — may differ from the requested one when auto-dedup adds a `(N)` suffix), `has_file_name_conflict` (`true` when stored name ≠ requested name), `mime_type`, `file_size_bytes`, `checksum` (format: `sha256:<hex>`), `file_uri`, `reused_existing_attachment` (`true` when an existing attachment with the same name AND same checksum was found and returned without re-uploading; `file_uri` is then omitted because the list endpoint does not surface it — call `get_attachment` for a download URL). With `override=true`, any existing attachment whose recorded name matches is soft-deleted first (returned as `overridden_attachment_ids` — empty array means nothing matched) and the new upload keeps the requested name; the same-checksum short-circuit still applies, so a no-op re-upload never deletes anything. Max 10 MB. Supported content: PDF, DOCX, XLSX, and any UTF-8 text file (XML, JSON, YAML, HTML, Markdown, CSV, source code, ...) |
 
+### Download destinations
+
+`download_spec_file` prefers the **`.specs/` folder in the MCP server's working
+directory** — dot-prefixed because it is conventionally gitignored, so a
+downloaded copy never shows up as untracked noise beside a repo's own `specs/`.
+
+- **`destination_path` omitted** → the file's remote path is mirrored under
+  `.specs/`, with the remote `specs/` root replaced:
+  `specs/add-oauth/proposal.md` → `.specs/add-oauth/proposal.md`. Any other root
+  is kept beneath `.specs/` (`openspec/changes/add-x/spec.md` →
+  `.specs/openspec/changes/add-x/spec.md`), so every download lands in one folder.
+  That includes the legacy `.spec/` prefix on old files, which nests as
+  `.specs/.spec/…` — the platform has required `specs/` or `openspec/` since,
+  so only pre-existing files land there.
+- **Relative `destination_path` rooted at `specs/`** → redirected to `.specs/`.
+  This is the remote path echoed back, and it would otherwise write into the
+  repo's own spec folder.
+- **Anything else** → honored exactly as given. An absolute path is the escape
+  hatch for saving into a literal `specs/` directory.
+
+The response reports which of the three applied as `destination_source`
+(`default` / `redirected` / `explicit`), plus a `note` for the first two, so a
+caller that passed `specs/...` and got `.specs/...` can see why.
+
+A `destination_path` that names a directory — it exists as one, or ends with a
+path separator — gets the spec file's basename appended. Across a redirect both
+the path as passed and the rewritten one are consulted, so whichever exists as a
+directory wins: `specs/add-oauth/`, an existing `specs/add-oauth/`, and an
+existing `.specs/add-oauth/` all land at `.specs/add-oauth/<basename>` rather
+than at a file named `.specs/add-oauth`. A bare `specs` is always the folder.
+Derived paths (default and redirected) are confined to `.specs/` and may not be
+`.specs/` itself; an explicit `destination_path` is not sandboxed.
+
 ### `include_download_url` semantics
 
 `get_spec_file`:

package/dist/index.js

@@ -565,12 +565,20 @@ var TokenManager = class {
       this.apiTokenRejection = rejection;
       throw rejection;
     }
+    if (response.status === 404) {
+      const body = await response.text().catch(() => "");
+      throw new HttpStatusError(
+        response.status,
+        body,
+        `Token exchange failed: ${url} returned 404, so no exchange endpoint is there. This URL comes from userAuthUrl in ~/.myspec/settings.json \u2014 check it names the environment the token was created in, and rewrite it with \`npx @myspec/mcp-server login --user-auth-url <url>\`. Note that --user-auth-url and MYSPEC_USER_AUTH_URL do not redirect the exchange on their own, and userAuthUrl in oauth_creds.json is ignored entirely.`
+      );
+    }
     if (!response.ok) {
       const body = await response.text().catch(() => "");
       throw new HttpStatusError(
         response.status,
         body,
-        `Token exchange failed: HTTP ${String(response.status)}`
+        `Token exchange failed: HTTP ${String(response.status)} from ${url}`
       );
     }
     const payload = await response.json().catch(() => null);
@@ -2624,11 +2632,37 @@ function resolveDownloadRoot(env = process.env) {
   }
   return path2.join(os2.homedir(), ".myspec");
 }
+var LOCAL_SPEC_DIR = ".specs";
+var REMOTE_SPEC_ROOT = "specs";
+function defaultSpecDestination(remoteFilePath) {
+  const segments = remoteFilePath.split("/").filter((s) => s !== "" && s !== ".");
+  if (segments[0] === REMOTE_SPEC_ROOT) {
+    segments.shift();
+  }
+  if (segments.length === 0) {
+    segments.push("content");
+  }
+  return path2.join(LOCAL_SPEC_DIR, ...segments);
+}
+function redirectSpecRootToLocal(destPath) {
+  if (path2.isAbsolute(destPath)) {
+    return null;
+  }
+  const segments = path2.normalize(destPath).split(path2.sep);
+  if (segments[0] !== REMOTE_SPEC_ROOT) {
+    return null;
+  }
+  if (segments.length === 1) {
+    return LOCAL_SPEC_DIR + path2.sep;
+  }
+  segments[0] = LOCAL_SPEC_DIR;
+  return segments.join(path2.sep);
+}
 function assertWithinRoot(target, root) {
   const resolvedTarget = path2.resolve(target);
   const resolvedRoot = path2.resolve(root);
   const rel = path2.relative(resolvedRoot, resolvedTarget);
-  if (rel.startsWith("..") || path2.isAbsolute(rel)) {
+  if (rel === ".." || rel.startsWith(".." + path2.sep) || path2.isAbsolute(rel)) {
     return `path resolves outside the configured root (${resolvedRoot}): ${resolvedTarget}`;
   }
   return null;
@@ -2659,20 +2693,25 @@ function maskHomedir(p, home = os2.homedir()) {
   return p;
 }
 async function resolveDestinationFile(destPath, basename4) {
-  const absPath = path2.isAbsolute(destPath) ? path2.resolve(destPath) : path2.resolve(process.cwd(), destPath);
-  const endsWithSep = destPath.endsWith(path2.sep) || destPath.endsWith("/");
-  let isDir = endsWithSep;
-  if (!isDir) {
-    try {
-      const info = await fs2.stat(absPath);
-      isDir = info.isDirectory();
-    } catch (err) {
-      if (!isFsNotFound2(err)) {
-        throw err;
-      }
+  const absPath = toAbsoluteDestination(destPath);
+  return await isDirectoryDestination(destPath) ? path2.join(absPath, basename4) : absPath;
+}
+async function isDirectoryDestination(destPath) {
+  if (destPath.endsWith(path2.sep) || destPath.endsWith("/")) {
+    return true;
+  }
+  try {
+    const info = await fs2.stat(toAbsoluteDestination(destPath));
+    return info.isDirectory();
+  } catch (err) {
+    if (!isFsNotFound2(err)) {
+      throw err;
     }
+    return false;
   }
-  return isDir ? path2.join(absPath, basename4) : absPath;
+}
+function toAbsoluteDestination(destPath) {
+  return path2.isAbsolute(destPath) ? path2.resolve(destPath) : path2.resolve(process.cwd(), destPath);
 }
 async function pathExists(p) {
   try {
@@ -2713,14 +2752,14 @@ var MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024;
 var inputSchema4 = {
   file_id: z4.string().min(1).describe("UUID of the file"),
   revision: z4.number().int().positive().optional().describe("Specific revision number to download (defaults to the latest revision)."),
-  destination_path: z4.string().min(1).describe(
-    "Local path to save the file to. Absolute, or relative to the MCP server's working directory. If it points to an existing directory (or ends with a path separator), the spec file's basename is appended."
+  destination_path: z4.string().min(1).optional().describe(
+    "Local path to save the file to. Optional: omit it to save the file under `.specs/` in the MCP server's working directory, mirroring its remote path (`specs/add-oauth/proposal.md` \u2192 `.specs/add-oauth/proposal.md`). When given, it is absolute or relative to that working directory; a relative path rooted at `specs/` is redirected to `.specs/`, so pass an absolute path to save into a literal `specs/` directory. If it points to an existing directory (or ends with a path separator), the spec file's basename is appended."
   ),
   overwrite: z4.boolean().optional().describe("Overwrite the destination file if it already exists (default: false).")
 };
 var downloadSpecFileTool = {
   name: "download_spec_file",
-  description: "Download a spec file's raw bytes to a local file at `destination_path`. Unlike read_spec_file, this handles binary files and files up to 50 MiB, and the response returns only metadata (saved path, size, revision) \u2014 not the content. Use it to save a large or binary file locally, then search or read it in chunks with other tools.",
+  description: "Download a spec file's raw bytes to a local file. By default it lands under `.specs/` in the MCP server's working directory, mirroring the file's remote path \u2014 pass `destination_path` only to save it somewhere else. Unlike read_spec_file, this handles binary files and files up to 50 MiB, and the response returns only metadata (saved path, size, revision) \u2014 not the content. Use it to save a large or binary file locally, then search or read it in chunks with other tools.",
   inputSchema: inputSchema4,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
@@ -2729,12 +2768,35 @@ var downloadSpecFileTool = {
       return errorResult(buildOversizeMessage(args.file_id, meta.fileSizeBytes));
     }
     const basename4 = path3.basename(meta.filePath) || "content";
+    const requested = args.destination_path;
+    let redirected = null;
     let destFile;
+    let destination = requested ?? "";
     try {
-      destFile = await resolveDestinationFile(args.destination_path, basename4);
+      if (requested === void 0) {
+        destination = defaultSpecDestination(meta.filePath);
+      } else {
+        redirected = await carryDirectoryIntent(requested, redirectSpecRootToLocal(requested));
+        destination = redirected ?? requested;
+      }
+      destFile = await resolveDestinationFile(destination, basename4);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      return errorResult(`Failed to resolve destination_path ${args.destination_path}: ${message}`);
+      return errorResult(`Failed to resolve destination_path ${maskHomedir(destination)}: ${message}`);
+    }
+    if (requested === void 0 || redirected !== null) {
+      const specRoot = path3.resolve(process.cwd(), LOCAL_SPEC_DIR);
+      const hint = requested === void 0 ? "Pass a destination_path to save elsewhere." : "Pass an absolute path to save into a literal specs/ directory.";
+      if (assertWithinRoot(destFile, specRoot) !== null) {
+        return errorResult(
+          `download_spec_file refused to write outside ${LOCAL_SPEC_DIR}/ (${maskHomedir(specRoot)}): ${maskHomedir(destFile)}. ${hint}`
+        );
+      }
+      if (path3.resolve(destFile) === specRoot) {
+        return errorResult(
+          `download_spec_file refused to write ${maskHomedir(destFile)}: that is the ${LOCAL_SPEC_DIR}/ folder itself, not a file inside it. ${hint}`
+        );
+      }
     }
     if (!args.overwrite && await pathExists(destFile)) {
       return errorResult(
@@ -2752,16 +2814,45 @@ var downloadSpecFileTool = {
       const message = err instanceof Error ? err.message : String(err);
       return errorResult(`Failed to write ${maskHomedir(destFile)}: ${message}`);
     }
+    const source = requested === void 0 ? "default" : redirected !== null ? "redirected" : "explicit";
     return jsonResult({
       file_id: meta.id,
       revision_number: downloaded.revisionNumber,
       file_path: meta.filePath,
       file_type: meta.fileType,
       saved_path: maskHomedir(destFile),
-      bytes_written: bytes.byteLength
+      bytes_written: bytes.byteLength,
+      // Say where the path came from, so a caller that passed `specs/...` and got
+      // `.specs/...` back can see why rather than hunting for a missing file.
+      destination_source: source,
+      ...source === "explicit" ? {} : { note: buildDestinationNote(source, requested) }
     });
   }
 };
+async function carryDirectoryIntent(requested, rewritten) {
+  if (rewritten === null || rewritten.endsWith(path3.sep)) {
+    return rewritten;
+  }
+  let isDir;
+  try {
+    isDir = await isDirectoryDestination(requested);
+  } catch (err) {
+    if (!isFilesystemError(err)) {
+      throw err;
+    }
+    isDir = false;
+  }
+  return isDir ? rewritten + path3.sep : rewritten;
+}
+function isFilesystemError(err) {
+  return typeof err === "object" && err !== null && typeof err.code === "string";
+}
+function buildDestinationNote(source, requested) {
+  if (source === "default") {
+    return `destination_path was omitted, so the file was saved under the preferred ${LOCAL_SPEC_DIR}/ folder in the working directory.`;
+  }
+  return `destination_path ${String(requested)} was rooted at specs/ and was redirected to the preferred ${LOCAL_SPEC_DIR}/ folder. Pass an absolute path to save into a literal specs/ directory.`;
+}
 function buildOversizeMessage(fileId, byteLength) {
   return `File ${fileId} is ${String(byteLength)} bytes which exceeds the download cap of ${String(MAX_DOWNLOAD_BYTES)} bytes.`;
 }
@@ -3041,7 +3132,7 @@ var inputSchema11 = {
 };
 var readSpecFileTool = {
   name: "read_spec_file",
-  description: "Return a spec file's UTF-8 content. Bytes are cached on disk under the configured cache root (default ~/.myspec) at `project/<projectId>/file/<fileId>/rev/<rev>/<basename>` and reused on subsequent reads of the same revision. Fails for binary files or files larger than 1 MiB \u2014 use download_spec_file with a `destination_path` to save those to a local file instead.",
+  description: "Return a spec file's UTF-8 content. Bytes are cached on disk under the configured cache root (default ~/.myspec) at `project/<projectId>/file/<fileId>/rev/<rev>/<basename>` and reused on subsequent reads of the same revision. Fails for binary files or files larger than 1 MiB \u2014 use download_spec_file to save those to a local file instead.",
   inputSchema: inputSchema11,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
@@ -3082,7 +3173,7 @@ var readSpecFileTool = {
     }
     if (isBinary(bytes)) {
       return errorResult(
-        `File ${args.file_id} appears to be binary (file_type=${meta.fileType}, size=${String(bytes.byteLength)} bytes). Use download_spec_file with a \`destination_path\` to save it to a local file.`
+        `File ${args.file_id} appears to be binary (file_type=${meta.fileType}, size=${String(bytes.byteLength)} bytes). Use download_spec_file to save it to a local file.`
       );
     }
     let text;
@@ -3090,7 +3181,7 @@ var readSpecFileTool = {
       text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
     } catch {
       return errorResult(
-        `File ${args.file_id} is not valid UTF-8 text. Use download_spec_file with a \`destination_path\` to save it to a local file.`
+        `File ${args.file_id} is not valid UTF-8 text. Use download_spec_file to save it to a local file.`
       );
     }
     return jsonResult({
@@ -3111,7 +3202,7 @@ var readSpecFileTool = {
   }
 };
 function buildOversizeMessage2(fileId, byteLength) {
-  return `File ${fileId} is ${String(byteLength)} bytes which exceeds the read cap of ${String(MAX_READ_BYTES)} bytes. Use download_spec_file with a \`destination_path\` to save it to a local file and read it in chunks.`;
+  return `File ${fileId} is ${String(byteLength)} bytes which exceeds the read cap of ${String(MAX_READ_BYTES)} bytes. Use download_spec_file to save it to a local file and read it in chunks.`;
 }
 function isBinary(bytes) {
   for (const byte of bytes) {
@@ -5057,13 +5148,16 @@ function printHelp() {
     "  login --org <slug>      Sign in and pin that organization. Tokens only work",
     "                          when an organization is active; the CLI asks when you",
     "                          belong to several and this flag is not given.",
-    "  logout                  Revoke refresh token and clear local credentials",
+    "  logout                  Sign out and clear the session credentials. A",
+    "                          configured apiToken is KEPT, so an unattended",
+    "                          install keeps working.",
     "  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",
+    "                          Uses the apiToken from ~/.myspec/oauth_creds.json if one",
+    "                          is set, otherwise the refresh_token saved by `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",

package/package.json

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