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

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

@@ -32,10 +32,11 @@ var REFRESH_TOKEN_PATTERN = /"refreshToken"\s*:\s*"[^"]+"/g;
 var API_TOKEN_PATTERN = /"apiToken"\s*:\s*"[^"]+"/g;
 var API_TOKEN_VALUE_PATTERN = /\bmsp_pat_[A-Za-z0-9]+/g;
 var ACCESS_TOKEN_PATTERN = /"accessToken"\s*:\s*"[^"]+"/g;
-var SNAKE_TOKEN_PATTERN = /"(access_token|refresh_token|id_token)"\s*:\s*"[^"]+"/g;
+var SNAKE_TOKEN_PATTERN = /"(access_token|refresh_token|id_token|token)"\s*:\s*"[^"]+"/g;
 var JWT_PATTERN = /\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
+var STREAM_URL_PATTERN = /\/realtime\/v1\/stream\/[A-Za-z0-9_-]{20,}/g;
 function redactSensitive(value) {
-  return value.replace(BEARER_PATTERN, "Bearer [REDACTED]").replace(REFRESH_TOKEN_PATTERN, '"refreshToken":"[REDACTED]"').replace(API_TOKEN_PATTERN, '"apiToken":"[REDACTED]"').replace(API_TOKEN_VALUE_PATTERN, "[REDACTED_API_TOKEN]").replace(ACCESS_TOKEN_PATTERN, '"accessToken":"[REDACTED]"').replace(SNAKE_TOKEN_PATTERN, (_match, key) => `"${key}":"[REDACTED]"`).replace(JWT_PATTERN, "[REDACTED_JWT]");
+  return value.replace(BEARER_PATTERN, "Bearer [REDACTED]").replace(REFRESH_TOKEN_PATTERN, '"refreshToken":"[REDACTED]"').replace(API_TOKEN_PATTERN, '"apiToken":"[REDACTED]"').replace(API_TOKEN_VALUE_PATTERN, "[REDACTED_API_TOKEN]").replace(ACCESS_TOKEN_PATTERN, '"accessToken":"[REDACTED]"').replace(SNAKE_TOKEN_PATTERN, (_match, key) => `"${key}":"[REDACTED]"`).replace(JWT_PATTERN, "[REDACTED_JWT]").replace(STREAM_URL_PATTERN, "/realtime/v1/stream/[REDACTED_STREAM_TOKEN]");
 }
 var ConfigError = class extends Error {
   constructor(message) {
@@ -2716,6 +2717,127 @@ var HttpArtifactClient = class {
   }
 };
 
+// ../../packages/platform-client/stream/types/stream-token.types.ts
+function optionalDate(value) {
+  return value ? new Date(value) : null;
+}
+function transformStreamToken(raw) {
+  return {
+    id: raw.id,
+    tokenPrefix: raw.token_prefix,
+    label: raw.label ?? "",
+    resourceType: raw.resource_type,
+    resourceId: raw.resource_id,
+    eventTypes: raw.event_types ?? [],
+    createdBy: raw.created_by,
+    createdAt: new Date(raw.created_at),
+    expiresAt: new Date(raw.expires_at),
+    revokedAt: optionalDate(raw.revoked_at),
+    resourceDeletedAt: optionalDate(raw.resource_deleted_at),
+    lastConnectedAt: optionalDate(raw.last_connected_at),
+    connectCount: raw.connect_count,
+    live: raw.live
+  };
+}
+function transformStreamTokenMintResult(raw) {
+  if (!raw.token || !raw.url) {
+    throw new Error("stream token mint response carried no token or url");
+  }
+  return { ...transformStreamToken(raw), token: raw.token, url: raw.url };
+}
+function transformStreamTokenListResult(raw) {
+  return {
+    tokens: (raw.tokens ?? []).map(transformStreamToken),
+    total: raw.total ?? 0
+  };
+}
+function transformStreamCatalogue(raw) {
+  return {
+    resources: (raw.resources ?? []).map((resource) => ({
+      resourceType: resource.resource_type,
+      eventTypes: resource.event_types ?? []
+    })),
+    maxTtlSeconds: raw.max_ttl_seconds,
+    defaultTtlSeconds: raw.default_ttl_seconds
+  };
+}
+function buildCreateStreamTokenBody(request) {
+  const body = {
+    resource_type: request.resourceType,
+    resource_id: request.resourceId
+  };
+  body.event_types = request.eventTypes;
+  if (request.ttlSeconds !== void 0) {
+    body.ttl_seconds = request.ttlSeconds;
+  }
+  if (request.label) {
+    body.label = request.label;
+  }
+  return body;
+}
+
+// ../../packages/platform-client/stream/http/stream-token.http-client.ts
+var BASE_PATH2 = "/realtime/v1";
+function requestOptions2(options) {
+  return options ?? {};
+}
+var HttpStreamTokenClient = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  httpClient;
+  async createStreamToken(request, jwtToken, options) {
+    const raw = await this.httpClient.post(
+      `${BASE_PATH2}/stream-tokens`,
+      buildCreateStreamTokenBody(request),
+      jwtToken,
+      requestOptions2(options)
+    );
+    return transformStreamTokenMintResult(raw);
+  }
+  async listStreamTokens(options, jwtToken, httpOptions) {
+    const query = new URLSearchParams();
+    if (options?.resourceId) {
+      query.set("resource_id", options.resourceId);
+    }
+    if (options?.liveOnly) {
+      query.set("live", "true");
+    }
+    if (options?.mineOnly) {
+      query.set("mine", "true");
+    }
+    if (options?.limit !== void 0) {
+      query.set("limit", String(options.limit));
+    }
+    if (options?.offset !== void 0) {
+      query.set("offset", String(options.offset));
+    }
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+    const raw = await this.httpClient.get(
+      `${BASE_PATH2}/stream-tokens${suffix}`,
+      jwtToken,
+      requestOptions2(httpOptions)
+    );
+    return transformStreamTokenListResult(raw);
+  }
+  async revokeStreamToken(id, jwtToken, options) {
+    const raw = await this.httpClient.delete(
+      `${BASE_PATH2}/stream-tokens/${encodeURIComponent(id)}`,
+      jwtToken,
+      requestOptions2(options)
+    );
+    return transformStreamToken(raw);
+  }
+  async getStreamCatalogue(jwtToken, options) {
+    const raw = await this.httpClient.get(
+      `${BASE_PATH2}/stream-catalogue`,
+      jwtToken,
+      requestOptions2(options)
+    );
+    return transformStreamCatalogue(raw);
+  }
+};
+
 // src/platform/client.ts
 var silentLogger = {
   debug: () => void 0,
@@ -3003,9 +3125,24 @@ var PlatformClient = class {
       session: new HttpSpecSessionClient(httpClient),
       file: new HttpFileClient(httpClient),
       attachment: new HttpAttachmentClient(httpClient),
-      artifact: new HttpArtifactClient(httpClient)
+      artifact: new HttpArtifactClient(httpClient),
+      streamToken: new HttpStreamTokenClient(httpClient)
     };
   }
+  // ------------------------------------------------------- stream tokens
+  //
+  // A stream token is a presigned WebSocket URL for a project's event feed —
+  // the URL is the whole credential, which is what lets a tool that takes one
+  // string and nothing else consume the feed.
+  async createStreamToken(request) {
+    return this.withTokenRetry((jwt, c) => c.streamToken.createStreamToken(request, jwt));
+  }
+  async listStreamTokens(opts = {}) {
+    return this.withTokenRetry((jwt, c) => c.streamToken.listStreamTokens(opts, jwt));
+  }
+  async revokeStreamToken(id) {
+    return this.withTokenRetry((jwt, c) => c.streamToken.revokeStreamToken(id, jwt));
+  }
   // ----------------------------------------------------------- artifacts
   //
   // Every write is attributed `actorKind: 'ai'`: an MCP client is an
@@ -3793,6 +3930,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 +4010,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 +4019,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 +4113,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 +4181,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 +4354,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 +4391,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 +4442,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 +5189,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 +5201,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);
@@ -5186,6 +5410,133 @@ var rollbackArtifactTool = {
   }
 };
 
+// src/server/tools/create_stream_token.ts
+import { z as z34 } from "zod";
+
+// src/server/tools/stream-token-output.ts
+import { z as z33 } from "zod";
+var projectStreamEventTypes = [
+  "project.updated",
+  "project.deleted",
+  "spec_file.created",
+  "spec_file.updated",
+  "spec_file.deleted",
+  "spec_file.lock",
+  "attachment.created",
+  "attachment.deleted",
+  "spec_session.created",
+  "spec_session.updated",
+  "spec_session.deleted",
+  "*"
+];
+var streamEventTypesSchema = z33.array(z33.enum(projectStreamEventTypes)).min(1).describe(
+  'Event types to receive. Required \u2014 pass ["*"] to follow all of them. spec_file.updated covers new revisions, rollbacks, and moves to or from the trash; spec_file.lock covers acquire, renew, release and takeover; spec_session.updated covers completion, archive, unarchive and rename.'
+);
+function streamTokenSummary(token) {
+  return {
+    id: token.id,
+    token_prefix: token.tokenPrefix,
+    label: token.label,
+    resource_type: token.resourceType,
+    resource_id: token.resourceId,
+    event_types: token.eventTypes,
+    created_by: token.createdBy,
+    created_at: token.createdAt.toISOString(),
+    expires_at: token.expiresAt.toISOString(),
+    live: token.live,
+    connect_count: token.connectCount,
+    ...token.revokedAt ? { revoked_at: token.revokedAt.toISOString() } : {},
+    ...token.resourceDeletedAt ? { resource_deleted_at: token.resourceDeletedAt.toISOString() } : {},
+    ...token.lastConnectedAt ? { last_connected_at: token.lastConnectedAt.toISOString() } : {}
+  };
+}
+function streamTokenMintOutput(result) {
+  return {
+    ...streamTokenSummary(result),
+    url: result.url,
+    note: "Treat this URL as a password: anyone who has it can read this project's events until it expires, with no further authentication. Pass it straight to a WebSocket client and do NOT write it to a file, a commit, an issue or a chat reply, and do not log or repeat it. It is shown once and cannot be retrieved again. If it may have been exposed, call revoke_stream_token with the id above. Open it with subprotocol 'v1'; each text frame is one JSON event, and reconnecting with ?after=<seq> resumes from the last frame you saw."
+  };
+}
+
+// src/server/tools/create_stream_token.ts
+var inputSchema32 = {
+  resource_type: z34.enum(["project"]).default("project").describe("What to follow. Only 'project' is supported today."),
+  resource_id: z34.string().min(1).describe("UUID of the project to stream events for."),
+  event_types: streamEventTypesSchema,
+  ttl_seconds: z34.number().int().positive().optional().describe(
+    "How long the URL stays valid. Defaults to 24 hours, capped at 7 days. Out-of-range values are clamped rather than rejected \u2014 check expires_at in the result."
+  ),
+  label: z34.string().optional().describe("Short human-readable label, so a person can recognise this token in a listing.")
+};
+var createStreamTokenTool = {
+  name: "create_stream_token",
+  description: "Create a short-lived WebSocket URL that streams a project's events in real time \u2014 like an S3 presigned URL, the returned URL is the whole credential and needs no auth header. Choose the project and the event types to follow; the result carries the full wss:// URL. Feed it to any WebSocket client with subprotocol 'v1' (for example Claude Code's Monitor tool). Each text frame is one JSON event carrying a `seq` cursor; reconnect with ?after=<seq> to resume without missing events. Defaults to 24 hours, 7 days maximum. TREAT THE RETURNED URL LIKE A PASSWORD: anyone holding it can read every event on this project until it expires, without authenticating. Pass it directly to the WebSocket client; never write it to a file, a commit, an issue or a chat reply, and never log or repeat it. It is shown once and cannot be retrieved again. If it may have been exposed, revoke it at once with revoke_stream_token \u2014 that is also how you end one early. Prefer the shortest ttl_seconds that covers the work.",
+  inputSchema: inputSchema32,
+  handler: async (args, ctx) => {
+    const result = await ctx.client.createStreamToken({
+      resourceType: args.resource_type,
+      resourceId: args.resource_id,
+      eventTypes: args.event_types,
+      ttlSeconds: args.ttl_seconds,
+      label: args.label
+    });
+    return jsonResult(streamTokenMintOutput(result));
+  }
+};
+
+// src/server/tools/list_stream_tokens.ts
+import { z as z35 } from "zod";
+var LIST_DEFAULT5 = 50;
+var LIST_MAX5 = 200;
+var inputSchema33 = {
+  resource_id: z35.string().optional().describe("Only tokens following this project."),
+  live_only: z35.boolean().optional().describe("Hide expired and revoked tokens."),
+  mine_only: z35.boolean().optional().describe(
+    "Only tokens you created. Off by default, so a leaked URL can be found \u2014 note that revoking one you did not mint needs the organisation owner or admin role."
+  ),
+  limit: z35.number().int().positive().optional().describe(`Max tokens to return (default ${String(LIST_DEFAULT5)}, capped at ${String(LIST_MAX5)}).`),
+  offset: z35.number().int().nonnegative().optional().describe("Pagination offset (default 0).")
+};
+var listStreamTokensTool = {
+  name: "list_stream_tokens",
+  description: "List the stream tokens in your organisation, with their scope, expiry and whether each is still live. Secrets are never returned \u2014 only a short prefix to tell tokens apart. Returns `total` and, when more remain, `next_offset`.",
+  inputSchema: inputSchema33,
+  handler: async (args, ctx) => {
+    const limit = clampLimit(args.limit, LIST_DEFAULT5, LIST_MAX5);
+    const offset = args.offset ?? 0;
+    const page = await ctx.client.listStreamTokens({
+      resourceId: args.resource_id,
+      liveOnly: args.live_only,
+      mineOnly: args.mine_only,
+      limit,
+      offset
+    });
+    const next = nextOffsetOf(offset, page.tokens.length, page.total);
+    return jsonResult({
+      tokens: page.tokens.map(streamTokenSummary),
+      total: page.total,
+      limit,
+      offset,
+      ...next === void 0 ? {} : { next_offset: next }
+    });
+  }
+};
+
+// src/server/tools/revoke_stream_token.ts
+import { z as z36 } from "zod";
+var inputSchema34 = {
+  id: z36.string().min(1).describe("Token id (from create_stream_token or list_stream_tokens) \u2014 NOT the secret itself.")
+};
+var revokeStreamTokenTool = {
+  name: "revoke_stream_token",
+  description: "Revoke a stream token immediately, closing its URL and deleting the events buffered for it. Use this as soon as a stream is no longer needed, or if its URL may have leaked \u2014 the URL is the credential, so revoking is the only way to stop it before it expires. Revoking a token you minted yourself always works. Revoking one somebody ELSE minted additionally requires the organisation owner or admin role, and is refused with 403 otherwise \u2014 so when hunting a leaked URL you did not create, expect that refusal and ask an organisation owner or admin rather than retrying.",
+  inputSchema: inputSchema34,
+  handler: async (args, ctx) => {
+    const token = await ctx.client.revokeStreamToken(args.id);
+    return jsonResult({ ...streamTokenSummary(token), revoked: true });
+  }
+};
+
 // src/server/server.ts
 function buildServer(deps) {
   const server = new McpServer({
@@ -5223,6 +5574,9 @@ function buildServer(deps) {
   registerTool(server, createArtifactTool, deps.client);
   registerTool(server, writeArtifactRevisionTool, deps.client);
   registerTool(server, rollbackArtifactTool, deps.client);
+  registerTool(server, createStreamTokenTool, deps.client);
+  registerTool(server, listStreamTokensTool, deps.client);
+  registerTool(server, revokeStreamTokenTool, deps.client);
   return server;
 }
 async function startStdioServer(deps) {
@@ -5376,7 +5730,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 z33 } from "zod";
+import { z as z37 } from "zod";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // src/reverse/ignore.ts
@@ -5681,37 +6035,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 = z33.object({
-  path: z33.string(),
-  recursive: z33.boolean().optional(),
-  maxEntries: z33.number().int().positive().optional(),
-  includeIgnored: z33.boolean().optional()
+var listDirInput = z37.object({
+  path: z37.string(),
+  recursive: z37.boolean().optional(),
+  maxEntries: z37.number().int().positive().optional(),
+  includeIgnored: z37.boolean().optional()
 });
-var readFileInput = z33.object({
-  path: z33.string(),
-  offset: z33.number().int().nonnegative().optional(),
-  limit: z33.number().int().positive().optional(),
-  includeIgnored: z33.boolean().optional()
+var readFileInput = z37.object({
+  path: z37.string(),
+  offset: z37.number().int().nonnegative().optional(),
+  limit: z37.number().int().positive().optional(),
+  includeIgnored: z37.boolean().optional()
 });
-var grepInput = z33.object({
-  pattern: z33.string().describe(
+var grepInput = z37.object({
+  pattern: z37.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: z33.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
-  isRegex: z33.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
-  caseSensitive: z33.boolean().optional(),
-  maxMatches: z33.number().int().positive().optional(),
-  contextLines: z33.number().int().nonnegative().optional(),
-  includeIgnored: z33.boolean().optional()
+  path: z37.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
+  isRegex: z37.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
+  caseSensitive: z37.boolean().optional(),
+  maxMatches: z37.number().int().positive().optional(),
+  contextLines: z37.number().int().nonnegative().optional(),
+  includeIgnored: z37.boolean().optional()
 });
-var packCodebaseInput = z33.object({
-  subpath: z33.string().optional(),
-  includePatterns: z33.string().optional(),
-  ignorePatterns: z33.string().optional()
+var packCodebaseInput = z37.object({
+  subpath: z37.string().optional(),
+  includePatterns: z37.string().optional(),
+  ignorePatterns: z37.string().optional()
 });
-var packCodebaseReadPageInput = z33.object({
-  outputId: z33.string(),
-  page: z33.number().int().positive()
+var packCodebaseReadPageInput = z37.object({
+  outputId: z37.string(),
+  page: z37.number().int().positive()
 });
 function structuredError(error, message, extra) {
   const payload = { error, message, ...extra ?? {} };
@@ -6239,7 +6593,7 @@ function jsonSchemaFromZod(schema) {
   return zodToJson(schema);
 }
 function zodToJson(schema) {
-  if (schema instanceof z33.ZodObject) {
+  if (schema instanceof z37.ZodObject) {
     const shape = schema.shape;
     const properties = {};
     const required = [];
@@ -6254,19 +6608,19 @@ function zodToJson(schema) {
     if (required.length > 0) out.required = required;
     return out;
   }
-  if (schema instanceof z33.ZodOptional) {
+  if (schema instanceof z37.ZodOptional) {
     return zodToJson(schema.unwrap());
   }
-  if (schema instanceof z33.ZodString) {
+  if (schema instanceof z37.ZodString) {
     return { type: "string" };
   }
-  if (schema instanceof z33.ZodNumber) {
+  if (schema instanceof z37.ZodNumber) {
     return { type: "number" };
   }
-  if (schema instanceof z33.ZodBoolean) {
+  if (schema instanceof z37.ZodBoolean) {
     return { type: "boolean" };
   }
-  if (schema instanceof z33.ZodEnum) {
+  if (schema instanceof z37.ZodEnum) {
     return { type: "string", enum: schema.options };
   }
   return { type: "string" };

package/package.json

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