@myspec/mcp-server 0.4.0-next.98 → 0.4.0

package/README.md

@@ -291,9 +291,9 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 | `list_projects` | `query?`, `limit?`, `offset?` | Paginated list of projects |
 | `get_project` | `project_id` | Project + active sessions + files + attachments |
 | `get_spec_file` | `file_id`, optional `include_download_url` | File metadata, including `content_version` (see [Concurrent edits](#concurrent-edits-content_version)); with `include_download_url=N` also returns a download URL targeting revision `N` |
-| `read_spec_file` | `file_id`, optional `revision` | UTF-8 content of the file, plus `content_version` when reading the latest revision (errors for binary or files > 1 MiB — use `download_spec_file` for those). Cached on disk under `MYSPEC_DOWNLOAD_ROOT` |
+| `read_spec_file` | `file_id`, optional `revision`, optional `offset`, optional `limit` | UTF-8 content paginated by line (`offset` is 1-based, default/cap 2000 lines, 1 MiB per response) with `content`, `start_line`, `end_line`, `read_lines`, `total_lines`, `truncated`, `next_offset`; plus `content_version` when reading the latest revision (errors for binary or files > 8 MiB — use `download_spec_file` for those). Cached on disk under `MYSPEC_DOWNLOAD_ROOT`, so paging through a file downloads it once |
 | `download_spec_file` | `file_id`, optional `destination_path`, optional `revision`, optional `overwrite` | Downloads the file's raw bytes to a local file — by default under `.specs/` in the working directory (see [Download destinations](#download-destinations)). Handles binary files and files up to 50 MiB. Refuses to replace an existing file unless `overwrite=true`. Returns only metadata (`saved_path`, `bytes_written`, `revision_number`, `destination_source`) — **not** the content, so a large file can be saved locally and read in chunks |
-| `list_spec_file` | `project_id`, optional `path`, optional `trashed` | Lists a project's spec files (`file_id`, `file_path`, `file_type`, `file_size_bytes`, `revision_count`, `session_id`, `updated_at`). Filter to a directory with `path` (exact file or everything under it; `""`/`"/"`/omit = all). `trashed=true` lists the Trash Bin instead of live files |
+| `list_spec_file` | `project_id`, optional `path`, optional `trashed`, optional `limit`, optional `offset` | Lists a project's spec files (`file_id`, `file_path`, `file_type`, `file_size_bytes`, `revision_count`, `session_id`, `updated_at`, plus `trashed_at` on Trash Bin entries). Filter to a directory with `path` (exact file or everything under it; `""`/`"/"`/omit = all). `trashed=true` lists the Trash Bin instead of live files. Returns `total`, `limit`, `offset` and, when more records remain, `next_offset` (default 50, capped at 200). Ordered by `file_path` when `path` or `trashed` is given, most-recently-created first otherwise |
 | `move_spec_file_to_trash` | `file_id` | Moves a spec file to the Trash Bin (recoverable — hidden from listings and AI-agent tools, restorable indefinitely). Not a permanent delete |
 | `restore_spec_file_from_trash` | `file_id` | Restores a trashed spec file back to the active file list, reversing `move_spec_file_to_trash` |
 | `get_attachment` | `attachment_id`, optional `include_download_url` | Attachment metadata (looked up org-scoped by id); with `include_download_url>0` also returns a signed download URL |
@@ -306,6 +306,12 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 | `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 |
+| `list_artifacts` | `project_id`, optional `limit`, optional `offset` | Paginated list of a project's live artifacts — multi-file bundles (an HTML mockup: `index.html` + `styles.css` + `app.js` + assets) the platform versions as ONE snapshot. Each entry carries `revision_count`, the head number and the `expected_version` to pass when writing |
+| `get_artifact` | `artifact_id`, optional `revision` | Artifact metadata plus the file manifest (path, content type, size, checksum) of the head revision, or of `revision` |
+| `read_artifact_file` | `artifact_id`, `path`, optional `revision`, optional `offset`, optional `limit` | One file's UTF-8 content paginated by line (same `content`/`total_lines`/`truncated`/`next_offset` shape as `read_attachment`); binary files are refused |
+| `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 |
 
 ### Download destinations
 

package/dist/index.js

@@ -32,10 +32,11 @@ var REFRESH_TOKEN_PATTERN = /"refreshToken"\s*:\s*"[^"]+"/g;
 var API_TOKEN_PATTERN = /"apiToken"\s*:\s*"[^"]+"/g;
 var API_TOKEN_VALUE_PATTERN = /\bmsp_pat_[A-Za-z0-9]+/g;
 var ACCESS_TOKEN_PATTERN = /"accessToken"\s*:\s*"[^"]+"/g;
-var SNAKE_TOKEN_PATTERN = /"(access_token|refresh_token|id_token)"\s*:\s*"[^"]+"/g;
+var SNAKE_TOKEN_PATTERN = /"(access_token|refresh_token|id_token|token)"\s*:\s*"[^"]+"/g;
 var JWT_PATTERN = /\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
+var STREAM_URL_PATTERN = /\/realtime\/v1\/stream\/[A-Za-z0-9_-]{20,}/g;
 function redactSensitive(value) {
-  return value.replace(BEARER_PATTERN, "Bearer [REDACTED]").replace(REFRESH_TOKEN_PATTERN, '"refreshToken":"[REDACTED]"').replace(API_TOKEN_PATTERN, '"apiToken":"[REDACTED]"').replace(API_TOKEN_VALUE_PATTERN, "[REDACTED_API_TOKEN]").replace(ACCESS_TOKEN_PATTERN, '"accessToken":"[REDACTED]"').replace(SNAKE_TOKEN_PATTERN, (_match, key) => `"${key}":"[REDACTED]"`).replace(JWT_PATTERN, "[REDACTED_JWT]");
+  return value.replace(BEARER_PATTERN, "Bearer [REDACTED]").replace(REFRESH_TOKEN_PATTERN, '"refreshToken":"[REDACTED]"').replace(API_TOKEN_PATTERN, '"apiToken":"[REDACTED]"').replace(API_TOKEN_VALUE_PATTERN, "[REDACTED_API_TOKEN]").replace(ACCESS_TOKEN_PATTERN, '"accessToken":"[REDACTED]"').replace(SNAKE_TOKEN_PATTERN, (_match, key) => `"${key}":"[REDACTED]"`).replace(JWT_PATTERN, "[REDACTED_JWT]").replace(STREAM_URL_PATTERN, "/realtime/v1/stream/[REDACTED_STREAM_TOKEN]");
 }
 var ConfigError = class extends Error {
   constructor(message) {
@@ -1349,7 +1350,10 @@ var KNOWN_CONFLICT_REASONS = [
   "revision_mismatch",
   "path_taken",
   "precondition_required",
-  "precondition_malformed"
+  "precondition_malformed",
+  "slug_taken",
+  "blob_reclaimed",
+  "lock_timeout"
 ];
 var PlatformHttpError = class extends Error {
   status;
@@ -2436,6 +2440,404 @@ var HttpSpecSessionClient = class {
   }
 };
 
+// ../../packages/platform-client/artifact/types/artifact.types.ts
+function transformArtifactResponse(raw) {
+  return {
+    id: raw.id,
+    projectId: raw.project_id,
+    org: raw.org,
+    sessionId: raw.session_id ?? null,
+    kind: raw.kind,
+    name: raw.name,
+    slug: raw.slug,
+    description: raw.description ?? "",
+    entryPath: raw.entry_path,
+    revisionCount: raw.revision_count,
+    createdBy: raw.created_by,
+    createdAt: new Date(raw.created_at),
+    updatedAt: new Date(raw.updated_at),
+    trashedAt: raw.trashed_at ? new Date(raw.trashed_at) : void 0,
+    deletedAt: raw.deleted_at ? new Date(raw.deleted_at) : void 0
+  };
+}
+function transformArtifactRevisionResponse(raw) {
+  return {
+    id: raw.id,
+    artifactId: raw.artifact_id,
+    revisionNumber: raw.revision_number,
+    source: raw.source,
+    restoredFromRevision: raw.restored_from_revision,
+    message: raw.message ?? "",
+    changedBy: raw.changed_by,
+    changedByKind: raw.changed_by_kind === "ai" ? "ai" : "human",
+    sessionId: raw.session_id ?? null,
+    fileCount: raw.file_count,
+    totalBytes: raw.total_bytes,
+    manifestChecksum: raw.manifest_checksum,
+    createdAt: new Date(raw.created_at)
+  };
+}
+function transformArtifactFileEntry(raw) {
+  return {
+    path: raw.path,
+    contentType: raw.content_type,
+    sizeBytes: raw.size_bytes,
+    checksum: raw.checksum
+  };
+}
+function transformArtifactRevisionDetail(raw) {
+  return {
+    ...transformArtifactRevisionResponse(raw),
+    files: (raw.files ?? []).map(transformArtifactFileEntry)
+  };
+}
+function transformArtifactDetail(raw) {
+  return {
+    artifact: transformArtifactResponse(raw.artifact),
+    head: transformArtifactRevisionDetail(raw.head)
+  };
+}
+function transformArtifactWriteResult(raw) {
+  return {
+    artifact: transformArtifactResponse(raw.artifact),
+    revision: transformArtifactRevisionDetail(raw.revision),
+    noChange: raw.no_change === true
+  };
+}
+function transformArtifactListResult(raw) {
+  return {
+    items: (raw.items ?? []).map(transformArtifactResponse),
+    total: raw.total,
+    limit: raw.limit,
+    offset: raw.offset
+  };
+}
+function transformArtifactRevisionListResult(raw) {
+  return {
+    items: (raw.items ?? []).map(transformArtifactRevisionResponse),
+    total: raw.total,
+    limit: raw.limit,
+    offset: raw.offset
+  };
+}
+function buildFilesBody(files) {
+  return files.map((f) => {
+    const body = { path: f.path, content: f.content };
+    if (f.encoding) {
+      body.encoding = f.encoding;
+    }
+    if (f.contentType) {
+      body.content_type = f.contentType;
+    }
+    return body;
+  });
+}
+function buildCreateArtifactBody(request) {
+  const body = {
+    name: request.name,
+    files: buildFilesBody(request.files)
+  };
+  if (request.slug) body.slug = request.slug;
+  if (request.kind) body.kind = request.kind;
+  if (request.description !== void 0) body.description = request.description;
+  if (request.entryPath) body.entry_path = request.entryPath;
+  if (request.message) body.message = request.message;
+  if (request.sessionId) body.session_id = request.sessionId;
+  return body;
+}
+function buildCreateArtifactRevisionBody(request) {
+  const body = { files: buildFilesBody(request.files) };
+  if (request.message) body.message = request.message;
+  if (request.baseRevision !== void 0) body.base_revision = request.baseRevision;
+  if (request.remove && request.remove.length > 0) body.remove = request.remove;
+  if (request.entryPath) body.entry_path = request.entryPath;
+  if (request.sessionId) body.session_id = request.sessionId;
+  return body;
+}
+function buildRollbackArtifactBody(request) {
+  const body = { revision_number: request.revisionNumber };
+  if (request.message) body.message = request.message;
+  if (request.sessionId) body.session_id = request.sessionId;
+  return body;
+}
+function buildUpdateArtifactBody(request) {
+  const body = {};
+  if (request.name !== void 0) body.name = request.name;
+  if (request.description !== void 0) body.description = request.description;
+  if (request.entryPath !== void 0) body.entry_path = request.entryPath;
+  return body;
+}
+
+// ../../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";
+function 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;
+}
+function requestOptions(headers) {
+  return Object.keys(headers).length > 0 ? { headers } : {};
+}
+function encodeArtifactPath(path4) {
+  return path4.split("/").map(encodeURIComponent).join("/");
+}
+function paginationQuery(opts) {
+  const params = new URLSearchParams();
+  if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+  if (opts?.offset !== void 0) params.set("offset", String(opts.offset));
+  if (opts?.kind) params.set("kind", opts.kind);
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}
+var HttpArtifactClient = class {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  async createArtifact(projectId, request, jwtToken, opts) {
+    const raw = await this.httpClient.post(
+      `${BASE_PATH}/projects/${projectId}/artifacts`,
+      buildCreateArtifactBody(request),
+      jwtToken,
+      requestOptions(writeHeaders(opts))
+    );
+    return transformArtifactWriteResult(raw);
+  }
+  async listArtifacts(projectId, jwtToken, opts) {
+    const raw = await this.httpClient.get(
+      `${BASE_PATH}/projects/${projectId}/artifacts${paginationQuery(opts)}`,
+      jwtToken,
+      {}
+    );
+    return transformArtifactListResult(raw);
+  }
+  async listTrashedArtifacts(projectId, jwtToken) {
+    const raw = await this.httpClient.get(
+      `${BASE_PATH}/projects/${projectId}/artifacts/trashed`,
+      jwtToken,
+      {}
+    );
+    return (raw.items ?? []).map(transformArtifactResponse);
+  }
+  async getArtifact(artifactId, jwtToken) {
+    const raw = await this.httpClient.get(
+      `${BASE_PATH}/artifacts/${artifactId}`,
+      jwtToken,
+      {}
+    );
+    return transformArtifactDetail(raw);
+  }
+  async updateArtifact(artifactId, request, jwtToken) {
+    const raw = await this.httpClient.patch(
+      `${BASE_PATH}/artifacts/${artifactId}`,
+      buildUpdateArtifactBody(request),
+      jwtToken,
+      {}
+    );
+    return transformArtifactResponse(raw);
+  }
+  async trashArtifact(artifactId, jwtToken) {
+    await this.httpClient.delete(`${BASE_PATH}/artifacts/${artifactId}`, jwtToken, {});
+  }
+  async restoreArtifact(artifactId, jwtToken) {
+    await this.httpClient.post(
+      `${BASE_PATH}/artifacts/${artifactId}/restore`,
+      {},
+      jwtToken,
+      {}
+    );
+  }
+  async deleteArtifactPermanently(artifactId, jwtToken) {
+    await this.httpClient.delete(
+      `${BASE_PATH}/artifacts/${artifactId}/permanent`,
+      jwtToken,
+      {}
+    );
+  }
+  async createRevision(artifactId, request, jwtToken, opts) {
+    const raw = await this.httpClient.post(
+      `${BASE_PATH}/artifacts/${artifactId}/revisions`,
+      buildCreateArtifactRevisionBody(request),
+      jwtToken,
+      requestOptions(writeHeaders(opts))
+    );
+    return transformArtifactWriteResult(raw);
+  }
+  async rollback(artifactId, request, jwtToken, opts) {
+    const raw = await this.httpClient.post(
+      `${BASE_PATH}/artifacts/${artifactId}/rollback`,
+      buildRollbackArtifactBody(request),
+      jwtToken,
+      requestOptions(writeHeaders(opts))
+    );
+    return transformArtifactWriteResult(raw);
+  }
+  async listRevisions(artifactId, jwtToken, opts) {
+    const raw = await this.httpClient.get(
+      `${BASE_PATH}/artifacts/${artifactId}/revisions${paginationQuery(opts)}`,
+      jwtToken,
+      {}
+    );
+    return transformArtifactRevisionListResult(raw);
+  }
+  async getRevision(artifactId, revisionNumber, jwtToken) {
+    const raw = await this.httpClient.get(
+      `${BASE_PATH}/artifacts/${artifactId}/revisions/${revisionNumber}`,
+      jwtToken,
+      {}
+    );
+    return transformArtifactRevisionDetail(raw);
+  }
+  fileUrl(artifactId, path4, revision) {
+    const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
+    const encoded = encodeArtifactPath(path4);
+    return revision === void 0 ? `${baseUrl}${BASE_PATH}/artifacts/${artifactId}/files/${encoded}` : `${baseUrl}${BASE_PATH}/artifacts/${artifactId}/revisions/${revision}/files/${encoded}`;
+  }
+  async downloadFile(artifactId, path4, jwtToken, opts) {
+    const response = await fetch(this.fileUrl(artifactId, path4, opts?.revision), {
+      method: "GET",
+      headers: { Authorization: `Bearer ${jwtToken}` }
+    });
+    if (!response.ok) {
+      await throwFromResponse(response, "Artifact file download failed");
+    }
+    const buffer = await response.arrayBuffer();
+    return {
+      content: new Uint8Array(buffer),
+      contentType: response.headers.get("Content-Type") ?? "application/octet-stream",
+      checksum: (response.headers.get("ETag") ?? "").replace(/"/g, "").trim()
+    };
+  }
+};
+
+// ../../packages/platform-client/stream/types/stream-token.types.ts
+function optionalDate(value) {
+  return value ? new Date(value) : null;
+}
+function transformStreamToken(raw) {
+  return {
+    id: raw.id,
+    tokenPrefix: raw.token_prefix,
+    label: raw.label ?? "",
+    resourceType: raw.resource_type,
+    resourceId: raw.resource_id,
+    eventTypes: raw.event_types ?? [],
+    createdBy: raw.created_by,
+    createdAt: new Date(raw.created_at),
+    expiresAt: new Date(raw.expires_at),
+    revokedAt: optionalDate(raw.revoked_at),
+    resourceDeletedAt: optionalDate(raw.resource_deleted_at),
+    lastConnectedAt: optionalDate(raw.last_connected_at),
+    connectCount: raw.connect_count,
+    live: raw.live
+  };
+}
+function transformStreamTokenMintResult(raw) {
+  if (!raw.token || !raw.url) {
+    throw new Error("stream token mint response carried no token or url");
+  }
+  return { ...transformStreamToken(raw), token: raw.token, url: raw.url };
+}
+function transformStreamTokenListResult(raw) {
+  return {
+    tokens: (raw.tokens ?? []).map(transformStreamToken),
+    total: raw.total ?? 0
+  };
+}
+function transformStreamCatalogue(raw) {
+  return {
+    resources: (raw.resources ?? []).map((resource) => ({
+      resourceType: resource.resource_type,
+      eventTypes: resource.event_types ?? []
+    })),
+    maxTtlSeconds: raw.max_ttl_seconds,
+    defaultTtlSeconds: raw.default_ttl_seconds
+  };
+}
+function buildCreateStreamTokenBody(request) {
+  const body = {
+    resource_type: request.resourceType,
+    resource_id: request.resourceId
+  };
+  body.event_types = request.eventTypes;
+  if (request.ttlSeconds !== void 0) {
+    body.ttl_seconds = request.ttlSeconds;
+  }
+  if (request.label) {
+    body.label = request.label;
+  }
+  return body;
+}
+
+// ../../packages/platform-client/stream/http/stream-token.http-client.ts
+var BASE_PATH2 = "/realtime/v1";
+function requestOptions2(options) {
+  return options ?? {};
+}
+var HttpStreamTokenClient = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  httpClient;
+  async createStreamToken(request, jwtToken, options) {
+    const raw = await this.httpClient.post(
+      `${BASE_PATH2}/stream-tokens`,
+      buildCreateStreamTokenBody(request),
+      jwtToken,
+      requestOptions2(options)
+    );
+    return transformStreamTokenMintResult(raw);
+  }
+  async listStreamTokens(options, jwtToken, httpOptions) {
+    const query = new URLSearchParams();
+    if (options?.resourceId) {
+      query.set("resource_id", options.resourceId);
+    }
+    if (options?.liveOnly) {
+      query.set("live", "true");
+    }
+    if (options?.mineOnly) {
+      query.set("mine", "true");
+    }
+    if (options?.limit !== void 0) {
+      query.set("limit", String(options.limit));
+    }
+    if (options?.offset !== void 0) {
+      query.set("offset", String(options.offset));
+    }
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+    const raw = await this.httpClient.get(
+      `${BASE_PATH2}/stream-tokens${suffix}`,
+      jwtToken,
+      requestOptions2(httpOptions)
+    );
+    return transformStreamTokenListResult(raw);
+  }
+  async revokeStreamToken(id, jwtToken, options) {
+    const raw = await this.httpClient.delete(
+      `${BASE_PATH2}/stream-tokens/${encodeURIComponent(id)}`,
+      jwtToken,
+      requestOptions2(options)
+    );
+    return transformStreamToken(raw);
+  }
+  async getStreamCatalogue(jwtToken, options) {
+    const raw = await this.httpClient.get(
+      `${BASE_PATH2}/stream-catalogue`,
+      jwtToken,
+      requestOptions2(options)
+    );
+    return transformStreamCatalogue(raw);
+  }
+};
+
 // src/platform/client.ts
 var silentLogger = {
   debug: () => void 0,
@@ -2722,9 +3124,58 @@ var PlatformClient = class {
       project: new HttpProjectClient(httpClient),
       session: new HttpSpecSessionClient(httpClient),
       file: new HttpFileClient(httpClient),
-      attachment: new HttpAttachmentClient(httpClient)
+      attachment: new HttpAttachmentClient(httpClient),
+      artifact: new HttpArtifactClient(httpClient),
+      streamToken: new HttpStreamTokenClient(httpClient)
     };
   }
+  // ------------------------------------------------------- stream tokens
+  //
+  // A stream token is a presigned WebSocket URL for a project's event feed —
+  // the URL is the whole credential, which is what lets a tool that takes one
+  // string and nothing else consume the feed.
+  async createStreamToken(request) {
+    return this.withTokenRetry((jwt, c) => c.streamToken.createStreamToken(request, jwt));
+  }
+  async listStreamTokens(opts = {}) {
+    return this.withTokenRetry((jwt, c) => c.streamToken.listStreamTokens(opts, jwt));
+  }
+  async revokeStreamToken(id) {
+    return this.withTokenRetry((jwt, c) => c.streamToken.revokeStreamToken(id, jwt));
+  }
+  // ----------------------------------------------------------- artifacts
+  //
+  // Every write is attributed `actorKind: 'ai'`: an MCP client is an
+  // assistant acting on the user's behalf, exactly as for spec files.
+  async listArtifacts(projectId, opts = {}) {
+    return this.withTokenRetry((jwt, c) => c.artifact.listArtifacts(projectId, jwt, opts));
+  }
+  async getArtifact(artifactId) {
+    return this.withTokenRetry((jwt, c) => c.artifact.getArtifact(artifactId, jwt));
+  }
+  async getArtifactRevision(artifactId, revisionNumber) {
+    return this.withTokenRetry((jwt, c) => c.artifact.getRevision(artifactId, revisionNumber, jwt));
+  }
+  async downloadArtifactFile(artifactId, path4, revision) {
+    return this.withTokenRetry(
+      (jwt, c) => c.artifact.downloadFile(artifactId, path4, jwt, revision === void 0 ? void 0 : { revision })
+    );
+  }
+  async createArtifact(projectId, request) {
+    return this.withTokenRetry(
+      (jwt, c) => c.artifact.createArtifact(projectId, request, jwt, { actorKind: "ai" })
+    );
+  }
+  async createArtifactRevision(artifactId, request, expectedVersion) {
+    return this.withTokenRetry(
+      (jwt, c) => c.artifact.createRevision(artifactId, request, jwt, { expectedVersion, actorKind: "ai" })
+    );
+  }
+  async rollbackArtifact(artifactId, request, expectedVersion) {
+    return this.withTokenRetry(
+      (jwt, c) => c.artifact.rollback(artifactId, request, jwt, { expectedVersion, actorKind: "ai" })
+    );
+  }
   async withTokenRetry(call) {
     const clients = await this.clients();
     const jwt = await this.tokenManager.getValidAccessToken();
@@ -3479,6 +3930,9 @@ function sliceWindow(items, limit, offset) {
   };
 }
 function nextOffsetOf(offset, returned, total) {
+  if (returned === 0) {
+    return void 0;
+  }
   const end = offset + returned;
   return end < total ? end : void 0;
 }
@@ -3556,6 +4010,8 @@ var listProjectsTool = {
 // src/server/tools/list_spec_file.ts
 import { z as z13 } from "zod";
 var PAGE_SIZE = 100;
+var LIST_DEFAULT2 = 50;
+var LIST_MAX2 = 200;
 var inputSchema13 = {
   project_id: z13.string().min(1).describe("UUID of the project whose spec files to list."),
   path: z13.string().optional().describe(
@@ -3563,26 +4019,57 @@ var inputSchema13 = {
   ),
   trashed: z13.boolean().optional().describe(
     "When true, list files in the project Trash Bin instead. When false or omitted, list only live files (trashed files excluded)."
-  )
+  ),
+  limit: z13.number().int().positive().optional().describe(
+    `Max files to return (default ${String(LIST_DEFAULT2)}, capped at ${String(LIST_MAX2)}).`
+  ),
+  offset: z13.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
 };
 var listSpecFileTool = {
   name: "list_spec_file",
-  description: 'List a project\'s spec files with id, path, and metadata (revision count, file size of the latest revision, file type, owning session, last update). Filter to a directory with `path` (exact file or everything under it; pass "", "/", or omit for all). Set `trashed=true` to list files in the Trash Bin instead of live files.',
+  description: 'List a project\'s spec files with id, path, and metadata (revision count, file size of the latest revision, file type, owning session, last update). Filter to a directory with `path` (exact file or everything under it; pass "", "/", or omit for all). Set `trashed=true` to list files in the Trash Bin instead of live files. Ordered by `file_path` ascending whenever `path` or `trashed` is given, most-recently-created first otherwise. Returns `total` and, when more records remain, `next_offset`.',
   inputSchema: inputSchema13,
   handler: async (args, ctx) => {
     const trashed = args.trashed ?? false;
-    const files = trashed ? await ctx.client.listTrashedFiles(args.project_id) : await listAllLiveFiles(ctx.client, args.project_id);
+    const limit = clampLimit(args.limit, LIST_DEFAULT2, LIST_MAX2);
+    const offset = args.offset ?? 0;
     const prefix = normalizePrefix(args.path);
-    const matches = files.filter((f) => isUnderPath(f.filePath, prefix)).map(toEntry).sort((a, b) => a.file_path.localeCompare(b.file_path));
-    return jsonResult({
-      project_id: args.project_id,
-      path: prefix,
-      trashed,
-      total: matches.length,
-      files: matches
-    });
+    if (trashed) {
+      const all2 = await ctx.client.listTrashedFiles(args.project_id);
+      return windowedListResult(args.project_id, prefix, true, all2, limit, offset);
+    }
+    if (prefix === "") {
+      const page = await ctx.client.listFiles(args.project_id, { limit, offset });
+      const next = nextOffsetOf(offset, page.files.length, page.total);
+      return jsonResult({
+        project_id: args.project_id,
+        path: prefix,
+        trashed: false,
+        files: page.files.map(toEntry),
+        total: page.total,
+        limit,
+        offset,
+        ...next === void 0 ? {} : { next_offset: next }
+      });
+    }
+    const all = await listAllLiveFiles(ctx.client, args.project_id);
+    return windowedListResult(args.project_id, prefix, false, all, limit, offset);
   }
 };
+function windowedListResult(projectId, prefix, trashed, files, limit, offset) {
+  const matches = files.filter((f) => isUnderPath(f.filePath, prefix)).map(toEntry).sort((a, b) => a.file_path.localeCompare(b.file_path));
+  const window = sliceWindow(matches, limit, offset);
+  return jsonResult({
+    project_id: projectId,
+    path: prefix,
+    trashed,
+    files: window.items,
+    total: window.total,
+    limit: window.limit,
+    offset,
+    ...window.next_offset === void 0 ? {} : { next_offset: window.next_offset }
+  });
+}
 async function listAllLiveFiles(client, projectId) {
   const all = [];
   let offset = 0;
@@ -3626,24 +4113,24 @@ function isUnderPath(filePath, prefix) {
 
 // src/server/tools/list_spec_sessions.ts
 import { z as z14 } from "zod";
-var LIST_DEFAULT2 = 10;
-var LIST_MAX2 = 20;
+var LIST_DEFAULT3 = 10;
+var LIST_MAX3 = 20;
 var inputSchema14 = {
   project_id: z14.string().min(1).describe("UUID of the project whose spec sessions to list."),
   archive_filter: z14.enum(["active", "archived", "all"]).optional().describe("Which sessions to list: 'active' (default), 'archived', or 'all'."),
   status: z14.enum(["generating", "pending_input", "completed"]).optional().describe("Filter by session status."),
   query: z14.string().optional().describe("Search term matched against the session summary."),
   limit: z14.number().int().positive().optional().describe(
-    `Max sessions to return (default ${String(LIST_DEFAULT2)}, capped at ${String(LIST_MAX2)}).`
+    `Max sessions to return (default ${String(LIST_DEFAULT3)}, capped at ${String(LIST_MAX3)}).`
   ),
   offset: z14.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
 };
 var listSpecSessionsTool = {
   name: "list_spec_sessions",
-  description: `List a project's spec sessions (metadata plus session_summary and context_size_bytes \u2014 never the context itself or the chat transcript). Filter with archive_filter ('active'/'archived'/'all'), status, and query (searches the session summary). Capped at ${String(LIST_MAX2)} per page; returns \`total\` and \`next_offset\`.`,
+  description: `List a project's spec sessions (metadata plus session_summary and context_size_bytes \u2014 never the context itself or the chat transcript). Filter with archive_filter ('active'/'archived'/'all'), status, and query (searches the session summary). Capped at ${String(LIST_MAX3)} per page; returns \`total\` and \`next_offset\`.`,
   inputSchema: inputSchema14,
   handler: async (args, ctx) => {
-    const limit = clampLimit(args.limit, LIST_DEFAULT2, LIST_MAX2);
+    const limit = clampLimit(args.limit, LIST_DEFAULT3, LIST_MAX3);
     const offset = args.offset ?? 0;
     const result = await ctx.client.listProjectSessions(args.project_id, {
       archiveFilter: args.archive_filter ?? "active",
@@ -3694,6 +4181,9 @@ var MAX_LINES_PER_CALL = 2e3;
 var MAX_RESPONSE_BYTES = 1 * 1024 * 1024;
 function normalizeNewlines(text) {
   const withoutBom = text.startsWith("\uFEFF") ? text.slice(1) : text;
+  if (!withoutBom.includes("\r")) {
+    return withoutBom;
+  }
   return withoutBom.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
 }
 function splitIntoLines(text) {
@@ -3864,20 +4354,27 @@ var readAttachmentTool = {
 import { promises as fs3 } from "fs";
 import { createHash as createHash2 } from "crypto";
 import { z as z17 } from "zod";
-var MAX_READ_BYTES = 1 * 1024 * 1024;
+var MAX_READABLE_SPEC_FILE_BYTES = 8 * 1024 * 1024;
 var inputSchema17 = {
   file_id: z17.string().min(1).describe("UUID of the file"),
-  revision: z17.number().int().positive().optional().describe("Specific revision number to read (defaults to the latest revision).")
+  revision: z17.number().int().positive().optional().describe("Specific revision number to read (defaults to the latest revision)."),
+  offset: z17.number().int().nonnegative().optional().describe("1-based line number to start reading from (default 1; 0 is an alias for 1)."),
+  limit: z17.number().int().positive().optional().describe("Max lines to return (default 2000, capped at 2000; larger values are clamped).")
 };
 var readSpecFileTool = {
   name: "read_spec_file",
-  description: "Return a spec file's UTF-8 content. Bytes are cached on disk under the configured cache root (default ~/.myspec) at `project/<projectId>/file/<fileId>/rev/<rev>/<basename>` and reused on subsequent reads of the same revision. Fails for binary files or files larger than 1 MiB \u2014 use download_spec_file to save those to a local file instead.",
+  description: "Return a window of a spec file's UTF-8 content, paginated by line (offset/limit, default and cap 2000 lines, 1 MiB per response). Large files are read across multiple calls using `next_offset`. Bytes are cached on disk under the configured cache root (default ~/.myspec) at `project/<projectId>/file/<fileId>/rev/<rev>/<basename>` and reused on subsequent reads of the same revision, so paging through a file downloads it once. Files above 8 MiB and binary content are refused \u2014 use download_spec_file to save those to a local file instead.",
   inputSchema: inputSchema17,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
     const targetRevision = args.revision ?? meta.revisionCount;
     const isLatestRevision = targetRevision === meta.revisionCount;
-    if (isLatestRevision && meta.fileSizeBytes > MAX_READ_BYTES) {
+    if (args.revision !== void 0 && args.revision > meta.revisionCount) {
+      return errorResult(
+        `revision=${String(args.revision)} is greater than revision_count=${String(meta.revisionCount)} for file ${args.file_id}.`
+      );
+    }
+    if (isLatestRevision && meta.fileSizeBytes > MAX_READABLE_SPEC_FILE_BYTES) {
       return errorResult(buildOversizeMessage2(args.file_id, meta.fileSizeBytes));
     }
     const cacheRoot = resolveDownloadRoot();
@@ -3894,20 +4391,42 @@ var readSpecFileTool = {
         `read_spec_file refused to write cache: ${escape}. This indicates an unexpected platform response shape (projectId/fileId/filePath).`
       );
     }
-    const cached = await pathExists(cachePath) ? await fs3.readFile(cachePath) : null;
+    const cachedSize = await fileSizeOrNull(cachePath);
+    if (cachedSize !== null && cachedSize > MAX_READABLE_SPEC_FILE_BYTES) {
+      return errorResult(buildOversizeMessage2(args.file_id, cachedSize));
+    }
+    const cached = cachedSize === null ? null : await fs3.readFile(cachePath);
     const cacheHit = cached !== null && (!isLatestRevision || sha256Prefixed2(cached) === meta.checksum);
     let bytes;
+    let effectiveRevision = targetRevision;
+    let effectiveCachePath = cachePath;
     if (cacheHit) {
       bytes = cached;
     } else {
       const downloaded = await ctx.client.downloadFile(args.file_id, args.revision);
       bytes = downloaded.bytes;
-      if (bytes.byteLength > MAX_READ_BYTES) {
+      if (bytes.byteLength > MAX_READABLE_SPEC_FILE_BYTES) {
         return errorResult(buildOversizeMessage2(args.file_id, bytes.byteLength));
       }
-      await writeBytesAtomically(cachePath, bytes);
+      if (downloaded.revisionNumber !== targetRevision) {
+        effectiveRevision = downloaded.revisionNumber;
+        effectiveCachePath = computeFileCachePath({
+          cacheRoot,
+          projectId: meta.projectId,
+          fileId: meta.id,
+          revision: effectiveRevision,
+          filePath: meta.filePath
+        });
+        const raceEscape = assertWithinRoot(effectiveCachePath, cacheRoot);
+        if (raceEscape) {
+          return errorResult(
+            `read_spec_file refused to write cache: ${raceEscape}. This indicates an unexpected platform response shape (projectId/fileId/filePath).`
+          );
+        }
+      }
+      await writeBytesAtomically(effectiveCachePath, bytes);
     }
-    if (bytes.byteLength > MAX_READ_BYTES) {
+    if (bytes.byteLength > MAX_READABLE_SPEC_FILE_BYTES) {
       return errorResult(buildOversizeMessage2(args.file_id, bytes.byteLength));
     }
     if (isBinary2(bytes)) {
@@ -3923,25 +4442,44 @@ var readSpecFileTool = {
         `File ${args.file_id} is not valid UTF-8 text. Use download_spec_file to save it to a local file.`
       );
     }
+    const paginated = paginateText(text, args.offset, args.limit);
+    if (!paginated.ok) {
+      return errorResult(paginated.error);
+    }
     return jsonResult({
       file_id: meta.id,
-      revision_number: targetRevision,
+      revision_number: effectiveRevision,
       // Pass this back as update_spec_file's expected_version so an edit made by
       // someone else since this read is reported instead of overwritten. It
       // describes the file's CURRENT content, so it is emitted only when that is
       // what was read — beside a historical revision it would invite an update
       // that overwrites everything written since.
-      ...isLatestRevision && meta.contentVersion !== void 0 ? { content_version: meta.contentVersion } : {},
+      // ...and only when it describes THESE bytes. If a concurrent save moved
+      // the revision under us, meta.contentVersion belongs to the older one:
+      // a stale token is fail-safe (the platform answers 409) but it would
+      // cost the model a round trip it cannot diagnose, so omit it and let the
+      // re-read supply a current one.
+      ...isLatestRevision && effectiveRevision === targetRevision && meta.contentVersion !== void 0 ? { content_version: meta.contentVersion } : {},
       file_path: meta.filePath,
       file_type: meta.fileType,
-      cache_path: maskHomedir(cachePath),
+      cache_path: maskHomedir(effectiveCachePath),
       cache_hit: cacheHit,
-      content: text
+      // `content` plus the window fields (start_line/end_line/read_lines/
+      // total_lines/truncated/next_offset) — the same shape read_attachment
+      // and mcp-server-http's read_spec_file return.
+      ...paginated.window
     });
   }
 };
 function buildOversizeMessage2(fileId, byteLength) {
-  return `File ${fileId} is ${String(byteLength)} bytes which exceeds the read cap of ${String(MAX_READ_BYTES)} bytes. Use download_spec_file to save it to a local file and read it in chunks.`;
+  return `File ${fileId} is ${String(byteLength)} bytes which exceeds the read cap of ${String(MAX_READABLE_SPEC_FILE_BYTES)} bytes. Use download_spec_file to save it to a local file and read it in chunks.`;
+}
+async function fileSizeOrNull(filePath) {
+  try {
+    return (await fs3.stat(filePath)).size;
+  } catch {
+    return null;
+  }
 }
 function isBinary2(bytes) {
   for (const byte of bytes) {
@@ -4571,6 +5109,434 @@ var uploadSpecFileTool = {
   }
 };
 
+// src/server/tools/list_artifacts.ts
+import { z as z27 } 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.")
+  })
+).describe("Files of the bundle.");
+function artifactSummary(a) {
+  return {
+    id: a.id,
+    project_id: a.projectId,
+    name: a.name,
+    slug: a.slug,
+    kind: a.kind,
+    description: a.description,
+    entry_path: a.entryPath,
+    revision_count: a.revisionCount,
+    session_id: a.sessionId,
+    created_by: a.createdBy,
+    created_at: a.createdAt,
+    updated_at: a.updatedAt,
+    ...a.trashedAt ? { trashed_at: a.trashedAt } : {}
+  };
+}
+function fileEntry(f) {
+  return { path: f.path, content_type: f.contentType, size_bytes: f.sizeBytes, checksum: f.checksum };
+}
+function revisionSummary(r) {
+  return {
+    id: r.id,
+    revision_number: r.revisionNumber,
+    source: r.source,
+    ...r.restoredFromRevision === void 0 ? {} : { restored_from_revision: r.restoredFromRevision },
+    message: r.message,
+    changed_by: r.changedBy,
+    changed_by_kind: r.changedByKind,
+    file_count: r.fileCount,
+    total_bytes: r.totalBytes,
+    manifest_checksum: r.manifestChecksum,
+    created_at: r.createdAt,
+    ..."files" in r ? { files: r.files.map(fileEntry) } : {}
+  };
+}
+function writeResultOutput(result) {
+  return {
+    artifact: artifactSummary(result.artifact),
+    revision: revisionSummary(result.revision),
+    no_change: result.noChange
+  };
+}
+function isArtifactWriteConflict(conflict) {
+  return conflict.reason === "revision_mismatch" || conflict.reason === "blob_reclaimed" || conflict.reason === "lock_timeout" || conflict.reason === "unknown";
+}
+function artifactConflictMessage(artifactId, conflict) {
+  if (conflict.reason === "lock_timeout") {
+    return `Artifact ${artifactId} was NOT written: another write or a storage collection held its lock and this call timed out waiting. Nothing changed \u2014 retry the same call as-is.`;
+  }
+  if (conflict.reason === "blob_reclaimed") {
+    return `Artifact ${artifactId} was NOT written: a file this write relied on from an older revision is no longer stored (that revision was pruned). Call get_artifact to read the current head, then resend the full content of every file (a full snapshot, or a patch based on the head).`;
+  }
+  const head = conflict.currentVersion === void 0 ? "" : ` The head is now revision ${String(conflict.currentVersion)}.`;
+  return `Artifact ${artifactId} was NOT written: it changed since the revision this write was based on.${head} Call get_artifact to read the current head, reapply your change to it, and retry with expected_version (or base_revision) set to that head.`;
+}
+function artifactCreateConflictMessage(conflict) {
+  if (conflict.reason === "slug_taken") {
+    return "Artifact was NOT created: the slug is already taken in this project (trashed artifacts keep their slug). Pick another slug, or call list_artifacts to find the existing artifact and write a new revision to it instead.";
+  }
+  if (conflict.reason === "lock_timeout") {
+    return "Artifact was NOT created: the platform timed out waiting for a lock. Nothing changed \u2014 retry the same call as-is.";
+  }
+  return `Artifact was NOT created: the platform reported a conflict (${conflict.reason}). Re-read the project's artifacts with list_artifacts before retrying.`;
+}
+
+// src/server/tools/list_artifacts.ts
+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).")
+};
+var listArtifactsTool = {
+  name: "list_artifacts",
+  description: "List a project's live artifacts (multi-file bundles such as HTML mockups, each versioned as one snapshot) with id, slug, entry path and revision_count. Returns `total` and, when more remain, `next_offset`. Use get_artifact for the file manifest and read_artifact_file for content.",
+  inputSchema: inputSchema26,
+  handler: async (args, ctx) => {
+    const limit = clampLimit(args.limit, LIST_DEFAULT4, LIST_MAX4);
+    const offset = args.offset ?? 0;
+    const page = await ctx.client.listArtifacts(args.project_id, { limit, offset });
+    const next = nextOffsetOf(offset, page.items.length, page.total);
+    return jsonResult({
+      project_id: args.project_id,
+      artifacts: page.items.map(artifactSummary),
+      total: page.total,
+      limit,
+      offset,
+      ...next === void 0 ? {} : { next_offset: next }
+    });
+  }
+};
+
+// src/server/tools/get_artifact.ts
+import { z as z28 } 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).")
+};
+var getArtifactTool = {
+  name: "get_artifact",
+  description: "Get an artifact's metadata plus the file manifest (path, content type, size, checksum of every file) of its head revision, or of `revision` when given. `revision_count` is the head number AND the value to pass as expected_version when writing; it only ever grows because rollback appends a revision rather than discarding history.",
+  inputSchema: inputSchema27,
+  handler: async (args, ctx) => {
+    const detail = await ctx.client.getArtifact(args.artifact_id);
+    if (args.revision === void 0) {
+      return jsonResult({ artifact: artifactSummary(detail.artifact), revision: revisionSummary(detail.head) });
+    }
+    if (args.revision > detail.artifact.revisionCount) {
+      return errorResult(
+        `revision=${String(args.revision)} is greater than revision_count=${String(detail.artifact.revisionCount)} for artifact ${args.artifact_id}.`
+      );
+    }
+    const revision = await ctx.client.getArtifactRevision(args.artifact_id, args.revision);
+    return jsonResult({ artifact: artifactSummary(detail.artifact), revision: revisionSummary(revision) });
+  }
+};
+
+// src/server/tools/read_artifact_file.ts
+import { z as z29 } 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).")
+};
+var readArtifactFileTool = {
+  name: "read_artifact_file",
+  description: "Return one artifact file's UTF-8 content, paginated by line (offset/limit, default and cap 2000 lines, 1 MiB per response) with `total_lines`, `truncated` and `next_offset`. Reads the head revision unless `revision` is given. Binary files (images, fonts) cannot be read through this tool; get_artifact lists their size and checksum.",
+  inputSchema: inputSchema28,
+  handler: async (args, ctx) => {
+    const file = await ctx.client.downloadArtifactFile(args.artifact_id, args.path, args.revision);
+    if (file.content.byteLength > MAX_READABLE_ARTIFACT_FILE_BYTES) {
+      return errorResult(
+        `File ${args.path} of artifact ${args.artifact_id} is ${String(file.content.byteLength)} bytes, above the ${String(MAX_READABLE_ARTIFACT_FILE_BYTES)}-byte read ceiling.`
+      );
+    }
+    if (isBinary(file.content)) {
+      return errorResult(
+        `File ${args.path} of artifact ${args.artifact_id} appears to be binary (content_type=${file.contentType}, size=${String(file.content.byteLength)} bytes) and cannot be read through this tool.`
+      );
+    }
+    const text = decodeUtf8Strict(file.content);
+    if (text === null) {
+      return errorResult(
+        `File ${args.path} of artifact ${args.artifact_id} is not valid UTF-8 text (content_type=${file.contentType}).`
+      );
+    }
+    const paginated = paginateText(text, args.offset, args.limit);
+    if (!paginated.ok) {
+      return errorResult(paginated.error);
+    }
+    return jsonResult({
+      artifact_id: args.artifact_id,
+      path: args.path,
+      ...args.revision === void 0 ? {} : { revision_number: args.revision },
+      content_type: file.contentType,
+      checksum: file.checksum,
+      ...paginated.window
+    });
+  }
+};
+
+// src/server/tools/create_artifact.ts
+import { z as z30 } 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)."),
+  files: artifactFilesSchema
+};
+var createArtifactTool = {
+  name: "create_artifact",
+  description: "Create an artifact \u2014 a bundle of files (e.g. an HTML mockup: index.html + styles.css + app.js) the platform versions AS ONE snapshot \u2014 with the given files as revision 1. At most 50 files, 2 MiB per file, 10 MiB per revision. Fails with a conflict when the slug is already taken in the project (trashed artifacts still own their slug).",
+  inputSchema: inputSchema29,
+  handler: async (args, ctx) => {
+    try {
+      const result = await ctx.client.createArtifact(args.project_id, {
+        name: args.name,
+        slug: args.slug,
+        description: args.description,
+        entryPath: args.entry_path,
+        message: args.message,
+        files: args.files.map((f) => ({
+          path: f.path,
+          content: f.content,
+          encoding: f.encoding,
+          contentType: f.content_type
+        }))
+      });
+      return jsonResult(writeResultOutput(result));
+    } catch (err) {
+      const conflict = conflictOf(err);
+      if (conflict) {
+        return errorResult(artifactCreateConflictMessage(conflict));
+      }
+      throw err;
+    }
+  }
+};
+
+// src/server/tools/write_artifact_revision.ts
+import { z as z31 } from "zod";
+var inputSchema30 = {
+  artifact_id: z31.string().min(1).describe("UUID of the artifact."),
+  files: artifactFilesSchema,
+  base_revision: z31.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(
+    "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.")
+};
+var writeArtifactRevisionTool = {
+  name: "write_artifact_revision",
+  description: "Write a new revision of an artifact. FULL mode (no base_revision): `files` becomes the whole bundle. PATCH mode (base_revision set): only the changed files are sent, plus `remove` for paths to drop \u2014 the platform stores the complete result either way. Every revision is immutable; the newest N are retained (50 by default, set by the platform; older ones are pruned); use rollback_artifact to restore an earlier one. Read the current head with get_artifact first and pass its revision_count as expected_version.",
+  inputSchema: inputSchema30,
+  handler: async (args, ctx) => {
+    if (args.remove && args.remove.length > 0 && args.base_revision === void 0) {
+      return errorResult("`remove` is only valid in patch mode: set base_revision to the revision you are editing.");
+    }
+    try {
+      const result = await ctx.client.createArtifactRevision(
+        args.artifact_id,
+        {
+          files: args.files.map((f) => ({
+            path: f.path,
+            content: f.content,
+            encoding: f.encoding,
+            contentType: f.content_type
+          })),
+          remove: args.remove,
+          baseRevision: args.base_revision,
+          message: args.message,
+          entryPath: args.entry_path
+        },
+        args.expected_version
+      );
+      return jsonResult(writeResultOutput(result));
+    } catch (err) {
+      const conflict = conflictOf(err);
+      if (!conflict || !isArtifactWriteConflict(conflict)) {
+        throw err;
+      }
+      return errorResult(artifactConflictMessage(args.artifact_id, conflict));
+    }
+  }
+};
+
+// src/server/tools/rollback_artifact.ts
+import { z as z32 } 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".')
+};
+var rollbackArtifactTool = {
+  name: "rollback_artifact",
+  description: "Restore an earlier revision of an artifact. Like `git revert`, this APPENDS a new revision whose files equal the chosen one \u2014 history is never rewritten, and the new head is revision_count + 1. Only the newest N revisions are retained (50 by default, set by the platform): older ones are pruned, and rolling back to a pruned revision fails with not found \u2014 list the revisions (get_artifact) first when in doubt. Rolling back to the head itself is allowed and recorded with no_change=true.",
+  inputSchema: inputSchema31,
+  handler: async (args, ctx) => {
+    try {
+      const result = await ctx.client.rollbackArtifact(
+        args.artifact_id,
+        { revisionNumber: args.revision_number, message: args.message },
+        args.expected_version
+      );
+      return jsonResult(writeResultOutput(result));
+    } catch (err) {
+      const conflict = conflictOf(err);
+      if (!conflict || !isArtifactWriteConflict(conflict)) {
+        throw err;
+      }
+      return errorResult(artifactConflictMessage(args.artifact_id, conflict));
+    }
+  }
+};
+
+// src/server/tools/create_stream_token.ts
+import { z as z34 } from "zod";
+
+// src/server/tools/stream-token-output.ts
+import { z as z33 } from "zod";
+var projectStreamEventTypes = [
+  "project.updated",
+  "project.deleted",
+  "spec_file.created",
+  "spec_file.updated",
+  "spec_file.deleted",
+  "spec_file.lock",
+  "attachment.created",
+  "attachment.deleted",
+  "spec_session.created",
+  "spec_session.updated",
+  "spec_session.deleted",
+  "*"
+];
+var streamEventTypesSchema = z33.array(z33.enum(projectStreamEventTypes)).min(1).describe(
+  'Event types to receive. Required \u2014 pass ["*"] to follow all of them. spec_file.updated covers new revisions, rollbacks, and moves to or from the trash; spec_file.lock covers acquire, renew, release and takeover; spec_session.updated covers completion, archive, unarchive and rename.'
+);
+function streamTokenSummary(token) {
+  return {
+    id: token.id,
+    token_prefix: token.tokenPrefix,
+    label: token.label,
+    resource_type: token.resourceType,
+    resource_id: token.resourceId,
+    event_types: token.eventTypes,
+    created_by: token.createdBy,
+    created_at: token.createdAt.toISOString(),
+    expires_at: token.expiresAt.toISOString(),
+    live: token.live,
+    connect_count: token.connectCount,
+    ...token.revokedAt ? { revoked_at: token.revokedAt.toISOString() } : {},
+    ...token.resourceDeletedAt ? { resource_deleted_at: token.resourceDeletedAt.toISOString() } : {},
+    ...token.lastConnectedAt ? { last_connected_at: token.lastConnectedAt.toISOString() } : {}
+  };
+}
+function streamTokenMintOutput(result) {
+  return {
+    ...streamTokenSummary(result),
+    url: result.url,
+    note: "Treat this URL as a password: anyone who has it can read this project's events until it expires, with no further authentication. Pass it straight to a WebSocket client and do NOT write it to a file, a commit, an issue or a chat reply, and do not log or repeat it. It is shown once and cannot be retrieved again. If it may have been exposed, call revoke_stream_token with the id above. Open it with subprotocol 'v1'; each text frame is one JSON event, and reconnecting with ?after=<seq> resumes from the last frame you saw."
+  };
+}
+
+// src/server/tools/create_stream_token.ts
+var inputSchema32 = {
+  resource_type: z34.enum(["project"]).default("project").describe("What to follow. Only 'project' is supported today."),
+  resource_id: z34.string().min(1).describe("UUID of the project to stream events for."),
+  event_types: streamEventTypesSchema,
+  ttl_seconds: z34.number().int().positive().optional().describe(
+    "How long the URL stays valid. Defaults to 24 hours, capped at 7 days. Out-of-range values are clamped rather than rejected \u2014 check expires_at in the result."
+  ),
+  label: z34.string().optional().describe("Short human-readable label, so a person can recognise this token in a listing.")
+};
+var createStreamTokenTool = {
+  name: "create_stream_token",
+  description: "Create a short-lived WebSocket URL that streams a project's events in real time \u2014 like an S3 presigned URL, the returned URL is the whole credential and needs no auth header. Choose the project and the event types to follow; the result carries the full wss:// URL. Feed it to any WebSocket client with subprotocol 'v1' (for example Claude Code's Monitor tool). Each text frame is one JSON event carrying a `seq` cursor; reconnect with ?after=<seq> to resume without missing events. Defaults to 24 hours, 7 days maximum. TREAT THE RETURNED URL LIKE A PASSWORD: anyone holding it can read every event on this project until it expires, without authenticating. Pass it directly to the WebSocket client; never write it to a file, a commit, an issue or a chat reply, and never log or repeat it. It is shown once and cannot be retrieved again. If it may have been exposed, revoke it at once with revoke_stream_token \u2014 that is also how you end one early. Prefer the shortest ttl_seconds that covers the work.",
+  inputSchema: inputSchema32,
+  handler: async (args, ctx) => {
+    const result = await ctx.client.createStreamToken({
+      resourceType: args.resource_type,
+      resourceId: args.resource_id,
+      eventTypes: args.event_types,
+      ttlSeconds: args.ttl_seconds,
+      label: args.label
+    });
+    return jsonResult(streamTokenMintOutput(result));
+  }
+};
+
+// src/server/tools/list_stream_tokens.ts
+import { z as z35 } from "zod";
+var LIST_DEFAULT5 = 50;
+var LIST_MAX5 = 200;
+var inputSchema33 = {
+  resource_id: z35.string().optional().describe("Only tokens following this project."),
+  live_only: z35.boolean().optional().describe("Hide expired and revoked tokens."),
+  mine_only: z35.boolean().optional().describe(
+    "Only tokens you created. Off by default, so a leaked URL can be found \u2014 note that revoking one you did not mint needs the organisation owner or admin role."
+  ),
+  limit: z35.number().int().positive().optional().describe(`Max tokens to return (default ${String(LIST_DEFAULT5)}, capped at ${String(LIST_MAX5)}).`),
+  offset: z35.number().int().nonnegative().optional().describe("Pagination offset (default 0).")
+};
+var listStreamTokensTool = {
+  name: "list_stream_tokens",
+  description: "List the stream tokens in your organisation, with their scope, expiry and whether each is still live. Secrets are never returned \u2014 only a short prefix to tell tokens apart. Returns `total` and, when more remain, `next_offset`.",
+  inputSchema: inputSchema33,
+  handler: async (args, ctx) => {
+    const limit = clampLimit(args.limit, LIST_DEFAULT5, LIST_MAX5);
+    const offset = args.offset ?? 0;
+    const page = await ctx.client.listStreamTokens({
+      resourceId: args.resource_id,
+      liveOnly: args.live_only,
+      mineOnly: args.mine_only,
+      limit,
+      offset
+    });
+    const next = nextOffsetOf(offset, page.tokens.length, page.total);
+    return jsonResult({
+      tokens: page.tokens.map(streamTokenSummary),
+      total: page.total,
+      limit,
+      offset,
+      ...next === void 0 ? {} : { next_offset: next }
+    });
+  }
+};
+
+// src/server/tools/revoke_stream_token.ts
+import { z as z36 } from "zod";
+var inputSchema34 = {
+  id: z36.string().min(1).describe("Token id (from create_stream_token or list_stream_tokens) \u2014 NOT the secret itself.")
+};
+var revokeStreamTokenTool = {
+  name: "revoke_stream_token",
+  description: "Revoke a stream token immediately, closing its URL and deleting the events buffered for it. Use this as soon as a stream is no longer needed, or if its URL may have leaked \u2014 the URL is the credential, so revoking is the only way to stop it before it expires. Revoking a token you minted yourself always works. Revoking one somebody ELSE minted additionally requires the organisation owner or admin role, and is refused with 403 otherwise \u2014 so when hunting a leaked URL you did not create, expect that refusal and ask an organisation owner or admin rather than retrying.",
+  inputSchema: inputSchema34,
+  handler: async (args, ctx) => {
+    const token = await ctx.client.revokeStreamToken(args.id);
+    return jsonResult({ ...streamTokenSummary(token), revoked: true });
+  }
+};
+
 // src/server/server.ts
 function buildServer(deps) {
   const server = new McpServer({
@@ -4602,6 +5568,15 @@ function buildServer(deps) {
   registerTool(server, archiveSpecSessionTool, deps.client);
   registerTool(server, unarchiveSpecSessionTool, deps.client);
   registerTool(server, deleteSpecSessionTool, deps.client);
+  registerTool(server, listArtifactsTool, deps.client);
+  registerTool(server, getArtifactTool, deps.client);
+  registerTool(server, readArtifactFileTool, deps.client);
+  registerTool(server, createArtifactTool, deps.client);
+  registerTool(server, writeArtifactRevisionTool, deps.client);
+  registerTool(server, rollbackArtifactTool, deps.client);
+  registerTool(server, createStreamTokenTool, deps.client);
+  registerTool(server, listStreamTokensTool, deps.client);
+  registerTool(server, revokeStreamTokenTool, deps.client);
   return server;
 }
 async function startStdioServer(deps) {
@@ -4755,7 +5730,7 @@ async function canonicaliseRoot(root) {
 import { promises as fs4 } from "fs";
 import { join as join2, relative } from "path";
 import { spawn } from "child_process";
-import { z as z26 } from "zod";
+import { z as z37 } from "zod";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // src/reverse/ignore.ts
@@ -5060,37 +6035,37 @@ var READ_FILE_MAX_LINES = 2e3;
 var LIST_DIR_HARD_CAP = 5e3;
 var LIST_DIR_DEFAULT_CAP = 1e3;
 var GREP_MAX_MATCHES_DEFAULT = 200;
-var listDirInput = z26.object({
-  path: z26.string(),
-  recursive: z26.boolean().optional(),
-  maxEntries: z26.number().int().positive().optional(),
-  includeIgnored: z26.boolean().optional()
+var listDirInput = z37.object({
+  path: z37.string(),
+  recursive: z37.boolean().optional(),
+  maxEntries: z37.number().int().positive().optional(),
+  includeIgnored: z37.boolean().optional()
 });
-var readFileInput = z26.object({
-  path: z26.string(),
-  offset: z26.number().int().nonnegative().optional(),
-  limit: z26.number().int().positive().optional(),
-  includeIgnored: z26.boolean().optional()
+var readFileInput = z37.object({
+  path: z37.string(),
+  offset: z37.number().int().nonnegative().optional(),
+  limit: z37.number().int().positive().optional(),
+  includeIgnored: z37.boolean().optional()
 });
-var grepInput = z26.object({
-  pattern: z26.string().describe(
+var grepInput = z37.object({
+  pattern: z37.string().describe(
     "Search pattern. Interpreted as a regular expression by default (ripgrep syntax), e.g. `foo|bar` or `[Rr]ole`. Set `isRegex: false` to match the pattern as an exact literal string instead."
   ),
-  path: 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()
+  path: z37.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
+  isRegex: z37.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
+  caseSensitive: z37.boolean().optional(),
+  maxMatches: z37.number().int().positive().optional(),
+  contextLines: z37.number().int().nonnegative().optional(),
+  includeIgnored: z37.boolean().optional()
 });
-var packCodebaseInput = z26.object({
-  subpath: z26.string().optional(),
-  includePatterns: z26.string().optional(),
-  ignorePatterns: z26.string().optional()
+var packCodebaseInput = z37.object({
+  subpath: z37.string().optional(),
+  includePatterns: z37.string().optional(),
+  ignorePatterns: z37.string().optional()
 });
-var packCodebaseReadPageInput = z26.object({
-  outputId: z26.string(),
-  page: z26.number().int().positive()
+var packCodebaseReadPageInput = z37.object({
+  outputId: z37.string(),
+  page: z37.number().int().positive()
 });
 function structuredError(error, message, extra) {
   const payload = { error, message, ...extra ?? {} };
@@ -5618,7 +6593,7 @@ function jsonSchemaFromZod(schema) {
   return zodToJson(schema);
 }
 function zodToJson(schema) {
-  if (schema instanceof z26.ZodObject) {
+  if (schema instanceof z37.ZodObject) {
     const shape = schema.shape;
     const properties = {};
     const required = [];
@@ -5633,19 +6608,19 @@ function zodToJson(schema) {
     if (required.length > 0) out.required = required;
     return out;
   }
-  if (schema instanceof z26.ZodOptional) {
+  if (schema instanceof z37.ZodOptional) {
     return zodToJson(schema.unwrap());
   }
-  if (schema instanceof z26.ZodString) {
+  if (schema instanceof z37.ZodString) {
     return { type: "string" };
   }
-  if (schema instanceof z26.ZodNumber) {
+  if (schema instanceof z37.ZodNumber) {
     return { type: "number" };
   }
-  if (schema instanceof z26.ZodBoolean) {
+  if (schema instanceof z37.ZodBoolean) {
     return { type: "boolean" };
   }
-  if (schema instanceof z26.ZodEnum) {
+  if (schema instanceof z37.ZodEnum) {
     return { type: "string", enum: schema.options };
   }
   return { type: "string" };

package/package.json

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