@myspec/mcp-server 0.4.0-next.107 → 0.4.0-next.108

package/README.md

@@ -291,9 +291,9 @@ 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, 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` |
+| `read_spec_file` | `file_id`, optional `revision`, optional `offset`, optional `limit` | UTF-8 content paginated by line (`offset` is 1-based, default/cap 2000 lines, 1 MiB per response) with `content`, `start_line`, `end_line`, `read_lines`, `total_lines`, `truncated`, `next_offset`; plus `content_version` when reading the latest revision (errors for binary or files > 8 MiB — use `download_spec_file` for those). Cached on disk under `MYSPEC_DOWNLOAD_ROOT`, so paging through a file downloads it once |
 | `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 |
+| `list_spec_file` | `project_id`, optional `path`, optional `trashed`, optional `limit`, optional `offset` | Lists a project's spec files (`file_id`, `file_path`, `file_type`, `file_size_bytes`, `revision_count`, `session_id`, `updated_at`, plus `trashed_at` on Trash Bin entries). Filter to a directory with `path` (exact file or everything under it; `""`/`"/"`/omit = all). `trashed=true` lists the Trash Bin instead of live files. Returns `total`, `limit`, `offset` and, when more records remain, `next_offset` (default 50, capped at 200). Ordered by `file_path` when `path` or `trashed` is given, most-recently-created first otherwise |
 | `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 |

package/dist/index.js

@@ -3793,6 +3793,9 @@ function sliceWindow(items, limit, offset) {
   };
 }
 function nextOffsetOf(offset, returned, total) {
+  if (returned === 0) {
+    return void 0;
+  }
   const end = offset + returned;
   return end < total ? end : void 0;
 }
@@ -3870,6 +3873,8 @@ var listProjectsTool = {
 // src/server/tools/list_spec_file.ts
 import { z as z13 } from "zod";
 var PAGE_SIZE = 100;
+var LIST_DEFAULT2 = 50;
+var LIST_MAX2 = 200;
 var inputSchema13 = {
   project_id: z13.string().min(1).describe("UUID of the project whose spec files to list."),
   path: z13.string().optional().describe(
@@ -3877,26 +3882,57 @@ var inputSchema13 = {
   ),
   trashed: z13.boolean().optional().describe(
     "When true, list files in the project Trash Bin instead. When false or omitted, list only live files (trashed files excluded)."
-  )
+  ),
+  limit: z13.number().int().positive().optional().describe(
+    `Max files to return (default ${String(LIST_DEFAULT2)}, capped at ${String(LIST_MAX2)}).`
+  ),
+  offset: z13.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
 };
 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.',
+  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. Ordered by `file_path` ascending whenever `path` or `trashed` is given, most-recently-created first otherwise. Returns `total` and, when more records remain, `next_offset`.',
   inputSchema: inputSchema13,
   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 limit = clampLimit(args.limit, LIST_DEFAULT2, LIST_MAX2);
+    const offset = args.offset ?? 0;
     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
-    });
+    if (trashed) {
+      const all2 = await ctx.client.listTrashedFiles(args.project_id);
+      return windowedListResult(args.project_id, prefix, true, all2, limit, offset);
+    }
+    if (prefix === "") {
+      const page = await ctx.client.listFiles(args.project_id, { limit, offset });
+      const next = nextOffsetOf(offset, page.files.length, page.total);
+      return jsonResult({
+        project_id: args.project_id,
+        path: prefix,
+        trashed: false,
+        files: page.files.map(toEntry),
+        total: page.total,
+        limit,
+        offset,
+        ...next === void 0 ? {} : { next_offset: next }
+      });
+    }
+    const all = await listAllLiveFiles(ctx.client, args.project_id);
+    return windowedListResult(args.project_id, prefix, false, all, limit, offset);
   }
 };
+function windowedListResult(projectId, prefix, trashed, files, limit, offset) {
+  const matches = files.filter((f) => isUnderPath(f.filePath, prefix)).map(toEntry).sort((a, b) => a.file_path.localeCompare(b.file_path));
+  const window = sliceWindow(matches, limit, offset);
+  return jsonResult({
+    project_id: projectId,
+    path: prefix,
+    trashed,
+    files: window.items,
+    total: window.total,
+    limit: window.limit,
+    offset,
+    ...window.next_offset === void 0 ? {} : { next_offset: window.next_offset }
+  });
+}
 async function listAllLiveFiles(client, projectId) {
   const all = [];
   let offset = 0;
@@ -3940,24 +3976,24 @@ function isUnderPath(filePath, prefix) {
 
 // src/server/tools/list_spec_sessions.ts
 import { z as z14 } from "zod";
-var LIST_DEFAULT2 = 10;
-var LIST_MAX2 = 20;
+var LIST_DEFAULT3 = 10;
+var LIST_MAX3 = 20;
 var inputSchema14 = {
   project_id: z14.string().min(1).describe("UUID of the project whose spec sessions to list."),
   archive_filter: z14.enum(["active", "archived", "all"]).optional().describe("Which sessions to list: 'active' (default), 'archived', or 'all'."),
   status: z14.enum(["generating", "pending_input", "completed"]).optional().describe("Filter by session status."),
   query: z14.string().optional().describe("Search term matched against the session summary."),
   limit: z14.number().int().positive().optional().describe(
-    `Max sessions to return (default ${String(LIST_DEFAULT2)}, capped at ${String(LIST_MAX2)}).`
+    `Max sessions to return (default ${String(LIST_DEFAULT3)}, capped at ${String(LIST_MAX3)}).`
   ),
   offset: z14.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
 };
 var listSpecSessionsTool = {
   name: "list_spec_sessions",
-  description: `List a project's spec sessions (metadata plus session_summary and context_size_bytes \u2014 never the context itself or the chat transcript). Filter with archive_filter ('active'/'archived'/'all'), status, and query (searches the session summary). Capped at ${String(LIST_MAX2)} per page; returns \`total\` and \`next_offset\`.`,
+  description: `List a project's spec sessions (metadata plus session_summary and context_size_bytes \u2014 never the context itself or the chat transcript). Filter with archive_filter ('active'/'archived'/'all'), status, and query (searches the session summary). Capped at ${String(LIST_MAX3)} per page; returns \`total\` and \`next_offset\`.`,
   inputSchema: inputSchema14,
   handler: async (args, ctx) => {
-    const limit = clampLimit(args.limit, LIST_DEFAULT2, LIST_MAX2);
+    const limit = clampLimit(args.limit, LIST_DEFAULT3, LIST_MAX3);
     const offset = args.offset ?? 0;
     const result = await ctx.client.listProjectSessions(args.project_id, {
       archiveFilter: args.archive_filter ?? "active",
@@ -4008,6 +4044,9 @@ var MAX_LINES_PER_CALL = 2e3;
 var MAX_RESPONSE_BYTES = 1 * 1024 * 1024;
 function normalizeNewlines(text) {
   const withoutBom = text.startsWith("\uFEFF") ? text.slice(1) : text;
+  if (!withoutBom.includes("\r")) {
+    return withoutBom;
+  }
   return withoutBom.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
 }
 function splitIntoLines(text) {
@@ -4178,20 +4217,27 @@ var readAttachmentTool = {
 import { promises as fs3 } from "fs";
 import { createHash as createHash2 } from "crypto";
 import { z as z17 } from "zod";
-var MAX_READ_BYTES = 1 * 1024 * 1024;
+var MAX_READABLE_SPEC_FILE_BYTES = 8 * 1024 * 1024;
 var inputSchema17 = {
   file_id: z17.string().min(1).describe("UUID of the file"),
-  revision: z17.number().int().positive().optional().describe("Specific revision number to read (defaults to the latest revision).")
+  revision: z17.number().int().positive().optional().describe("Specific revision number to read (defaults to the latest revision)."),
+  offset: z17.number().int().nonnegative().optional().describe("1-based line number to start reading from (default 1; 0 is an alias for 1)."),
+  limit: z17.number().int().positive().optional().describe("Max lines to return (default 2000, capped at 2000; larger values are clamped).")
 };
 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 to save those to a local file instead.",
+  description: "Return a window of a spec file's UTF-8 content, paginated by line (offset/limit, default and cap 2000 lines, 1 MiB per response). Large files are read across multiple calls using `next_offset`. 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, so paging through a file downloads it once. Files above 8 MiB and binary content are refused \u2014 use download_spec_file to save those to a local file instead.",
   inputSchema: inputSchema17,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
     const targetRevision = args.revision ?? meta.revisionCount;
     const isLatestRevision = targetRevision === meta.revisionCount;
-    if (isLatestRevision && meta.fileSizeBytes > MAX_READ_BYTES) {
+    if (args.revision !== void 0 && args.revision > meta.revisionCount) {
+      return errorResult(
+        `revision=${String(args.revision)} is greater than revision_count=${String(meta.revisionCount)} for file ${args.file_id}.`
+      );
+    }
+    if (isLatestRevision && meta.fileSizeBytes > MAX_READABLE_SPEC_FILE_BYTES) {
       return errorResult(buildOversizeMessage2(args.file_id, meta.fileSizeBytes));
     }
     const cacheRoot = resolveDownloadRoot();
@@ -4208,20 +4254,42 @@ var readSpecFileTool = {
         `read_spec_file refused to write cache: ${escape}. This indicates an unexpected platform response shape (projectId/fileId/filePath).`
       );
     }
-    const cached = await pathExists(cachePath) ? await fs3.readFile(cachePath) : null;
+    const cachedSize = await fileSizeOrNull(cachePath);
+    if (cachedSize !== null && cachedSize > MAX_READABLE_SPEC_FILE_BYTES) {
+      return errorResult(buildOversizeMessage2(args.file_id, cachedSize));
+    }
+    const cached = cachedSize === null ? null : await fs3.readFile(cachePath);
     const cacheHit = cached !== null && (!isLatestRevision || sha256Prefixed2(cached) === meta.checksum);
     let bytes;
+    let effectiveRevision = targetRevision;
+    let effectiveCachePath = cachePath;
     if (cacheHit) {
       bytes = cached;
     } else {
       const downloaded = await ctx.client.downloadFile(args.file_id, args.revision);
       bytes = downloaded.bytes;
-      if (bytes.byteLength > MAX_READ_BYTES) {
+      if (bytes.byteLength > MAX_READABLE_SPEC_FILE_BYTES) {
         return errorResult(buildOversizeMessage2(args.file_id, bytes.byteLength));
       }
-      await writeBytesAtomically(cachePath, bytes);
+      if (downloaded.revisionNumber !== targetRevision) {
+        effectiveRevision = downloaded.revisionNumber;
+        effectiveCachePath = computeFileCachePath({
+          cacheRoot,
+          projectId: meta.projectId,
+          fileId: meta.id,
+          revision: effectiveRevision,
+          filePath: meta.filePath
+        });
+        const raceEscape = assertWithinRoot(effectiveCachePath, cacheRoot);
+        if (raceEscape) {
+          return errorResult(
+            `read_spec_file refused to write cache: ${raceEscape}. This indicates an unexpected platform response shape (projectId/fileId/filePath).`
+          );
+        }
+      }
+      await writeBytesAtomically(effectiveCachePath, bytes);
     }
-    if (bytes.byteLength > MAX_READ_BYTES) {
+    if (bytes.byteLength > MAX_READABLE_SPEC_FILE_BYTES) {
       return errorResult(buildOversizeMessage2(args.file_id, bytes.byteLength));
     }
     if (isBinary2(bytes)) {
@@ -4237,25 +4305,44 @@ var readSpecFileTool = {
         `File ${args.file_id} is not valid UTF-8 text. Use download_spec_file to save it to a local file.`
       );
     }
+    const paginated = paginateText(text, args.offset, args.limit);
+    if (!paginated.ok) {
+      return errorResult(paginated.error);
+    }
     return jsonResult({
       file_id: meta.id,
-      revision_number: targetRevision,
+      revision_number: effectiveRevision,
       // Pass this back as update_spec_file's expected_version so an edit made by
       // someone else since this read is reported instead of overwritten. It
       // describes the file's CURRENT content, so it is emitted only when that is
       // what was read — beside a historical revision it would invite an update
       // that overwrites everything written since.
-      ...isLatestRevision && meta.contentVersion !== void 0 ? { content_version: meta.contentVersion } : {},
+      // ...and only when it describes THESE bytes. If a concurrent save moved
+      // the revision under us, meta.contentVersion belongs to the older one:
+      // a stale token is fail-safe (the platform answers 409) but it would
+      // cost the model a round trip it cannot diagnose, so omit it and let the
+      // re-read supply a current one.
+      ...isLatestRevision && effectiveRevision === targetRevision && meta.contentVersion !== void 0 ? { content_version: meta.contentVersion } : {},
       file_path: meta.filePath,
       file_type: meta.fileType,
-      cache_path: maskHomedir(cachePath),
+      cache_path: maskHomedir(effectiveCachePath),
       cache_hit: cacheHit,
-      content: text
+      // `content` plus the window fields (start_line/end_line/read_lines/
+      // total_lines/truncated/next_offset) — the same shape read_attachment
+      // and mcp-server-http's read_spec_file return.
+      ...paginated.window
     });
   }
 };
 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 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_READABLE_SPEC_FILE_BYTES)} bytes. Use download_spec_file to save it to a local file and read it in chunks.`;
+}
+async function fileSizeOrNull(filePath) {
+  try {
+    return (await fs3.stat(filePath)).size;
+  } catch {
+    return null;
+  }
 }
 function isBinary2(bytes) {
   for (const byte of bytes) {
@@ -4965,11 +5052,11 @@ function artifactCreateConflictMessage(conflict) {
 }
 
 // src/server/tools/list_artifacts.ts
-var LIST_DEFAULT3 = 50;
-var LIST_MAX3 = 100;
+var LIST_DEFAULT4 = 50;
+var LIST_MAX4 = 100;
 var inputSchema26 = {
   project_id: z27.string().min(1).describe("UUID of the project whose artifacts to list."),
-  limit: z27.number().int().positive().optional().describe(`Max artifacts to return (default ${String(LIST_DEFAULT3)}, capped at ${String(LIST_MAX3)}).`),
+  limit: z27.number().int().positive().optional().describe(`Max artifacts to return (default ${String(LIST_DEFAULT4)}, capped at ${String(LIST_MAX4)}).`),
   offset: z27.number().int().nonnegative().optional().describe("Pagination offset (default 0).")
 };
 var listArtifactsTool = {
@@ -4977,7 +5064,7 @@ var listArtifactsTool = {
   description: "List a project's live artifacts (multi-file bundles such as HTML mockups, each versioned as one snapshot) with id, slug, entry path and revision_count. Returns `total` and, when more remain, `next_offset`. Use get_artifact for the file manifest and read_artifact_file for content.",
   inputSchema: inputSchema26,
   handler: async (args, ctx) => {
-    const limit = clampLimit(args.limit, LIST_DEFAULT3, LIST_MAX3);
+    const limit = clampLimit(args.limit, LIST_DEFAULT4, LIST_MAX4);
     const offset = args.offset ?? 0;
     const page = await ctx.client.listArtifacts(args.project_id, { limit, offset });
     const next = nextOffsetOf(offset, page.items.length, page.total);

package/package.json

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