feat: Add create-actor-version and delete-actor-version tools

README.md

@@ -249,7 +249,7 @@ Here are some special MCP operations and how the Apify MCP Server supports them:
 - **Actor tasks**: Create, inspect, and update your saved Actor tasks, and publish or unpublish their public landing pages.
 - **Schedules**: Create, inspect, update, and delete schedules that run your Actors and tasks automatically.
 - **Builds**: Build an Actor version, list builds, check the status of a build, and retrieve its build log.
-- **Actor versions**: Read an Actor version's files with a hash for each file and a revision for the whole set, create an Actor from files, and change a version's files with checks that catch changes made since your last read.
+- **Actor versions**: Read an Actor version's files with a hash for each file and a revision for the whole set, create an Actor from files, change a version's files with checks that catch changes made since your last read, add a version from files or as a copy of another version, and delete a version.
 - **Apify API**: Search the Apify API reference, inspect an operation, and send requests to the API to read or change data.
 
 ### Overview of available tools
@@ -301,6 +301,8 @@ Legend for the **Enabled by default** column:
 | `get-actor-version` | versions | Get an Actor version's file listing with hashes and the content of the files you ask for. |  |
 | `create-actor` | versions | Create a private Actor in your account from files, optionally starting a build. |  |
 | `update-actor-version` | versions | Write, edit, or delete files of an Actor version in one all-or-nothing write. |  |
+| `create-actor-version` | versions | Add a version to an Actor, from files or as a copy of another version, optionally starting a build. |  |
+| `delete-actor-version` | versions | Delete an Actor version; its builds and their tags stay. |  |
 | `apify-api-search` | api | Search the Apify API reference for operations by keywords. Returns each one's method, path, and docs page. |  |
 | `apify-api-details` | api | Get the parameters and request body schema of the Apify API operations on a path. |  |
 | `apify-api-read` | api | Send a GET request to an Apify API path, such as `actor-runs` or `/v2/actor-runs`, like `apify api` in the Apify CLI. Read-only: it refuses the `method` query parameter and a GET to the synchronous run endpoints, which starts a paid run. |  |

src/const.ts

@@ -70,6 +70,8 @@ export const HELPER_TOOLS = {
     ACTOR_TASK_UPDATE: 'update-actor-task',
     ACTOR_TASK_PUBLISH: 'publish-actor-task',
     ACTOR_TASK_UNPUBLISH: 'unpublish-actor-task',
+    ACTOR_VERSION_CREATE: 'create-actor-version',
+    ACTOR_VERSION_DELETE: 'delete-actor-version',
     ACTOR_VERSION_GET: 'get-actor-version',
     ACTOR_VERSION_UPDATE: 'update-actor-version',
     DATASET_GET: 'get-dataset',
@@ -287,6 +289,10 @@ export const APIFY_ERROR_TYPE_CANNOT_START_ACTOR_RUNS = 'cannot-start-actor-runs
 export const APIFY_ERROR_TYPE_CANNOT_PUBLISH_ACTOR_TASK = 'cannot-publish-actor-task';
 export const APIFY_ERROR_TYPE_INVALID_INPUT = 'invalid-input';
 export const APIFY_ERROR_TYPE_ACTOR_NAME_NOT_UNIQUE = 'actor-name-not-unique';
+export const APIFY_ERROR_TYPE_VERSION_ALREADY_EXISTS = 'version-already-exists';
+export const APIFY_ERROR_TYPE_TOO_FEW_VERSIONS = 'too-few-versions';
+export const APIFY_ERROR_TYPE_TOO_MANY_VERSIONS = 'too-many-versions';
+export const APIFY_ERROR_TYPE_VERSIONS_SIZE_EXCEEDED = 'versions-size-exceeded';
 export const APIFY_ERROR_TYPE_PAGE_NOT_FOUND = 'page-not-found';
 
 // HTTP status codes

src/tools/AGENTS.md

@@ -39,14 +39,19 @@ direct actor tools, `search-actors`, `fetch-actor-details`) is mode-agnostic.
     first, pointing at the newest failed one) and `build-actor` (start a build of one version and wait for it); `build_helpers.ts` holds the
     allowlisted build result shape, the build start and wait calls (the wait reports progress), the
     shared `waitSecs` field, the shared build response and the by-status next-step text.
-  - `versions/`: `get-actor-version` (an Actor version's file manifest with hashes, revision, and
-    requested content), `create-actor` (a new Actor with one version in a single POST), and
+  - `versions/`: `get-actor-version` (an Actor version's build tag, file manifest with hashes, revision,
+    and requested content), `create-actor` (a new Actor with one version in a single POST),
     `update-actor-version` (write, edit, and delete operations applied all-or-nothing to a fresh read,
-    stored with one version PUT that carries only the source keys). `source_files.ts` holds the file
-    shape, the manifest builder, the hash and revision rules, and the text-or-base64 detection;
+    stored with one version PUT that carries only the source keys), `create-actor-version` (a new
+    version in one POST, from files or as a copy of another version's files and non-secret env vars,
+    with no default buildTag), and `delete-actor-version` (reads the Actor first, since apify-client
+    reports a delete of a missing version as done, and returns the tags still on its builds). `source_files.ts` holds the file shape, the
+    manifest builder, the hash and revision rules, and the text-or-base64 detection;
     `source_helpers.ts` holds the Actor and version lookup, the file input shape, and the response
-    after a write, which starts the build for autoBuild. Versions not stored as files (Git repository,
-    gist, or zip) are refused.
+    after a write, which starts the build for autoBuild. get-actor-version, update-actor-version, and a
+    copy in create-actor-version refuse a version not stored as files (Git repository, gist, or zip);
+    create-actor-version from files and delete-actor-version work whatever the Actor's versions are
+    stored as, but delete-actor-version takes expectedRevision only for a version stored as files.
   - `api/` — the generic Apify API tools: search the operations of the published OpenAPI spec, get the
     operations on a path, and send a GET, or a POST, PUT, PATCH, or DELETE, to a path. The write tool is in
     no category (`UNCATEGORIZED_TOOLS`): `tools=api` serves the other three, and a session gets the write

src/tools/registry.ts

@@ -55,6 +55,8 @@ import { publishActorTask } from './tasks/publish_actor_task.js';
 import { unpublishActorTask } from './tasks/unpublish_actor_task.js';
 import { updateActorTask } from './tasks/update_actor_task.js';
 import { createActor } from './versions/create_actor.js';
+import { createActorVersion } from './versions/create_actor_version.js';
+import { deleteActorVersion } from './versions/delete_actor_version.js';
 import { getActorVersion } from './versions/get_actor_version.js';
 import { updateActorVersion } from './versions/update_actor_version.js';
 import { callActorWidget } from './widgets/call_actor_widget.js';
@@ -80,7 +82,7 @@ export const toolCategories = {
     tasks: [createActorTask, getActorTask, updateActorTask, publishActorTask, unpublishActorTask],
     schedules: [createSchedule, getSchedule, updateSchedule, deleteSchedule],
     builds: [getActorBuild, getActorBuildLog, getActorBuildList, buildActor],
-    versions: [getActorVersion, createActor, updateActorVersion],
+    versions: [getActorVersion, createActor, updateActorVersion, createActorVersion, deleteActorVersion],
     api: [apifyApiSearch, apifyApiDetails, apifyApiRead],
     dev: [reportProblem],
 } satisfies Record<string, ToolEntry[]>;

src/tools/structured_output_schemas.ts

@@ -587,6 +587,10 @@ export const getActorVersionToolOutputSchema = {
         actorId: { type: 'string', description: 'Actor ID' },
         fullName: { type: 'string', description: 'Actor full name, username/name' },
         versionNumber: { type: 'string', description: 'Version number, e.g. 0.1' },
+        buildTag: {
+            type: 'string',
+            description: 'Tag that new builds of this version get, e.g. latest; absent when the version has none',
+        },
         revision: { type: 'string', description: 'Identifies the whole file set; changes when any file changes' },
         files: {
             type: 'array',
@@ -644,7 +648,7 @@ const sourceWriteBuildProperties = {
     warnings: {
         type: 'array',
         items: { type: 'string' },
-        description: 'Things to know about the written files, such as empty files the build skips',
+        description: 'Things to know about the written version, such as empty files the build skips',
     },
 };
 
@@ -669,6 +673,38 @@ export const createActorToolOutputSchema = {
     required: ['actorId', 'fullName', 'versionNumber', 'revision', 'files'],
 };
 
+/** Schema for create-actor-version: the new version and its files. */
+export const createActorVersionToolOutputSchema = {
+    type: 'object' as const,
+    properties: {
+        actorId: { type: 'string', description: 'Actor ID' },
+        fullName: { type: 'string', description: 'Actor full name, username/name' },
+        versionNumber: { type: 'string', description: 'Number of the new version, e.g. 0.2' },
+        revision: createActorToolOutputSchema.properties.revision,
+        files: createActorToolOutputSchema.properties.files,
+        ...sourceWriteBuildProperties,
+    },
+    required: ['actorId', 'fullName', 'versionNumber', 'revision', 'files'],
+};
+
+/** Schema for delete-actor-version: the version that was deleted. */
+export const deleteActorVersionToolOutputSchema = {
+    type: 'object' as const,
+    properties: {
+        actorId: { type: 'string', description: 'Actor ID' },
+        fullName: { type: 'string', description: 'Actor full name, username/name' },
+        versionNumber: { type: 'string', description: 'Number of the deleted version' },
+        deleted: { type: 'boolean', description: 'Always true' },
+        tags: {
+            type: 'array',
+            items: { type: 'string' },
+            description:
+                'Tags that point to a build of the deleted version, empty when none; runs with such a tag still use that build',
+        },
+    },
+    required: ['actorId', 'fullName', 'versionNumber', 'deleted', 'tags'],
+};
+
 /** Schema for update-actor-version: the new revision and what changed. */
 export const updateActorVersionToolOutputSchema = {
     type: 'object' as const,

src/tools/versions/create_actor.ts

@@ -1,28 +1,22 @@
 import type { ActorCollectionCreateOptions, ActorVersionSourceFile } from 'apify-client';
-import { ActorSourceType, ApifyApiError } from 'apify-client';
+import { ActorSourceType } from 'apify-client';
 import dedent from 'dedent';
 import { z } from 'zod';
 
 import { APIFY_ERROR_TYPE_ACTOR_NAME_NOT_UNIQUE, HELPER_TOOLS } from '../../const.js';
-import { UserInputError } from '../../errors.js';
 import type { InternalToolArgs, ToolEntry, ToolInputSchema } from '../../types.js';
 import { TOOL_TYPE } from '../../types.js';
 import { compileSchema, fixZodSchemaRequired } from '../../utils/ajv.js';
-import { respondAborted, respondUserError } from '../../utils/mcp.js';
+import { respondAborted } from '../../utils/mcp.js';
 import { createActorToolOutputSchema } from '../structured_output_schemas.js';
-import { buildFilesManifest, buildFilesRevision } from './source_files.js';
 import {
-    buildEmptyFilesWarnings,
-    buildSourceFileEntry,
+    buildSourceFileEntries,
     extractSourceFiles,
     redactSourceToolArgs,
     resolveVersion,
-    respondAfterWrite,
-    respondToSourceToolError,
+    respondAfterCreate,
+    respondToCreateError,
     sourceFileArgs,
-    validateFileContent,
-    validateFilePath,
-    validatePathCharacters,
 } from './source_helpers.js';
 
 const createActorArgs = z.object({
@@ -47,46 +41,6 @@ const createActorArgs = z.object({
         .describe('Start a build of the version after creating the Actor, and return without waiting. Default: false.'),
 });
 
-/** The folders above a file, outermost first: `a` and `a/b` for `a/b/c.js`. */
-function listFolders(path: string): string[] {
-    const segments = path.split('/');
-    return segments.slice(1).map((_, index) => segments.slice(0, index + 1).join('/'));
-}
-
-/**
- * The entries to send, one per file; throws `UserInputError` for a path no file can be written at, and for a path
- * given twice, since the platform puts the Actor name in the first .actor/actor.json and the build uses the last.
- * Paths are checked through a set and a map, since comparing each file with every earlier one took 8 s for 20,000.
- */
-function buildSourceFileEntries(files: readonly z.infer<typeof sourceFileArgs>[]): ActorVersionSourceFile[] {
-    const entries: ActorVersionSourceFile[] = [];
-    const filePaths = new Set<string>();
-    const firstFileByFolder = new Map<string, string>();
-    for (const [index, file] of files.entries()) {
-        validatePathCharacters(file.path, `files[${index}]`);
-        const entry = buildSourceFileEntry(file);
-        const label = `files[${index}] (${file.path})`;
-        validateFilePath(entry.name, label);
-        validateFileContent(entry, label);
-        if (filePaths.has(entry.name)) {
-            throw new UserInputError(`${label} repeats the path ${entry.name}; each path can be sent only once.`);
-        }
-        const folders = listFolders(entry.name);
-        const collision = folders.find((folder) => filePaths.has(folder)) ?? firstFileByFolder.get(entry.name);
-        if (collision !== undefined) {
-            throw new UserInputError(
-                `${label} collides with ${collision}; one path cannot be both a file and a folder.`,
-            );
-        }
-        filePaths.add(entry.name);
-        for (const folder of folders) {
-            if (!firstFileByFolder.has(folder)) firstFileByFolder.set(folder, entry.name);
-        }
-        entries.push(entry);
-    }
-    return entries;
-}
-
 /** The `version` of .actor/actor.json when it is a non-empty string in valid JSON, as `apify push` reads it. */
 function readActorJsonVersion(entries: readonly ActorVersionSourceFile[]): string | undefined {
     const actorJson = entries.find(({ name, format }) => name === '.actor/actor.json' && format === 'TEXT');
@@ -168,41 +122,21 @@ export const createActor: ToolEntry = Object.freeze({
             // The platform sets the name in .actor/actor.json on create, so the stored files, not the sent ones, match
             // a later read.
             const version = resolveVersion(created, undefined, fullName);
-            const files = buildFilesManifest(
-                extractSourceFiles(version, `Version ${version.versionNumber} of ${fullName}`),
-            );
-            const emptyPaths = files.filter(({ sizeBytes }) => sizeBytes === 0).map(({ path }) => path);
-            return await respondAfterWrite({
+            return await respondAfterCreate({
                 toolArgs,
                 autoBuild: parsed.autoBuild,
-                target: { actorId: created.id, versionNumber: version.versionNumber },
-                structuredContent: {
-                    actorId: created.id,
-                    fullName,
-                    versionNumber: version.versionNumber,
-                    revision: buildFilesRevision(files),
-                    files: files.map(({ path, sizeBytes, hash }) => ({ path, sizeBytes, hash })),
-                    ...buildEmptyFilesWarnings(emptyPaths),
-                },
+                created: { actorId: created.id, fullName, versionNumber: version.versionNumber },
+                sourceFiles: extractSourceFiles(version, `Version ${version.versionNumber} of ${fullName}`),
                 summary: `Created the private Actor ${fullName}.`,
             });
         } catch (error) {
-            if (
-                error instanceof ApifyApiError &&
-                error.type === APIFY_ERROR_TYPE_ACTOR_NAME_NOT_UNIQUE &&
-                error.attempt > 1
-            ) {
-                const readTool = loadedToolNames.includes(HELPER_TOOLS.ACTOR_VERSION_GET)
-                    ? `; ${HELPER_TOOLS.ACTOR_VERSION_GET} reads its files`
-                    : '';
-                return respondUserError(
-                    `The platform refused the name ${parsed.name} as taken when the request was retried, so an earlier ` +
-                        `attempt of this call may have created the Actor ${parsed.name}. ` +
-                        `If it holds the files you sent, this call created it${readTool}.`,
-                    { httpStatus: error.statusCode },
-                );
-            }
-            return respondToSourceToolError(error);
+            return respondToCreateError(error, {
+                takenErrorType: APIFY_ERROR_TYPE_ACTOR_NAME_NOT_UNIQUE,
+                loadedToolNames,
+                refused: `the name ${parsed.name}`,
+                created: `the Actor ${parsed.name}`,
+                sentFiles: 'the files you sent',
+            });
         }
     },
 } as const);