refactor: Extract shared injectMcpSessionId helper (#1074)

Part of #1066 (checkbox: shared `injectMcpSessionId` helper).

## What we're solving

The mcpSessionId injection — `params._meta ??= {};
params._meta.mcpSessionId = <id>` — was duplicated in `src/stdio.ts` and
`src/dev_server.ts`. The "always create params" invariant, and the
comment explaining why (requests like `listTasks`/`getTasks` have no
params; skipping creation makes injection silently fail and breaks
multi-node session isolation), lived only in stdio.ts.

## How

Add `injectMcpSessionId(params, mcpSessionId)` to `src/utils/mcp.ts`,
carrying the invariant and its comment once. Both entry points call it.
A unit test locks the always-create invariant and the mutate-and-return
semantics.

- **stdio.ts**: behavior unchanged (it already always-created params).
- **dev_server.ts**: now *also* always-creates params via the helper.
Previously it injected only when `req.body.params` already existed (`if
(req.body?.params && sessionId)`); it now injects whenever there's a
session (`if (sessionId && req.body)`).


🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_016pXZvhEoE6Lz3DpBSL3n1Y

---
_Generated by [Claude
Code](https://claude.ai/code/session_016pXZvhEoE6Lz3DpBSL3n1Y)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jirispilka

src/dev_server.ts

@@ -16,6 +16,7 @@ import { parseBooleanOrNull } from '@apify/utilities';
 import { ApifyClient } from './apify_client.js';
 import { ActorsMcpServer } from './mcp/server.js';
 import { resolvePaymentProvider } from './payments/index.js';
+import { injectMcpSessionId } from './utils/mcp.js';
 import { parseServerMode } from './utils/server_mode.js';
 
 // DEV ONLY. This is a local dev/standby-emulation server, not the hosted HTTP server.
@@ -208,9 +209,8 @@ export function createExpressApp(): express.Express {
             }
 
             // Inject session ID into request params for the reused existing session
-            if (req.body?.params && sessionId) {
-                req.body.params._meta ??= {};
-                req.body.params._meta.mcpSessionId = sessionId;
+            if (sessionId && req.body) {
+                req.body.params = injectMcpSessionId(req.body.params, sessionId);
             }
 
             // Handle the request with existing transport - no need to reconnect

src/stdio.ts

@@ -38,6 +38,7 @@ import { getTelemetryEnv } from './telemetry.js';
 import type { ApifyRequestParams, Input, ServerModeOption, TelemetryEnv, ToolSelector } from './types.js';
 import { isApiTokenRequired } from './utils/auth.js';
 import { parseCommaSeparatedList } from './utils/generic.js';
+import { injectMcpSessionId } from './utils/mcp.js';
 import { parseServerMode } from './utils/server_mode.js';
 import { getPackageVersion } from './utils/version.js';
 
@@ -239,12 +240,7 @@ async function main() {
     transport.onmessage = (message) => {
         const msgRecord = message as Record<string, unknown>;
         // Inject session ID into all requests for task isolation and session tracking.
-        // CRITICAL: Always create params object if missing (some requests like listTasks/getTasks don't have params),
-        // otherwise mcpSessionId injection fails, breaking session isolation in multi-node setups.
-        const params = (msgRecord.params || {}) as ApifyRequestParams;
-        params._meta ??= {};
-        params._meta.mcpSessionId = mcpSessionId;
-        msgRecord.params = params;
+        msgRecord.params = injectMcpSessionId(msgRecord.params as ApifyRequestParams | undefined, mcpSessionId);
 
         sdkOnMessage?.(message);
     };

src/utils/mcp.ts

@@ -1,7 +1,7 @@
 import type { CallToolResult, ContentBlock } from '@modelcontextprotocol/sdk/types.js';
 
 import { FAILURE_CATEGORY, TOOL_STATUS } from '../const.js';
-import type { AjvErrorDetails, FailureCategory, ToolTelemetryContext } from '../types.js';
+import type { AjvErrorDetails, ApifyRequestParams, FailureCategory, ToolTelemetryContext } from '../types.js';
 import { ACTOR_RUN_LIMIT_MESSAGE, isActorRunLimitError } from './apify_errors.js';
 import { wrapJsonText } from './encode_text.js';
 import { getHttpStatusCode } from './logging.js';
@@ -10,6 +10,21 @@ import { classifyFailureCategory, getToolStatusFromError } from './tool_status.j
 /** MCP `_meta` key for Apify Actor run information. Namespaced per MCP spec. */
 export const APIFY_ACTOR_RUN_META_KEY = 'com.apify/ActorRun';
 
+/**
+ * Injects the MCP session ID into request parameters.
+ * Always ensures a params object exists, even for requests that normally have no params (e.g., listTasks/getTasks),
+ * otherwise mcpSessionId injection fails, breaking session isolation in multi-node setups.
+ * @param params Request parameters (may be undefined)
+ * @param mcpSessionId Session ID to inject
+ * @returns Params object with _meta.mcpSessionId set
+ */
+export function injectMcpSessionId(params: ApifyRequestParams | undefined, mcpSessionId: string): ApifyRequestParams {
+    const result = (params || {}) as ApifyRequestParams;
+    result._meta ??= {};
+    result._meta.mcpSessionId = mcpSessionId;
+    return result;
+}
+
 /**
  * Builds usage metadata for MCP response from a source object containing Apify run costs.
  * Nests fields under the `com.apify/ActorRun` namespaced key as required by the MCP `_meta` spec

tests/unit/utils.mcp.test.ts

@@ -8,6 +8,7 @@ import { wrapJsonText } from '../../src/utils/encode_text.js';
 import {
     computeToolResponseBytes,
     getToolCallErrorUserText,
+    injectMcpSessionId,
     respondAborted,
     respondErrorNoTelemetry,
     respondJson,
@@ -19,6 +20,42 @@ import {
 } from '../../src/utils/mcp.js';
 import { textOf } from './helpers/tool_context.js';
 
+describe('injectMcpSessionId()', () => {
+    it('returns a new params object with _meta.mcpSessionId when params is undefined', () => {
+        const result = injectMcpSessionId(undefined, 'session-123');
+        expect(result).toEqual({
+            _meta: { mcpSessionId: 'session-123' },
+        });
+        expect(typeof result).toBe('object');
+    });
+
+    it('mutates and returns the same object when params exists without _meta', () => {
+        const input = { foo: 'bar' };
+        const result = injectMcpSessionId(input, 'session-456');
+        expect(result === input).toBe(true);
+        expect(result).toEqual({
+            foo: 'bar',
+            _meta: { mcpSessionId: 'session-456' },
+        });
+    });
+
+    it('preserves other _meta fields and overwrites an existing mcpSessionId', () => {
+        const input = {
+            someParam: 'value',
+            _meta: {
+                apifyToken: 'token-abc',
+                mcpSessionId: 'old-session',
+            },
+        };
+        const result = injectMcpSessionId(input, 'session-789');
+        expect(result === input).toBe(true);
+        expect(result._meta).toEqual({
+            apifyToken: 'token-abc',
+            mcpSessionId: 'session-789',
+        });
+    });
+});
+
 describe('respondOk()', () => {
     it('returns a success response with the raw text and no isError/telemetry', () => {
         const result = respondOk('all good');