@myspec/mcp-server 0.5.0-next.116 → 0.5.0-next.118

package/README.md

@@ -313,6 +313,13 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 | `create_artifact` | `project_id`, `name`, `files[]` (`path`, `content`, optional `encoding` utf8/base64, optional `content_type`), optional `slug`, `description`, `entry_path`, `message` | Creates the artifact with revision 1. Limits: 50 files, 2 MiB per file, 10 MiB per revision. A taken slug is a conflict |
 | `write_artifact_revision` | `artifact_id`, `files[]`, optional `base_revision` (patch mode), `remove[]`, `expected_version`, `message`, `entry_path` | Appends an immutable revision. Full mode replaces the whole bundle; patch mode (with `base_revision`) sends only changed files plus paths to `remove`. A stale `expected_version` is reported as a conflict naming the new head — re-read with `get_artifact` and retry |
 | `rollback_artifact` | `artifact_id`, `revision_number`, optional `expected_version`, `message` | Restores an earlier revision by APPENDING a revision with its files (`git revert` semantics); history is never rewritten, but only the newest N revisions are retained (50 by default, `ARTIFACT_MAX_REVISIONS` on the platform), so a pruned target answers not found |
+| `list_spec_file_comments` | `file_id`, optional `status` (`open`/`resolved`/`orphaned`) | Lists the review comment threads on a spec file. Each thread carries `anchor_quote`, `anchor_status` (`anchored`, or `orphaned` when the passage can no longer be located), `anchor_start`/`anchor_end`, `resolved`, and its `comments` — each with `content_version`, the token `update_spec_file_comment` takes as `expected_version`. A tombstoned first comment is returned with `deleted: true` and no `body`. Works on a trashed file |
+| `create_spec_file_comment_thread` | `file_id`, `body`, `anchor_quote`, optional `anchor_prefix`, `anchor_suffix` | Opens a review comment on a passage. Quote the passage verbatim — the server searches the current content for it and derives the character offsets itself, so do NOT send them. `anchor_prefix`/`anchor_suffix` are the surrounding text, which disambiguates a passage appearing more than once. Conflicts on a trashed file: a file staged for deletion does not gather new discussion |
+| `reply_spec_file_comment_thread` | `file_id`, `thread_id`, `body` | Replies to an existing thread. Conflicts on a trashed file |
+| `update_spec_file_comment` | `file_id`, `comment_id`, `body`, optional `expected_version` | Edits the body of one of YOUR OWN comments; the platform refuses somebody else's. `expected_version` is the **comment's** own `content_version`, not the file's — pairing it with the file would fail an edit because somebody saved the document. Works on a trashed file |
+| `delete_spec_file_comment` | `file_id`, `comment_id` | Soft-deletes one of YOUR OWN comments. Three outcomes, reported in the result: a reply disappears (`comment: null`); a first comment with live replies becomes a tombstone so the thread keeps a head (`comment` is the tombstone); a first comment with no live replies takes the whole thread (`thread_deleted: true`) |
+
+There is deliberately **no tool to resolve, unresolve or re-anchor a thread**. Those three are human-only: resolving declares a review finished, and re-anchoring is the repair a person makes after the automatic pass has already failed to locate the passage. The platform refuses them for an AI caller with a 403, so a tool would only ever return an error.
 
 ### Brownfield sessions: start the bridge first
 

package/dist/index.js

@@ -1353,7 +1353,11 @@ var KNOWN_CONFLICT_REASONS = [
   "precondition_malformed",
   "slug_taken",
   "blob_reclaimed",
-  "lock_timeout"
+  "lock_timeout",
+  "content_moved",
+  "file_trashed",
+  "thread_not_orphaned",
+  "version_conflict"
 ];
 var PlatformHttpError = class extends Error {
   status;
@@ -1425,6 +1429,9 @@ function conflictOf(err) {
     own || fromMessage ? { ...fromMessage ?? {}, ...own ?? {} } : void 0
   );
 }
+function isPlatformConflictError(err) {
+  return conflictOf(err) !== void 0;
+}
 function isPlatformPreconditionRequiredError(err) {
   return isPlatformHttpError(err) && err.status === 428;
 }
@@ -1855,6 +1862,113 @@ function transformSpecSessionResponse(raw) {
 // ../../packages/platform-client/project/types/lock.types.ts
 var SPEC_FILE_LOCK_TTL_MS = 2 * 6e4;
 
+// ../../packages/platform-client/project/types/comment.types.ts
+var COMMENT_THREAD_FILTER_PARAM = "status";
+var MAX_COMMENT_BODY_LENGTH = 1e4;
+var MAX_ANCHOR_QUOTE_LENGTH = 2e3;
+var MAX_ANCHOR_CONTEXT_LENGTH = 64;
+function parseTimestamp(raw) {
+  if (!raw) {
+    return null;
+  }
+  const parsed = new Date(raw);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+function toCommentActorKind(raw) {
+  return raw === "ai" ? "ai" : "human";
+}
+function toAnchorStatus(raw) {
+  return raw === "anchored" ? "anchored" : "orphaned";
+}
+function toCreateCommentThreadRequest(input) {
+  return {
+    body: input.body,
+    anchor_quote: input.anchorQuote,
+    anchor_prefix: input.anchorPrefix,
+    anchor_suffix: input.anchorSuffix
+  };
+}
+function toCreateCommentReplyRequest(body) {
+  return { body };
+}
+function toUpdateCommentRequest(body) {
+  return { body };
+}
+function toReanchorCommentThreadRequest(anchor) {
+  return {
+    anchor_quote: anchor.anchorQuote,
+    anchor_prefix: anchor.anchorPrefix,
+    anchor_suffix: anchor.anchorSuffix
+  };
+}
+function transformSpecFileCommentResponse(raw) {
+  return {
+    id: raw.id,
+    threadId: raw.thread_id,
+    org: raw.org,
+    authorId: raw.author_id,
+    authorKind: toCommentActorKind(raw.author_kind),
+    body: raw.body,
+    deleted: raw.deleted,
+    contentVersion: raw.content_version,
+    createdAt: parseTimestamp(raw.created_at),
+    updatedAt: parseTimestamp(raw.updated_at),
+    deletedAt: parseTimestamp(raw.deleted_at)
+  };
+}
+function transformSpecFileCommentThreadResponse(raw) {
+  return {
+    id: raw.id,
+    specFileId: raw.spec_file_id,
+    projectId: raw.project_id,
+    org: raw.org,
+    rootCommentId: raw.root_comment_id ?? null,
+    anchorContentVersion: raw.anchor_content_version,
+    anchorRevision: raw.anchor_revision,
+    anchorStart: raw.anchor_start,
+    anchorEnd: raw.anchor_end,
+    anchorQuote: raw.anchor_quote,
+    anchorPrefix: raw.anchor_prefix,
+    anchorSuffix: raw.anchor_suffix,
+    anchorStatus: toAnchorStatus(raw.anchor_status),
+    createdBy: raw.created_by,
+    createdByKind: toCommentActorKind(raw.created_by_kind),
+    resolvedAt: parseTimestamp(raw.resolved_at),
+    resolvedBy: raw.resolved_by ?? null,
+    createdAt: parseTimestamp(raw.created_at),
+    updatedAt: parseTimestamp(raw.updated_at),
+    // Always an array: consumers map over it on every render, so the empty case
+    // must not be a value each one has to guard.
+    comments: (raw.comments ?? []).map(transformSpecFileCommentResponse)
+  };
+}
+function transformSpecFileCommentCountResponse(raw) {
+  return {
+    specFileId: raw.spec_file_id,
+    openThreadCount: raw.open_thread_count
+  };
+}
+function transformSpecFileCommentThreadList(raw) {
+  return (raw.threads ?? []).map(transformSpecFileCommentThreadResponse);
+}
+function transformProjectCommentCounts(raw) {
+  return (raw.counts ?? []).map(transformSpecFileCommentCountResponse);
+}
+function transformProjectCommentActivity(raw) {
+  return {
+    threads: (raw.threads ?? []).map(transformSpecFileCommentThreadResponse),
+    total: raw.total,
+    limit: raw.limit,
+    offset: raw.offset
+  };
+}
+function transformDeleteCommentResult(raw) {
+  return {
+    comment: raw.comment ? transformSpecFileCommentResponse(raw.comment) : null,
+    threadDeleted: raw.thread_deleted
+  };
+}
+
 // ../../packages/platform-client/project/http/attachment.http-client.ts
 var UPLOAD_TIMEOUT_MS = 3e4;
 var HttpAttachmentClient = class {
@@ -2440,6 +2554,137 @@ var HttpSpecSessionClient = class {
   }
 };
 
+// ../../packages/platform-client/project/http/comment.http-client.ts
+var HEADER_EXPECTED_VERSION2 = "X-Expected-Version";
+var HEADER_ACTOR_KIND2 = "X-Actor-Kind";
+function segment(value) {
+  return encodeURIComponent(value);
+}
+var HttpSpecFileCommentClient = class {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /**
+   * Turns the shared write options into request headers.
+   *
+   * Both halves are forwarded EXACTLY as given and neither is defaulted. That
+   * matters most for what this does NOT do: it never substitutes
+   * `actorKind: 'human'` for an absent value. Resolve, unresolve and re-anchor
+   * are human-only and the platform parses the header fail-closed (AR-PRJ-26),
+   * so a client-side default would turn a 403 the caller should see into a
+   * successful write attributed to a person who never acted.
+   */
+  writeHeaders(opts) {
+    const headers = {};
+    if (opts?.expectedVersion !== void 0) {
+      headers[HEADER_EXPECTED_VERSION2] = String(opts.expectedVersion);
+    }
+    if (opts?.actorKind) {
+      headers[HEADER_ACTOR_KIND2] = opts.actorKind;
+    }
+    return headers;
+  }
+  async listThreads(fileId, jwtToken, opts) {
+    const query = new URLSearchParams();
+    if (opts?.filter) {
+      query.set(COMMENT_THREAD_FILTER_PARAM, opts.filter);
+    }
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+    const raw = await this.httpClient.get(
+      `/project/v1/files/${segment(fileId)}/comments${suffix}`,
+      jwtToken,
+      {}
+    );
+    return transformSpecFileCommentThreadList(raw);
+  }
+  async createThread(fileId, input, jwtToken, opts) {
+    const raw = await this.httpClient.post(
+      `/project/v1/files/${segment(fileId)}/comments`,
+      toCreateCommentThreadRequest(input),
+      jwtToken,
+      { headers: this.writeHeaders(opts) }
+    );
+    return transformSpecFileCommentThreadResponse(raw);
+  }
+  async replyToThread(fileId, threadId, body, jwtToken, opts) {
+    const raw = await this.httpClient.post(
+      `/project/v1/files/${segment(fileId)}/comments/${segment(threadId)}/replies`,
+      toCreateCommentReplyRequest(body),
+      jwtToken,
+      { headers: this.writeHeaders(opts) }
+    );
+    return transformSpecFileCommentResponse(raw);
+  }
+  async editComment(fileId, commentId, body, jwtToken, opts) {
+    const raw = await this.httpClient.patch(
+      `/project/v1/files/${segment(fileId)}/comments/${segment(commentId)}`,
+      toUpdateCommentRequest(body),
+      jwtToken,
+      { headers: this.writeHeaders(opts) }
+    );
+    return transformSpecFileCommentResponse(raw);
+  }
+  async deleteComment(fileId, commentId, jwtToken, opts) {
+    const raw = await this.httpClient.delete(
+      `/project/v1/files/${segment(fileId)}/comments/${segment(commentId)}`,
+      jwtToken,
+      { headers: this.writeHeaders(opts) }
+    );
+    return transformDeleteCommentResult(raw);
+  }
+  async resolveThread(fileId, threadId, jwtToken, opts) {
+    const raw = await this.httpClient.put(
+      `/project/v1/files/${segment(fileId)}/comments/${segment(threadId)}/resolve`,
+      {},
+      jwtToken,
+      { headers: this.writeHeaders(opts) }
+    );
+    return transformSpecFileCommentThreadResponse(raw);
+  }
+  async unresolveThread(fileId, threadId, jwtToken, opts) {
+    const raw = await this.httpClient.delete(
+      `/project/v1/files/${segment(fileId)}/comments/${segment(threadId)}/resolve`,
+      jwtToken,
+      { headers: this.writeHeaders(opts) }
+    );
+    return transformSpecFileCommentThreadResponse(raw);
+  }
+  async reanchorThread(fileId, threadId, anchor, jwtToken, opts) {
+    const raw = await this.httpClient.post(
+      `/project/v1/files/${segment(fileId)}/comments/${segment(threadId)}/reanchor`,
+      toReanchorCommentThreadRequest(anchor),
+      jwtToken,
+      { headers: this.writeHeaders(opts) }
+    );
+    return transformSpecFileCommentThreadResponse(raw);
+  }
+  async getProjectCommentCounts(projectId, jwtToken) {
+    const raw = await this.httpClient.get(
+      `/project/v1/projects/${segment(projectId)}/comment-counts`,
+      jwtToken,
+      {}
+    );
+    return transformProjectCommentCounts(raw);
+  }
+  async listProjectCommentActivity(projectId, jwtToken, opts) {
+    const query = new URLSearchParams();
+    if (opts?.limit !== void 0) {
+      query.set("limit", String(opts.limit));
+    }
+    if (opts?.offset !== void 0) {
+      query.set("offset", String(opts.offset));
+    }
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+    const raw = await this.httpClient.get(
+      `/project/v1/projects/${segment(projectId)}/comments${suffix}`,
+      jwtToken,
+      {}
+    );
+    return transformProjectCommentActivity(raw);
+  }
+};
+
 // ../../packages/platform-client/artifact/types/artifact.types.ts
 function transformArtifactResponse(raw) {
   return {
@@ -2570,15 +2815,15 @@ function buildUpdateArtifactBody(request) {
 
 // ../../packages/platform-client/artifact/http/artifact.http-client.ts
 var BASE_PATH = "/artifact/v1";
-var HEADER_EXPECTED_VERSION2 = "X-Expected-Version";
-var HEADER_ACTOR_KIND2 = "X-Actor-Kind";
+var HEADER_EXPECTED_VERSION3 = "X-Expected-Version";
+var HEADER_ACTOR_KIND3 = "X-Actor-Kind";
 function writeHeaders(opts) {
   const headers = {};
   if (opts?.expectedVersion !== void 0) {
-    headers[HEADER_EXPECTED_VERSION2] = String(opts.expectedVersion);
+    headers[HEADER_EXPECTED_VERSION3] = String(opts.expectedVersion);
   }
   if (opts?.actorKind) {
-    headers[HEADER_ACTOR_KIND2] = opts.actorKind;
+    headers[HEADER_ACTOR_KIND3] = opts.actorKind;
   }
   return headers;
 }
@@ -3155,7 +3400,8 @@ var PlatformClient = class {
       file: new HttpFileClient(httpClient),
       attachment: new HttpAttachmentClient(httpClient),
       artifact: new HttpArtifactClient(httpClient),
-      streamToken: new HttpStreamTokenClient(httpClient)
+      streamToken: new HttpStreamTokenClient(httpClient),
+      comment: new HttpSpecFileCommentClient(httpClient)
     };
   }
   // ------------------------------------------------------- stream tokens
@@ -3205,6 +3451,60 @@ var PlatformClient = class {
       (jwt, c) => c.artifact.rollback(artifactId, request, jwt, { expectedVersion, actorKind: "ai" })
     );
   }
+  // ------------------------------------------------------------- comments
+  //
+  // Review discussion on a spec file. Every WRITE below carries
+  // `actorKind: 'ai'` (AR-MCP-3): an MCP client is an assistant acting on the
+  // user's behalf, and it writes under the USER'S OWN JWT, so the header is the
+  // only thing that can tell a person's comment from a model's. Omitting it
+  // would not fail -- the platform's permissive parse on these paths defaults
+  // to `human` -- it would just file the comment under the user's name.
+  //
+  // There is deliberately no resolve, unresolve or re-anchor method here, and
+  // no tool for one (AR-MCP-2). The platform refuses `ai` on those three routes
+  // with a 403, so a method would only ever produce an error the model then has
+  // to interpret.
+  /** Lists a spec file's comment threads, optionally filtered by status. */
+  async listSpecFileComments(fileId, opts = {}) {
+    return this.withTokenRetry(
+      (jwt, c) => c.comment.listThreads(fileId, jwt, opts.filter ? { filter: opts.filter } : {})
+    );
+  }
+  /** Opens a thread on a passage. The server locates the quote and derives the offsets. */
+  async createSpecFileCommentThread(fileId, input) {
+    return this.withTokenRetry(
+      (jwt, c) => c.comment.createThread(fileId, input, jwt, { actorKind: "ai" })
+    );
+  }
+  /** Replies to an existing thread. */
+  async replyToSpecFileCommentThread(fileId, threadId, body) {
+    return this.withTokenRetry(
+      (jwt, c) => c.comment.replyToThread(fileId, threadId, body, jwt, { actorKind: "ai" })
+    );
+  }
+  /**
+   * Edits one of the caller's own comments.
+   *
+   * `expectedVersion` is the COMMENT's own contentVersion, not the file's:
+   * pairing it with the file would make an edit fail because somebody saved the
+   * document, which has nothing to do with whether this comment moved. Only the
+   * caller's own value is sent -- substituting one read a moment ago would
+   * guard nothing, exactly as in saveSpecFileRevision.
+   */
+  async updateSpecFileComment(fileId, commentId, body, opts = {}) {
+    return this.withTokenRetry(
+      (jwt, c) => c.comment.editComment(fileId, commentId, body, jwt, {
+        ...opts.expectedVersion === void 0 ? {} : { expectedVersion: opts.expectedVersion },
+        actorKind: "ai"
+      })
+    );
+  }
+  /** Soft-deletes one of the caller's own comments. */
+  async deleteSpecFileComment(fileId, commentId) {
+    return this.withTokenRetry(
+      (jwt, c) => c.comment.deleteComment(fileId, commentId, jwt, { actorKind: "ai" })
+    );
+  }
   async withTokenRetry(call) {
     const clients = await this.clients();
     const jwt = await this.tokenManager.getValidAccessToken();
@@ -4790,11 +5090,245 @@ function conflictMessage(filePath, conflict) {
   return `${filePath} was NOT updated: ${who} changed it${when} since you read it.${rev} Their version was kept \u2014 nothing of theirs was overwritten. Re-read the file with get_spec_file (or read_spec_file), decide how your change should combine with theirs, then update again passing the content_version that re-read returns as expected_version.${version} Do not simply resend the same content \u2014 you would undo their work.`;
 }
 
+// src/server/tools/spec_file_comments.ts
+import { z as z24 } from "zod";
+var LIST_BODY_PREVIEW_CHARS = 1e3;
+var LIST_MAX_THREADS = 100;
+function commentSummary(comment, opts = {}) {
+  const body = comment.body;
+  const truncated = opts.preview === true && body !== void 0 && body.length > LIST_BODY_PREVIEW_CHARS;
+  return {
+    comment_id: comment.id,
+    thread_id: comment.threadId,
+    author_id: comment.authorId,
+    author_kind: comment.authorKind,
+    // Absent for a tombstone: a soft-deleted root kept so the thread still has
+    // a head to render. `deleted` is the flag to branch on, not a missing body.
+    body: truncated ? body.slice(0, LIST_BODY_PREVIEW_CHARS) : body,
+    // Only ever present and true, so a caller can test it without knowing which
+    // shape produced the comment.
+    ...truncated ? { body_truncated: true } : {},
+    deleted: comment.deleted,
+    content_version: comment.contentVersion,
+    created_at: comment.createdAt?.toISOString(),
+    updated_at: comment.updatedAt?.toISOString()
+  };
+}
+function threadSummary(thread, opts = {}) {
+  return {
+    thread_id: thread.id,
+    spec_file_id: thread.specFileId,
+    root_comment_id: thread.rootCommentId,
+    anchor_quote: thread.anchorQuote,
+    // 'anchored' or 'orphaned'. An orphan's passage can no longer be located,
+    // and only a person can repair it — there is no tool here that can.
+    anchor_status: thread.anchorStatus,
+    anchor_start: thread.anchorStart,
+    anchor_end: thread.anchorEnd,
+    // Display only: revision_count is reusable and decrements on revert.
+    anchor_revision: thread.anchorRevision,
+    resolved: thread.resolvedAt !== null,
+    resolved_by: thread.resolvedBy,
+    resolved_at: thread.resolvedAt?.toISOString(),
+    created_by: thread.createdBy,
+    created_by_kind: thread.createdByKind,
+    created_at: thread.createdAt?.toISOString(),
+    comments: thread.comments.map((c) => commentSummary(c, opts))
+  };
+}
+function uuidField(what) {
+  return z24.uuid().describe(what);
+}
+var CONFLICT_REASON = {
+  fileTrashed: "file_trashed",
+  lockTimeout: "lock_timeout",
+  contentMoved: "content_moved",
+  threadNotOrphaned: "thread_not_orphaned",
+  versionConflict: "version_conflict"
+};
+function conflictAdvice(err, parts) {
+  const reason = conflictOf(err)?.reason;
+  switch (reason) {
+    case CONFLICT_REASON.lockTimeout:
+      return "Nothing was written: another write held the file briefly and this one timed out waiting. Retry the same call unchanged.";
+    case CONFLICT_REASON.contentMoved:
+      return "Nothing was written: the file changed while the passage was being located, so the anchor would have pointed at text that is no longer current. Re-read the file, find the passage again, and retry.";
+    case CONFLICT_REASON.fileTrashed:
+      return parts.whenTrashed;
+    default:
+      return parts.otherwise;
+  }
+}
+var listInputSchema = {
+  file_id: uuidField("UUID of the spec file whose comments to list."),
+  status: z24.enum(["open", "resolved", "orphaned"]).optional().describe(
+    "Narrow to open (unresolved) threads, resolved ones, or orphaned ones whose passage can no longer be located. Omit for all of them."
+  )
+};
+var listSpecFileCommentsTool = {
+  name: "list_spec_file_comments",
+  description: "List the review comment threads on a spec file. Each thread carries the passage it is anchored to, whether it is resolved, its anchor status, and its comments. Works on a trashed file as well as a live one. Read this before editing a file under review. Returns at most 100 threads (with total_threads and truncated) and previews each comment body to 1000 characters, flagging it with body_truncated; narrow with `status` to see fewer threads in full.",
+  inputSchema: listInputSchema,
+  handler: async (args, ctx) => {
+    const threads = await ctx.client.listSpecFileComments(args.file_id, {
+      ...args.status ? { filter: args.status } : {}
+    });
+    const page = threads.slice(0, LIST_MAX_THREADS);
+    return jsonResult({
+      threads: page.map((t) => threadSummary(t, { preview: true })),
+      total_threads: threads.length,
+      // Only when something was actually withheld, so its absence means "you
+      // have all of it" rather than "nobody thought about it".
+      ...threads.length > page.length ? { truncated: true } : {}
+    });
+  }
+};
+var createInputSchema = {
+  file_id: uuidField("UUID of the spec file to comment on."),
+  body: z24.string().min(1).max(MAX_COMMENT_BODY_LENGTH).describe("The comment text, in markdown."),
+  // The three anchor limits are exported by the contract for exactly this, and
+  // the context one is SHORT (64). A description reading "the text immediately
+  // BEFORE the quote" invites a whole preceding sentence, which is the default
+  // reading rather than a corner case — so the ceiling is enforced in the
+  // schema, where the model sees it, rather than discovered as a 400.
+  anchor_quote: z24.string().min(1).max(MAX_ANCHOR_QUOTE_LENGTH).describe(
+    `The exact passage this comment is about, copied verbatim from the file. The server searches the current content for it, so it must match the text as written. Read the file with read_spec_file first. At most ${String(MAX_ANCHOR_QUOTE_LENGTH)} characters.`
+  ),
+  anchor_prefix: z24.string().max(MAX_ANCHOR_CONTEXT_LENGTH).optional().describe(
+    `The text immediately BEFORE the quote, which disambiguates a passage appearing more than once. At most ${String(MAX_ANCHOR_CONTEXT_LENGTH)} characters \u2014 a few words, not a sentence. Send an empty string when the quote starts the file.`
+  ),
+  anchor_suffix: z24.string().max(MAX_ANCHOR_CONTEXT_LENGTH).optional().describe(
+    `The text immediately AFTER the quote. At most ${String(MAX_ANCHOR_CONTEXT_LENGTH)} characters. Empty when the quote ends the file.`
+  )
+};
+var createSpecFileCommentThreadTool = {
+  name: "create_spec_file_comment_thread",
+  description: "Open a review comment on a specific passage of a spec file. Quote the passage exactly as it appears. Do NOT send character offsets \u2014 the server locates the quote itself. Refused with a conflict on a trashed file: a file staged for deletion does not gather new discussion.",
+  inputSchema: createInputSchema,
+  handler: async (args, ctx) => {
+    try {
+      const thread = await ctx.client.createSpecFileCommentThread(args.file_id, {
+        body: args.body,
+        anchorQuote: args.anchor_quote,
+        // Always sent, even empty: an omitted key is indistinguishable from a
+        // client that does not know about the field.
+        anchorPrefix: args.anchor_prefix ?? "",
+        anchorSuffix: args.anchor_suffix ?? ""
+      });
+      return jsonResult({ thread: threadSummary(thread) });
+    } catch (err) {
+      if (isPlatformConflictError(err)) {
+        return errorResult(
+          `No thread was created on ${args.file_id}. ` + conflictAdvice(err, {
+            // CONFIRMED trashed: the platform said so, so this states it.
+            whenTrashed: "The file is in the Trash Bin, so it gathers no new discussion. Restore it with restore_spec_file_from_trash first.",
+            // NOT confirmed — an older platform, or a reason this build does
+            // not know. Worded as a hypothesis with a way to check it, which
+            // is also what keeps the two branches distinguishable in a test:
+            // asserting the trashed wording alone would pass against this one
+            // too, so deleting the branch above would go unnoticed.
+            otherwise: "The write was refused as a conflict, and the platform gave no reason. The usual cause is a trashed file \u2014 confirm with get_spec_file before doing anything else."
+          })
+        );
+      }
+      throw err;
+    }
+  }
+};
+var replyInputSchema = {
+  file_id: uuidField("UUID of the spec file the thread belongs to."),
+  thread_id: uuidField("UUID of the thread to reply to, from list_spec_file_comments."),
+  body: z24.string().min(1).max(MAX_COMMENT_BODY_LENGTH).describe("The reply text, in markdown.")
+};
+var replySpecFileCommentThreadTool = {
+  name: "reply_spec_file_comment_thread",
+  description: "Reply to an existing review comment thread on a spec file. Use this to answer a reviewer's question or report what you changed. Refused with a conflict on a trashed file.",
+  inputSchema: replyInputSchema,
+  handler: async (args, ctx) => {
+    try {
+      const comment = await ctx.client.replyToSpecFileCommentThread(
+        args.file_id,
+        args.thread_id,
+        args.body
+      );
+      return jsonResult({ comment: commentSummary(comment) });
+    } catch (err) {
+      if (isPlatformConflictError(err)) {
+        return errorResult(
+          `No reply was posted to ${args.thread_id}. ` + conflictAdvice(err, {
+            whenTrashed: "The file is in the Trash Bin, so it gathers no new discussion. Restore it with restore_spec_file_from_trash first.",
+            otherwise: "The reply was refused as a conflict, and the platform gave no reason. The usual cause is a trashed file \u2014 confirm with get_spec_file before doing anything else."
+          })
+        );
+      }
+      throw err;
+    }
+  }
+};
+var updateInputSchema = {
+  file_id: uuidField("UUID of the spec file the comment belongs to."),
+  comment_id: uuidField("UUID of the comment to edit. Must be your own."),
+  body: z24.string().min(1).max(MAX_COMMENT_BODY_LENGTH).describe("The replacement text, in markdown. Replaces the comment entirely."),
+  expected_version: z24.number().int().nonnegative().optional().describe(
+    "The COMMENT's own content_version as last read by list_spec_file_comments \u2014 not the file's. Sending it makes the edit fail rather than silently overwrite one made since."
+  )
+};
+var updateSpecFileCommentTool = {
+  name: "update_spec_file_comment",
+  description: "Edit the body of one of YOUR OWN comments on a spec file. The platform refuses a comment written by somebody else. Pass the comment's own content_version as expected_version to avoid overwriting an edit made since you read it. Works on a trashed file.",
+  inputSchema: updateInputSchema,
+  handler: async (args, ctx) => {
+    try {
+      const comment = await ctx.client.updateSpecFileComment(
+        args.file_id,
+        args.comment_id,
+        args.body,
+        {
+          // Only the caller's own value is sent. Substituting a version read a
+          // moment ago would guard nothing — it cannot detect an edit made before
+          // that read, which is the edit that matters.
+          ...args.expected_version === void 0 ? {} : { expectedVersion: args.expected_version }
+        }
+      );
+      return jsonResult({ comment: commentSummary(comment) });
+    } catch (err) {
+      if (isPlatformConflictError(err)) {
+        return errorResult(
+          `${args.comment_id} was NOT edited. ` + conflictAdvice(err, {
+            // An edit is allowed on a trashed file (AR-PRJ-45), so the
+            // trashed reason cannot reach this route — both branches below
+            // describe the version race, which is the only conflict it emits.
+            whenTrashed: "It has changed since the version you passed. Re-read it with list_spec_file_comments, re-apply your change, and retry with the new content_version.",
+            otherwise: "It has changed since the version you passed. Re-read it with list_spec_file_comments, re-apply your change, and retry with the new content_version."
+          })
+        );
+      }
+      throw err;
+    }
+  }
+};
+var deleteInputSchema = {
+  file_id: uuidField("UUID of the spec file the comment belongs to."),
+  comment_id: uuidField("UUID of the comment to delete. Must be your own.")
+};
+var deleteSpecFileCommentTool = {
+  name: "delete_spec_file_comment",
+  description: "Soft-delete one of YOUR OWN comments on a spec file. Three outcomes, reported in the result: a reply simply disappears (comment: null); a first comment with live replies becomes a tombstone so the thread keeps a head (comment: the tombstone); and a first comment with no live replies takes the whole thread (thread_deleted: true).",
+  inputSchema: deleteInputSchema,
+  handler: async (args, ctx) => {
+    const result = await ctx.client.deleteSpecFileComment(args.file_id, args.comment_id);
+    return jsonResult({
+      comment: result.comment ? commentSummary(result.comment) : null,
+      thread_deleted: result.threadDeleted
+    });
+  }
+};
+
 // src/server/tools/upload_attachment.ts
 import { createHash as createHash3 } from "crypto";
 import { lstat, readFile as readFile2 } from "fs/promises";
 import { basename, extname, isAbsolute as isAbsolute2 } from "path";
-import { z as z24 } from "zod";
+import { z as z25 } from "zod";
 var DEFAULT_MIME = "application/octet-stream";
 var MAX_ATTACHMENT_MB2 = MAX_ATTACHMENT_BYTES / (1024 * 1024);
 var STRUCTURED_EXTENSION_MIME = {
@@ -4900,15 +5434,15 @@ function inferMimeFromName(name) {
   return DEFAULT_MIME;
 }
 var inputSchema24 = {
-  project_id: z24.string().min(1).describe("UUID of the project to attach the file to."),
-  file_path: z24.string().min(1).describe(
+  project_id: z25.string().min(1).describe("UUID of the project to attach the file to."),
+  file_path: z25.string().min(1).describe(
     "Absolute path to the local file to upload. The MCP server reads this path from its own host."
   ),
-  file_name: z24.string().min(1).optional().describe("Override the filename recorded on the attachment. Defaults to the path basename."),
-  mime_type: z24.string().min(1).optional().describe(
+  file_name: z25.string().min(1).optional().describe("Override the filename recorded on the attachment. Defaults to the path basename."),
+  mime_type: z25.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: z24.boolean().optional().describe(
+  override: z25.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)."
   )
 };
@@ -5039,7 +5573,7 @@ var uploadAttachmentTool = {
 };
 
 // src/server/tools/upload_spec_file.ts
-import { z as z25 } from "zod";
+import { z as z26 } from "zod";
 
 // src/server/spec-path.ts
 var MAX_SPEC_DIR_DEPTH = 3;
@@ -5096,17 +5630,17 @@ var SPEC_FILE_TYPES = [
   "openspec-spec"
 ];
 var inputSchema25 = {
-  project_id: z25.string().min(1).describe("UUID of the project to upload the file into."),
-  file_path: z25.string().min(1).describe(
+  project_id: z26.string().min(1).describe("UUID of the project to upload the file into."),
+  file_path: z26.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: z25.string().min(1).optional().describe(
+  content: z26.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: z25.string().min(1).optional().describe(
+  local_file_path: z26.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: z25.enum(SPEC_FILE_TYPES).optional().describe("Spec file type. Omit to derive from the filename (e.g. proposal.md \u2192 proposal).")
+  file_type: z26.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",
@@ -5142,16 +5676,16 @@ var uploadSpecFileTool = {
 };
 
 // src/server/tools/list_artifacts.ts
-import { z as z27 } from "zod";
+import { z as z28 } from "zod";
 
 // src/server/tools/artifact-output.ts
-import { z as z26 } from "zod";
-var artifactFilesSchema = z26.array(
-  z26.object({
-    path: z26.string().min(1).describe('Bundle-relative path, "/"-separated, no leading slash (e.g. assets/logo.svg).'),
-    content: z26.string().describe("The file content, in `encoding` (default utf8)."),
-    encoding: z26.enum(["utf8", "base64"]).optional().describe("utf8 (default) for text; base64 for binary files such as images."),
-    content_type: z26.string().optional().describe("Hint used only for extensions the platform does not recognise.")
+import { z as z27 } from "zod";
+var artifactFilesSchema = z27.array(
+  z27.object({
+    path: z27.string().min(1).describe('Bundle-relative path, "/"-separated, no leading slash (e.g. assets/logo.svg).'),
+    content: z27.string().describe("The file content, in `encoding` (default utf8)."),
+    encoding: z27.enum(["utf8", "base64"]).optional().describe("utf8 (default) for text; base64 for binary files such as images."),
+    content_type: z27.string().optional().describe("Hint used only for extensions the platform does not recognise.")
   })
 ).describe("Files of the bundle.");
 function artifactSummary(a) {
@@ -5224,9 +5758,9 @@ function artifactCreateConflictMessage(conflict) {
 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_DEFAULT4)}, capped at ${String(LIST_MAX4)}).`),
-  offset: z27.number().int().nonnegative().optional().describe("Pagination offset (default 0).")
+  project_id: z28.string().min(1).describe("UUID of the project whose artifacts to list."),
+  limit: z28.number().int().positive().optional().describe(`Max artifacts to return (default ${String(LIST_DEFAULT4)}, capped at ${String(LIST_MAX4)}).`),
+  offset: z28.number().int().nonnegative().optional().describe("Pagination offset (default 0).")
 };
 var listArtifactsTool = {
   name: "list_artifacts",
@@ -5249,10 +5783,10 @@ var listArtifactsTool = {
 };
 
 // src/server/tools/get_artifact.ts
-import { z as z28 } from "zod";
+import { z as z29 } from "zod";
 var inputSchema27 = {
-  artifact_id: z28.string().min(1).describe("UUID of the artifact."),
-  revision: z28.number().int().positive().optional().describe("Revision whose manifest to return (defaults to the head revision).")
+  artifact_id: z29.string().min(1).describe("UUID of the artifact."),
+  revision: z29.number().int().positive().optional().describe("Revision whose manifest to return (defaults to the head revision).")
 };
 var getArtifactTool = {
   name: "get_artifact",
@@ -5274,14 +5808,14 @@ var getArtifactTool = {
 };
 
 // src/server/tools/read_artifact_file.ts
-import { z as z29 } from "zod";
+import { z as z30 } from "zod";
 var MAX_READABLE_ARTIFACT_FILE_BYTES = 8 * 1024 * 1024;
 var inputSchema28 = {
-  artifact_id: z29.string().min(1).describe("UUID of the artifact."),
-  path: z29.string().min(1).describe("Bundle-relative path of the file (e.g. index.html, assets/app.js)."),
-  revision: z29.number().int().positive().optional().describe("Revision to read from (defaults to the head revision)."),
-  offset: z29.number().int().nonnegative().optional().describe("1-based line number to start reading from (default 1; 0 is an alias for 1)."),
-  limit: z29.number().int().positive().optional().describe("Max lines to return (default 2000, capped at 2000; larger values are clamped).")
+  artifact_id: z30.string().min(1).describe("UUID of the artifact."),
+  path: z30.string().min(1).describe("Bundle-relative path of the file (e.g. index.html, assets/app.js)."),
+  revision: z30.number().int().positive().optional().describe("Revision to read from (defaults to the head revision)."),
+  offset: z30.number().int().nonnegative().optional().describe("1-based line number to start reading from (default 1; 0 is an alias for 1)."),
+  limit: z30.number().int().positive().optional().describe("Max lines to return (default 2000, capped at 2000; larger values are clamped).")
 };
 var readArtifactFileTool = {
   name: "read_artifact_file",
@@ -5321,14 +5855,14 @@ var readArtifactFileTool = {
 };
 
 // src/server/tools/create_artifact.ts
-import { z as z30 } from "zod";
+import { z as z31 } from "zod";
 var inputSchema29 = {
-  project_id: z30.string().min(1).describe("UUID of the project to create the artifact in."),
-  name: z30.string().min(1).describe("Display name (max 200 characters)."),
-  slug: z30.string().optional().describe("URL-safe identifier, unique within the project; derived from the name when omitted."),
-  description: z30.string().optional().describe("Optional description (max 2000 characters)."),
-  entry_path: z30.string().optional().describe("The file a renderer opens first. Defaults to index.html when present, else the only file."),
-  message: z30.string().optional().describe("Short summary of this first revision (max 500 characters)."),
+  project_id: z31.string().min(1).describe("UUID of the project to create the artifact in."),
+  name: z31.string().min(1).describe("Display name (max 200 characters)."),
+  slug: z31.string().optional().describe("URL-safe identifier, unique within the project; derived from the name when omitted."),
+  description: z31.string().optional().describe("Optional description (max 2000 characters)."),
+  entry_path: z31.string().optional().describe("The file a renderer opens first. Defaults to index.html when present, else the only file."),
+  message: z31.string().optional().describe("Short summary of this first revision (max 500 characters)."),
   files: artifactFilesSchema
 };
 var createArtifactTool = {
@@ -5362,19 +5896,19 @@ var createArtifactTool = {
 };
 
 // src/server/tools/write_artifact_revision.ts
-import { z as z31 } from "zod";
+import { z as z32 } from "zod";
 var inputSchema30 = {
-  artifact_id: z31.string().min(1).describe("UUID of the artifact."),
+  artifact_id: z32.string().min(1).describe("UUID of the artifact."),
   files: artifactFilesSchema,
-  base_revision: z31.number().int().positive().optional().describe(
+  base_revision: z32.number().int().positive().optional().describe(
     "PATCH mode: start from this revision's files, upsert `files` by path and drop `remove` paths. Omit for FULL mode, where `files` is the complete new file set. Patch mode defaults expected_version to base_revision."
   ),
-  remove: z31.array(z31.string().min(1)).optional().describe("Patch mode only: paths to drop from the base revision."),
-  expected_version: z31.number().int().nonnegative().optional().describe(
+  remove: z32.array(z32.string().min(1)).optional().describe("Patch mode only: paths to drop from the base revision."),
+  expected_version: z32.number().int().nonnegative().optional().describe(
     "The revision_count this write is based on (from get_artifact). The platform refuses the write with a conflict if the head moved. Defaults to base_revision in patch mode, else the current head."
   ),
-  message: z31.string().optional().describe("Short summary of the change (max 500 characters)."),
-  entry_path: z31.string().optional().describe("Change the file a renderer opens first, from this revision on.")
+  message: z32.string().optional().describe("Short summary of the change (max 500 characters)."),
+  entry_path: z32.string().optional().describe("Change the file a renderer opens first, from this revision on.")
 };
 var writeArtifactRevisionTool = {
   name: "write_artifact_revision",
@@ -5413,12 +5947,12 @@ var writeArtifactRevisionTool = {
 };
 
 // src/server/tools/rollback_artifact.ts
-import { z as z32 } from "zod";
+import { z as z33 } from "zod";
 var inputSchema31 = {
-  artifact_id: z32.string().min(1).describe("UUID of the artifact."),
-  revision_number: z32.number().int().positive().describe("The revision whose files to restore."),
-  expected_version: z32.number().int().nonnegative().optional().describe("The revision_count this rollback is based on (from get_artifact); defaults to the current head."),
-  message: z32.string().optional().describe('Optional summary; defaults to "Rolled back to revision N".')
+  artifact_id: z33.string().min(1).describe("UUID of the artifact."),
+  revision_number: z33.number().int().positive().describe("The revision whose files to restore."),
+  expected_version: z33.number().int().nonnegative().optional().describe("The revision_count this rollback is based on (from get_artifact); defaults to the current head."),
+  message: z33.string().optional().describe('Optional summary; defaults to "Rolled back to revision N".')
 };
 var rollbackArtifactTool = {
   name: "rollback_artifact",
@@ -5443,10 +5977,10 @@ var rollbackArtifactTool = {
 };
 
 // src/server/tools/create_stream_token.ts
-import { z as z34 } from "zod";
+import { z as z35 } from "zod";
 
 // src/server/tools/stream-token-output.ts
-import { z as z33 } from "zod";
+import { z as z34 } from "zod";
 var projectStreamEventTypes = [
   "project.updated",
   "project.deleted",
@@ -5454,6 +5988,10 @@ var projectStreamEventTypes = [
   "spec_file.updated",
   "spec_file.deleted",
   "spec_file.lock",
+  "spec_file_comment.created",
+  "spec_file_comment.updated",
+  "spec_file_comment.thread_state_changed",
+  "spec_file_comment.anchors_updated",
   "attachment.created",
   "attachment.deleted",
   "spec_session.created",
@@ -5461,8 +5999,8 @@ var projectStreamEventTypes = [
   "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.'
+var streamEventTypesSchema = z34.array(z34.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; spec_file_comment.updated covers a body edit and a soft delete, thread_state_changed covers resolve and unresolve, and anchors_updated is batched across every thread one save moved.'
 );
 function streamTokenSummary(token) {
   return {
@@ -5492,13 +6030,13 @@ function streamTokenMintOutput(result) {
 
 // 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."),
+  resource_type: z35.enum(["project"]).default("project").describe("What to follow. Only 'project' is supported today."),
+  resource_id: z35.string().min(1).describe("UUID of the project to stream events for."),
   event_types: streamEventTypesSchema,
-  ttl_seconds: z34.number().int().positive().optional().describe(
+  ttl_seconds: z35.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.")
+  label: z35.string().optional().describe("Short human-readable label, so a person can recognise this token in a listing.")
 };
 var createStreamTokenTool = {
   name: "create_stream_token",
@@ -5517,17 +6055,17 @@ var createStreamTokenTool = {
 };
 
 // src/server/tools/list_stream_tokens.ts
-import { z as z35 } from "zod";
+import { z as z36 } 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(
+  resource_id: z36.string().optional().describe("Only tokens following this project."),
+  live_only: z36.boolean().optional().describe("Hide expired and revoked tokens."),
+  mine_only: z36.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).")
+  limit: z36.number().int().positive().optional().describe(`Max tokens to return (default ${String(LIST_DEFAULT5)}, capped at ${String(LIST_MAX5)}).`),
+  offset: z36.number().int().nonnegative().optional().describe("Pagination offset (default 0).")
 };
 var listStreamTokensTool = {
   name: "list_stream_tokens",
@@ -5555,9 +6093,9 @@ var listStreamTokensTool = {
 };
 
 // src/server/tools/revoke_stream_token.ts
-import { z as z36 } from "zod";
+import { z as z37 } 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.")
+  id: z37.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",
@@ -5570,7 +6108,7 @@ var revokeStreamTokenTool = {
 };
 
 // src/server/tools/start_spec_session.ts
-import { z as z37 } from "zod";
+import { z as z38 } from "zod";
 
 // src/server/tools/start-session-core.ts
 var START_SESSION_WAIT_MS = 75e3;
@@ -5963,27 +6501,27 @@ var START_SESSION_DESCRIPTION_BASE = "Start a NEW MySpec chat session on the use
 // src/server/tools/start_spec_session.ts
 var BRIDGE_COMMAND = "npx -y @myspec/mcp-server reverse --root <path>";
 var inputSchema35 = {
-  project_id: z37.string().min(1).describe("UUID of the project to start the session in."),
-  mode: z37.enum(["generate", "edit"]).describe(
+  project_id: z38.string().min(1).describe("UUID of the project to start the session in."),
+  mode: z38.enum(["generate", "edit"]).describe(
     "'generate' writes a new spec bundle from scratch; 'edit' changes the spec files of an existing bundle."
   ),
-  prompt: z37.string().min(1).describe(
+  prompt: z38.string().min(1).describe(
     "The opening message. Write it as the user would: what they want specced, and the repository context you have gathered that they would otherwise have to retype."
   ),
-  workflow_id: z37.string().optional().describe(
+  workflow_id: z38.string().optional().describe(
     "Workflow variant id, e.g. myspec-greenfield-v1, enterprise-greenfield-v1, speckit-greenfield-v1, openspec-brownfield-v1, myspec-brownfield-v1, myspec-edit-v1, myspec-edit-brownfield-v1. Omit to use the default for the chosen mode. Must agree with mode \u2014 a contradiction is rejected, not silently resolved."
   ),
-  language: z37.enum(SPEC_SESSION_LANGUAGES).optional().describe(
+  language: z38.enum(SPEC_SESSION_LANGUAGES).optional().describe(
     "Output language the session locks to on its first turn. Defaults to 'en'. A session's language is immutable once set."
   ),
-  model_id: z37.string().optional().describe("Model id to run the session with, e.g. openai:gpt-6-astra."),
-  attachment_ids: z37.array(z37.string().min(1)).max(MAX_REFERENCE_IDS).optional().describe(
+  model_id: z38.string().optional().describe("Model id to run the session with, e.g. openai:gpt-6-astra."),
+  attachment_ids: z38.array(z38.string().min(1)).max(MAX_REFERENCE_IDS).optional().describe(
     `Project attachment ids to cite in the opening message, as the composer @-mentions do. At most ${String(MAX_REFERENCE_IDS)}.`
   ),
-  spec_file_ids: z37.array(z37.string().min(1)).max(MAX_REFERENCE_IDS).optional().describe(
+  spec_file_ids: z38.array(z38.string().min(1)).max(MAX_REFERENCE_IDS).optional().describe(
     `Existing spec file ids to cite in the opening message. Required in practice for edit sessions. At most ${String(MAX_REFERENCE_IDS)}.`
   ),
-  session_title: z37.string().min(1).max(SESSION_TITLE_MAX_LENGTH).optional().describe(
+  session_title: z38.string().min(1).max(SESSION_TITLE_MAX_LENGTH).optional().describe(
     `Human-readable session title, stored as context.sessionSummary (max ${String(SESSION_TITLE_MAX_LENGTH)} characters). A workflow that names the session itself during its interview will overwrite it, exactly as in the webapp.`
   )
 };
@@ -6213,6 +6751,11 @@ function buildServer(deps) {
   registerTool(server, listStreamTokensTool, ctx);
   registerTool(server, revokeStreamTokenTool, ctx);
   registerTool(server, startSpecSessionTool, ctx);
+  registerTool(server, listSpecFileCommentsTool, ctx);
+  registerTool(server, createSpecFileCommentThreadTool, ctx);
+  registerTool(server, replySpecFileCommentThreadTool, ctx);
+  registerTool(server, updateSpecFileCommentTool, ctx);
+  registerTool(server, deleteSpecFileCommentTool, ctx);
   return server;
 }
 async function startStdioServer(deps) {
@@ -6366,7 +6909,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 z38 } from "zod";
+import { z as z39 } from "zod";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // src/reverse/ignore.ts
@@ -6671,37 +7214,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 = z38.object({
-  path: z38.string(),
-  recursive: z38.boolean().optional(),
-  maxEntries: z38.number().int().positive().optional(),
-  includeIgnored: z38.boolean().optional()
+var listDirInput = z39.object({
+  path: z39.string(),
+  recursive: z39.boolean().optional(),
+  maxEntries: z39.number().int().positive().optional(),
+  includeIgnored: z39.boolean().optional()
 });
-var readFileInput = z38.object({
-  path: z38.string(),
-  offset: z38.number().int().nonnegative().optional(),
-  limit: z38.number().int().positive().optional(),
-  includeIgnored: z38.boolean().optional()
+var readFileInput = z39.object({
+  path: z39.string(),
+  offset: z39.number().int().nonnegative().optional(),
+  limit: z39.number().int().positive().optional(),
+  includeIgnored: z39.boolean().optional()
 });
-var grepInput = z38.object({
-  pattern: z38.string().describe(
+var grepInput = z39.object({
+  pattern: z39.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: z38.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
-  isRegex: z38.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
-  caseSensitive: z38.boolean().optional(),
-  maxMatches: z38.number().int().positive().optional(),
-  contextLines: z38.number().int().nonnegative().optional(),
-  includeIgnored: z38.boolean().optional()
+  path: z39.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
+  isRegex: z39.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
+  caseSensitive: z39.boolean().optional(),
+  maxMatches: z39.number().int().positive().optional(),
+  contextLines: z39.number().int().nonnegative().optional(),
+  includeIgnored: z39.boolean().optional()
 });
-var packCodebaseInput = z38.object({
-  subpath: z38.string().optional(),
-  includePatterns: z38.string().optional(),
-  ignorePatterns: z38.string().optional()
+var packCodebaseInput = z39.object({
+  subpath: z39.string().optional(),
+  includePatterns: z39.string().optional(),
+  ignorePatterns: z39.string().optional()
 });
-var packCodebaseReadPageInput = z38.object({
-  outputId: z38.string(),
-  page: z38.number().int().positive()
+var packCodebaseReadPageInput = z39.object({
+  outputId: z39.string(),
+  page: z39.number().int().positive()
 });
 function structuredError(error, message, extra) {
   const payload = { error, message, ...extra ?? {} };
@@ -7229,7 +7772,7 @@ function jsonSchemaFromZod(schema) {
   return zodToJson(schema);
 }
 function zodToJson(schema) {
-  if (schema instanceof z38.ZodObject) {
+  if (schema instanceof z39.ZodObject) {
     const shape = schema.shape;
     const properties = {};
     const required = [];
@@ -7244,19 +7787,19 @@ function zodToJson(schema) {
     if (required.length > 0) out.required = required;
     return out;
   }
-  if (schema instanceof z38.ZodOptional) {
+  if (schema instanceof z39.ZodOptional) {
     return zodToJson(schema.unwrap());
   }
-  if (schema instanceof z38.ZodString) {
+  if (schema instanceof z39.ZodString) {
     return { type: "string" };
   }
-  if (schema instanceof z38.ZodNumber) {
+  if (schema instanceof z39.ZodNumber) {
     return { type: "number" };
   }
-  if (schema instanceof z38.ZodBoolean) {
+  if (schema instanceof z39.ZodBoolean) {
     return { type: "boolean" };
   }
-  if (schema instanceof z38.ZodEnum) {
+  if (schema instanceof z39.ZodEnum) {
     return { type: "string", enum: schema.options };
   }
   return { type: "string" };

package/package.json

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