@myspec/mcp-server 0.1.4-next.52 → 0.1.4-next.54

package/README.md

@@ -90,7 +90,8 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 | `list_projects` | `query?`, `limit?`, `offset?` | Paginated list of projects |
 | `get_project` | `project_id` | Project + active sessions + files + attachments |
 | `get_spec_file` | `file_id`, optional `include_download_url` | File metadata; 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 (errors for binary). Cached on disk under `MYSPEC_DOWNLOAD_ROOT` |
+| `read_spec_file` | `file_id`, optional `revision` | UTF-8 content of the file (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 |
 | `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` |

package/dist/index.js

@@ -2132,16 +2132,177 @@ var deleteProjectTool = {
   }
 };
 
-// src/server/tools/get_attachment.ts
+// src/server/tools/download_spec_file.ts
+import path3 from "path";
 import { z as z4 } from "zod";
+
+// src/server/download-path.ts
+import { randomBytes as randomBytes2 } from "crypto";
+import { promises as fs2 } from "fs";
+import os2 from "os";
+import path2 from "path";
+function resolveDownloadRoot(env = process.env) {
+  const configured = env.MYSPEC_DOWNLOAD_ROOT;
+  if (configured) {
+    if (!path2.isAbsolute(configured)) {
+      throw new Error(`MYSPEC_DOWNLOAD_ROOT must be an absolute path (got: ${configured})`);
+    }
+    return path2.resolve(configured);
+  }
+  return path2.join(os2.homedir(), ".myspec");
+}
+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)) {
+    return `path resolves outside the configured root (${resolvedRoot}): ${resolvedTarget}`;
+  }
+  return null;
+}
+function computeFileCachePath(args) {
+  const basename4 = path2.basename(args.filePath) || "content";
+  return path2.join(
+    args.cacheRoot,
+    "project",
+    args.projectId,
+    "file",
+    args.fileId,
+    "rev",
+    String(args.revision),
+    basename4
+  );
+}
+function maskHomedir(p, home = os2.homedir()) {
+  if (!home) {
+    return p;
+  }
+  if (p === home) {
+    return "~";
+  }
+  if (p.startsWith(home + path2.sep)) {
+    return "~" + p.slice(home.length);
+  }
+  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;
+      }
+    }
+  }
+  return isDir ? path2.join(absPath, basename4) : absPath;
+}
+async function pathExists(p) {
+  try {
+    await fs2.stat(p);
+    return true;
+  } catch (err) {
+    if (isFsNotFound2(err)) {
+      return false;
+    }
+    throw err;
+  }
+}
+function isFsNotFound2(err) {
+  const code = typeof err === "object" && err !== null ? err.code : void 0;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+async function writeBytesAtomically(target, bytes) {
+  const dir = path2.dirname(target);
+  await fs2.mkdir(dir, { recursive: true });
+  const suffix = randomBytes2(6).toString("hex");
+  const tmp = path2.join(dir, `.${path2.basename(target)}.${process.pid.toString()}.${suffix}.tmp`);
+  const handle = await fs2.open(tmp, "wx", 384);
+  try {
+    try {
+      await handle.write(bytes);
+    } finally {
+      await handle.close();
+    }
+    await fs2.rename(tmp, target);
+  } catch (err) {
+    await fs2.rm(tmp, { force: true });
+    throw err;
+  }
+}
+
+// src/server/tools/download_spec_file.ts
+var MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024;
 var inputSchema4 = {
-  attachment_id: z4.string().min(1).describe("UUID of the attachment"),
-  include_download_url: z4.number().int().nonnegative().optional().describe("Set to any positive value to include a signed download URL. Omit or 0 to skip.")
+  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."
+  ),
+  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.",
+  inputSchema: inputSchema4,
+  handler: async (args, ctx) => {
+    const meta = await ctx.client.getFileMetadata(args.file_id);
+    const targetRevision = args.revision ?? meta.revisionCount;
+    if (targetRevision === meta.revisionCount && meta.fileSizeBytes > MAX_DOWNLOAD_BYTES) {
+      return errorResult(buildOversizeMessage(args.file_id, meta.fileSizeBytes));
+    }
+    const basename4 = path3.basename(meta.filePath) || "content";
+    let destFile;
+    try {
+      destFile = await resolveDestinationFile(args.destination_path, basename4);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return errorResult(`Failed to resolve destination_path ${args.destination_path}: ${message}`);
+    }
+    if (!args.overwrite && await pathExists(destFile)) {
+      return errorResult(
+        `Destination already exists: ${maskHomedir(destFile)}. Pass overwrite: true to replace it.`
+      );
+    }
+    const downloaded = await ctx.client.downloadFile(args.file_id, args.revision);
+    const bytes = downloaded.bytes;
+    if (bytes.byteLength > MAX_DOWNLOAD_BYTES) {
+      return errorResult(buildOversizeMessage(args.file_id, bytes.byteLength));
+    }
+    try {
+      await writeBytesAtomically(destFile, bytes);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return errorResult(`Failed to write ${maskHomedir(destFile)}: ${message}`);
+    }
+    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
+    });
+  }
+};
+function buildOversizeMessage(fileId, byteLength) {
+  return `File ${fileId} is ${String(byteLength)} bytes which exceeds the download cap of ${String(MAX_DOWNLOAD_BYTES)} bytes.`;
+}
+
+// src/server/tools/get_attachment.ts
+import { z as z5 } from "zod";
+var inputSchema5 = {
+  attachment_id: z5.string().min(1).describe("UUID of the attachment"),
+  include_download_url: z5.number().int().nonnegative().optional().describe("Set to any positive value to include a signed download URL. Omit or 0 to skip.")
 };
 var getAttachmentTool = {
   name: "get_attachment",
   description: "Get attachment metadata. With `include_download_url>0`, also returns a signed `download_url`.",
-  inputSchema: inputSchema4,
+  inputSchema: inputSchema5,
   handler: async (args, ctx) => {
     const attachment = await ctx.client.getAttachmentMetadata(args.attachment_id);
     if (!attachment) {
@@ -2170,14 +2331,14 @@ var getAttachmentTool = {
 };
 
 // src/server/tools/get_project.ts
-import { z as z5 } from "zod";
-var inputSchema5 = {
-  project_id: z5.string().min(1).describe("UUID of the project to fetch")
+import { z as z6 } from "zod";
+var inputSchema6 = {
+  project_id: z6.string().min(1).describe("UUID of the project to fetch")
 };
 var getProjectTool = {
   name: "get_project",
   description: "Get details for a project including all active spec sessions, files (id + metadata), and attachments (id + metadata).",
-  inputSchema: inputSchema5,
+  inputSchema: inputSchema6,
   handler: async (args, ctx) => {
     const [project, sessions, files, attachments] = await Promise.all([
       ctx.client.getProject(args.project_id),
@@ -2223,17 +2384,17 @@ var getProjectTool = {
 };
 
 // src/server/tools/get_spec_file.ts
-import { z as z6 } from "zod";
-var inputSchema6 = {
-  file_id: z6.string().min(1).describe("UUID of the file"),
-  include_download_url: z6.number().int().nonnegative().optional().describe(
+import { z as z7 } from "zod";
+var inputSchema7 = {
+  file_id: z7.string().min(1).describe("UUID of the file"),
+  include_download_url: z7.number().int().nonnegative().optional().describe(
     "Revision number to include a download URL for. Returns a signed, time-limited URL for that revision (latest or historical) that needs no credentials. Omit or 0 to skip."
   )
 };
 var getSpecFileTool = {
   name: "get_spec_file",
   description: "Get spec file metadata. With `include_download_url=N`, also returns a signed, time-limited download URL for revision N (latest or historical). The URL is self-authenticating, so no credentials are returned.",
-  inputSchema: inputSchema6,
+  inputSchema: inputSchema7,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
     const base = {
@@ -2269,18 +2430,18 @@ var getSpecFileTool = {
 };
 
 // src/server/tools/list_projects.ts
-import { z as z7 } from "zod";
-var inputSchema7 = {
-  query: z7.string().optional().describe(
+import { z as z8 } from "zod";
+var inputSchema8 = {
+  query: z8.string().optional().describe(
     "Search term to filter projects by name. Omit to list all projects."
   ),
-  limit: z7.number().int().positive().max(100).optional().describe("Max projects to return (default 20)"),
-  offset: z7.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
+  limit: z8.number().int().positive().max(100).optional().describe("Max projects to return (default 20)"),
+  offset: z8.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
 };
 var listProjectsTool = {
   name: "list_projects",
   description: "List or search MySpec projects accessible to the authenticated user.",
-  inputSchema: inputSchema7,
+  inputSchema: inputSchema8,
   handler: async (args, ctx) => {
     const result = await ctx.client.listProjects({
       query: args.query,
@@ -2303,21 +2464,21 @@ var listProjectsTool = {
 };
 
 // src/server/tools/list_spec_file.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var PAGE_SIZE = 100;
-var inputSchema8 = {
-  project_id: z8.string().min(1).describe("UUID of the project whose spec files to list."),
-  path: z8.string().optional().describe(
+var inputSchema9 = {
+  project_id: z9.string().min(1).describe("UUID of the project whose spec files to list."),
+  path: z9.string().optional().describe(
     'Directory prefix to filter by, e.g. ".spec" or ".spec/design". Matches the exact file and everything under that directory. Pass "", "/", or omit to list all files.'
   ),
-  trashed: z8.boolean().optional().describe(
+  trashed: z9.boolean().optional().describe(
     "When true, list files in the project Trash Bin instead. When false or omitted, list only live files (trashed files excluded)."
   )
 };
 var listSpecFileTool = {
   name: "list_spec_file",
   description: 'List a project\'s spec files with id, path, and metadata (revision count, file size of the latest revision, file type, owning session, last update). Filter to a directory with `path` (exact file or everything under it; pass "", "/", or omit for all). Set `trashed=true` to list files in the Trash Bin instead of live files.',
-  inputSchema: inputSchema8,
+  inputSchema: inputSchema9,
   handler: async (args, ctx) => {
     const trashed = args.trashed ?? false;
     const files = trashed ? await ctx.client.listTrashedFiles(args.project_id) : await listAllLiveFiles(ctx.client, args.project_id);
@@ -2374,14 +2535,14 @@ function isUnderPath(filePath, prefix) {
 }
 
 // src/server/tools/move_spec_file_to_trash.ts
-import { z as z9 } from "zod";
-var inputSchema9 = {
-  file_id: z9.string().min(1).describe("UUID of the spec file to move to the Trash Bin.")
+import { z as z10 } from "zod";
+var inputSchema10 = {
+  file_id: z10.string().min(1).describe("UUID of the spec file to move to the Trash Bin.")
 };
 var moveSpecFileToTrashTool = {
   name: "move_spec_file_to_trash",
   description: "Move a spec file to the Trash Bin. This is recoverable \u2014 the file is hidden from the default file list and AI-agent tools but kept restorable indefinitely via `restore_spec_file_from_trash`. It is NOT a permanent delete.",
-  inputSchema: inputSchema9,
+  inputSchema: inputSchema10,
   handler: async (args, ctx) => {
     await ctx.client.trashFile(args.file_id);
     return jsonResult({ trashed: true, file_id: args.file_id });
@@ -2390,88 +2551,21 @@ var moveSpecFileToTrashTool = {
 
 // src/server/tools/read_spec_file.ts
 import { promises as fs3 } from "fs";
-import os3 from "os";
-import path3 from "path";
-import { z as z10 } from "zod";
-
-// src/server/download-path.ts
-import { promises as fs2 } from "fs";
-import os2 from "os";
-import path2 from "path";
-function resolveDownloadRoot(env = process.env) {
-  const configured = env.MYSPEC_DOWNLOAD_ROOT;
-  if (configured) {
-    if (!path2.isAbsolute(configured)) {
-      throw new Error(`MYSPEC_DOWNLOAD_ROOT must be an absolute path (got: ${configured})`);
-    }
-    return path2.resolve(configured);
-  }
-  return path2.join(os2.homedir(), ".myspec");
-}
-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)) {
-    return `path resolves outside the configured root (${resolvedRoot}): ${resolvedTarget}`;
-  }
-  return null;
-}
-function computeFileCachePath(args) {
-  const basename4 = path2.basename(args.filePath) || "content";
-  return path2.join(
-    args.cacheRoot,
-    "project",
-    args.projectId,
-    "file",
-    args.fileId,
-    "rev",
-    String(args.revision),
-    basename4
-  );
-}
-async function pathExists(p) {
-  try {
-    await fs2.stat(p);
-    return true;
-  } catch (err) {
-    if (isFsNotFound2(err)) {
-      return false;
-    }
-    throw err;
-  }
-}
-function isFsNotFound2(err) {
-  return typeof err === "object" && err !== null && err.code === "ENOENT";
-}
-async function writeBytesAtomically(target, bytes) {
-  const dir = path2.dirname(target);
-  await fs2.mkdir(dir, { recursive: true });
-  const tmp = path2.join(dir, `.${path2.basename(target)}.${process.pid.toString()}.tmp`);
-  const handle = await fs2.open(tmp, "wx", 384);
-  try {
-    await handle.write(bytes);
-  } finally {
-    await handle.close();
-  }
-  await fs2.rename(tmp, target);
-}
-
-// src/server/tools/read_spec_file.ts
+import { z as z11 } from "zod";
 var MAX_READ_BYTES = 1 * 1024 * 1024;
-var inputSchema10 = {
-  file_id: z10.string().min(1).describe("UUID of the file"),
-  revision: z10.number().int().positive().optional().describe("Specific revision number to read (defaults to the latest revision).")
+var inputSchema11 = {
+  file_id: z11.string().min(1).describe("UUID of the file"),
+  revision: z11.number().int().positive().optional().describe("Specific revision number to read (defaults to the latest revision).")
 };
 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 get_spec_file with `include_download_url` to obtain a download URL for those.",
-  inputSchema: inputSchema10,
+  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.",
+  inputSchema: inputSchema11,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
     const targetRevision = args.revision ?? meta.revisionCount;
     if (targetRevision === meta.revisionCount && meta.fileSizeBytes > MAX_READ_BYTES) {
-      return errorResult(buildOversizeMessage(args.file_id, meta.fileSizeBytes));
+      return errorResult(buildOversizeMessage2(args.file_id, meta.fileSizeBytes));
     }
     const cacheRoot = resolveDownloadRoot();
     const cachePath = computeFileCachePath({
@@ -2496,16 +2590,16 @@ var readSpecFileTool = {
       const downloaded = await ctx.client.downloadFile(args.file_id, args.revision);
       bytes = downloaded.bytes;
       if (bytes.byteLength > MAX_READ_BYTES) {
-        return errorResult(buildOversizeMessage(args.file_id, bytes.byteLength));
+        return errorResult(buildOversizeMessage2(args.file_id, bytes.byteLength));
       }
       await writeBytesAtomically(cachePath, bytes);
     }
     if (bytes.byteLength > MAX_READ_BYTES) {
-      return errorResult(buildOversizeMessage(args.file_id, bytes.byteLength));
+      return errorResult(buildOversizeMessage2(args.file_id, bytes.byteLength));
     }
     if (isBinary(bytes)) {
       return errorResult(
-        `File ${args.file_id} appears to be binary (file_type=${meta.fileType}, size=${String(bytes.byteLength)} bytes). Use get_spec_file with \`include_download_url\` to obtain a download URL.`
+        `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.`
       );
     }
     let text;
@@ -2513,7 +2607,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 get_spec_file with \`include_download_url\` to obtain a download URL.`
+        `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.`
       );
     }
     return jsonResult({
@@ -2527,20 +2621,8 @@ var readSpecFileTool = {
     });
   }
 };
-function buildOversizeMessage(fileId, byteLength) {
-  return `File ${fileId} is ${String(byteLength)} bytes which exceeds the read cap of ${String(MAX_READ_BYTES)} bytes. Use get_spec_file with \`include_download_url\` to obtain a download URL and fetch it directly.`;
-}
-function maskHomedir(p, home = os3.homedir()) {
-  if (!home) {
-    return p;
-  }
-  if (p === home) {
-    return "~";
-  }
-  if (p.startsWith(home + path3.sep)) {
-    return "~" + p.slice(home.length);
-  }
-  return p;
+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.`;
 }
 function isBinary(bytes) {
   for (const byte of bytes) {
@@ -2552,14 +2634,14 @@ function isBinary(bytes) {
 }
 
 // src/server/tools/restore_spec_file_from_trash.ts
-import { z as z11 } from "zod";
-var inputSchema11 = {
-  file_id: z11.string().min(1).describe("UUID of the spec file to restore from the Trash Bin.")
+import { z as z12 } from "zod";
+var inputSchema12 = {
+  file_id: z12.string().min(1).describe("UUID of the spec file to restore from the Trash Bin.")
 };
 var restoreSpecFileFromTrashTool = {
   name: "restore_spec_file_from_trash",
   description: "Restore a spec file from the Trash Bin back to the active file list, reversing `move_spec_file_to_trash`. The file becomes visible again to the default file list and AI-agent tools.",
-  inputSchema: inputSchema11,
+  inputSchema: inputSchema12,
   handler: async (args, ctx) => {
     await ctx.client.restoreFile(args.file_id);
     return jsonResult({ restored: true, file_id: args.file_id });
@@ -2567,14 +2649,14 @@ var restoreSpecFileFromTrashTool = {
 };
 
 // src/server/tools/unarchive_project.ts
-import { z as z12 } from "zod";
-var inputSchema12 = {
-  project_id: z12.string().min(1).describe("UUID of the project to unarchive.")
+import { z as z13 } from "zod";
+var inputSchema13 = {
+  project_id: z13.string().min(1).describe("UUID of the project to unarchive.")
 };
 var unarchiveProjectTool = {
   name: "unarchive_project",
   description: 'Unarchive a project (sets status to "active"). Idempotent: unarchiving an already-active project succeeds.',
-  inputSchema: inputSchema12,
+  inputSchema: inputSchema13,
   handler: async (args, ctx) => {
     const project = await ctx.client.unarchiveProject(args.project_id);
     return jsonResult({ project: projectSummary(project) });
@@ -2582,19 +2664,19 @@ var unarchiveProjectTool = {
 };
 
 // src/server/tools/update_project.ts
-import { z as z13 } from "zod";
-var inputSchema13 = {
-  project_id: z13.string().min(1).describe("UUID of the project to update."),
-  name: z13.string().min(1).optional().describe("New project name."),
-  description: z13.string().optional().describe("New project description."),
-  project_type: z13.enum(["greenfield", "brownfield", "auto"]).optional().describe(
+import { z as z14 } from "zod";
+var inputSchema14 = {
+  project_id: z14.string().min(1).describe("UUID of the project to update."),
+  name: z14.string().min(1).optional().describe("New project name."),
+  description: z14.string().optional().describe("New project description."),
+  project_type: z14.enum(["greenfield", "brownfield", "auto"]).optional().describe(
     "Codebase type. 'greenfield' or 'brownfield' sets it explicitly; 'auto' clears it so the workflow decides. Omit to leave unchanged."
   )
 };
 var updateProjectTool = {
   name: "update_project",
   description: "Update a project's metadata (name, description, project_type). Returns the updated metadata.",
-  inputSchema: inputSchema13,
+  inputSchema: inputSchema14,
   handler: async (args, ctx) => {
     if (args.name === void 0 && args.description === void 0 && args.project_type === void 0) {
       return errorResult(
@@ -2617,7 +2699,7 @@ var updateProjectTool = {
 };
 
 // src/server/tools/update_spec_file.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 
 // src/server/tools/spec-content-source.ts
 import { readFile, stat } from "fs/promises";
@@ -2689,21 +2771,21 @@ function specFileSummary(file) {
 }
 
 // src/server/tools/update_spec_file.ts
-var inputSchema14 = {
-  file_id: z14.string().min(1).optional().describe("UUID of the spec file to overwrite. Provide this or (project_id + file_path)."),
-  project_id: z14.string().min(1).optional().describe("UUID of the project. Required (with file_path) when file_id is not given."),
-  file_path: z14.string().min(1).optional().describe("Path of the spec file. Required (with project_id) when file_id is not given."),
-  content: z14.string().min(1).optional().describe(
+var inputSchema15 = {
+  file_id: z15.string().min(1).optional().describe("UUID of the spec file to overwrite. Provide this or (project_id + file_path)."),
+  project_id: z15.string().min(1).optional().describe("UUID of the project. Required (with file_path) when file_id is not given."),
+  file_path: z15.string().min(1).optional().describe("Path of the spec file. Required (with project_id) when file_id is not given."),
+  content: z15.string().min(1).optional().describe(
     "Full UTF-8 replacement content, saved as a new revision. Provide this OR local_file_path (exactly one). Use for in-memory / generated content."
   ),
-  local_file_path: z14.string().min(1).optional().describe(
+  local_file_path: z15.string().min(1).optional().describe(
     "Path to a local file whose bytes become the new revision; the server reads it directly. Provide this OR content (exactly one). Absolute paths are most reliable; a relative path resolves against the MCP server working directory. Point this only at an intended spec file \u2014 its bytes are uploaded to the project as-is; never use it for secrets or unrelated files."
   )
 };
 var updateSpecFileTool = {
   name: "update_spec_file",
   description: "Overwrite an existing spec file by saving a new revision. Provide the new body inline via `content` or by pointing at a local file with `local_file_path` \u2014 exactly one is required. Prefer `local_file_path` when the body is already an existing local file (the server reads it directly); use `content` for text generated in-memory. Reference the file by file_id or by (project_id + file_path).",
-  inputSchema: inputSchema14,
+  inputSchema: inputSchema15,
   handler: async (args, ctx) => {
     const resolved = await resolveSpecContent({
       content: args.content,
@@ -2739,7 +2821,7 @@ var updateSpecFileTool = {
 import { createHash as createHash2 } from "crypto";
 import { lstat, readFile as readFile2 } from "fs/promises";
 import { basename, extname, isAbsolute as isAbsolute2 } from "path";
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 var DEFAULT_MIME = "application/octet-stream";
 var MAX_ATTACHMENT_MB = MAX_ATTACHMENT_BYTES / (1024 * 1024);
 var STRUCTURED_EXTENSION_MIME = {
@@ -2839,23 +2921,23 @@ function inferMimeFromName(name) {
   }
   return DEFAULT_MIME;
 }
-var inputSchema15 = {
-  project_id: z15.string().min(1).describe("UUID of the project to attach the file to."),
-  file_path: z15.string().min(1).describe(
+var inputSchema16 = {
+  project_id: z16.string().min(1).describe("UUID of the project to attach the file to."),
+  file_path: z16.string().min(1).describe(
     "Absolute path to the local file to upload. The MCP server reads this path from its own host."
   ),
-  file_name: z15.string().min(1).optional().describe("Override the filename recorded on the attachment. Defaults to the path basename."),
-  mime_type: z15.string().min(1).optional().describe(
+  file_name: z16.string().min(1).optional().describe("Override the filename recorded on the attachment. Defaults to the path basename."),
+  mime_type: z16.string().min(1).optional().describe(
     "Override the MIME type sent to the platform. The platform re-detects from content, so this is only a hint. If omitted, inferred from the file extension \u2014 structured (.pdf, .docx, .xlsx) keep their canonical MIME; common UTF-8 text formats (.xml, .json, .yaml, .html, .csv, .md, source code, ...) are sent as text/plain."
   ),
-  override: z15.boolean().optional().describe(
+  override: z16.boolean().optional().describe(
     "When true, any existing (non-deleted) attachment on the project whose recorded filename exactly matches `file_name` (or the path basename) is soft-deleted before the new upload, so the new attachment keeps the original name instead of getting an auto-dedup `(1)` suffix. The platform has no in-place content-replace API, so the new upload always gets a new `attachment_id`; any replaced ids are returned as `overridden_attachment_ids` (array, possibly empty) so callers can refresh stored references. Defaults to false (let the platform auto-dedup)."
   )
 };
 var uploadAttachmentTool = {
   name: "upload_attachment",
   description: `Upload a local file as a new attachment on a project. Reads \`file_path\` from the host running the MCP server, computes its SHA256, then performs the two-phase platform upload. Max ${String(MAX_ATTACHMENT_MB)} MB. Supported content: PDF, DOCX, XLSX, and any UTF-8 text file (XML, JSON, YAML, HTML, Markdown, CSV, source code, ...). Binary files outside the structured types will be rejected by the platform.`,
-  inputSchema: inputSchema15,
+  inputSchema: inputSchema16,
   handler: async (args, ctx) => {
     if (!isAbsolute2(args.file_path)) {
       return errorResult(`file_path must be an absolute path; got "${args.file_path}".`);
@@ -2979,7 +3061,7 @@ var uploadAttachmentTool = {
 };
 
 // src/server/tools/upload_spec_file.ts
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 
 // src/server/spec-path.ts
 var MAX_SPEC_DIR_DEPTH = 3;
@@ -3032,23 +3114,23 @@ var SPEC_FILE_TYPES = [
   "proposal",
   "openspec-spec"
 ];
-var inputSchema16 = {
-  project_id: z16.string().min(1).describe("UUID of the project to upload the file into."),
-  file_path: z16.string().min(1).describe(
+var inputSchema17 = {
+  project_id: z17.string().min(1).describe("UUID of the project to upload the file into."),
+  file_path: z17.string().min(1).describe(
     'Path of the new spec file, rooted at "specs" or "openspec" with at most 3 directory levels below the root (e.g. specs/changes/add-oauth-login/proposal.md).'
   ),
-  content: z16.string().min(1).optional().describe(
+  content: z17.string().min(1).optional().describe(
     "Full UTF-8 text content of the spec file. Provide this OR local_file_path (exactly one). Use for in-memory / generated content."
   ),
-  local_file_path: z16.string().min(1).optional().describe(
+  local_file_path: z17.string().min(1).optional().describe(
     "Path to a local file whose bytes become the spec file body; the server reads it directly. Provide this OR content (exactly one). Absolute paths are most reliable; a relative path resolves against the MCP server working directory. Point this only at an intended spec file \u2014 its bytes are uploaded to the project as-is; never use it for secrets or unrelated files."
   ),
-  file_type: z16.enum(SPEC_FILE_TYPES).optional().describe("Spec file type. Omit to derive from the filename (e.g. proposal.md \u2192 proposal).")
+  file_type: z17.enum(SPEC_FILE_TYPES).optional().describe("Spec file type. Omit to derive from the filename (e.g. proposal.md \u2192 proposal).")
 };
 var uploadSpecFileTool = {
   name: "upload_spec_file",
   description: "Upload a new, session-less spec file into a project. Provide the file body inline via `content` or by pointing at a local file with `local_file_path` \u2014 exactly one is required. Prefer `local_file_path` when the body is already an existing local file (the server reads it directly, avoiding sending large content through the model); use `content` for text generated in-memory. Rejects if a file already exists at the same path (use update_spec_file to overwrite).",
-  inputSchema: inputSchema16,
+  inputSchema: inputSchema17,
   handler: async (args, ctx) => {
     const pathError = validateSpecFilePath(args.file_path);
     if (pathError) {
@@ -3088,6 +3170,7 @@ function buildServer(deps) {
   registerTool(server, getProjectTool, deps.client);
   registerTool(server, getSpecFileTool, deps.client);
   registerTool(server, readSpecFileTool, deps.client);
+  registerTool(server, downloadSpecFileTool, deps.client);
   registerTool(server, listSpecFileTool, deps.client);
   registerTool(server, getAttachmentTool, deps.client);
   registerTool(server, uploadAttachmentTool, deps.client);
@@ -3253,7 +3336,7 @@ async function canonicaliseRoot(root) {
 import { promises as fs4 } from "fs";
 import { join as join2, relative } from "path";
 import { spawn } from "child_process";
-import { z as z17 } from "zod";
+import { z as z18 } from "zod";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // src/reverse/ignore.ts
@@ -3558,37 +3641,37 @@ var READ_FILE_MAX_LINES = 2e3;
 var LIST_DIR_HARD_CAP = 5e3;
 var LIST_DIR_DEFAULT_CAP = 1e3;
 var GREP_MAX_MATCHES_DEFAULT = 200;
-var listDirInput = z17.object({
-  path: z17.string(),
-  recursive: z17.boolean().optional(),
-  maxEntries: z17.number().int().positive().optional(),
-  includeIgnored: z17.boolean().optional()
+var listDirInput = z18.object({
+  path: z18.string(),
+  recursive: z18.boolean().optional(),
+  maxEntries: z18.number().int().positive().optional(),
+  includeIgnored: z18.boolean().optional()
 });
-var readFileInput = z17.object({
-  path: z17.string(),
-  offset: z17.number().int().nonnegative().optional(),
-  limit: z17.number().int().positive().optional(),
-  includeIgnored: z17.boolean().optional()
+var readFileInput = z18.object({
+  path: z18.string(),
+  offset: z18.number().int().nonnegative().optional(),
+  limit: z18.number().int().positive().optional(),
+  includeIgnored: z18.boolean().optional()
 });
-var grepInput = z17.object({
-  pattern: z17.string().describe(
+var grepInput = z18.object({
+  pattern: z18.string().describe(
     "Search pattern. Interpreted as a regular expression by default (ripgrep syntax), e.g. `foo|bar` or `[Rr]ole`. Set `isRegex: false` to match the pattern as an exact literal string instead."
   ),
-  path: z17.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
-  isRegex: z17.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
-  caseSensitive: z17.boolean().optional(),
-  maxMatches: z17.number().int().positive().optional(),
-  contextLines: z17.number().int().nonnegative().optional(),
-  includeIgnored: z17.boolean().optional()
+  path: z18.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
+  isRegex: z18.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
+  caseSensitive: z18.boolean().optional(),
+  maxMatches: z18.number().int().positive().optional(),
+  contextLines: z18.number().int().nonnegative().optional(),
+  includeIgnored: z18.boolean().optional()
 });
-var packCodebaseInput = z17.object({
-  subpath: z17.string().optional(),
-  includePatterns: z17.string().optional(),
-  ignorePatterns: z17.string().optional()
+var packCodebaseInput = z18.object({
+  subpath: z18.string().optional(),
+  includePatterns: z18.string().optional(),
+  ignorePatterns: z18.string().optional()
 });
-var packCodebaseReadPageInput = z17.object({
-  outputId: z17.string(),
-  page: z17.number().int().positive()
+var packCodebaseReadPageInput = z18.object({
+  outputId: z18.string(),
+  page: z18.number().int().positive()
 });
 function structuredError(error, message, extra) {
   const payload = { error, message, ...extra ?? {} };
@@ -4116,7 +4199,7 @@ function jsonSchemaFromZod(schema) {
   return zodToJson(schema);
 }
 function zodToJson(schema) {
-  if (schema instanceof z17.ZodObject) {
+  if (schema instanceof z18.ZodObject) {
     const shape = schema.shape;
     const properties = {};
     const required = [];
@@ -4131,19 +4214,19 @@ function zodToJson(schema) {
     if (required.length > 0) out.required = required;
     return out;
   }
-  if (schema instanceof z17.ZodOptional) {
+  if (schema instanceof z18.ZodOptional) {
     return zodToJson(schema.unwrap());
   }
-  if (schema instanceof z17.ZodString) {
+  if (schema instanceof z18.ZodString) {
     return { type: "string" };
   }
-  if (schema instanceof z17.ZodNumber) {
+  if (schema instanceof z18.ZodNumber) {
     return { type: "number" };
   }
-  if (schema instanceof z17.ZodBoolean) {
+  if (schema instanceof z18.ZodBoolean) {
     return { type: "boolean" };
   }
-  if (schema instanceof z17.ZodEnum) {
+  if (schema instanceof z18.ZodEnum) {
     return { type: "string", enum: schema.options };
   }
   return { type: "string" };

package/package.json

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