@myspec/mcp-server 0.4.0-next.95 → 0.4.0-next.97

package/README.md

@@ -298,6 +298,14 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 | `restore_spec_file_from_trash` | `file_id` | Restores a trashed spec file back to the active file list, reversing `move_spec_file_to_trash` |
 | `get_attachment` | `attachment_id`, optional `include_download_url` | Attachment metadata (looked up org-scoped by id); with `include_download_url>0` also returns a signed download URL |
 | `upload_attachment` | `project_id`, `file_path` (absolute), optional `file_name`, optional `mime_type`, optional `override` | Uploads the local file as a new attachment on the project. Returns `attachment_id`, `file_name` (the **effective** name the platform stored — may differ from the requested one when auto-dedup adds a `(N)` suffix), `has_file_name_conflict` (`true` when stored name ≠ requested name), `mime_type`, `file_size_bytes`, `checksum` (format: `sha256:<hex>`), `file_uri`, `reused_existing_attachment` (`true` when an existing attachment with the same name AND same checksum was found and returned without re-uploading; `file_uri` is then omitted because the list endpoint does not surface it — call `get_attachment` for a download URL). With `override=true`, any existing attachment whose recorded name matches is soft-deleted first (returned as `overridden_attachment_ids` — empty array means nothing matched) and the new upload keeps the requested name; the same-checksum short-circuit still applies, so a no-op re-upload never deletes anything. Max 10 MB. Supported content: PDF, DOCX, XLSX, and any UTF-8 text file (XML, JSON, YAML, HTML, Markdown, CSV, source code, ...) |
+| `list_attachments` | `project_id`, optional `limit`, optional `offset` | Paginated attachment metadata (`id`, `name`, `mime_type`, `file_size_bytes`, `checksum`, `created_at`) — `file_size_bytes` is always present so a caller can size-check before `read_attachment`. Default 50 per page, capped at 200; returns `total` and `next_offset` while records remain |
+| `read_attachment` | `attachment_id`, optional `offset`, optional `limit` | The attachment's content inline. UTF-8 text is 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`. Images (PNG, JPEG, GIF, WEBP) are returned whole as an MCP image block (never paginated, up to 10 MiB). Other binary types (PDF, DOCX, XLSX, ...) error with a pointer to the webapp and to `get_attachment include_download_url` as the local alternative |
+| `list_spec_sessions` | `project_id`, optional `archive_filter` (`active`/`archived`/`all`), optional `status`, optional `query`, optional `limit`, optional `offset` | Paginated session metadata plus `session_summary` and `context_size_bytes` — never the context itself or the chat transcript. Default 10 per page, capped at 20 |
+| `get_spec_session` | `session_id`, optional `include_context` | Session metadata (status, counters, timestamps, `archived_at`), `session_summary`, `context_size_bytes` and `context_keys`. `include_context=true` returns the full context under a 1 MiB ceiling (above it the tool errors with the actual size). The chat transcript is never returned |
+| `rename_spec_session` | `session_id`, `session_summary` | Sets `context.sessionSummary` (max 500 chars) via read-merge-write, preserving every other context key; works on archived sessions; refuses when the context is not a JSON object. Returns `renamed`, `session_id`, `session_summary` |
+| `archive_spec_session` | `session_id` | Archives the session (idempotent — re-archiving keeps the original `archived_at`); the required confirmation step before `delete_spec_session` |
+| `unarchive_spec_session` | `session_id` | Returns an archived session to the active list |
+| `delete_spec_session` | `session_id` | Soft-deletes an ARCHIVED session. Refuses non-archived sessions with an archive-first error and never archives on the caller's behalf |
 
 ### Download destinations
 

package/dist/index.js

@@ -2471,6 +2471,32 @@ var PlatformClient = class {
     };
     return this.withTokenRetry((jwt, c) => c.session.listSpecSessions(projectId, jwt, merged));
   }
+  async getSpecSession(sessionId) {
+    return this.withTokenRetry((jwt, c) => c.session.getSpecSession(sessionId, jwt));
+  }
+  /**
+   * Writes ONLY the session's `context` field (rename's read-merge-write).
+   * Deliberately narrow: status, chatHistory and the counters stay
+   * unreachable from the MCP surface. The platform permits context-only
+   * updates on archived sessions, so rename works there too.
+   */
+  async updateSpecSessionContext(sessionId, context) {
+    return this.withTokenRetry((jwt, c) => c.session.updateSpecSession(sessionId, { context }, jwt));
+  }
+  /** Idempotent: re-archiving keeps the original archivedAt. */
+  async archiveSpecSession(sessionId) {
+    return this.withTokenRetry((jwt, c) => c.session.archiveSpecSession(sessionId, jwt));
+  }
+  async unarchiveSpecSession(sessionId) {
+    return this.withTokenRetry((jwt, c) => c.session.unarchiveSpecSession(sessionId, jwt));
+  }
+  /**
+   * Soft-deletes a spec session. The platform rejects this unless the session
+   * is already archived, surfacing a validation error the caller reports.
+   */
+  async deleteSpecSession(sessionId) {
+    await this.withTokenRetry((jwt, c) => c.session.deleteSpecSession(sessionId, jwt));
+  }
   async listFiles(projectId, opts = {}) {
     return this.withTokenRetry((jwt, c) => c.file.listFiles(projectId, jwt, opts));
   }
@@ -2744,6 +2770,14 @@ function jsonResult(value) {
 function errorResult(message) {
   return { content: [{ type: "text", text: message }], isError: true };
 }
+function imageResult(dataBase64, mimeType, metadata) {
+  return {
+    content: [
+      { type: "text", text: JSON.stringify(metadata, null, 2) },
+      { type: "image", data: dataBase64, mimeType }
+    ]
+  };
+}
 
 // src/server/tools/archive_project.ts
 import { z } from "zod";
@@ -2775,16 +2809,63 @@ var archiveProjectTool = {
   }
 };
 
-// src/server/tools/create_project.ts
+// src/server/tools/archive_spec_session.ts
 import { z as z2 } from "zod";
+
+// src/server/tools/session-output.ts
+function sessionNotFound(err, sessionId) {
+  return statusOf(err) === 404 ? errorResult(`Session ${sessionId} not found.`) : null;
+}
+function sessionMetadata(s) {
+  return {
+    id: s.id,
+    project_id: s.projectId,
+    org: s.org,
+    user_id: s.userId,
+    status: s.status,
+    message_count: s.messageCount,
+    token_count: s.tokenCount,
+    started_at: s.startedAt,
+    completed_at: s.completedAt ?? null,
+    archived_at: s.archivedAt ?? null,
+    created_at: s.createdAt,
+    updated_at: s.updatedAt
+  };
+}
+
+// src/server/tools/archive_spec_session.ts
 var inputSchema2 = {
-  name: z2.string().describe("Name of the project to create."),
-  description: z2.string().optional().describe("Optional project description.")
+  session_id: z2.string().min(1).describe("UUID of the spec session to archive")
+};
+var archiveSpecSessionTool = {
+  name: "archive_spec_session",
+  description: "Archive a spec session. Archiving is the confirmation step required before delete_spec_session, and is reversible via unarchive_spec_session. Idempotent: archiving an already-archived session succeeds and keeps the original archived_at.",
+  inputSchema: inputSchema2,
+  handler: async (args, ctx) => {
+    let session;
+    try {
+      session = await ctx.client.archiveSpecSession(args.session_id);
+    } catch (err) {
+      const notFound = sessionNotFound(err, args.session_id);
+      if (notFound) {
+        return notFound;
+      }
+      throw err;
+    }
+    return jsonResult({ session: sessionMetadata(session) });
+  }
+};
+
+// src/server/tools/create_project.ts
+import { z as z3 } from "zod";
+var inputSchema3 = {
+  name: z3.string().describe("Name of the project to create."),
+  description: z3.string().optional().describe("Optional project description.")
 };
 var createProjectTool = {
   name: "create_project",
   description: "Create a new project. Returns the created project id and metadata.",
-  inputSchema: inputSchema2,
+  inputSchema: inputSchema3,
   handler: async (args, ctx) => {
     const name = args.name.trim();
     if (name === "") {
@@ -2799,14 +2880,14 @@ var createProjectTool = {
 };
 
 // src/server/tools/delete_project.ts
-import { z as z3 } from "zod";
-var inputSchema3 = {
-  project_id: z3.string().min(1).describe("UUID of the project to delete.")
+import { z as z4 } from "zod";
+var inputSchema4 = {
+  project_id: z4.string().min(1).describe("UUID of the project to delete.")
 };
 var deleteProjectTool = {
   name: "delete_project",
   description: "Soft-delete a project. Only a project that is already archived can be deleted. If the project is still active, this tool refuses and you must NOT archive it on the user's behalf to make the deletion go through \u2014 instead, reconfirm with the user whether deleting the project is truly intended.",
-  inputSchema: inputSchema3,
+  inputSchema: inputSchema4,
   handler: async (args, ctx) => {
     let status;
     try {
@@ -2831,9 +2912,38 @@ var deleteProjectTool = {
   }
 };
 
+// src/server/tools/delete_spec_session.ts
+import { z as z5 } from "zod";
+var inputSchema5 = {
+  session_id: z5.string().min(1).describe("UUID of the spec session to delete")
+};
+var deleteSpecSessionTool = {
+  name: "delete_spec_session",
+  description: "Soft-delete a spec session. Only an ARCHIVED session can be deleted \u2014 archive it first with archive_spec_session. This tool never archives on your behalf: archiving is the user's confirmation step, and collapsing the two-step destructive flow would remove the only checkpoint the platform provides. Check archived_at via get_spec_session to see whether delete is permitted.",
+  inputSchema: inputSchema5,
+  handler: async (args, ctx) => {
+    try {
+      await ctx.client.deleteSpecSession(args.session_id);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (/must be archived/i.test(message)) {
+        return errorResult(
+          `Session ${args.session_id} was NOT deleted: session must be archived before it can be deleted. Archive it first with archive_spec_session \u2014 after reconfirming with the user that deleting this session is intended.`
+        );
+      }
+      const notFound = sessionNotFound(err, args.session_id);
+      if (notFound) {
+        return notFound;
+      }
+      throw err;
+    }
+    return jsonResult({ deleted: true, session_id: args.session_id });
+  }
+};
+
 // src/server/tools/download_spec_file.ts
 import path3 from "path";
-import { z as z4 } from "zod";
+import { z as z6 } from "zod";
 
 // src/server/download-path.ts
 import { randomBytes as randomBytes2 } from "crypto";
@@ -2967,18 +3077,18 @@ async function writeBytesAtomically(target, bytes) {
 
 // src/server/tools/download_spec_file.ts
 var MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024;
-var inputSchema4 = {
-  file_id: z4.string().min(1).describe("UUID of the file"),
-  revision: z4.number().int().positive().optional().describe("Specific revision number to download (defaults to the latest revision)."),
-  destination_path: z4.string().min(1).optional().describe(
+var inputSchema6 = {
+  file_id: z6.string().min(1).describe("UUID of the file"),
+  revision: z6.number().int().positive().optional().describe("Specific revision number to download (defaults to the latest revision)."),
+  destination_path: z6.string().min(1).optional().describe(
     "Local path to save the file to. Optional: omit it to save the file under `.specs/` in the MCP server's working directory, mirroring its remote path (`specs/add-oauth/proposal.md` \u2192 `.specs/add-oauth/proposal.md`). When given, it is absolute or relative to that working directory; a relative path rooted at `specs/` is redirected to `.specs/`, so pass an absolute path to save into a literal `specs/` directory. If it points to an existing directory (or ends with a path separator), the spec file's basename is appended."
   ),
-  overwrite: z4.boolean().optional().describe("Overwrite the destination file if it already exists (default: false).")
+  overwrite: z6.boolean().optional().describe("Overwrite the destination file if it already exists (default: false).")
 };
 var downloadSpecFileTool = {
   name: "download_spec_file",
   description: "Download a spec file's raw bytes to a local file. By default it lands under `.specs/` in the MCP server's working directory, mirroring the file's remote path \u2014 pass `destination_path` only to save it somewhere else. Unlike read_spec_file, this handles binary files and files up to 50 MiB, and the response returns only metadata (saved path, size, revision) \u2014 not the content. Use it to save a large or binary file locally, then search or read it in chunks with other tools.",
-  inputSchema: inputSchema4,
+  inputSchema: inputSchema6,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
     const targetRevision = args.revision ?? meta.revisionCount;
@@ -3076,15 +3186,15 @@ function buildOversizeMessage(fileId, byteLength) {
 }
 
 // src/server/tools/get_attachment.ts
-import { z as z5 } from "zod";
-var inputSchema5 = {
-  attachment_id: z5.string().min(1).describe("UUID of the attachment"),
-  include_download_url: z5.number().int().nonnegative().optional().describe("Set to any positive value to include a signed download URL. Omit or 0 to skip.")
+import { z as z7 } from "zod";
+var inputSchema7 = {
+  attachment_id: z7.string().min(1).describe("UUID of the attachment"),
+  include_download_url: z7.number().int().nonnegative().optional().describe("Set to any positive value to include a signed download URL. Omit or 0 to skip.")
 };
 var getAttachmentTool = {
   name: "get_attachment",
   description: "Get attachment metadata. With `include_download_url>0`, also returns a signed `download_url`.",
-  inputSchema: inputSchema5,
+  inputSchema: inputSchema7,
   handler: async (args, ctx) => {
     const attachment = await ctx.client.getAttachmentMetadata(args.attachment_id);
     if (!attachment) {
@@ -3113,14 +3223,14 @@ var getAttachmentTool = {
 };
 
 // src/server/tools/get_project.ts
-import { z as z6 } from "zod";
-var inputSchema6 = {
-  project_id: z6.string().min(1).describe("UUID of the project to fetch")
+import { z as z8 } from "zod";
+var inputSchema8 = {
+  project_id: z8.string().min(1).describe("UUID of the project to fetch")
 };
 var getProjectTool = {
   name: "get_project",
   description: "Get details for a project including all active spec sessions, files (id + metadata), and attachments (id + metadata).",
-  inputSchema: inputSchema6,
+  inputSchema: inputSchema8,
   handler: async (args, ctx) => {
     const [project, sessions, files, attachments] = await Promise.all([
       ctx.client.getProject(args.project_id),
@@ -3166,7 +3276,7 @@ var getProjectTool = {
 };
 
 // src/server/tools/get_spec_file.ts
-import { z as z7 } from "zod";
+import { z as z9 } from "zod";
 
 // src/server/tools/spec-file-output.ts
 function specFileSummary(file) {
@@ -3186,16 +3296,16 @@ function specFileSummary(file) {
 }
 
 // src/server/tools/get_spec_file.ts
-var inputSchema7 = {
-  file_id: z7.string().min(1).describe("UUID of the file"),
-  include_download_url: z7.number().int().nonnegative().optional().describe(
+var inputSchema9 = {
+  file_id: z9.string().min(1).describe("UUID of the file"),
+  include_download_url: z9.number().int().nonnegative().optional().describe(
     "Revision number to include a download URL for. Returns a signed, time-limited URL for that revision (latest or historical) that needs no credentials. Omit or 0 to skip."
   )
 };
 var getSpecFileTool = {
   name: "get_spec_file",
   description: "Get spec file metadata. With `include_download_url=N`, also returns a signed, time-limited download URL for revision N (latest or historical). The URL is self-authenticating, so no credentials are returned.",
-  inputSchema: inputSchema7,
+  inputSchema: inputSchema9,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
     const base = specFileSummary(meta);
@@ -3219,19 +3329,209 @@ var getSpecFileTool = {
   }
 };
 
+// src/server/tools/get_spec_session.ts
+import { z as z10 } from "zod";
+
+// src/util/bytes.ts
+function encodeBase64(bytes) {
+  const CHUNK = 32768;
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(binary);
+}
+function isBinary(bytes) {
+  return bytes.includes(0);
+}
+function decodeUtf8Strict(bytes) {
+  try {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+function utf8ByteLength(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+// src/server/session-context.ts
+var MAX_CONTEXT_RESPONSE_BYTES = 1 * 1024 * 1024;
+var SESSION_SUMMARY_MAX_LENGTH = 500;
+function jsonTypeOf(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean") {
+    return t;
+  }
+  return "object";
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function introspectContext(context) {
+  if (context === null || context === void 0) {
+    return { session_summary: null, context_size_bytes: 0, context_keys: [] };
+  }
+  const sizeBytes = contextSizeBytes(context);
+  if (!isPlainObject(context)) {
+    const type = jsonTypeOf(context);
+    return {
+      session_summary: null,
+      context_size_bytes: sizeBytes,
+      context_keys: [],
+      ...type !== "object" && type !== "null" ? { context_type: type } : {}
+    };
+  }
+  const summary = context.sessionSummary;
+  return {
+    session_summary: typeof summary === "string" ? summary : null,
+    context_size_bytes: sizeBytes,
+    context_keys: Object.entries(context).map(([key, value]) => ({
+      key,
+      size_bytes: value === void 0 ? 0 : utf8ByteLength(JSON.stringify(value))
+    }))
+  };
+}
+function contextSizeBytes(context) {
+  if (context === null || context === void 0) {
+    return 0;
+  }
+  return utf8ByteLength(JSON.stringify(context));
+}
+function mergeSessionSummary(context, sessionSummary) {
+  if (context === null || context === void 0) {
+    return { ok: true, context: { sessionSummary } };
+  }
+  if (isPlainObject(context)) {
+    return { ok: true, context: { ...context, sessionSummary } };
+  }
+  return { ok: false, actualType: jsonTypeOf(context) };
+}
+
+// src/server/tools/get_spec_session.ts
+var inputSchema10 = {
+  session_id: z10.string().min(1).describe("UUID of the spec session"),
+  include_context: z10.boolean().optional().describe(
+    "When true, include the whole context JSONB (subject to a 1 MiB ceiling \u2014 above it the tool errors with the actual size). Default false: the response instead carries context_size_bytes and context_keys so you can see the size and shape before asking."
+  )
+};
+var getSpecSessionTool = {
+  name: "get_spec_session",
+  description: "Get one spec session's metadata: status, counters, timestamps, archived_at (delete eligibility), session_summary, plus context_size_bytes and context_keys describing the context without returning it. Set include_context=true for the full context (1 MiB ceiling). The chat transcript is never returned.",
+  inputSchema: inputSchema10,
+  handler: async (args, ctx) => {
+    let session;
+    try {
+      session = await ctx.client.getSpecSession(args.session_id);
+    } catch (err) {
+      const notFound = sessionNotFound(err, args.session_id);
+      if (notFound) {
+        return notFound;
+      }
+      throw err;
+    }
+    const summary = introspectContext(session.context);
+    const base = {
+      ...sessionMetadata(session),
+      session_summary: summary.session_summary,
+      context_size_bytes: summary.context_size_bytes,
+      context_keys: summary.context_keys,
+      ...summary.context_type === void 0 ? {} : { context_type: summary.context_type }
+    };
+    if (args.include_context !== true) {
+      return jsonResult(base);
+    }
+    const size = contextSizeBytes(session.context);
+    if (size > MAX_CONTEXT_RESPONSE_BYTES) {
+      return errorResult(
+        `Session ${session.id} context is ${String(size)} bytes, above the ${String(MAX_CONTEXT_RESPONSE_BYTES)}-byte include_context ceiling. Structured JSON is not truncated; use context_keys to locate what you need, or read the session in the MySpec webapp.`
+      );
+    }
+    return jsonResult({ ...base, context: session.context ?? null });
+  }
+};
+
+// src/server/tools/list_attachments.ts
+import { z as z11 } from "zod";
+
+// src/util/list-paging.ts
+function clampLimit(limit, defaultLimit, maxLimit) {
+  const requested = limit ?? defaultLimit;
+  return Math.min(Math.max(1, requested), maxLimit);
+}
+function sliceWindow(items, limit, offset) {
+  const total = items.length;
+  const start = Math.min(Math.max(0, offset), total);
+  const slice = items.slice(start, start + limit);
+  const end = start + slice.length;
+  return {
+    items: [...slice],
+    total,
+    limit,
+    offset: start,
+    ...end < total ? { next_offset: end } : {}
+  };
+}
+function nextOffsetOf(offset, returned, total) {
+  const end = offset + returned;
+  return end < total ? end : void 0;
+}
+
+// src/server/tools/list_attachments.ts
+var LIST_DEFAULT = 50;
+var LIST_MAX = 200;
+var inputSchema11 = {
+  project_id: z11.string().min(1).describe("UUID of the project whose attachments to list."),
+  limit: z11.number().int().positive().optional().describe(
+    `Max attachments to return (default ${String(LIST_DEFAULT)}, capped at ${String(LIST_MAX)}).`
+  ),
+  offset: z11.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
+};
+var listAttachmentsTool = {
+  name: "list_attachments",
+  description: "List a project's attachments (metadata only, always including file_size_bytes so a caller can check the size before read_attachment). Returns `total` and, when more records remain, `next_offset`.",
+  inputSchema: inputSchema11,
+  handler: async (args, ctx) => {
+    const all = await ctx.client.listAttachments(args.project_id);
+    const limit = clampLimit(args.limit, LIST_DEFAULT, LIST_MAX);
+    const window = sliceWindow(all, limit, args.offset ?? 0);
+    return jsonResult({
+      project_id: args.project_id,
+      attachments: window.items.map((a) => ({
+        id: a.id,
+        name: a.name,
+        mime_type: a.mimeType,
+        file_size_bytes: a.fileSizeBytes,
+        checksum: a.checksum,
+        created_at: a.createdAt
+      })),
+      total: window.total,
+      limit: window.limit,
+      offset: window.offset,
+      ...window.next_offset === void 0 ? {} : { next_offset: window.next_offset }
+    });
+  }
+};
+
 // src/server/tools/list_projects.ts
-import { z as z8 } from "zod";
-var inputSchema8 = {
-  query: z8.string().optional().describe(
+import { z as z12 } from "zod";
+var inputSchema12 = {
+  query: z12.string().optional().describe(
     "Search term to filter projects by name. Omit to list all projects."
   ),
-  limit: z8.number().int().positive().max(100).optional().describe("Max projects to return (default 20)"),
-  offset: z8.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
+  limit: z12.number().int().positive().max(100).optional().describe("Max projects to return (default 20)"),
+  offset: z12.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
 };
 var listProjectsTool = {
   name: "list_projects",
   description: "List or search MySpec projects accessible to the authenticated user.",
-  inputSchema: inputSchema8,
+  inputSchema: inputSchema12,
   handler: async (args, ctx) => {
     const result = await ctx.client.listProjects({
       query: args.query,
@@ -3254,21 +3554,21 @@ var listProjectsTool = {
 };
 
 // src/server/tools/list_spec_file.ts
-import { z as z9 } from "zod";
+import { z as z13 } from "zod";
 var PAGE_SIZE = 100;
-var inputSchema9 = {
-  project_id: z9.string().min(1).describe("UUID of the project whose spec files to list."),
-  path: z9.string().optional().describe(
+var inputSchema13 = {
+  project_id: z13.string().min(1).describe("UUID of the project whose spec files to list."),
+  path: z13.string().optional().describe(
     'Directory prefix to filter by, e.g. ".spec" or ".spec/design". Matches the exact file and everything under that directory. Pass "", "/", or omit to list all files.'
   ),
-  trashed: z9.boolean().optional().describe(
+  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)."
   )
 };
 var listSpecFileTool = {
   name: "list_spec_file",
   description: 'List a project\'s spec files with id, path, and metadata (revision count, file size of the latest revision, file type, owning session, last update). Filter to a directory with `path` (exact file or everything under it; pass "", "/", or omit for all). Set `trashed=true` to list files in the Trash Bin instead of live files.',
-  inputSchema: inputSchema9,
+  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);
@@ -3324,34 +3624,255 @@ function isUnderPath(filePath, prefix) {
   return filePath === prefix || filePath.startsWith(prefix + "/");
 }
 
+// src/server/tools/list_spec_sessions.ts
+import { z as z14 } from "zod";
+var LIST_DEFAULT2 = 10;
+var LIST_MAX2 = 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)}).`
+  ),
+  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\`.`,
+  inputSchema: inputSchema14,
+  handler: async (args, ctx) => {
+    const limit = clampLimit(args.limit, LIST_DEFAULT2, LIST_MAX2);
+    const offset = args.offset ?? 0;
+    const result = await ctx.client.listProjectSessions(args.project_id, {
+      archiveFilter: args.archive_filter ?? "active",
+      ...args.status === void 0 ? {} : { status: args.status },
+      ...args.query === void 0 ? {} : { query: args.query },
+      limit,
+      offset
+    });
+    const next = nextOffsetOf(offset, result.sessions.length, result.total);
+    return jsonResult({
+      project_id: args.project_id,
+      sessions: result.sessions.map((s) => {
+        const summary = introspectContext(s.context);
+        return {
+          ...sessionMetadata(s),
+          session_summary: summary.session_summary,
+          context_size_bytes: summary.context_size_bytes
+        };
+      }),
+      total: result.total,
+      limit,
+      offset,
+      ...next === void 0 ? {} : { next_offset: next }
+    });
+  }
+};
+
 // src/server/tools/move_spec_file_to_trash.ts
-import { z as z10 } from "zod";
-var inputSchema10 = {
-  file_id: z10.string().min(1).describe("UUID of the spec file to move to the Trash Bin.")
+import { z as z15 } from "zod";
+var inputSchema15 = {
+  file_id: z15.string().min(1).describe("UUID of the spec file to move to the Trash Bin.")
 };
 var moveSpecFileToTrashTool = {
   name: "move_spec_file_to_trash",
   description: "Move a spec file to the Trash Bin. This is recoverable \u2014 the file is hidden from the default file list and AI-agent tools but kept restorable indefinitely via `restore_spec_file_from_trash`. It is NOT a permanent delete.",
-  inputSchema: inputSchema10,
+  inputSchema: inputSchema15,
   handler: async (args, ctx) => {
     await ctx.client.trashFile(args.file_id);
     return jsonResult({ trashed: true, file_id: args.file_id });
   }
 };
 
+// src/server/tools/read_attachment.ts
+import { z as z16 } from "zod";
+
+// src/util/paginate-lines.ts
+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;
+  return withoutBom.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+function splitIntoLines(text) {
+  const parts = text.split("\n");
+  if (parts.length > 0 && parts[parts.length - 1] === "") {
+    parts.pop();
+  }
+  return parts;
+}
+function truncateToBytes(value, maxBytes) {
+  const encoded = new TextEncoder().encode(value);
+  if (encoded.byteLength <= maxBytes) {
+    return value;
+  }
+  const decoded = new TextDecoder("utf-8").decode(encoded.subarray(0, maxBytes));
+  return decoded.replace(/�+$/, "");
+}
+function paginateText(text, offsetArg, limitArg) {
+  const lines = splitIntoLines(normalizeNewlines(text));
+  const totalLines = lines.length;
+  const rawOffset = offsetArg ?? 1;
+  const offset = rawOffset === 0 ? 1 : rawOffset;
+  if (offset < 1) {
+    return {
+      ok: false,
+      error: `Invalid offset ${String(rawOffset)}; offset is 1-based and must be >= 1.`
+    };
+  }
+  if (totalLines === 0) {
+    return {
+      ok: true,
+      window: {
+        content: "",
+        start_line: 1,
+        end_line: 0,
+        read_lines: 0,
+        total_lines: 0,
+        truncated: false
+      }
+    };
+  }
+  if (offset > totalLines) {
+    return {
+      ok: false,
+      error: `Offset ${String(rawOffset)} is past the end of the file (total ${String(totalLines)} lines).`
+    };
+  }
+  const effectiveLimit = Math.min(Math.max(1, limitArg ?? MAX_LINES_PER_CALL), MAX_LINES_PER_CALL);
+  const startIdx = offset - 1;
+  const lineWindowEnd = Math.min(startIdx + effectiveLimit, totalLines);
+  const out = [];
+  let usedBytes = 0;
+  let index = startIdx;
+  let byteCeilingHit = false;
+  for (; index < lineWindowEnd; index++) {
+    const line = lines[index] ?? "";
+    const lineBytes = utf8ByteLength(line);
+    const separatorBytes = out.length > 0 ? 1 : 0;
+    if (usedBytes + separatorBytes + lineBytes > MAX_RESPONSE_BYTES) {
+      if (out.length === 0) {
+        out.push(
+          `${truncateToBytes(line, MAX_RESPONSE_BYTES)}\u2026 [truncated, ${String(lineBytes)} bytes total]`
+        );
+      }
+      byteCeilingHit = true;
+      break;
+    }
+    usedBytes += separatorBytes + lineBytes;
+    out.push(line);
+  }
+  const endLine = startIdx + out.length;
+  const truncated = byteCeilingHit || endLine < totalLines;
+  return {
+    ok: true,
+    window: {
+      content: out.join("\n"),
+      start_line: offset,
+      end_line: endLine,
+      read_lines: out.length,
+      total_lines: totalLines,
+      truncated,
+      ...truncated && endLine < totalLines ? { next_offset: endLine + 1 } : {}
+    }
+  };
+}
+
+// src/server/tools/read_attachment.ts
+var MAX_ATTACHMENT_MB = MAX_ATTACHMENT_BYTES / (1024 * 1024);
+var IMAGE_MIME_TYPES = /* @__PURE__ */ new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp"
+]);
+var TEXT_MIME_TYPES = /* @__PURE__ */ new Set([
+  "application/json",
+  "application/xml",
+  "application/x-yaml",
+  "application/yaml",
+  "image/svg+xml"
+]);
+var GENERIC_MIME_TYPES = /* @__PURE__ */ new Set(["application/octet-stream", ""]);
+var inputSchema16 = {
+  attachment_id: z16.string().min(1).describe("UUID of the attachment to read"),
+  offset: z16.number().int().nonnegative().optional().describe(
+    "1-based line number to start reading from (text attachments only; default 1; 0 is an alias for 1)."
+  ),
+  limit: z16.number().int().positive().optional().describe("Max lines to return (text attachments only; default 2000, capped at 2000).")
+};
+var readAttachmentTool = {
+  name: "read_attachment",
+  description: `Return an attachment's content inline. UTF-8 text is paginated by line (offset/limit, 1 MiB per response). Images (png, jpeg, gif, webp) are returned whole as an MCP image block \u2014 never paginated \u2014 up to the ${String(MAX_ATTACHMENT_MB)} MiB attachment limit; a 10 MiB image is roughly 13.4 MiB of base64, so check file_size_bytes (from get_attachment or list_attachments) before reading a large one. Other binary types (pdf, docx, xlsx, \u2026) cannot be read here; view them in the MySpec webapp.`,
+  inputSchema: inputSchema16,
+  handler: async (args, ctx) => {
+    const meta = await ctx.client.getAttachmentMetadata(args.attachment_id);
+    if (!meta) {
+      return errorResult(`Attachment ${args.attachment_id} not found.`);
+    }
+    const mime = meta.mimeType;
+    if (IMAGE_MIME_TYPES.has(mime)) {
+      if (meta.fileSizeBytes > MAX_ATTACHMENT_BYTES) {
+        return errorResult(
+          `Attachment ${meta.id} is ${String(meta.fileSizeBytes)} bytes, above the ${String(MAX_ATTACHMENT_MB)} MiB image ceiling.`
+        );
+      }
+      const bytes2 = await ctx.client.downloadAttachment(meta.id);
+      if (bytes2.byteLength > MAX_ATTACHMENT_BYTES) {
+        return errorResult(
+          `Attachment ${meta.id} is ${String(bytes2.byteLength)} bytes, above the ${String(MAX_ATTACHMENT_MB)} MiB image ceiling.`
+        );
+      }
+      return imageResult(encodeBase64(bytes2), mime, {
+        attachment_id: meta.id,
+        file_name: meta.name,
+        mime_type: mime,
+        file_size_bytes: bytes2.byteLength
+      });
+    }
+    const declaredText = mime.startsWith("text/") || TEXT_MIME_TYPES.has(mime);
+    const generic = GENERIC_MIME_TYPES.has(mime);
+    if (!declaredText && !generic) {
+      return errorResult(
+        `Attachment ${meta.id} has MIME type ${mime}, which is neither UTF-8 text nor a supported image type (png, jpeg, gif, webp). View it in the MySpec webapp, or use get_attachment with include_download_url=1 for a signed URL to download it locally.`
+      );
+    }
+    const bytes = await ctx.client.downloadAttachment(meta.id);
+    const text = isBinary(bytes) ? null : decodeUtf8Strict(bytes);
+    if (text === null) {
+      return errorResult(
+        `Attachment ${meta.id} (MIME type ${mime}) is not valid UTF-8 text and is not a supported image type. View it in the MySpec webapp, or use get_attachment with include_download_url=1 for a signed URL to download it locally.`
+      );
+    }
+    const paginated = paginateText(text, args.offset, args.limit);
+    if (!paginated.ok) {
+      return errorResult(paginated.error);
+    }
+    return jsonResult({
+      attachment_id: meta.id,
+      file_name: meta.name,
+      mime_type: mime,
+      file_size_bytes: meta.fileSizeBytes,
+      ...paginated.window
+    });
+  }
+};
+
 // src/server/tools/read_spec_file.ts
 import { promises as fs3 } from "fs";
 import { createHash as createHash2 } from "crypto";
-import { z as z11 } from "zod";
+import { z as z17 } from "zod";
 var MAX_READ_BYTES = 1 * 1024 * 1024;
-var inputSchema11 = {
-  file_id: z11.string().min(1).describe("UUID of the file"),
-  revision: z11.number().int().positive().optional().describe("Specific revision number to read (defaults to the latest revision).")
+var 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).")
 };
 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.",
-  inputSchema: inputSchema11,
+  inputSchema: inputSchema17,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
     const targetRevision = args.revision ?? meta.revisionCount;
@@ -3389,7 +3910,7 @@ var readSpecFileTool = {
     if (bytes.byteLength > MAX_READ_BYTES) {
       return errorResult(buildOversizeMessage2(args.file_id, bytes.byteLength));
     }
-    if (isBinary(bytes)) {
+    if (isBinary2(bytes)) {
       return errorResult(
         `File ${args.file_id} appears to be binary (file_type=${meta.fileType}, size=${String(bytes.byteLength)} bytes). Use download_spec_file to save it to a local file.`
       );
@@ -3422,7 +3943,7 @@ var readSpecFileTool = {
 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.`;
 }
-function isBinary(bytes) {
+function isBinary2(bytes) {
   for (const byte of bytes) {
     if (byte === 0) {
       return true;
@@ -3434,15 +3955,59 @@ function sha256Prefixed2(content) {
   return "sha256:" + createHash2("sha256").update(content).digest("hex");
 }
 
+// src/server/tools/rename_spec_session.ts
+import { z as z18 } from "zod";
+var inputSchema18 = {
+  session_id: z18.string().min(1).describe("UUID of the spec session to rename"),
+  session_summary: z18.string().min(1).max(SESSION_SUMMARY_MAX_LENGTH).describe(
+    `New human-readable session title (max ${String(SESSION_SUMMARY_MAX_LENGTH)} characters). Stored as context.sessionSummary \u2014 the field the webapp displays and searches.`
+  )
+};
+var renameSpecSessionTool = {
+  name: "rename_spec_session",
+  description: "Rename a spec session by updating its context.sessionSummary \u2014 the session's human-readable title (there is no first-class name field). Permitted on both active and archived sessions. All other context keys are preserved untouched.",
+  inputSchema: inputSchema18,
+  handler: async (args, ctx) => {
+    if (args.session_summary.length > SESSION_SUMMARY_MAX_LENGTH) {
+      return errorResult(
+        `session_summary is ${String(args.session_summary.length)} characters; the limit is ${String(SESSION_SUMMARY_MAX_LENGTH)}.`
+      );
+    }
+    let session;
+    try {
+      session = await ctx.client.getSpecSession(args.session_id);
+    } catch (err) {
+      const notFound = sessionNotFound(err, args.session_id);
+      if (notFound) {
+        return notFound;
+      }
+      throw err;
+    }
+    const merged = mergeSessionSummary(session.context, args.session_summary);
+    if (!merged.ok) {
+      return errorResult(
+        `Session ${args.session_id} was NOT renamed: its context is a JSON ${merged.actualType}, not an object. This shape is unexpected, the tool cannot know what it encodes, and overwriting it would be unrecoverable. Inspect the session in the MySpec webapp.`
+      );
+    }
+    const updated = await ctx.client.updateSpecSessionContext(args.session_id, merged.context);
+    const summary = introspectContext(updated.context);
+    return jsonResult({
+      renamed: true,
+      session_id: updated.id,
+      session_summary: summary.session_summary
+    });
+  }
+};
+
 // src/server/tools/restore_spec_file_from_trash.ts
-import { z as z12 } from "zod";
-var inputSchema12 = {
-  file_id: z12.string().min(1).describe("UUID of the spec file to restore from the Trash Bin.")
+import { z as z19 } from "zod";
+var inputSchema19 = {
+  file_id: z19.string().min(1).describe("UUID of the spec file to restore from the Trash Bin.")
 };
 var restoreSpecFileFromTrashTool = {
   name: "restore_spec_file_from_trash",
   description: "Restore a spec file from the Trash Bin back to the active file list, reversing `move_spec_file_to_trash`. The file becomes visible again to the default file list and AI-agent tools.",
-  inputSchema: inputSchema12,
+  inputSchema: inputSchema19,
   handler: async (args, ctx) => {
     await ctx.client.restoreFile(args.file_id);
     return jsonResult({ restored: true, file_id: args.file_id });
@@ -3450,34 +4015,58 @@ var restoreSpecFileFromTrashTool = {
 };
 
 // src/server/tools/unarchive_project.ts
-import { z as z13 } from "zod";
-var inputSchema13 = {
-  project_id: z13.string().min(1).describe("UUID of the project to unarchive.")
+import { z as z20 } from "zod";
+var inputSchema20 = {
+  project_id: z20.string().min(1).describe("UUID of the project to unarchive.")
 };
 var unarchiveProjectTool = {
   name: "unarchive_project",
   description: 'Unarchive a project (sets status to "active"). Idempotent: unarchiving an already-active project succeeds.',
-  inputSchema: inputSchema13,
+  inputSchema: inputSchema20,
   handler: async (args, ctx) => {
     const project = await ctx.client.unarchiveProject(args.project_id);
     return jsonResult({ project: projectSummary(project) });
   }
 };
 
+// src/server/tools/unarchive_spec_session.ts
+import { z as z21 } from "zod";
+var inputSchema21 = {
+  session_id: z21.string().min(1).describe("UUID of the spec session to unarchive")
+};
+var unarchiveSpecSessionTool = {
+  name: "unarchive_spec_session",
+  description: "Unarchive a spec session, returning it to the active list.",
+  inputSchema: inputSchema21,
+  handler: async (args, ctx) => {
+    let session;
+    try {
+      session = await ctx.client.unarchiveSpecSession(args.session_id);
+    } catch (err) {
+      const notFound = sessionNotFound(err, args.session_id);
+      if (notFound) {
+        return notFound;
+      }
+      throw err;
+    }
+    return jsonResult({ session: sessionMetadata(session) });
+  }
+};
+
 // src/server/tools/update_project.ts
-import { z as z14 } from "zod";
-var inputSchema14 = {
-  project_id: z14.string().min(1).describe("UUID of the project to update."),
-  name: z14.string().min(1).optional().describe("New project name."),
-  description: z14.string().optional().describe("New project description."),
-  project_type: z14.enum(["greenfield", "brownfield", "auto"]).optional().describe(
+import { z as z22 } from "zod";
+var inputSchema22 = {
+  project_id: z22.string().min(1).describe("UUID of the project to update."),
+  name: z22.string().min(1).optional().describe("New project name."),
+  description: z22.string().optional().describe("New project description."),
+  project_type: z22.enum(["greenfield", "brownfield", "auto"]).optional().describe(
     "Codebase type. 'greenfield' or 'brownfield' sets it explicitly; 'auto' clears it so the workflow decides. Omit to leave unchanged."
   )
 };
 var updateProjectTool = {
   name: "update_project",
   description: "Update a project's metadata (name, description, project_type). Returns the updated metadata.",
-  inputSchema: inputSchema14,
+  inputSchema: inputSchema22,
   handler: async (args, ctx) => {
     if (args.name === void 0 && args.description === void 0 && args.project_type === void 0) {
       return errorResult(
@@ -3500,7 +4089,7 @@ var updateProjectTool = {
 };
 
 // src/server/tools/update_spec_file.ts
-import { z as z15 } from "zod";
+import { z as z23 } from "zod";
 
 // src/server/tools/spec-content-source.ts
 import { readFile, stat } from "fs/promises";
@@ -3556,24 +4145,24 @@ async function resolveSpecContent(input, maxBytes = MAX_LOCAL_SPEC_FILE_BYTES) {
 }
 
 // src/server/tools/update_spec_file.ts
-var inputSchema15 = {
-  file_id: z15.string().min(1).optional().describe("UUID of the spec file to overwrite. Provide this or (project_id + file_path)."),
-  project_id: z15.string().min(1).optional().describe("UUID of the project. Required (with file_path) when file_id is not given."),
-  file_path: z15.string().min(1).optional().describe("Path of the spec file. Required (with project_id) when file_id is not given."),
-  content: z15.string().min(1).optional().describe(
+var inputSchema23 = {
+  file_id: z23.string().min(1).optional().describe("UUID of the spec file to overwrite. Provide this or (project_id + file_path)."),
+  project_id: z23.string().min(1).optional().describe("UUID of the project. Required (with file_path) when file_id is not given."),
+  file_path: z23.string().min(1).optional().describe("Path of the spec file. Required (with project_id) when file_id is not given."),
+  content: z23.string().min(1).optional().describe(
     "Full UTF-8 replacement content, saved as a new revision. Provide this OR local_file_path (exactly one). Use for in-memory / generated content."
   ),
-  local_file_path: z15.string().min(1).optional().describe(
+  local_file_path: z23.string().min(1).optional().describe(
     "Path to a local file whose bytes become the new revision; the server reads it directly. Provide this OR content (exactly one). Absolute paths are most reliable; a relative path resolves against the MCP server working directory. Point this only at an intended spec file \u2014 its bytes are uploaded to the project as-is; never use it for secrets or unrelated files."
   ),
-  expected_version: z15.number().int().nonnegative().optional().describe(
+  expected_version: z23.number().int().nonnegative().optional().describe(
     "The content_version the new body was based on, from the get_spec_file or read_spec_file you worked from. The update is rejected with an actionable error if someone else changed the file since. Omit only when overwriting unconditionally is genuinely intended \u2014 the project may be configured to reject unversioned updates."
   )
 };
 var updateSpecFileTool = {
   name: "update_spec_file",
   description: "Overwrite an existing spec file by saving a new revision. Provide the new body inline via `content` or by pointing at a local file with `local_file_path` \u2014 exactly one is required. Prefer `local_file_path` when the body is already an existing local file (the server reads it directly); use `content` for text generated in-memory. Reference the file by file_id or by (project_id + file_path). Pass `expected_version` from the get_spec_file you based the new body on so a concurrent edit by someone else is reported instead of silently overwritten.",
-  inputSchema: inputSchema15,
+  inputSchema: inputSchema23,
   handler: async (args, ctx) => {
     const resolved = await resolveSpecContent({
       content: args.content,
@@ -3638,9 +4227,9 @@ function conflictMessage(filePath, conflict) {
 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 z16 } from "zod";
+import { z as z24 } from "zod";
 var DEFAULT_MIME = "application/octet-stream";
-var MAX_ATTACHMENT_MB = MAX_ATTACHMENT_BYTES / (1024 * 1024);
+var MAX_ATTACHMENT_MB2 = MAX_ATTACHMENT_BYTES / (1024 * 1024);
 var STRUCTURED_EXTENSION_MIME = {
   ".pdf": "application/pdf",
   ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
@@ -3743,23 +4332,23 @@ function inferMimeFromName(name) {
   }
   return DEFAULT_MIME;
 }
-var inputSchema16 = {
-  project_id: z16.string().min(1).describe("UUID of the project to attach the file to."),
-  file_path: z16.string().min(1).describe(
+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(
     "Absolute path to the local file to upload. The MCP server reads this path from its own host."
   ),
-  file_name: z16.string().min(1).optional().describe("Override the filename recorded on the attachment. Defaults to the path basename."),
-  mime_type: z16.string().min(1).optional().describe(
+  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(
     "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: z16.boolean().optional().describe(
+  override: z24.boolean().optional().describe(
     "When true, any existing (non-deleted) attachment on the project whose recorded filename exactly matches `file_name` (or the path basename) is soft-deleted before the new upload, so the new attachment keeps the original name instead of getting an auto-dedup `(1)` suffix. The platform has no in-place content-replace API, so the new upload always gets a new `attachment_id`; any replaced ids are returned as `overridden_attachment_ids` (array, possibly empty) so callers can refresh stored references. Defaults to false (let the platform auto-dedup)."
   )
 };
 var uploadAttachmentTool = {
   name: "upload_attachment",
-  description: `Upload a local file as a new attachment on a project. Reads \`file_path\` from the host running the MCP server, computes its SHA256, then performs the two-phase platform upload. Max ${String(MAX_ATTACHMENT_MB)} MB. Supported content: PDF, DOCX, XLSX, images (PNG, JPEG, GIF, WEBP), and any UTF-8 text file (XML, JSON, YAML, HTML, SVG, Markdown, CSV, source code, ...). Other binary files are rejected by the platform.`,
-  inputSchema: inputSchema16,
+  description: `Upload a local file as a new attachment on a project. Reads \`file_path\` from the host running the MCP server, computes its SHA256, then performs the two-phase platform upload. Max ${String(MAX_ATTACHMENT_MB2)} MB. Supported content: PDF, DOCX, XLSX, images (PNG, JPEG, GIF, WEBP), and any UTF-8 text file (XML, JSON, YAML, HTML, SVG, Markdown, CSV, source code, ...). Other binary files are rejected by the platform.`,
+  inputSchema: inputSchema24,
   handler: async (args, ctx) => {
     if (!isAbsolute2(args.file_path)) {
       return errorResult(`file_path must be an absolute path; got "${args.file_path}".`);
@@ -3792,7 +4381,7 @@ var uploadAttachmentTool = {
     }
     if (stats.size > MAX_ATTACHMENT_BYTES) {
       return errorResult(
-        `File size ${String(stats.size)} bytes exceeds the ${String(MAX_ATTACHMENT_MB)} MB attachment limit.`
+        `File size ${String(stats.size)} bytes exceeds the ${String(MAX_ATTACHMENT_MB2)} MB attachment limit.`
       );
     }
     let buf;
@@ -3811,7 +4400,7 @@ var uploadAttachmentTool = {
     }
     if (buf.byteLength > MAX_ATTACHMENT_BYTES) {
       return errorResult(
-        `File size ${String(buf.byteLength)} bytes exceeds the ${String(MAX_ATTACHMENT_MB)} MB attachment limit.`
+        `File size ${String(buf.byteLength)} bytes exceeds the ${String(MAX_ATTACHMENT_MB2)} MB attachment limit.`
       );
     }
     const fileName = args.file_name ?? basename(args.file_path);
@@ -3883,7 +4472,7 @@ var uploadAttachmentTool = {
 };
 
 // src/server/tools/upload_spec_file.ts
-import { z as z17 } from "zod";
+import { z as z25 } from "zod";
 
 // src/server/spec-path.ts
 var MAX_SPEC_DIR_DEPTH = 3;
@@ -3936,23 +4525,23 @@ var SPEC_FILE_TYPES = [
   "proposal",
   "openspec-spec"
 ];
-var inputSchema17 = {
-  project_id: z17.string().min(1).describe("UUID of the project to upload the file into."),
-  file_path: z17.string().min(1).describe(
+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(
     '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: z17.string().min(1).optional().describe(
+  content: z25.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: z17.string().min(1).optional().describe(
+  local_file_path: z25.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: z17.enum(SPEC_FILE_TYPES).optional().describe("Spec file type. Omit to derive from the filename (e.g. proposal.md \u2192 proposal).")
+  file_type: z25.enum(SPEC_FILE_TYPES).optional().describe("Spec file type. Omit to derive from the filename (e.g. proposal.md \u2192 proposal).")
 };
 var uploadSpecFileTool = {
   name: "upload_spec_file",
   description: "Upload a new, session-less spec file into a project. Provide the file body inline via `content` or by pointing at a local file with `local_file_path` \u2014 exactly one is required. Prefer `local_file_path` when the body is already an existing local file (the server reads it directly, avoiding sending large content through the model); use `content` for text generated in-memory. Rejects if a file already exists at the same path (use update_spec_file to overwrite).",
-  inputSchema: inputSchema17,
+  inputSchema: inputSchema25,
   handler: async (args, ctx) => {
     const pathError = validateSpecFilePath(args.file_path);
     if (pathError) {
@@ -4005,6 +4594,14 @@ function buildServer(deps) {
   registerTool(server, updateSpecFileTool, deps.client);
   registerTool(server, moveSpecFileToTrashTool, deps.client);
   registerTool(server, restoreSpecFileFromTrashTool, deps.client);
+  registerTool(server, listAttachmentsTool, deps.client);
+  registerTool(server, readAttachmentTool, deps.client);
+  registerTool(server, listSpecSessionsTool, deps.client);
+  registerTool(server, getSpecSessionTool, deps.client);
+  registerTool(server, renameSpecSessionTool, deps.client);
+  registerTool(server, archiveSpecSessionTool, deps.client);
+  registerTool(server, unarchiveSpecSessionTool, deps.client);
+  registerTool(server, deleteSpecSessionTool, deps.client);
   return server;
 }
 async function startStdioServer(deps) {
@@ -4158,7 +4755,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 z18 } from "zod";
+import { z as z26 } from "zod";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // src/reverse/ignore.ts
@@ -4255,7 +4852,7 @@ var PackCache = class {
       if (oldestKey === void 0) break;
       this.entries.delete(oldestKey);
     }
-    const lines = splitIntoLines(content);
+    const lines = splitIntoLines2(content);
     const pages = planPages(lines);
     const entry = {
       outputId,
@@ -4283,7 +4880,7 @@ var PackCache = class {
     }
   }
 };
-function splitIntoLines(text) {
+function splitIntoLines2(text) {
   const normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
   const parts = normalized.split("\n");
   if (parts.length > 0 && parts[parts.length - 1] === "") parts.pop();
@@ -4463,37 +5060,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 = z18.object({
-  path: z18.string(),
-  recursive: z18.boolean().optional(),
-  maxEntries: z18.number().int().positive().optional(),
-  includeIgnored: z18.boolean().optional()
+var listDirInput = z26.object({
+  path: z26.string(),
+  recursive: z26.boolean().optional(),
+  maxEntries: z26.number().int().positive().optional(),
+  includeIgnored: z26.boolean().optional()
 });
-var readFileInput = z18.object({
-  path: z18.string(),
-  offset: z18.number().int().nonnegative().optional(),
-  limit: z18.number().int().positive().optional(),
-  includeIgnored: z18.boolean().optional()
+var readFileInput = z26.object({
+  path: z26.string(),
+  offset: z26.number().int().nonnegative().optional(),
+  limit: z26.number().int().positive().optional(),
+  includeIgnored: z26.boolean().optional()
 });
-var grepInput = z18.object({
-  pattern: z18.string().describe(
+var grepInput = z26.object({
+  pattern: z26.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: z18.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
-  isRegex: z18.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
-  caseSensitive: z18.boolean().optional(),
-  maxMatches: z18.number().int().positive().optional(),
-  contextLines: z18.number().int().nonnegative().optional(),
-  includeIgnored: z18.boolean().optional()
+  path: z26.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
+  isRegex: z26.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
+  caseSensitive: z26.boolean().optional(),
+  maxMatches: z26.number().int().positive().optional(),
+  contextLines: z26.number().int().nonnegative().optional(),
+  includeIgnored: z26.boolean().optional()
 });
-var packCodebaseInput = z18.object({
-  subpath: z18.string().optional(),
-  includePatterns: z18.string().optional(),
-  ignorePatterns: z18.string().optional()
+var packCodebaseInput = z26.object({
+  subpath: z26.string().optional(),
+  includePatterns: z26.string().optional(),
+  ignorePatterns: z26.string().optional()
 });
-var packCodebaseReadPageInput = z18.object({
-  outputId: z18.string(),
-  page: z18.number().int().positive()
+var packCodebaseReadPageInput = z26.object({
+  outputId: z26.string(),
+  page: z26.number().int().positive()
 });
 function structuredError(error, message, extra) {
   const payload = { error, message, ...extra ?? {} };
@@ -4609,19 +5206,19 @@ async function handleRead(args, opts) {
       `Binary content detected in ${args.path}; line-based pagination doesn't apply. Skip this file or use local_fs_grep on neighbouring text files.`
     );
   }
-  const text = normalizeNewlines(raw.toString("utf-8"));
-  const lines = splitIntoLines2(text);
+  const text = normalizeNewlines2(raw.toString("utf-8"));
+  const lines = splitIntoLines3(text);
   const page = paginateLines(lines, args.offset, args.limit);
   if ("error" in page) {
     return structuredError("invalid_offset", page.error);
   }
   return structuredOk(page);
 }
-function normalizeNewlines(s) {
+function normalizeNewlines2(s) {
   const noBom = s.charCodeAt(0) === 65279 ? s.slice(1) : s;
   return noBom.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
 }
-function splitIntoLines2(text) {
+function splitIntoLines3(text) {
   const parts = text.split("\n");
   if (parts.length > 0 && parts[parts.length - 1] === "") parts.pop();
   return parts;
@@ -4934,7 +5531,7 @@ function registerLocalFsTools(server, opts) {
     },
     {
       name: "local_pack_codebase",
-      description: "Pack the entire local codebase (under the granted --root) into a single XML bundle using `npx repomix@latest --style xml --compress`. Prefer this over many `local_fs_read_file` calls when you need broad codebase context. Output is paginated at ~2500 lines per page; a `<file>` block is never split across a page boundary, but the `<files>` root wrapper spans pages (its opener is on the first files page and its closer on the last) \u2014 always keep reading while `hasMore` is true rather than stopping at a `</files>`. The response includes `outputId`, `page`, `totalPages`, `totalLines`, `pageLines`, `hasMore`, and a `nextPage` hint. Use `local_pack_codebase_read_page` to fetch subsequent pages by `outputId`. Repeat calls with the same `subpath`/`includePatterns`/`ignorePatterns` return the same `outputId` and are served instantly from the 30-minute cache without re-running repomix.",
+      description: "Pack the local codebase (under the granted --root) into a single compressed XML bundle (embedded repomix, `--style xml --compress`; file bodies use `\u22EE----` delimiters). Prefer this over many `local_fs_read_file` calls when you need broad codebase context. Output is paginated at ~2500 lines per page; a `<file>` block is never split across a page boundary, but the `<files>` root wrapper spans pages (its opener is on the first files page and its closer on the last) \u2014 never treat a missing `</files>` as truncation. The response includes `outputId`, `page`, `totalPages`, `totalLines`, `pageLines`, `hasMore`, and a `nextPage` hint; page 1 opens with the full directory structure. Fetch further pages with `local_pack_codebase_read_page` while `totalPages` is small; for a large pack (roughly 10+ pages) do NOT page through everything \u2014 use page 1 as the repo map, then re-pack narrowed with `subpath`/`includePatterns` or switch to `local_fs_grep`/`local_fs_read_file` for targeted reads. Repeat calls with the same `subpath`/`includePatterns`/`ignorePatterns` return the same `outputId` and are served instantly from the 30-minute cache without re-running repomix.",
       inputSchema: jsonSchemaFromZod(packCodebaseInput),
       handler: async (args) => {
         try {
@@ -4947,7 +5544,7 @@ function registerLocalFsTools(server, opts) {
     },
     {
       name: "local_pack_codebase_read_page",
-      description: "Read a specific page of a previously packed codebase output. Provide the `outputId` returned by `local_pack_codebase` and the 1-indexed `page` to fetch. Each page is up to ~2500 lines of XML; no `<file>` block is split across pages, but the `<files>` root wrapper spans pages \u2014 keep fetching while `hasMore` is true, do not stop at a `</files>`. Cache entries expire after 30 minutes; on cache miss, re-run `local_pack_codebase` (same args return the same outputId \u2014 re-pack is cheap, served from cache).",
+      description: "Read a specific page of a previously packed codebase output. Provide the `outputId` returned by `local_pack_codebase` and the 1-indexed `page` to fetch. Each page is up to ~2500 lines of the compressed XML bundle; no `<file>` block is split across pages, but the `<files>` root wrapper spans pages \u2014 never treat a missing `</files>` as truncation. Cache entries expire after 30 minutes; on cache miss, re-run `local_pack_codebase` (same args return the same outputId \u2014 re-pack is cheap, served from cache).",
       inputSchema: jsonSchemaFromZod(packCodebaseReadPageInput),
       handler: (args) => {
         try {
@@ -5021,7 +5618,7 @@ function jsonSchemaFromZod(schema) {
   return zodToJson(schema);
 }
 function zodToJson(schema) {
-  if (schema instanceof z18.ZodObject) {
+  if (schema instanceof z26.ZodObject) {
     const shape = schema.shape;
     const properties = {};
     const required = [];
@@ -5036,19 +5633,19 @@ function zodToJson(schema) {
     if (required.length > 0) out.required = required;
     return out;
   }
-  if (schema instanceof z18.ZodOptional) {
+  if (schema instanceof z26.ZodOptional) {
     return zodToJson(schema.unwrap());
   }
-  if (schema instanceof z18.ZodString) {
+  if (schema instanceof z26.ZodString) {
     return { type: "string" };
   }
-  if (schema instanceof z18.ZodNumber) {
+  if (schema instanceof z26.ZodNumber) {
     return { type: "number" };
   }
-  if (schema instanceof z18.ZodBoolean) {
+  if (schema instanceof z26.ZodBoolean) {
     return { type: "boolean" };
   }
-  if (schema instanceof z18.ZodEnum) {
+  if (schema instanceof z26.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.95",
+  "version": "0.4.0-next.97",
   "description": "MySpec MCP server — exposes MySpec platform projects, files and attachments to MCP-aware clients via OAuth-authenticated access tokens.",
   "type": "module",
   "repository": {