feat: long running tasks #360

MQ37 · 2025-12-10T09:43:20Z

For PR reviewers: I recommend reading the full commit messages as I was instructing agent to always read the changes and summarize the changes in the messages.

Changes:

updated MCP SDK to latest version
encountered issues with ZOD where it generated wrong schema for optional and default properties as they were marked as required - created PR into zod to fix this fix: JSON .optional().default() fields marked as required colinhacks/zod#5532
bumped node version to 24 (hopefully) everywheere
implemented the long running tasks handlers - we are using in memory tasks store for stdio and Actor
added async task execution, task are isolated by session id (another possibly way is to isolate them by user id which could be interesting use case). ⚠️ This is implemented only for the NORMAL Actor tools (no MCP servers), for internal tools it does not make sense. Currently the long running task tool call mode is optional and not enforced.
in the internal repo implemented redis tasks store with multi node setup
- wrote multi node tests that are passing
- tasks result are stored by default for 5 minutes (we should revisit this in future). Maximum task TTL is capped at 10 minutes, clients can request more but they will get 10 minutes at maximum.
TODO we should add long running tasks to telemetry, I would personally split that to another issue/PR since this is quite large already. Issue here Telemetry - add tracking for long running tasks #362
for now I would keep the tasks related debug logs but we surely can remove them in future

…d JSON schema generation - Upgrade @modelcontextprotocol/sdk from 1.18.1 to 1.24.3 and Zod from 3.24.1 to 4.1.13 - Replace deprecated zod-to-json-schema package with native z.toJSONSchema() across all tool files - Remove zod-to-json-schema from dependencies (no longer needed) - Add compileSchema() wrapper in ajv.ts that: * Removes $schema property to fix AJV validation errors * Filters fields with defaults from required array (fixes Zod v4 bug where optional fields with defaults are marked required) - Fix type assertion in tools.ts for cloning HelperTools with call method (cast to HelperTool) - Fix type guard in suite.ts to check message.content.type before accessing text property - Update prompts to handle new MCP SDK message content types - All dependencies updated to compatible versions

commit f554832 Author: Apify Release Bot <[email protected]> Date: Mon Dec 8 17:05:39 2025 +0000 chore(release): Update changelog, package.json, manifest.json and server.json versions [skip ci] commit 17a349b Author: Jakub Drobník <[email protected]> Date: Mon Dec 8 18:04:44 2025 +0100 fix: update node to v24 (#356) commit 16f1e1e Author: Apify Release Bot <[email protected]> Date: Mon Dec 8 15:44:33 2025 +0000 chore(release): Update changelog, package.json, manifest.json and server.json versions [skip ci] commit b1de40e Author: drobnikj <[email protected]> Date: Mon Dec 8 16:41:41 2025 +0100 fix: remove latest tag from npm publish release.yaml commit b9511cb Author: Apify Release Bot <[email protected]> Date: Mon Dec 8 15:33:11 2025 +0000 chore(release): Update changelog, package.json, manifest.json and server.json versions [skip ci] commit fad9ad6 Author: drobnikj <[email protected]> Date: Mon Dec 8 16:31:18 2025 +0100 fix: release workflow using --access public param commit 54b952f Author: Apify Release Bot <[email protected]> Date: Mon Dec 8 15:26:20 2025 +0000 chore(release): Update changelog, package.json, manifest.json and server.json versions [skip ci] commit 9a34990 Author: drobnikj <[email protected]> Date: Mon Dec 8 16:21:47 2025 +0100 fix: update node setup in releasing wf commit e8564b3 Author: Apify Release Bot <[email protected]> Date: Mon Dec 8 14:43:22 2025 +0000 chore(release): Update changelog, package.json, manifest.json and server.json versions [skip ci] commit 1f0b374 Merge: 94a8e60 d3cff7c Author: Jakub Drobník <[email protected]> Date: Mon Dec 8 15:37:38 2025 +0100 feat: trusted publishing of npm package (#355) commit d3cff7c Author: drobnikj <[email protected]> Date: Fri Dec 5 18:11:59 2025 +0100 feat: trusted publishing of npm package

**Core Task Infrastructure:** - Add TaskStore support for managing long-running tool executions - Use InMemoryTaskStore for stdio transport, allow custom task store for HTTP/SSE - Implement task handlers: ListTasks, GetTask, GetTaskPayload, CancelTask - Create executeToolAndUpdateTask for asynchronous tool execution with status tracking **Session ID Injection:** - Inject mcpSessionId into all requests at transport layer for session isolation - Generate unique session IDs for stdio and HTTP/SSE connections - Thread mcpSessionId through task creation and execution pipeline - Pass mcpSessionId to task store operations for proper task scoping **Task Execution Flow:** - Support optional long-running tasks for tools that declare taskSupport capability - Return task object immediately upon creation for polling-based clients - Execute tool asynchronously with automatic status updates (pending → working → completed/failed) - Store tool results and error information with task completion **Type & Configuration:** - Add ALLOWED_TASK_TOOL_EXECUTION_MODES for task support validation - Update ActorsMcpServerOptions to accept custom task store - Add execution.taskSupport capability to Actor tools - Declare MCP tasks capability in server initialization **Testing & Documentation:** - Add integration test for long-running task workflow - Update unit tests to provide InMemoryTaskStore - Document APIFY_TOKEN requirement for integration tests in AGENTS.md - Add comprehensive logging for task lifecycle events

commit f4ca0a3 Author: Jakub Kopecký <[email protected]> Date: Tue Dec 9 09:58:19 2025 +0100 chore: Clean up duplicate entries in CHANGELOG.md (#357) Clean up duplicate entries in CHANGELOG.md Removed duplicate entries for version 0.6.2 in CHANGELOG. commit f554832 Author: Apify Release Bot <[email protected]> Date: Mon Dec 8 17:05:39 2025 +0000 chore(release): Update changelog, package.json, manifest.json and server.json versions [skip ci] commit 17a349b Author: Jakub Drobník <[email protected]> Date: Mon Dec 8 18:04:44 2025 +0100 fix: update node to v24 (#356) commit 16f1e1e Author: Apify Release Bot <[email protected]> Date: Mon Dec 8 15:44:33 2025 +0000 chore(release): Update changelog, package.json, manifest.json and server.json versions [skip ci] commit b1de40e Author: drobnikj <[email protected]> Date: Mon Dec 8 16:41:41 2025 +0100 fix: remove latest tag from npm publish release.yaml commit b9511cb Author: Apify Release Bot <[email protected]> Date: Mon Dec 8 15:33:11 2025 +0000 chore(release): Update changelog, package.json, manifest.json and server.json versions [skip ci] commit fad9ad6 Author: drobnikj <[email protected]> Date: Mon Dec 8 16:31:18 2025 +0100 fix: release workflow using --access public param commit 54b952f Author: Apify Release Bot <[email protected]> Date: Mon Dec 8 15:26:20 2025 +0000 chore(release): Update changelog, package.json, manifest.json and server.json versions [skip ci] commit 9a34990 Author: drobnikj <[email protected]> Date: Mon Dec 8 16:21:47 2025 +0100 fix: update node setup in releasing wf commit e8564b3 Author: Apify Release Bot <[email protected]> Date: Mon Dec 8 14:43:22 2025 +0000 chore(release): Update changelog, package.json, manifest.json and server.json versions [skip ci] commit 1f0b374 Merge: 94a8e60 d3cff7c Author: Jakub Drobník <[email protected]> Date: Mon Dec 8 15:37:38 2025 +0100 feat: trusted publishing of npm package (#355) commit d3cff7c Author: drobnikj <[email protected]> Date: Fri Dec 5 18:11:59 2025 +0100 feat: trusted publishing of npm package

- Extract isTaskCancelled() helper to prevent terminal state transition errors when tasks are cancelled immediately after creation - Add pre-execution and mid-execution cancellation checks to skip state transitions from cancelled (terminal) status - Move telemetry preparation before try-catch to avoid re-fetching user data in error handlers - Add null-safety guards to all task request handlers (ListTasks, GetTask, GetTaskPayload, CancelTask) - Add integration tests for long-running task operations and cancellation scenarios

…ID injection - Only actor tools support long-running task execution; other tool types now throw error - Fixed critical issue where session ID wasn't injected into requests without params - Refactored executeToolAndUpdateTask() to accept single object parameter for cleaner API - Removed unused userRentedActorIds parameter from task execution flow - Added helpful comments explaining task store logging and future refactoring needs - Added 'npm run check' script for combined type-check and linting

pkg-pr-new · 2025-12-11T11:42:56Z

Open in StackBlitz

npm i https://pkg.pr.new/apify/apify-mcp-server/@apify/actors-mcp-server@360

commit: 152530c

…failing)

…ents

jirispilka

We should use the task status from MCP (@modelcontextprotocol/sdk/dist/esm/types.d.ts) as we are repeating the strings: failed, working, etc at some may places
The changes in tools, update of packages.json etc should have been a separate PR. It would make this PR more manageable
Well, server.ts already had a lot of technical debt. Now it has nearly doubled. I'm thinking out loud here: If we are gonna merge this PR to release long-running tasks, in the coming sprints we are gonna need to ask for a couple of days for refactoring. I'm thinking about whether to postpone the release and do the refactoring right away, or accumulate the tech debt?

src/mcp/server.ts

Co-authored-by: Jiří Spilka <[email protected]>

MQ37 · 2025-12-14T10:31:19Z

We should use the task status from MCP (@modelcontextprotocol/sdk/dist/esm/types.d.ts) as we are repeating the strings: failed, working, etc at some may places

Will look into it.

The changes in tools, update of packages.json etc should have been a separate PR. It would make this PR more manageable

Agree, but it is already done.

Well, server.ts already had a lot of technical debt. Now it has nearly doubled. I'm thinking out loud here: If we are gonna merge this PR to release long-running tasks, in the coming sprints we are gonna need to ask for a couple of days for refactoring. I'm thinking about whether to postpone the release and do the refactoring right away, or accumulate the tech debt?

Honestly I would merge this technical debt and then create a separate PR for refactoring. This PR is already large and I would be against making it even larger and more complex. And yes, we definitely should reserve a few days for refactoring and giving the codebase some love.

MQ37 added 7 commits December 8, 2025 14:50

install packages and lint

9b8303f

comment

b175406

github-actions bot assigned MQ37 Dec 10, 2025

github-actions bot added the t-ai Issues owned by the AI team. label Dec 10, 2025

MQ37 added 2 commits December 10, 2025 16:24

fix: force install npm dependencies in workflows to ensure consistency

b8c97d9

khanbilal732 approved these changes Dec 11, 2025

View reviewed changes

Merge branch 'master' into long-running-tasks

196fa2d

MQ37 marked this pull request as ready for review December 11, 2025 11:41

MQ37 added the beta Create beta prereleases label Dec 11, 2025

MQ37 requested a review from jirispilka December 11, 2025 11:46

jirispilka added 2 commits December 13, 2025 23:27

fix: update openai in devDependencies to 6.10.0 (otherwise npm i was …

bd6ba53

…failing)

feat: add taskId support to progress tracking and update related comm…

409d470

…ents

jirispilka reviewed Dec 13, 2025

View reviewed changes

src/mcp/server.ts Outdated Show resolved Hide resolved

src/mcp/server.ts Outdated Show resolved Hide resolved

src/mcp/server.ts Show resolved Hide resolved

MQ37 and others added 3 commits December 14, 2025 11:27

Update src/mcp/server.ts

b04336e

Co-authored-by: Jiří Spilka <[email protected]>

Update src/mcp/server.ts

947f678

Co-authored-by: Jiří Spilka <[email protected]>

Update src/mcp/server.ts

6b7f25c

Co-authored-by: Jiří Spilka <[email protected]>

Merge branch 'master' into long-running-tasks

152530c

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: long running tasks #360

feat: long running tasks #360

Uh oh!

MQ37 commented Dec 10, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Dec 11, 2025 •

edited

Loading

Uh oh!

jirispilka left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MQ37 commented Dec 14, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: long running tasks #360

Are you sure you want to change the base?

feat: long running tasks #360

Uh oh!

Conversation

MQ37 commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jirispilka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MQ37 commented Dec 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

MQ37 commented Dec 10, 2025 •

edited

Loading

pkg-pr-new bot commented Dec 11, 2025 •

edited

Loading

MQ37 commented Dec 14, 2025 •

edited

Loading