@myspec/mcp-server 0.1.2-next.37 → 0.1.2-next.39

package/README.md

@@ -80,7 +80,7 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 |---|---|
 | `MYSPEC_USER_AUTH_URL` | user-auth base URL (default `https://auth.myspec.dev`). The webapp URL is derived from it; the platform / ai-agent URLs are discovered via the webapp. |
 | `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_DOWNLOAD_ROOT` | Absolute path used by `read_spec_file` as its on-disk cache root (default: `~/.myspec`). Tools never write outside this root. |
 | `MYSPEC_AI_AGENT_WS_URL` | ai-agent WebSocket URL for `reverse`; skips the webapp discovery call |
 
 ## Tools
@@ -89,14 +89,17 @@ 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_file` | `file_id`, optional `include_download_url` | File metadata; with `include_download_url=N` also returns a download URL targeting revision `N` |
-| `read_file` | `file_id`, optional `revision` | UTF-8 content of the file (errors for binary). Cached on disk under `MYSPEC_DOWNLOAD_ROOT` |
+| `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` |
+| `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, ...) |
 
 ### `include_download_url` semantics
 
-`get_file`:
+`get_spec_file`:
 
 - Omit or `0` → metadata only.
 - Equal to current `revision_count` → adds `download_url` (signed) and `expires_at`.

package/dist/index.js

@@ -99,7 +99,7 @@ function applyCorsHeaders(res) {
   res.setHeader("Access-Control-Allow-Headers", "Content-Type");
 }
 async function waitForOAuthCallback(opts) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const settledFlag = { value: false };
     const timeoutRef = { handle: void 0 };
     const rlRef = { handle: void 0 };
@@ -157,7 +157,7 @@ async function waitForOAuthCallback(opts) {
       res.setHeader("Content-Type", "text/html");
       res.end(SUCCESS_HTML);
       settle(() => {
-        resolve2({ code });
+        resolve3({ code });
       });
     });
     server.on("error", (err) => {
@@ -204,7 +204,7 @@ async function waitForOAuthCallback(opts) {
         }
         settle(() => {
           opts.logger("Captured pasted token; finishing sign-in...");
-          resolve2({ code });
+          resolve3({ code });
         });
       });
     }
@@ -348,10 +348,10 @@ function createFileCredentialsStore(paths = {}) {
 async function loadOauthCreds(target) {
   try {
     if (process.platform !== "win32") {
-      const stat = await fs.stat(target);
-      if ((stat.mode & 63) !== 0) {
+      const stat2 = await fs.stat(target);
+      if ((stat2.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.`
+          `Refusing to load credentials from ${target}: file mode is too permissive (${(stat2.mode & 511).toString(8)}). Run \`chmod 600 ${target}\` and retry.`
         );
       }
     }
@@ -840,7 +840,7 @@ function calculateDelay(attempt, config) {
   return Math.round(cappedDelay * jitterMultiplier);
 }
 function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 async function withRetry(fn, config = DEFAULT_RETRY_CONFIG, shouldRetry = defaultShouldRetry) {
   const startTime = Date.now();
@@ -1890,6 +1890,26 @@ var PlatformClient = class {
   async deleteProject(projectId) {
     await this.withTokenRetry((jwt, c) => c.project.deleteProject(projectId, jwt));
   }
+  /**
+   * Moves a spec file to the Trash Bin (recoverable). The platform hides a
+   * trashed file from the default file list and all AI-agent tools, but keeps
+   * it restorable indefinitely via {@link restoreFile}.
+   */
+  async trashFile(fileId) {
+    await this.withTokenRetry((jwt, c) => c.file.trashFile(fileId, jwt));
+  }
+  /** Restores a spec file from the Trash Bin back to the active file list. */
+  async restoreFile(fileId) {
+    await this.withTokenRetry((jwt, c) => c.file.restoreFile(fileId, jwt));
+  }
+  /**
+   * Lists every spec file currently in the project's Trash Bin. The platform
+   * returns all trashed files in one response (no pagination), so this is a
+   * single call rather than a paged loop like {@link listFiles}.
+   */
+  async listTrashedFiles(projectId) {
+    return this.withTokenRetry((jwt, c) => c.file.listTrashedFiles(projectId, jwt));
+  }
   /**
    * Two-phase upload of a new, session-less ("unbound") spec file. Reserves a
    * file id (Phase 1, `sessionId` omitted so the file is unbound), then PUTs
@@ -2131,61 +2151,15 @@ var getAttachmentTool = {
   }
 };
 
-// src/server/tools/get_file.ts
+// src/server/tools/get_project.ts
 import { z as z5 } from "zod";
 var inputSchema5 = {
-  file_id: z5.string().min(1).describe("UUID of the file"),
-  include_download_url: z5.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 getFileTool = {
-  name: "get_file",
-  description: "Get 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: inputSchema5,
-  handler: async (args, ctx) => {
-    const meta = await ctx.client.getFileMetadata(args.file_id);
-    const base = {
-      id: meta.id,
-      project_id: meta.projectId,
-      session_id: meta.sessionId,
-      file_type: meta.fileType,
-      file_path: meta.filePath,
-      file_size_bytes: meta.fileSizeBytes,
-      checksum: meta.checksum,
-      revision_count: meta.revisionCount,
-      created_at: meta.createdAt,
-      updated_at: meta.updatedAt
-    };
-    const requested = args.include_download_url ?? 0;
-    if (requested <= 0) {
-      return jsonResult(base);
-    }
-    if (requested > meta.revisionCount) {
-      return errorResult(
-        `include_download_url=${String(requested)} is greater than revision_count=${String(meta.revisionCount)} for file ${meta.id}.`
-      );
-    }
-    const isLatest = requested === meta.revisionCount;
-    const signed = isLatest ? await ctx.client.getFileDownloadUrl(meta.id) : await ctx.client.getRevisionDownloadUrl(meta.id, requested);
-    const downloadBlock = {
-      download_url: signed.signedUrl,
-      download_revision: requested,
-      expires_at: signed.expiresAt.toISOString()
-    };
-    return jsonResult({ ...base, ...downloadBlock });
-  }
-};
-
-// src/server/tools/get_project.ts
-import { z as z6 } from "zod";
-var inputSchema6 = {
-  project_id: z6.string().min(1).describe("UUID of the project to fetch")
+  project_id: z5.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: inputSchema6,
+  inputSchema: inputSchema5,
   handler: async (args, ctx) => {
     const [project, sessions, files, attachments] = await Promise.all([
       ctx.client.getProject(args.project_id),
@@ -2230,6 +2204,52 @@ 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(
+    "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,
+  handler: async (args, ctx) => {
+    const meta = await ctx.client.getFileMetadata(args.file_id);
+    const base = {
+      id: meta.id,
+      project_id: meta.projectId,
+      session_id: meta.sessionId,
+      file_type: meta.fileType,
+      file_path: meta.filePath,
+      file_size_bytes: meta.fileSizeBytes,
+      checksum: meta.checksum,
+      revision_count: meta.revisionCount,
+      created_at: meta.createdAt,
+      updated_at: meta.updatedAt
+    };
+    const requested = args.include_download_url ?? 0;
+    if (requested <= 0) {
+      return jsonResult(base);
+    }
+    if (requested > meta.revisionCount) {
+      return errorResult(
+        `include_download_url=${String(requested)} is greater than revision_count=${String(meta.revisionCount)} for file ${meta.id}.`
+      );
+    }
+    const isLatest = requested === meta.revisionCount;
+    const signed = isLatest ? await ctx.client.getFileDownloadUrl(meta.id) : await ctx.client.getRevisionDownloadUrl(meta.id, requested);
+    const downloadBlock = {
+      download_url: signed.signedUrl,
+      download_revision: requested,
+      expires_at: signed.expiresAt.toISOString()
+    };
+    return jsonResult({ ...base, ...downloadBlock });
+  }
+};
+
 // src/server/tools/list_projects.ts
 import { z as z7 } from "zod";
 var inputSchema7 = {
@@ -2264,11 +2284,97 @@ var listProjectsTool = {
   }
 };
 
-// src/server/tools/read_file.ts
+// src/server/tools/list_spec_file.ts
+import { z as z8 } 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(
+    '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(
+    "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,
+  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);
+    const prefix = normalizePrefix(args.path);
+    const matches = files.filter((f) => isUnderPath(f.filePath, prefix)).map(toEntry).sort((a, b) => a.file_path.localeCompare(b.file_path));
+    return jsonResult({
+      project_id: args.project_id,
+      path: prefix,
+      trashed,
+      total: matches.length,
+      files: matches
+    });
+  }
+};
+async function listAllLiveFiles(client, projectId) {
+  const all = [];
+  let offset = 0;
+  for (; ; ) {
+    const page = await client.listFiles(projectId, { limit: PAGE_SIZE, offset });
+    all.push(...page.files);
+    offset += page.files.length;
+    if (page.files.length < PAGE_SIZE || offset >= page.total) {
+      return all;
+    }
+  }
+}
+function toEntry(file) {
+  const entry = {
+    file_id: file.id,
+    file_path: file.filePath,
+    file_type: file.fileType,
+    file_size_bytes: file.fileSizeBytes,
+    revision_count: file.revisionCount,
+    session_id: file.sessionId,
+    updated_at: file.updatedAt
+  };
+  if (file.trashedAt) {
+    entry.trashed_at = file.trashedAt;
+  }
+  return entry;
+}
+function normalizePrefix(path4) {
+  if (!path4) {
+    return "";
+  }
+  const trimmed = path4.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+  return trimmed;
+}
+function isUnderPath(filePath, prefix) {
+  if (prefix === "") {
+    return true;
+  }
+  return filePath === prefix || filePath.startsWith(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.")
+};
+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,
+  handler: async (args, ctx) => {
+    await ctx.client.trashFile(args.file_id);
+    return jsonResult({ trashed: true, file_id: args.file_id });
+  }
+};
+
+// src/server/tools/read_spec_file.ts
 import { promises as fs3 } from "fs";
 import os3 from "os";
 import path3 from "path";
-import { z as z8 } from "zod";
+import { z as z10 } from "zod";
 
 // src/server/download-path.ts
 import { promises as fs2 } from "fs";
@@ -2333,16 +2439,16 @@ async function writeBytesAtomically(target, bytes) {
   await fs2.rename(tmp, target);
 }
 
-// src/server/tools/read_file.ts
+// src/server/tools/read_spec_file.ts
 var MAX_READ_BYTES = 1 * 1024 * 1024;
-var inputSchema8 = {
-  file_id: z8.string().min(1).describe("UUID of the file"),
-  revision: z8.number().int().positive().optional().describe("Specific revision number to read (defaults to the latest revision).")
+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 readFileTool = {
-  name: "read_file",
-  description: "Return a 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_file with `include_download_url` to obtain a download URL for those.",
-  inputSchema: inputSchema8,
+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,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
     const targetRevision = args.revision ?? meta.revisionCount;
@@ -2360,7 +2466,7 @@ var readFileTool = {
     const escape = assertWithinRoot(cachePath, cacheRoot);
     if (escape) {
       return errorResult(
-        `read_file refused to write cache: ${escape}. This indicates an unexpected platform response shape (projectId/fileId/filePath).`
+        `read_spec_file refused to write cache: ${escape}. This indicates an unexpected platform response shape (projectId/fileId/filePath).`
       );
     }
     let bytes;
@@ -2381,7 +2487,7 @@ var readFileTool = {
     }
     if (isBinary(bytes)) {
       return errorResult(
-        `File ${args.file_id} appears to be binary (file_type=${meta.fileType}, size=${String(bytes.byteLength)} bytes). Use get_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 get_spec_file with \`include_download_url\` to obtain a download URL.`
       );
     }
     let text;
@@ -2389,7 +2495,7 @@ var readFileTool = {
       text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
     } catch {
       return errorResult(
-        `File ${args.file_id} is not valid UTF-8 text. Use get_file with \`include_download_url\` to obtain a download URL.`
+        `File ${args.file_id} is not valid UTF-8 text. Use get_spec_file with \`include_download_url\` to obtain a download URL.`
       );
     }
     return jsonResult({
@@ -2404,7 +2510,7 @@ var readFileTool = {
   }
 };
 function buildOversizeMessage(fileId, byteLength) {
-  return `File ${fileId} is ${String(byteLength)} bytes which exceeds the read cap of ${String(MAX_READ_BYTES)} bytes. Use get_file with \`include_download_url\` to obtain a download URL and fetch it directly.`;
+  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) {
@@ -2427,15 +2533,30 @@ function isBinary(bytes) {
   return false;
 }
 
+// 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.")
+};
+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,
+  handler: async (args, ctx) => {
+    await ctx.client.restoreFile(args.file_id);
+    return jsonResult({ restored: true, file_id: args.file_id });
+  }
+};
+
 // src/server/tools/unarchive_project.ts
-import { z as z9 } from "zod";
-var inputSchema9 = {
-  project_id: z9.string().min(1).describe("UUID of the project to unarchive.")
+import { z as z12 } from "zod";
+var inputSchema12 = {
+  project_id: z12.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: inputSchema9,
+  inputSchema: inputSchema12,
   handler: async (args, ctx) => {
     const project = await ctx.client.unarchiveProject(args.project_id);
     return jsonResult({ project: projectSummary(project) });
@@ -2443,19 +2564,19 @@ var unarchiveProjectTool = {
 };
 
 // src/server/tools/update_project.ts
-import { z as z10 } from "zod";
-var inputSchema10 = {
-  project_id: z10.string().min(1).describe("UUID of the project to update."),
-  name: z10.string().min(1).optional().describe("New project name."),
-  description: z10.string().optional().describe("New project description."),
-  project_type: z10.enum(["greenfield", "brownfield", "auto"]).optional().describe(
+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(
     "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: inputSchema10,
+  inputSchema: inputSchema13,
   handler: async (args, ctx) => {
     if (args.name === void 0 && args.description === void 0 && args.project_type === void 0) {
       return errorResult(
@@ -2478,7 +2599,60 @@ var updateProjectTool = {
 };
 
 // src/server/tools/update_spec_file.ts
-import { z as z11 } from "zod";
+import { z as z14 } from "zod";
+
+// src/server/tools/spec-content-source.ts
+import { readFile, stat } from "fs/promises";
+import { isAbsolute, resolve } from "path";
+var MAX_LOCAL_SPEC_FILE_BYTES = 5 * 1024 * 1024;
+async function resolveSpecContent(input, maxBytes = MAX_LOCAL_SPEC_FILE_BYTES) {
+  const { content, localFilePath } = input;
+  if (content !== void 0 && localFilePath !== void 0) {
+    return { error: "Provide either content or local_file_path, not both." };
+  }
+  if (content !== void 0) {
+    return { bytes: new TextEncoder().encode(content) };
+  }
+  if (localFilePath === void 0) {
+    return { error: "Provide the file body via content or local_file_path (one is required)." };
+  }
+  const absPath = isAbsolute(localFilePath) ? localFilePath : resolve(process.cwd(), localFilePath);
+  let info;
+  try {
+    info = await stat(absPath);
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT") {
+      return { error: `local file not found: ${absPath}` };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return { error: `failed to read local file ${absPath}: ${message}` };
+  }
+  if (!info.isFile()) {
+    return { error: `local_file_path is not a regular file: ${absPath}` };
+  }
+  if (info.size === 0) {
+    return { error: `local file is empty: ${absPath}` };
+  }
+  if (info.size > maxBytes) {
+    return {
+      error: `local file is too large (${String(info.size)} bytes); max is ${String(maxBytes)} bytes.`
+    };
+  }
+  let raw;
+  try {
+    raw = await readFile(absPath);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { error: `failed to read local file ${absPath}: ${message}` };
+  }
+  if (raw.byteLength > maxBytes) {
+    return {
+      error: `local file is too large (${String(raw.byteLength)} bytes); max is ${String(maxBytes)} bytes.`
+    };
+  }
+  return { bytes: new Uint8Array(raw) };
+}
 
 // src/server/tools/spec-file-output.ts
 function specFileSummary(file) {
@@ -2497,17 +2671,29 @@ function specFileSummary(file) {
 }
 
 // src/server/tools/update_spec_file.ts
-var inputSchema11 = {
-  file_id: z11.string().min(1).optional().describe("UUID of the spec file to overwrite. Provide this or (project_id + file_path)."),
-  project_id: z11.string().min(1).optional().describe("UUID of the project. Required (with file_path) when file_id is not given."),
-  file_path: z11.string().min(1).optional().describe("Path of the spec file. Required (with project_id) when file_id is not given."),
-  content: z11.string().min(1).describe("Full UTF-8 replacement content (non-empty), saved as a new revision.")
+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(
+    "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(
+    "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 from full content. Reference the file by file_id or by (project_id + file_path).",
-  inputSchema: inputSchema11,
+  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,
   handler: async (args, ctx) => {
+    const resolved = await resolveSpecContent({
+      content: args.content,
+      localFilePath: args.local_file_path
+    });
+    if (resolved.error || !resolved.bytes) {
+      return errorResult(resolved.error ?? "Failed to resolve file content.");
+    }
     let fileId;
     if (args.file_id) {
       const meta = await ctx.client.getFileMetadata(args.file_id).catch(() => null);
@@ -2526,17 +2712,16 @@ var updateSpecFileTool = {
     } else {
       return errorResult("Provide either file_id, or both project_id and file_path.");
     }
-    const content = new TextEncoder().encode(args.content);
-    const file = await ctx.client.saveSpecFileRevision(fileId, content);
+    const file = await ctx.client.saveSpecFileRevision(fileId, resolved.bytes);
     return jsonResult({ file: specFileSummary(file) });
   }
 };
 
 // src/server/tools/upload_attachment.ts
 import { createHash as createHash2 } from "crypto";
-import { lstat, readFile } from "fs/promises";
-import { basename, extname, isAbsolute } from "path";
-import { z as z12 } from "zod";
+import { lstat, readFile as readFile2 } from "fs/promises";
+import { basename, extname, isAbsolute as isAbsolute2 } from "path";
+import { z as z15 } from "zod";
 var DEFAULT_MIME = "application/octet-stream";
 var MAX_ATTACHMENT_MB = MAX_ATTACHMENT_BYTES / (1024 * 1024);
 var STRUCTURED_EXTENSION_MIME = {
@@ -2636,25 +2821,25 @@ function inferMimeFromName(name) {
   }
   return DEFAULT_MIME;
 }
-var inputSchema12 = {
-  project_id: z12.string().min(1).describe("UUID of the project to attach the file to."),
-  file_path: z12.string().min(1).describe(
+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(
     "Absolute path to the local file to upload. The MCP server reads this path from its own host."
   ),
-  file_name: z12.string().min(1).optional().describe("Override the filename recorded on the attachment. Defaults to the path basename."),
-  mime_type: z12.string().min(1).optional().describe(
+  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(
     "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: z12.boolean().optional().describe(
+  override: z15.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: inputSchema12,
+  inputSchema: inputSchema15,
   handler: async (args, ctx) => {
-    if (!isAbsolute(args.file_path)) {
+    if (!isAbsolute2(args.file_path)) {
       return errorResult(`file_path must be an absolute path; got "${args.file_path}".`);
     }
     let stats;
@@ -2690,7 +2875,7 @@ var uploadAttachmentTool = {
     }
     let buf;
     try {
-      buf = await readFile(args.file_path);
+      buf = await readFile2(args.file_path);
     } catch (err) {
       const code = err.code;
       if (code === "EACCES" || code === "EPERM") {
@@ -2776,7 +2961,7 @@ var uploadAttachmentTool = {
 };
 
 // src/server/tools/upload_spec_file.ts
-import { z as z13 } from "zod";
+import { z as z16 } from "zod";
 
 // src/server/spec-path.ts
 var MAX_SPEC_DIR_DEPTH = 3;
@@ -2794,15 +2979,16 @@ function validateSpecFilePath(filePath) {
   if (segments.some((s) => s === "" || s === ".")) {
     return 'file_path must be a normalized path (no empty, "." or trailing-slash segments).';
   }
-  if (segments[0] !== "specs") {
-    return "file_path must be rooted at 'specs' (e.g. specs/changes/add-oauth-login/proposal.md).";
+  const root = segments[0];
+  if (root !== "specs" && root !== "openspec") {
+    return "file_path must be rooted at 'specs' or 'openspec' (e.g. specs/changes/add-oauth-login/proposal.md).";
   }
   if (segments.length < 2) {
-    return "file_path must include a filename under 'specs' (e.g. specs/proposal.md).";
+    return `file_path must include a filename under '${root}' (e.g. ${root}/proposal.md).`;
   }
   const dirLevels = segments.length - 2;
   if (dirLevels > MAX_SPEC_DIR_DEPTH) {
-    return `file_path must not nest deeper than ${String(MAX_SPEC_DIR_DEPTH)} directory levels below specs.`;
+    return `file_path must not nest deeper than ${String(MAX_SPEC_DIR_DEPTH)} directory levels below the '${root}' root.`;
   }
   return null;
 }
@@ -2828,23 +3014,35 @@ var SPEC_FILE_TYPES = [
   "proposal",
   "openspec-spec"
 ];
-var inputSchema13 = {
-  project_id: z13.string().min(1).describe("UUID of the project to upload the file into."),
-  file_path: z13.string().min(1).describe(
-    'Path of the new spec file, rooted at "specs" with at most 3 directory levels below specs (e.g. specs/changes/add-oauth-login/proposal.md).'
+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(
+    '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: z13.string().min(1).describe("Full UTF-8 text content of the spec file (non-empty)."),
-  file_type: z13.enum(SPEC_FILE_TYPES).optional().describe("Spec file type. Omit to derive from the filename (e.g. proposal.md \u2192 proposal).")
+  content: z16.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(
+    "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).")
 };
 var uploadSpecFileTool = {
   name: "upload_spec_file",
-  description: "Upload a new, session-less spec file into a project from full content. Rejects if a file already exists at the same path (use update_spec_file to overwrite).",
-  inputSchema: inputSchema13,
+  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,
   handler: async (args, ctx) => {
     const pathError = validateSpecFilePath(args.file_path);
     if (pathError) {
       return errorResult(pathError);
     }
+    const resolved = await resolveSpecContent({
+      content: args.content,
+      localFilePath: args.local_file_path
+    });
+    if (resolved.error || !resolved.bytes) {
+      return errorResult(resolved.error ?? "Failed to resolve file content.");
+    }
     const existing = await ctx.client.findSpecFileByPath(args.project_id, args.file_path);
     if (existing) {
       return errorResult(
@@ -2852,12 +3050,11 @@ var uploadSpecFileTool = {
       );
     }
     const fileType = args.file_type ?? deriveFileType(args.file_path);
-    const content = new TextEncoder().encode(args.content);
     const file = await ctx.client.uploadSpecFile({
       projectId: args.project_id,
       filePath: args.file_path,
       fileType,
-      content
+      content: resolved.bytes
     });
     return jsonResult({ file: specFileSummary(file) });
   }
@@ -2871,8 +3068,9 @@ function buildServer(deps) {
   });
   registerTool(server, listProjectsTool, deps.client);
   registerTool(server, getProjectTool, deps.client);
-  registerTool(server, getFileTool, deps.client);
-  registerTool(server, readFileTool, deps.client);
+  registerTool(server, getSpecFileTool, deps.client);
+  registerTool(server, readSpecFileTool, deps.client);
+  registerTool(server, listSpecFileTool, deps.client);
   registerTool(server, getAttachmentTool, deps.client);
   registerTool(server, uploadAttachmentTool, deps.client);
   registerTool(server, createProjectTool, deps.client);
@@ -2882,6 +3080,8 @@ function buildServer(deps) {
   registerTool(server, deleteProjectTool, deps.client);
   registerTool(server, uploadSpecFileTool, deps.client);
   registerTool(server, updateSpecFileTool, deps.client);
+  registerTool(server, moveSpecFileToTrashTool, deps.client);
+  registerTool(server, restoreSpecFileFromTrashTool, deps.client);
   return server;
 }
 async function startStdioServer(deps) {
@@ -2949,13 +3149,13 @@ var WebSocketClientTransport = class {
     return Promise.resolve();
   }
   send(message) {
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       this.ws.send(JSON.stringify(message), (err) => {
         if (err) {
           reject(err);
           return;
         }
-        resolve2();
+        resolve3();
       });
     });
   }
@@ -2989,7 +3189,7 @@ var WebSocketClientTransport = class {
 
 // src/reverse/safe-path.ts
 import { realpath } from "fs/promises";
-import { isAbsolute as isAbsolute2, resolve, sep } from "path";
+import { isAbsolute as isAbsolute3, resolve as resolve2, sep } from "path";
 var PathOutsideRootError = class extends Error {
   constructor(userPath) {
     super(`path_outside_root: ${userPath}`);
@@ -3007,10 +3207,10 @@ var AbsolutePathError = class extends Error {
   userPath;
 };
 async function resolveSafePath(realRoot, userPath, opts = {}) {
-  if (isAbsolute2(userPath)) {
+  if (isAbsolute3(userPath)) {
     throw new AbsolutePathError(userPath);
   }
-  const joined = resolve(realRoot, userPath);
+  const joined = resolve2(realRoot, userPath);
   let resolved;
   try {
     resolved = await realpath(joined);
@@ -3035,7 +3235,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 z14 } from "zod";
+import { z as z17 } from "zod";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // src/reverse/ignore.ts
@@ -3115,7 +3315,7 @@ function ripgrepIgnoreGlobs() {
 
 // src/reverse/pack-codebase.ts
 import { createHash as createHash3 } from "crypto";
-import { mkdtemp, readFile as readFile2, rm } from "fs/promises";
+import { mkdtemp, readFile as readFile3, rm } from "fs/promises";
 import { tmpdir } from "os";
 import { join } from "path";
 import { runCli } from "repomix";
@@ -3252,7 +3452,7 @@ async function invokeRepomix(exec, targetDir, args, timeoutMs) {
   const execPromise = exec(["."], targetDir, options);
   try {
     await withTimeout(execPromise, timeoutMs);
-    const content = await readFile2(outputFile, "utf-8");
+    const content = await readFile3(outputFile, "utf-8");
     await rm(workDir, { recursive: true, force: true });
     return content;
   } catch (err) {
@@ -3285,37 +3485,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 = z14.object({
-  path: z14.string(),
-  recursive: z14.boolean().optional(),
-  maxEntries: z14.number().int().positive().optional(),
-  includeIgnored: z14.boolean().optional()
+var listDirInput = z17.object({
+  path: z17.string(),
+  recursive: z17.boolean().optional(),
+  maxEntries: z17.number().int().positive().optional(),
+  includeIgnored: z17.boolean().optional()
 });
-var readFileInput = z14.object({
-  path: z14.string(),
-  offset: z14.number().int().nonnegative().optional(),
-  limit: z14.number().int().positive().optional(),
-  includeIgnored: z14.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 grepInput = z14.object({
-  pattern: z14.string().describe(
+var grepInput = z17.object({
+  pattern: z17.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: z14.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
-  isRegex: z14.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
-  caseSensitive: z14.boolean().optional(),
-  maxMatches: z14.number().int().positive().optional(),
-  contextLines: z14.number().int().nonnegative().optional(),
-  includeIgnored: z14.boolean().optional()
+  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()
 });
-var packCodebaseInput = z14.object({
-  subpath: z14.string().optional(),
-  includePatterns: z14.string().optional(),
-  ignorePatterns: z14.string().optional()
+var packCodebaseInput = z17.object({
+  subpath: z17.string().optional(),
+  includePatterns: z17.string().optional(),
+  ignorePatterns: z17.string().optional()
 });
-var packCodebaseReadPageInput = z14.object({
-  outputId: z14.string(),
-  page: z14.number().int().positive()
+var packCodebaseReadPageInput = z17.object({
+  outputId: z17.string(),
+  page: z17.number().int().positive()
 });
 function structuredError(error, message, extra) {
   const payload = { error, message, ...extra ?? {} };
@@ -3402,20 +3602,20 @@ async function handleRead(args, opts) {
       return structuredError("path_ignored", `Path matches ignore rule ${check.rule ?? ""}`);
     }
   }
-  let stat;
+  let stat2;
   try {
-    stat = await fs4.stat(realPath);
+    stat2 = await fs4.stat(realPath);
   } catch (err) {
     return structuredError("stat_failed", errorMessage(err));
   }
-  if (!stat.isFile()) {
+  if (!stat2.isFile()) {
     return structuredError("not_a_file", `Not a regular file: ${args.path}`);
   }
-  if (stat.size > READ_FILE_MAX_BYTES) {
+  if (stat2.size > READ_FILE_MAX_BYTES) {
     return structuredError(
       "file_too_large",
-      `File is ${String(stat.size)} bytes; the read cap is ${String(READ_FILE_MAX_BYTES)} bytes. Use local_fs_grep to find the lines you need, or local_pack_codebase to pull the whole tree.`,
-      { sizeBytes: stat.size, maxBytes: READ_FILE_MAX_BYTES }
+      `File is ${String(stat2.size)} bytes; the read cap is ${String(READ_FILE_MAX_BYTES)} bytes. Use local_fs_grep to find the lines you need, or local_pack_codebase to pull the whole tree.`,
+      { sizeBytes: stat2.size, maxBytes: READ_FILE_MAX_BYTES }
     );
   }
   let raw;
@@ -3843,7 +4043,7 @@ function jsonSchemaFromZod(schema) {
   return zodToJson(schema);
 }
 function zodToJson(schema) {
-  if (schema instanceof z14.ZodObject) {
+  if (schema instanceof z17.ZodObject) {
     const shape = schema.shape;
     const properties = {};
     const required = [];
@@ -3858,19 +4058,19 @@ function zodToJson(schema) {
     if (required.length > 0) out.required = required;
     return out;
   }
-  if (schema instanceof z14.ZodOptional) {
+  if (schema instanceof z17.ZodOptional) {
     return zodToJson(schema.unwrap());
   }
-  if (schema instanceof z14.ZodString) {
+  if (schema instanceof z17.ZodString) {
     return { type: "string" };
   }
-  if (schema instanceof z14.ZodNumber) {
+  if (schema instanceof z17.ZodNumber) {
     return { type: "number" };
   }
-  if (schema instanceof z14.ZodBoolean) {
+  if (schema instanceof z17.ZodBoolean) {
     return { type: "boolean" };
   }
-  if (schema instanceof z14.ZodEnum) {
+  if (schema instanceof z17.ZodEnum) {
     return { type: "string", enum: schema.options };
   }
   return { type: "string" };
@@ -4020,7 +4220,7 @@ async function runOneConnection(opts) {
       pongTimer = null;
     }
   });
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     ws.once("close", (code, reasonBuf) => {
       clearInterval(pingTimer);
       if (pongTimer) clearTimeout(pongTimer);
@@ -4030,7 +4230,7 @@ async function runOneConnection(opts) {
 `
       );
       const terminal = TERMINAL_CLOSE_CODES.has(code);
-      resolve2({
+      resolve3({
         terminal,
         reason: `code=${String(code)} ${reasonStr}`,
         upMs: Date.now() - connectedAt,
@@ -4040,10 +4240,10 @@ async function runOneConnection(opts) {
   });
 }
 function waitForOpen(ws) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const onOpen = () => {
       ws.removeListener("error", onError);
-      resolve2();
+      resolve3();
     };
     const onError = (err) => {
       ws.removeListener("open", onOpen);
@@ -4054,7 +4254,7 @@ function waitForOpen(ws) {
   });
 }
 function sleep2(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 
 // src/index.ts

package/package.json

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