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

package/README.md

@@ -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

@@ -1349,7 +1349,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 +2439,283 @@ 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()
+    };
+  }
+};
+
 // src/platform/client.ts
 var silentLogger = {
   debug: () => void 0,
@@ -2722,9 +3002,43 @@ 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)
     };
   }
+  // ----------------------------------------------------------- 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();
@@ -4571,6 +4885,307 @@ 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_DEFAULT3 = 50;
+var LIST_MAX3 = 100;
+var inputSchema26 = {
+  project_id: z27.string().min(1).describe("UUID of the project whose artifacts to list."),
+  limit: z27.number().int().positive().optional().describe(`Max artifacts to return (default ${String(LIST_DEFAULT3)}, capped at ${String(LIST_MAX3)}).`),
+  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_DEFAULT3, LIST_MAX3);
+    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/server.ts
 function buildServer(deps) {
   const server = new McpServer({
@@ -4602,6 +5217,12 @@ 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);
   return server;
 }
 async function startStdioServer(deps) {
@@ -4755,7 +5376,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 z33 } from "zod";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // src/reverse/ignore.ts
@@ -5060,37 +5681,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 = z33.object({
+  path: z33.string(),
+  recursive: z33.boolean().optional(),
+  maxEntries: z33.number().int().positive().optional(),
+  includeIgnored: z33.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 = z33.object({
+  path: z33.string(),
+  offset: z33.number().int().nonnegative().optional(),
+  limit: z33.number().int().positive().optional(),
+  includeIgnored: z33.boolean().optional()
 });
-var grepInput = z26.object({
-  pattern: z26.string().describe(
+var grepInput = z33.object({
+  pattern: z33.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: z33.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
+  isRegex: z33.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
+  caseSensitive: z33.boolean().optional(),
+  maxMatches: z33.number().int().positive().optional(),
+  contextLines: z33.number().int().nonnegative().optional(),
+  includeIgnored: z33.boolean().optional()
 });
-var packCodebaseInput = z26.object({
-  subpath: z26.string().optional(),
-  includePatterns: z26.string().optional(),
-  ignorePatterns: z26.string().optional()
+var packCodebaseInput = z33.object({
+  subpath: z33.string().optional(),
+  includePatterns: z33.string().optional(),
+  ignorePatterns: z33.string().optional()
 });
-var packCodebaseReadPageInput = z26.object({
-  outputId: z26.string(),
-  page: z26.number().int().positive()
+var packCodebaseReadPageInput = z33.object({
+  outputId: z33.string(),
+  page: z33.number().int().positive()
 });
 function structuredError(error, message, extra) {
   const payload = { error, message, ...extra ?? {} };
@@ -5618,7 +6239,7 @@ function jsonSchemaFromZod(schema) {
   return zodToJson(schema);
 }
 function zodToJson(schema) {
-  if (schema instanceof z26.ZodObject) {
+  if (schema instanceof z33.ZodObject) {
     const shape = schema.shape;
     const properties = {};
     const required = [];
@@ -5633,19 +6254,19 @@ function zodToJson(schema) {
     if (required.length > 0) out.required = required;
     return out;
   }
-  if (schema instanceof z26.ZodOptional) {
+  if (schema instanceof z33.ZodOptional) {
     return zodToJson(schema.unwrap());
   }
-  if (schema instanceof z26.ZodString) {
+  if (schema instanceof z33.ZodString) {
     return { type: "string" };
   }
-  if (schema instanceof z26.ZodNumber) {
+  if (schema instanceof z33.ZodNumber) {
     return { type: "number" };
   }
-  if (schema instanceof z26.ZodBoolean) {
+  if (schema instanceof z33.ZodBoolean) {
     return { type: "boolean" };
   }
-  if (schema instanceof z26.ZodEnum) {
+  if (schema instanceof z33.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.106",
+  "version": "0.4.0-next.107",
   "description": "MySpec MCP server — exposes MySpec platform projects, files and attachments to MCP-aware clients via OAuth-authenticated access tokens.",
   "type": "module",
   "repository": {