feat!: Add create-actor and update-actor-version tools

AGENTS.md

@@ -47,7 +47,7 @@ After `pnpm run build`, run `mcpc` (no args) to check sessions: if `@stdio` (def
 - **Integration tests**: `pnpm run test:integration` (needs build + `APIFY_TOKEN`, humans only).
 - **Conformance tests**: `pnpm run test:conformance` (needs `APIFY_TOKEN`) builds and runs both protocol eras locally. `_integration_tests.yaml` calls `_conformance_tests.yaml` for the same `2026-07-28` and `2025-11-25` coverage in CI. Both eras always run; the command exits with the first non-zero code. Scenarios excluded from each era's gate are listed with reasons in `scripts/conformance_expected_failures_2026_07_28.yaml` and `scripts/conformance_expected_failures_2025_11_25.yaml`.
 - **Package manager**: this repo uses **pnpm 11+**. `devEngines.packageManager` is pinned with `onFail: "error"`, so npm / yarn refuse to run inside the checkout — use `pnpm install` only.
-- `tests/integration/suite.ts` wires the `stdio`, `2025-11-25` (streamable HTTP) and `2026-07-28` (stateless HTTP) transport dimensions into one shared suite. Add new integration cases to the matching capability array in `tests/test_kit/cases/*.cases.ts` (registration, tools, actors, apps, tasks, storage, schedules, payments) — each is a plain `Case[]` (`{ name, isDeploymentTest, run, ... }`), registered via `registerCases(name, cases, ctx)`. Mark a case `isDeploymentTest: true` only if it's worth running against `apify-mcp-server-internal`'s live staging and production deploys — the flag doesn't just share the case, it makes internal execute it for real on every release (see [DEVELOPMENT.md](./DEVELOPMENT.md#test-organization-across-repos)). Shared assertion helpers live in `tests/test_kit/helpers.ts`. Cases that share expensive setup (e.g. one seeded Actor run, see `storage.cases.ts`'s `normalModeRunFixture`) do so via `ctx.getFixture(fixture)`, memoized once per transport dimension — not a vitest `beforeAll`, so any subset of cases can share it while staying flat `Case` objects.
+- `tests/integration/suite.ts` wires the `stdio`, `2025-11-25` (streamable HTTP) and `2026-07-28` (stateless HTTP) transport dimensions into one shared suite. Add new integration cases to the matching capability array in `tests/test_kit/cases/*.cases.ts` (registration, tools, actors, apps, tasks, storage, schedules, source, payments) — each is a plain `Case[]` (`{ name, isDeploymentTest, run, ... }`), registered via `registerCases(name, cases, ctx)`. Mark a case `isDeploymentTest: true` only if it's worth running against `apify-mcp-server-internal`'s live staging and production deploys — the flag doesn't just share the case, it makes internal execute it for real on every release (see [DEVELOPMENT.md](./DEVELOPMENT.md#test-organization-across-repos)). Shared assertion helpers live in `tests/test_kit/helpers.ts`. Cases that share expensive setup (e.g. one seeded Actor run, see `storage.cases.ts`'s `normalModeRunFixture`) do so via `ctx.getFixture(fixture)`, memoized once per transport dimension — not a vitest `beforeAll`, so any subset of cases can share it while staying flat `Case` objects.
 - Follow existing test patterns (names, structure) — check neighboring files.
 - **Test naming**: `describe('fnName()')`, plain-verb `it()` names (no `should` prefix). Group with nested `describe()` per method when a factory/class exposes several.
 

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 source**: Read an Actor version's files, with a hash for each file and a revision for the whole set.
+- **Actor source**: 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.
 - **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
@@ -299,6 +299,8 @@ Legend for the **Enabled by default** column:
 | `get-actor-build-list` | builds | List the account's builds, or one Actor's, in every status, newest first. |  |
 | `build-actor` | builds | Build an Actor version and wait a bounded time for the build to finish. |  |
 | `get-actor-version` | source | Get an Actor version's file listing with hashes and the content of the files you ask for. |  |
+| `create-actor` | source | Create a private Actor in your account from files, optionally starting a build. |  |
+| `update-actor-version` | source | Write, edit, or delete files of an Actor version in one all-or-nothing write. |  |
 | `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

@@ -54,6 +54,7 @@ export const HELPER_TOOLS = {
     ACTOR_BUILD_LOG: 'get-actor-build-log',
     ACTOR_BUILD_LIST_GET: 'get-actor-build-list',
     ACTOR_CALL: 'call-actor',
+    ACTOR_CREATE: 'create-actor',
     ACTOR_CALL_WIDGET: 'call-actor-widget',
     ACTOR_DELETE: 'delete-actor',
     ACTOR_GET_DETAILS: 'fetch-actor-details',
@@ -70,6 +71,7 @@ export const HELPER_TOOLS = {
     ACTOR_TASK_PUBLISH: 'publish-actor-task',
     ACTOR_TASK_UNPUBLISH: 'unpublish-actor-task',
     ACTOR_VERSION_GET: 'get-actor-version',
+    ACTOR_VERSION_UPDATE: 'update-actor-version',
     DATASET_GET: 'get-dataset',
     DATASET_LIST_GET: 'get-dataset-list',
     DATASET_GET_ITEMS: 'get-dataset-items',
@@ -283,6 +285,7 @@ export const APIFY_ERROR_TYPE_MEMORY_LIMIT_EXCEEDED = 'memory-limit-exceeded';
 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_PAGE_NOT_FOUND = 'page-not-found';
 
 // HTTP status codes

src/tools/AGENTS.md

@@ -40,8 +40,12 @@ direct actor tools, `search-actors`, `fetch-actor-details`) is mode-agnostic.
     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.
   - `source/`: `get-actor-version` (an Actor version's file manifest with hashes, revision, and
-    requested content). `source_files.ts` holds the file shape, the manifest builder, the hash and
-    revision rules, and the text-or-base64 detection. Versions not stored as files (Git repository,
+    requested content), `create-actor` (a new Actor with one version in a single POST), and
+    `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;
+    `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.
   - `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

src/tools/registry.ts

@@ -41,7 +41,9 @@ import { createSchedule } from './schedules/create_schedule.js';
 import { deleteSchedule } from './schedules/delete_schedule.js';
 import { getSchedule } from './schedules/get_schedule.js';
 import { updateSchedule } from './schedules/update_schedule.js';
+import { createActor } from './source/create_actor.js';
 import { getActorVersion } from './source/get_actor_version.js';
+import { updateActorVersion } from './source/update_actor_version.js';
 import { getDataset } from './storage/get_dataset.js';
 import { getDatasetItems } from './storage/get_dataset_items.js';
 import { getDatasetList } from './storage/get_dataset_list.js';
@@ -78,7 +80,7 @@ export const toolCategories = {
     tasks: [createActorTask, getActorTask, updateActorTask, publishActorTask, unpublishActorTask],
     schedules: [createSchedule, getSchedule, updateSchedule, deleteSchedule],
     builds: [getActorBuild, getActorBuildLog, getActorBuildList, buildActor],
-    source: [getActorVersion],
+    source: [getActorVersion, createActor, updateActorVersion],
     api: [apifyApiSearch, apifyApiDetails, apifyApiRead],
     dev: [reportProblem],
 } satisfies Record<string, ToolEntry[]>;

src/tools/source/create_actor.ts

@@ -0,0 +1,208 @@
+import type { ActorCollectionCreateOptions, ActorVersionSourceFile } from 'apify-client';
+import { ActorSourceType, ApifyApiError } 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 { createActorToolOutputSchema } from '../structured_output_schemas.js';
+import { buildFilesManifest, buildFilesRevision } from './source_files.js';
+import {
+    buildEmptyFilesWarnings,
+    buildSourceFileEntry,
+    extractSourceFiles,
+    redactSourceToolArgs,
+    resolveVersion,
+    respondAfterWrite,
+    respondToSourceToolError,
+    sourceFileArgs,
+    validateFileContent,
+    validateFilePath,
+    validatePathCharacters,
+} from './source_helpers.js';
+
+const createActorArgs = z.object({
+    name: z.string().min(1).describe('Name of the new Actor, without a username, for example my-scraper.'),
+    title: z.string().min(1).optional().describe('Display title, for example My Scraper.'),
+    description: z.string().optional().describe('A short description of what the Actor does.'),
+    files: z.array(sourceFileArgs).min(1).describe("The Actor's files, each with its whole content."),
+    versionNumber: z
+        .string()
+        .optional()
+        .describe(
+            'Number of the version in MAJOR.MINOR form. Default: the version in .actor/actor.json, or 0.0 when it has none.',
+        ),
+    buildTag: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Tag that builds of the version get. The platform uses latest when it is omitted.'),
+    autoBuild: z
+        .boolean()
+        .default(false)
+        .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');
+    if (!actorJson) return undefined;
+    try {
+        const { version } = JSON.parse(actorJson.content) as { version?: unknown };
+        return typeof version === 'string' && version !== '' ? version : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * https://docs.apify.com/api/v2/actors-post
+ *  /v2/actors
+ *
+ * One POST creates the Actor and its version together, private and in the token's account. apify-client retries the
+ * POST after a network error, a timeout, a 429, or a 5xx, so when the platform saved an attempt it did not answer, the
+ * retry fails on the name that attempt took, and the call says the Actor may exist.
+ */
+export const createActor: ToolEntry = Object.freeze({
+    type: TOOL_TYPE.INTERNAL,
+    name: HELPER_TOOLS.ACTOR_CREATE,
+    title: 'Create Actor',
+    description: dedent`
+        Create a new private Actor in your account, with one version holding the files you give. It never changes an existing Actor: the platform refuses a name your account already uses.
+        - files: every file with its path and content. Binary files take base64 content with encoding base64; files with a binary extension such as .png default to it.
+        The platform sets the name field of .actor/actor.json to the Actor name, so the result lists each file's hash and the version's revision as stored.
+        autoBuild starts a build after creating the Actor and returns without waiting.
+
+        USAGE:
+        - Use to upload new Actor code to the Apify platform for the first time.
+
+        USAGE EXAMPLES:
+        - user_input: Create an Actor called hacker-news-scraper from these files`,
+    // `fixZodSchemaRequired` strips `autoBuild` from `required` because it has a default.
+    inputSchema: fixZodSchemaRequired(z.toJSONSchema(createActorArgs)) as ToolInputSchema,
+    outputSchema: createActorToolOutputSchema,
+    ajvValidate: compileSchema(z.toJSONSchema(createActorArgs)),
+    annotations: {
+        title: 'Create Actor',
+        readOnlyHint: false,
+        destructiveHint: false,
+        // A second call with the same name is refused rather than repeated.
+        idempotentHint: false,
+        // autoBuild starts a build, like build-actor.
+        openWorldHint: true,
+    },
+    redactArgs: (args: Record<string, unknown>) =>
+        redactSourceToolArgs(args, {
+            keys: ['name', 'title', 'description', 'versionNumber', 'buildTag', 'autoBuild'],
+            listKey: 'files',
+            entryKeys: ['path', 'encoding'],
+        }),
+    call: async (toolArgs: InternalToolArgs) => {
+        const { args, apifyClient: client, signal, loadedToolNames } = toolArgs;
+        const parsed = createActorArgs.parse(args);
+        // A cancel before the POST creates nothing; per the MCP spec the cancelled request gets no response.
+        if (signal?.aborted) return respondAborted();
+        try {
+            const sourceFiles = buildSourceFileEntries(parsed.files);
+            // The platform refuses a version without a number, so this defaults to what `apify push` uses.
+            // AJV turns a null versionNumber into an empty string, which counts as not given.
+            const versionNumber = parsed.versionNumber || readActorJsonVersion(sourceFiles) || '0.0';
+            const created = await client.actors().create({
+                name: parsed.name,
+                ...(parsed.title !== undefined && { title: parsed.title }),
+                ...(parsed.description !== undefined && { description: parsed.description }),
+                versions: [
+                    {
+                        versionNumber,
+                        ...(parsed.buildTag !== undefined && { buildTag: parsed.buildTag }),
+                        sourceType: ActorSourceType.SourceFiles,
+                        sourceFiles,
+                    },
+                ],
+            } satisfies ActorCollectionCreateOptions);
+            const fullName = `${created.username}/${created.name}`;
+            // 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({
+                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),
+                },
+                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);
+        }
+    },
+} as const);