:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(experiments): let MCP agents set variant notes and screenshots (#116140)
posthog[bot]020591c5d08e
diff --git a/docs/published/handbook/engineering/ai/implementing-mcp-tools.md b/docs/published/handbook/engineering/ai/implementing-mcp-tools.mdindex 179afa1e3822..4668a440b99b 100644--- a/docs/published/handbook/engineering/ai/implementing-mcp-tools.md+++ b/docs/published/handbook/engineering/ai/implementing-mcp-tools.md@@ -632,11 +632,13 @@ Product teams own their definitions and control which operations are exposed asThe module default-exports an object with any of these functions, written `export default { beforeRequest } satisfies ToolHooks<Params>` so a misspelled name fails typecheck:- `beforeRequest(context, params)` returns the params the request should use.+ - `transformBody(context, params, body)` returns the body to send after the handler selects its declared fields. Use it when a read must supply fields the caller does not pass, such as an experiment's stored parameters and concurrency version.- `afterResponse(context, params, result)` returns the result to send to the client.- `onError(context, params, error)` returns a result that handles the error, or rethrows it.Codegen wraps the generated handler with them, so the name, schema and metadata stay generated.A `beforeRequest` that throws stops the request, and `onError` does not see that error.+ A `transformBody` that throws stops the request and reaches `onError`. When merging stored state, send the version read with that state and surface a conflict instead of retrying a stale body.`hooks` cannot be combined with `confirmed_action`.`src/tools/featureFlags/updateFeatureFlagHooks.ts` is the reference.Do not shadow a generated tool with a hand-written tool of the same name.diff --git a/products/experiments/mcp/tools.yaml b/products/experiments/mcp/tools.yamlindex 012e4e214d1a..0cbe818ea50c 100644--- a/products/experiments/mcp/tools.yaml+++ b/products/experiments/mcp/tools.yaml@@ -295,7 +295,12 @@ tools:e.g. 20 for a 20% lift), recommended_sample_size (total across all variants),recommended_running_time (days), and exposure_estimate_config. When minimum_detectable_effect isomitted, the project's default MDE is stored instead, if the project has one.+ variant_notes:+ input_schema: ExperimentVariantNotesSchema+ variant_screenshot_media_ids:+ input_schema: ExperimentVariantScreenshotMediaIdsSchemaui_app: experiment+ hooks: experiments/createExperimentHooksresponse:include:- id@@ -309,6 +314,8 @@ tools:- end_date- created_at- running_time_calculation+ - parameters.variant_notes+ - parameters.variant_screenshot_media_ids- metrics- metrics_secondary- conclusion@@ -764,8 +771,9 @@ tools:maps to stopped, or "all"), archived state (defaults to non-archived), feature_flag_id, created_by_id, tags/ excluded_tags (JSON-encoded lists of tag names), and free-text search on name and feature flag key.Supports ordering by an allowlisted set of fields (model fields plus computed "duration" and "status").- Returns paginated results with each experiment's status, dates, feature flag key, and metrics summary. Use- the returned ID for get/update/lifecycle tools.+ Returns paginated results with each experiment's status, dates, feature flag key, and metrics summary.+ variants_with_notes and variants_with_screenshots list the keys of the variants that have notes or+ screenshots. Call experiment-get to read them. Use the returned ID for get/update/lifecycle tools.param_overrides:status:description: >@@ -780,6 +788,7 @@ tools:feature_flag_id:cast: string-intui_app: experiment-list+ hooks: experiments/listExperimentsHooksresponse:include:- id@@ -795,6 +804,8 @@ tools:- created_at- updated_at- tags+ - parameters.variant_notes+ - parameters.variant_screenshot_media_idsexperiment-metrics-recalculation-create:operation: experiments_metrics_recalculation_createenabled: true@@ -1542,6 +1553,10 @@ tools:Do NOT use this to change lifecycle state — use the dedicated launch, end, pause, resume, archive, orexperiment-ship-variant tools instead. The description accepts at most 3,000 characters and longer text isrejected, so keep the hypothesis summary short.+++ Updating variant notes or screenshots checks the version read before the update. A concurrent edit returns+ 409 without overwriting it. Read the latest experiment before retrying.include_params:- name- description@@ -1584,7 +1599,12 @@ tools:recommended_running_time (days), and exposure_estimate_config.saved_metrics_ids:input_schema: SavedMetricsAttachSchema+ variant_notes:+ input_schema: ExperimentVariantNotesSchema+ variant_screenshot_media_ids:+ input_schema: ExperimentVariantScreenshotMediaIdsSchemaui_app: experiment+ hooks: experiments/updateExperimentHooksresponse:include:- id@@ -1598,6 +1618,8 @@ tools:- end_date- created_at- running_time_calculation+ - parameters.variant_notes+ - parameters.variant_screenshot_media_ids- excluded_variants- metrics- metrics_secondarydiff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.jsonindex 6f247ba1eb54..6aa5327371f1 100644--- a/services/mcp/schema/generated-tool-definitions.json+++ b/services/mcp/schema/generated-tool-definitions.json@@ -5373,7 +5373,7 @@}},"experiment-list": {- "description": "List experiments in the current project. This is the primary tool for resolving experiment references — load the finding-experiments skill for guidance on searching by name, status, recency, or description. When the reference is a feature flag key, call experiment-get-by-flag-key instead of listing.\n\nSupports filtering by status (\"draft\", \"running\", \"paused\", \"exposure_frozen\", \"stopped\", \"complete\" which maps to stopped, or \"all\"), archived state (defaults to non-archived), feature_flag_id, created_by_id, tags / excluded_tags (JSON-encoded lists of tag names), and free-text search on name and feature flag key. Supports ordering by an allowlisted set of fields (model fields plus computed \"duration\" and \"status\"). Returns paginated results with each experiment's status, dates, feature flag key, and metrics summary. Use the returned ID for get/update/lifecycle tools.",+ "description": "List experiments in the current project. This is the primary tool for resolving experiment references — load the finding-experiments skill for guidance on searching by name, status, recency, or description. When the reference is a feature flag key, call experiment-get-by-flag-key instead of listing.\n\nSupports filtering by status (\"draft\", \"running\", \"paused\", \"exposure_frozen\", \"stopped\", \"complete\" which maps to stopped, or \"all\"), archived state (defaults to non-archived), feature_flag_id, created_by_id, tags / excluded_tags (JSON-encoded lists of tag names), and free-text search on name and feature flag key. Supports ordering by an allowlisted set of fields (model fields plus computed \"duration\" and \"status\"). Returns paginated results with each experiment's status, dates, feature flag key, and metrics summary. variants_with_notes and variants_with_screenshots list the keys of the variants that have notes or screenshots. Call experiment-get to read them. Use the returned ID for get/update/lifecycle tools.","category": "Experiments","feature": "experiments","summary": "Get all experiments",@@ -5654,7 +5654,7 @@}},"experiment-update": {- "description": "RULES (follow before calling):\n1. If changing rollout or variants on a RUNNING\n experiment, you MUST warn the user about user\n experience AND statistical implications BEFORE\n making the change and get explicit confirmation.\n Load the configuring-experiment-rollout skill for\n the full warning. Do NOT silently apply the change\n — even if the user asked directly.\n\n2. If the user mentions a percentage, clarify whether\n they mean variant split or overall rollout BEFORE\n calling.\n\n3. If adding or changing metrics, load the\n configuring-experiment-analytics skill first. Call\n read-data-schema to discover available events BEFORE\n suggesting or using any event name. Never suggest\n event names you haven't confirmed exist.\n\n4. For running experiments, set\n update_feature_flag_params=true when changing\n feature_flag config — without it, the request is\n rejected because the change would not sync to the\n feature flag.\n\n5. Setting allow_unknown_events=true REQUIRES EXPLICIT\n USER CONFIRMATION. When the API returns\n \"Event(s) '...' not found\", do NOT silently retry\n with allow_unknown_events=true. Default to\n course-correcting: surface the missing event names\n and ask whether the user meant a different (existing)\n event. Only set allow_unknown_events=true when the\n user explicitly confirms the event is intentional\n (e.g. about to be instrumented). Course-correcting\n to a known event is the expected default; flipping\n the flag is the exception.\n\n\nUpdate an experiment by ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Metrics can be changed at any time including while running. Cannot add/remove variants on non-draft experiments (changing percentages between existing variants is allowed). Cannot change holdout on non-draft experiments.\n\nDo NOT use this to change lifecycle state — use the dedicated launch, end, pause, resume, archive, or experiment-ship-variant tools instead. The description accepts at most 3,000 characters and longer text is rejected, so keep the hypothesis summary short.",+ "description": "RULES (follow before calling):\n1. If changing rollout or variants on a RUNNING\n experiment, you MUST warn the user about user\n experience AND statistical implications BEFORE\n making the change and get explicit confirmation.\n Load the configuring-experiment-rollout skill for\n the full warning. Do NOT silently apply the change\n — even if the user asked directly.\n\n2. If the user mentions a percentage, clarify whether\n they mean variant split or overall rollout BEFORE\n calling.\n\n3. If adding or changing metrics, load the\n configuring-experiment-analytics skill first. Call\n read-data-schema to discover available events BEFORE\n suggesting or using any event name. Never suggest\n event names you haven't confirmed exist.\n\n4. For running experiments, set\n update_feature_flag_params=true when changing\n feature_flag config — without it, the request is\n rejected because the change would not sync to the\n feature flag.\n\n5. Setting allow_unknown_events=true REQUIRES EXPLICIT\n USER CONFIRMATION. When the API returns\n \"Event(s) '...' not found\", do NOT silently retry\n with allow_unknown_events=true. Default to\n course-correcting: surface the missing event names\n and ask whether the user meant a different (existing)\n event. Only set allow_unknown_events=true when the\n user explicitly confirms the event is intentional\n (e.g. about to be instrumented). Course-correcting\n to a known event is the expected default; flipping\n the flag is the exception.\n\n\nUpdate an experiment by ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Metrics can be changed at any time including while running. Cannot add/remove variants on non-draft experiments (changing percentages between existing variants is allowed). Cannot change holdout on non-draft experiments.\n\nDo NOT use this to change lifecycle state — use the dedicated launch, end, pause, resume, archive, or experiment-ship-variant tools instead. The description accepts at most 3,000 characters and longer text is rejected, so keep the hypothesis summary short.\n\nUpdating variant notes or screenshots checks the version read before the update. A concurrent edit returns 409 without overwriting it. Read the latest experiment before retrying.","category": "Experiments","feature": "experiments","summary": "Update experiment",diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.jsonindex 818f95876ce3..71fe0e924c8f 100644--- a/services/mcp/schema/tool-definitions-all.json+++ b/services/mcp/schema/tool-definitions-all.json@@ -5459,7 +5459,7 @@}},"experiment-list": {- "description": "List experiments in the current project. This is the primary tool for resolving experiment references — load the finding-experiments skill for guidance on searching by name, status, recency, or description. When the reference is a feature flag key, call experiment-get-by-flag-key instead of listing.\n\nSupports filtering by status (\"draft\", \"running\", \"paused\", \"exposure_frozen\", \"stopped\", \"complete\" which maps to stopped, or \"all\"), archived state (defaults to non-archived), feature_flag_id, created_by_id, tags / excluded_tags (JSON-encoded lists of tag names), and free-text search on name and feature flag key. Supports ordering by an allowlisted set of fields (model fields plus computed \"duration\" and \"status\"). Returns paginated results with each experiment's status, dates, feature flag key, and metrics summary. Use the returned ID for get/update/lifecycle tools.",+ "description": "List experiments in the current project. This is the primary tool for resolving experiment references — load the finding-experiments skill for guidance on searching by name, status, recency, or description. When the reference is a feature flag key, call experiment-get-by-flag-key instead of listing.\n\nSupports filtering by status (\"draft\", \"running\", \"paused\", \"exposure_frozen\", \"stopped\", \"complete\" which maps to stopped, or \"all\"), archived state (defaults to non-archived), feature_flag_id, created_by_id, tags / excluded_tags (JSON-encoded lists of tag names), and free-text search on name and feature flag key. Supports ordering by an allowlisted set of fields (model fields plus computed \"duration\" and \"status\"). Returns paginated results with each experiment's status, dates, feature flag key, and metrics summary. variants_with_notes and variants_with_screenshots list the keys of the variants that have notes or screenshots. Call experiment-get to read them. Use the returned ID for get/update/lifecycle tools.","category": "Experiments","feature": "experiments","summary": "Get all experiments",@@ -5754,7 +5754,7 @@}},"experiment-update": {- "description": "RULES (follow before calling):\n1. If changing rollout or variants on a RUNNING\n experiment, you MUST warn the user about user\n experience AND statistical implications BEFORE\n making the change and get explicit confirmation.\n Load the configuring-experiment-rollout skill for\n the full warning. Do NOT silently apply the change\n — even if the user asked directly.\n\n2. If the user mentions a percentage, clarify whether\n they mean variant split or overall rollout BEFORE\n calling.\n\n3. If adding or changing metrics, load the\n configuring-experiment-analytics skill first. Call\n read-data-schema to discover available events BEFORE\n suggesting or using any event name. Never suggest\n event names you haven't confirmed exist.\n\n4. For running experiments, set\n update_feature_flag_params=true when changing\n feature_flag config — without it, the request is\n rejected because the change would not sync to the\n feature flag.\n\n5. Setting allow_unknown_events=true REQUIRES EXPLICIT\n USER CONFIRMATION. When the API returns\n \"Event(s) '...' not found\", do NOT silently retry\n with allow_unknown_events=true. Default to\n course-correcting: surface the missing event names\n and ask whether the user meant a different (existing)\n event. Only set allow_unknown_events=true when the\n user explicitly confirms the event is intentional\n (e.g. about to be instrumented). Course-correcting\n to a known event is the expected default; flipping\n the flag is the exception.\n\n\nUpdate an experiment by ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Metrics can be changed at any time including while running. Cannot add/remove variants on non-draft experiments (changing percentages between existing variants is allowed). Cannot change holdout on non-draft experiments.\n\nDo NOT use this to change lifecycle state — use the dedicated launch, end, pause, resume, archive, or experiment-ship-variant tools instead. The description accepts at most 3,000 characters and longer text is rejected, so keep the hypothesis summary short.",+ "description": "RULES (follow before calling):\n1. If changing rollout or variants on a RUNNING\n experiment, you MUST warn the user about user\n experience AND statistical implications BEFORE\n making the change and get explicit confirmation.\n Load the configuring-experiment-rollout skill for\n the full warning. Do NOT silently apply the change\n — even if the user asked directly.\n\n2. If the user mentions a percentage, clarify whether\n they mean variant split or overall rollout BEFORE\n calling.\n\n3. If adding or changing metrics, load the\n configuring-experiment-analytics skill first. Call\n read-data-schema to discover available events BEFORE\n suggesting or using any event name. Never suggest\n event names you haven't confirmed exist.\n\n4. For running experiments, set\n update_feature_flag_params=true when changing\n feature_flag config — without it, the request is\n rejected because the change would not sync to the\n feature flag.\n\n5. Setting allow_unknown_events=true REQUIRES EXPLICIT\n USER CONFIRMATION. When the API returns\n \"Event(s) '...' not found\", do NOT silently retry\n with allow_unknown_events=true. Default to\n course-correcting: surface the missing event names\n and ask whether the user meant a different (existing)\n event. Only set allow_unknown_events=true when the\n user explicitly confirms the event is intentional\n (e.g. about to be instrumented). Course-correcting\n to a known event is the expected default; flipping\n the flag is the exception.\n\n\nUpdate an experiment by ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Metrics can be changed at any time including while running. Cannot add/remove variants on non-draft experiments (changing percentages between existing variants is allowed). Cannot change holdout on non-draft experiments.\n\nDo NOT use this to change lifecycle state — use the dedicated launch, end, pause, resume, archive, or experiment-ship-variant tools instead. The description accepts at most 3,000 characters and longer text is rejected, so keep the hypothesis summary short.\n\nUpdating variant notes or screenshots checks the version read before the update. A concurrent edit returns 409 without overwriting it. Read the latest experiment before retrying.","category": "Experiments","feature": "experiments","summary": "Update experiment",diff --git a/services/mcp/schema/tool-inputs.json b/services/mcp/schema/tool-inputs.jsonindex 0103f76e02fa..eba27961bb69 100644--- a/services/mcp/schema/tool-inputs.json+++ b/services/mcp/schema/tool-inputs.json@@ -587,6 +587,29 @@},"required": ["id"]},+ "ExperimentVariantNotesSchema": {+ "type": "object",+ "propertyNames": {+ "type": "string"+ },+ "additionalProperties": {+ "type": "string"+ },+ "description": "Free-text notes per variant, keyed by variant key, shown under each variant in the experiment view. Use them to document what each variant changes. On update, only the variants you pass change and the notes of other variants stay. Pass an empty string to clear the note of a variant."+ },+ "ExperimentVariantScreenshotMediaIdsSchema": {+ "type": "object",+ "propertyNames": {+ "type": "string"+ },+ "additionalProperties": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "description": "Screenshot media IDs per variant, keyed by variant key, shown under each variant in the experiment view. Each value is the complete list of uploaded media IDs for that variant. On update, only the variants you pass change and the screenshots of other variants stay. Pass an empty list to remove all screenshots of a variant."+ },"ExternalDataJobsAfterSchema": {"type": "string","description": "ISO timestamp — only return jobs created after this date (e.g. \"2025-01-01T00:00:00Z\")."diff --git a/services/mcp/scripts/generate-tools.ts b/services/mcp/scripts/generate-tools.tsindex 147dce6dfa71..08276daad2bc 100644--- a/services/mcp/scripts/generate-tools.ts+++ b/services/mcp/scripts/generate-tools.ts@@ -1230,6 +1230,7 @@ function generateToolCode(handlerBody += ` body[${JSON.stringify(key)}] = ${JSON.stringify(value)}\n`}}+ const transformsBody = hasBody && !!config.hooksconst httpMethod = isSoftDelete ? 'PATCH' : resolved.methodhandlerBody += ` const result = await context.api.request<${responseType ?? 'unknown'}>({\n`@@ -1237,6 +1238,8 @@ function generateToolCode(handlerBody += ` path: ${pathExpr},\n`if (isSoftDelete) {handlerBody += ` body: { ${softDeleteField}: true },\n`+ } else if (transformsBody) {+ handlerBody += ` body: await transformRequestBody(${hooksVarName(toolName)}, context, params, body),\n`} else if (hasBody) {handlerBody += ` body,\n`}@@ -2099,7 +2102,7 @@ function generateCategoryFile(const hookedTools = enabledTools.filter(([, toolConfig]) => toolConfig.hooks)const hooksImportLines =hookedTools.length > 0- ? `import { withToolHooks } from '@/tools/tool-hooks'\n` ++ ? `import { ${toolCodes.some((code) => code.includes('transformRequestBody(')) ? 'transformRequestBody, ' : ''}withToolHooks } from '@/tools/tool-hooks'\n` +hookedTools.map(([name, toolConfig]) => `import ${hooksVarName(name)} from '@/tools/${toolConfig.hooks}'\n`).join('')diff --git a/services/mcp/src/schema/experiments.ts b/services/mcp/src/schema/experiments.tsindex 4c03026ca8e8..8438c3a61e77 100644--- a/services/mcp/src/schema/experiments.ts+++ b/services/mcp/src/schema/experiments.ts@@ -119,6 +119,8 @@ export const ExperimentSchema = z.object({minimum_detectable_effect: z.number().nullish(),recommended_running_time: z.number().nullish(),recommended_sample_size: z.number().nullish(),+ variant_notes: z.record(z.string(), z.string()).nullish(),+ variant_screenshot_media_ids: z.record(z.string(), z.union([z.string(), z.array(z.string())])).nullish(),}).nullish(),start_date: z.string().nullish(),diff --git a/services/mcp/src/schema/tool-inputs.ts b/services/mcp/src/schema/tool-inputs.tsindex 9f3dbe0f8922..b9218306c61a 100644--- a/services/mcp/src/schema/tool-inputs.ts+++ b/services/mcp/src/schema/tool-inputs.ts@@ -486,6 +486,20 @@ export const SavedMetricsAttachSchema = z"The complete desired set of shared (saved) metrics for the experiment — this REPLACES all existing saved-metric links, it does not append. To add or remove one, first read the experiment's current saved_metrics via experiment-get and resend the full set. Pass an empty array to detach all shared metrics.")+export const ExperimentVariantNotesSchema = z+ .record(z.string(), z.string())+ .describe(+ 'Free-text notes per variant, keyed by variant key, shown under each variant in the experiment view. Use them to document what each variant changes. On update, only the variants you pass change and the notes of other variants stay. Pass an empty string to clear the note of a variant.'+ )+ .optional()++export const ExperimentVariantScreenshotMediaIdsSchema = z+ .record(z.string(), z.array(z.string()))+ .describe(+ 'Screenshot media IDs per variant, keyed by variant key, shown under each variant in the experiment view. Each value is the complete list of uploaded media IDs for that variant. On update, only the variants you pass change and the screenshots of other variants stay. Pass an empty list to remove all screenshots of a variant.'+ )+ .optional()+// Agents reach for `experimentId` / `experiment_id` here as often as `id` — the same// alias set the generated experiment tools accept via their tools.yaml overrides.export const ExperimentResultsGetSchema = z.preprocess(diff --git a/services/mcp/src/tools/experiments/createExperimentHooks.ts b/services/mcp/src/tools/experiments/createExperimentHooks.tsnew file mode 100644index 000000000000..19a049cf20f2--- /dev/null+++ b/services/mcp/src/tools/experiments/createExperimentHooks.ts@@ -0,0 +1,8 @@+/** Hooks for the generated `experiment-create` tool. They move the variant detail inputs into `parameters`. */+import type { ToolHooks } from '@/tools/tool-hooks'++import { type VariantDetailParams, withVariantDetailsInParameters } from './variantDetails'++export default {+ transformBody: (_context, params, body) => withVariantDetailsInParameters(body, params, undefined),+} satisfies ToolHooks<VariantDetailParams>diff --git a/services/mcp/src/tools/experiments/listExperimentsHooks.ts b/services/mcp/src/tools/experiments/listExperimentsHooks.tsnew file mode 100644index 000000000000..3f50e534f60b--- /dev/null+++ b/services/mcp/src/tools/experiments/listExperimentsHooks.ts@@ -0,0 +1,11 @@+/** Hooks for the generated `experiment-list` tool. They summarize which variants have notes or screenshots. */+import type { ToolHooks } from '@/tools/tool-hooks'++import { summarizeVariantDetails } from './variantDetails'++export default {+ afterResponse: (_context, _params, result) => {+ const page = result as { results?: { parameters?: unknown }[] }+ return { ...page, results: (page.results ?? []).map(summarizeVariantDetails) }+ },+} satisfies ToolHooks<Record<string, unknown>>diff --git a/services/mcp/src/tools/experiments/updateExperimentHooks.ts b/services/mcp/src/tools/experiments/updateExperimentHooks.tsnew file mode 100644index 000000000000..5c4bf257d00f--- /dev/null+++ b/services/mcp/src/tools/experiments/updateExperimentHooks.ts@@ -0,0 +1,33 @@+/**+ * Hooks for the generated `experiment-update` tool. A PATCH replaces the whole `parameters`+ * object, so the hook reads the stored `parameters` and merges the variant detail inputs into it.+ */+import type { Schemas } from '@/api/generated'+import type { ToolHooks } from '@/tools/tool-hooks'+import type { Context } from '@/tools/types'++import { hasVariantDetails, type VariantDetailParams, withVariantDetailsInParameters } from './variantDetails'++type UpdateParams = VariantDetailParams & { id: number | string }++async function transformBody(+ context: Context,+ params: UpdateParams,+ body: Record<string, unknown>+): Promise<Record<string, unknown>> {+ if (!hasVariantDetails(params)) {+ return body+ }+ // No try/catch: a failed GET must abort before the PATCH, else the PATCH drops the other keys.+ const projectId = await context.stateManager.getProjectId()+ const existing = await context.api.request<Schemas.Experiment>({+ method: 'GET',+ path: `/api/projects/${encodeURIComponent(String(projectId))}/experiments/${encodeURIComponent(String(params.id))}/`,+ })+ return {+ ...withVariantDetailsInParameters(body, params, existing.parameters as Record<string, unknown> | null),+ version: existing.version ?? 0,+ }+}++export default { transformBody } satisfies ToolHooks<UpdateParams>diff --git a/services/mcp/src/tools/experiments/variantDetails.ts b/services/mcp/src/tools/experiments/variantDetails.tsnew file mode 100644index 000000000000..b4b9f7179eba--- /dev/null+++ b/services/mcp/src/tools/experiments/variantDetails.ts@@ -0,0 +1,84 @@+/**+ * Maps the `variant_notes` and `variant_screenshot_media_ids` tool inputs onto the experiment's+ * `parameters`, and summarizes them for list responses. The API stores both keys in `parameters`,+ * next to the deprecated flag-config keys that the tools do not expose.+ */++const VARIANT_DETAIL_KEYS = ['variant_notes', 'variant_screenshot_media_ids'] as const++// Reads project the linked flag's config into `parameters`. Writing these keys back sends flag+// config through the deprecated surface, so a merged `parameters` must not carry them.+const PROJECTED_FLAG_CONFIG_KEYS = new Set([+ 'feature_flag_variants',+ 'rollout_percentage',+ 'aggregation_group_type_index',+ 'feature_flag_payloads',+ 'ensure_experience_continuity',+])++type ExperimentParameters = Record<string, unknown>++export type VariantDetailParams = {+ variant_notes?: Record<string, string> | undefined+ variant_screenshot_media_ids?: Record<string, string[]> | undefined+ [key: string]: unknown+}++export function hasVariantDetails(params: VariantDetailParams): boolean {+ return VARIANT_DETAIL_KEYS.some((key) => params[key] !== undefined)+}++/**+ * Moves the variant detail inputs from the top level of the body into `parameters`. Each input+ * changes only the variants it names, so the result keeps the other variants of `existing`.+ */+export function withVariantDetailsInParameters(+ body: Record<string, unknown>,+ params: VariantDetailParams,+ existing: ExperimentParameters | null | undefined+): Record<string, unknown> {+ const { variant_notes: _notes, variant_screenshot_media_ids: _screenshots, ...rest } = body+ if (!hasVariantDetails(params)) {+ return rest+ }+ const parameters: ExperimentParameters = Object.fromEntries(+ Object.entries(existing ?? {}).filter(([key]) => !PROJECTED_FLAG_CONFIG_KEYS.has(key))+ )+ for (const key of VARIANT_DETAIL_KEYS) {+ const input = params[key]+ if (input !== undefined) {+ parameters[key] = { ...asRecord(parameters[key]), ...input }+ }+ }+ return { ...rest, parameters }+}++/** Replaces the variant detail maps of a list row with the keys of the variants that have them. */+export function summarizeVariantDetails<T extends { parameters?: unknown }>(+ row: T+): Omit<T, 'parameters'> & { variants_with_notes: string[]; variants_with_screenshots: string[] } {+ const { parameters, ...rest } = row+ const details = asRecord(parameters)+ return {+ ...rest,+ variants_with_notes: variantKeysWhere(details.variant_notes, (note) => typeof note === 'string' && note !== ''),+ variants_with_screenshots: variantKeysWhere(+ details.variant_screenshot_media_ids,+ (ids) =>+ (typeof ids === 'string' && ids !== '') ||+ (Array.isArray(ids) && ids.some((id) => typeof id === 'string' && id !== ''))+ ),+ }+}++function variantKeysWhere(value: unknown, predicate: (entry: unknown) => boolean): string[] {+ return Object.entries(asRecord(value))+ .filter(([, entry]) => predicate(entry))+ .map(([key]) => key)+}++function asRecord(value: unknown): Record<string, unknown> {+ return value !== null && typeof value === 'object' && !Array.isArray(value)+ ? (value as Record<string, unknown>)+ : {}+}diff --git a/services/mcp/src/tools/generated/experiments.ts b/services/mcp/src/tools/generated/experiments.tsindex c5ccbf8ddb5f..3a61893cefc4 100644--- a/services/mcp/src/tools/generated/experiments.ts+++ b/services/mcp/src/tools/generated/experiments.ts@@ -4,8 +4,16 @@ import { z } from 'zod'import type { Schemas } from '@/api/generated'import * as orvalSchemas from '@/generated/experiments/api'import { withUiApp } from '@/resources/ui-apps'-import { SavedMetricsAttachSchema } from '@/schema/tool-inputs'+import {+ ExperimentVariantNotesSchema,+ ExperimentVariantScreenshotMediaIdsSchema,+ SavedMetricsAttachSchema,+} from '@/schema/tool-inputs'import { castStringToInt, normalizeParamAliases } from '@/tools/cast-helpers'+import hooks_experimentCreate from '@/tools/experiments/createExperimentHooks'+import hooks_experimentList from '@/tools/experiments/listExperimentsHooks'+import hooks_experimentUpdate from '@/tools/experiments/updateExperimentHooks'+import { transformRequestBody, withToolHooks } from '@/tools/tool-hooks'import {withPostHogUrl,omitResponseFields,@@ -243,6 +251,8 @@ const ExperimentCreateSchema = () => {running_time_calculation: ExperimentsCreateBody.shape['running_time_calculation'].describe("Persist a running-time / sample-size plan onto the experiment (the planning target shown in the experiment's running-time panel). Object with optional keys: minimum_detectable_effect (percentage, e.g. 20 for a 20% lift), recommended_sample_size (total across all variants), recommended_running_time (days), and exposure_estimate_config. When minimum_detectable_effect is omitted, the project's default MDE is stored instead, if the project has one."),+ variant_notes: ExperimentVariantNotesSchema,+ variant_screenshot_media_ids: ExperimentVariantScreenshotMediaIdsSchema,})}@@ -250,64 +260,75 @@ const experimentCreate = (): ToolBase<ReturnType<typeof ExperimentCreateSchema>,withUiApp('experiment', {name: 'experiment-create',schema: ExperimentCreateSchema(),- handler: async (context: Context, params: z.infer<ReturnType<typeof ExperimentCreateSchema>>) => {- const projectId = await context.stateManager.getProjectId()- const body: Record<string, unknown> = {}- if (params.name !== undefined) {- body['name'] = params.name- }- if (params.description !== undefined) {- body['description'] = params.description- }- if (params.feature_flag_key !== undefined) {- body['feature_flag_key'] = params.feature_flag_key- }- if (params.feature_flag !== undefined) {- body['feature_flag'] = params.feature_flag- }- if (params.holdout_id !== undefined) {- body['holdout_id'] = params.holdout_id+ handler: withToolHooks(+ hooks_experimentCreate,+ async (context: Context, params: z.infer<ReturnType<typeof ExperimentCreateSchema>>) => {+ const projectId = await context.stateManager.getProjectId()+ const body: Record<string, unknown> = {}+ if (params.name !== undefined) {+ body['name'] = params.name+ }+ if (params.description !== undefined) {+ body['description'] = params.description+ }+ if (params.feature_flag_key !== undefined) {+ body['feature_flag_key'] = params.feature_flag_key+ }+ if (params.feature_flag !== undefined) {+ body['feature_flag'] = params.feature_flag+ }+ if (params.holdout_id !== undefined) {+ body['holdout_id'] = params.holdout_id+ }+ if (params.running_time_calculation !== undefined) {+ body['running_time_calculation'] = params.running_time_calculation+ }+ if (params.exposure_criteria !== undefined) {+ body['exposure_criteria'] = params.exposure_criteria+ }+ if (params.stats_config !== undefined) {+ body['stats_config'] = params.stats_config+ }+ if (params.allow_unknown_events !== undefined) {+ body['allow_unknown_events'] = params.allow_unknown_events+ }+ if (params.tags !== undefined) {+ body['tags'] = params.tags+ }+ if (params.variant_notes !== undefined) {+ body['variant_notes'] = params.variant_notes+ }+ if (params.variant_screenshot_media_ids !== undefined) {+ body['variant_screenshot_media_ids'] = params.variant_screenshot_media_ids+ }+ const result = await context.api.request<Schemas.Experiment>({+ method: 'POST',+ path: `/api/projects/${encodeURIComponent(String(projectId))}/experiments/`,+ body: await transformRequestBody(hooks_experimentCreate, context, params, body),+ })+ const filtered = pickResponseFields(result, [+ 'id',+ 'name',+ 'description',+ 'type',+ 'feature_flag_key',+ 'status',+ 'archived',+ 'start_date',+ 'end_date',+ 'created_at',+ 'running_time_calculation',+ 'parameters.variant_notes',+ 'parameters.variant_screenshot_media_ids',+ 'metrics',+ 'metrics_secondary',+ 'conclusion',+ 'conclusion_comment',+ 'tags',+ ]) as typeof result+ return await withPostHogUrl(context, filtered, `/experiments/${filtered.id}`)}- if (params.running_time_calculation !== undefined) {- body['running_time_calculation'] = params.running_time_calculation- }- if (params.exposure_criteria !== undefined) {- body['exposure_criteria'] = params.exposure_criteria- }- if (params.stats_config !== undefined) {- body['stats_config'] = params.stats_config- }- if (params.allow_unknown_events !== undefined) {- body['allow_unknown_events'] = params.allow_unknown_events- }- if (params.tags !== undefined) {- body['tags'] = params.tags- }- const result = await context.api.request<Schemas.Experiment>({- method: 'POST',- path: `/api/projects/${encodeURIComponent(String(projectId))}/experiments/`,- body,- })- const filtered = pickResponseFields(result, [- 'id',- 'name',- 'description',- 'type',- 'feature_flag_key',- 'status',- 'archived',- 'start_date',- 'end_date',- 'created_at',- 'running_time_calculation',- 'metrics',- 'metrics_secondary',- 'conclusion',- 'conclusion_comment',- 'tags',- ]) as typeof result- return await withPostHogUrl(context, filtered, `/experiments/${filtered.id}`)- },+ ),})const ExperimentCreateFromPromptSchema = () => {@@ -770,57 +791,64 @@ const experimentList = (): ToolBase<withUiApp('experiment-list', {name: 'experiment-list',schema: ExperimentListSchema(),- handler: async (context: Context, params: z.infer<ReturnType<typeof ExperimentListSchema>>) => {- const projectId = await context.stateManager.getProjectId()- const result = await context.api.request<Schemas.PaginatedExperimentBasicList>({- method: 'GET',- path: `/api/projects/${encodeURIComponent(String(projectId))}/experiments/`,- query: {- archived: params.archived,- created_by_id: params.created_by_id,- event: params.event,- excluded_tags: params.excluded_tags,- feature_flag_id: params.feature_flag_id,- limit: params.limit,- offset: params.offset,- order: params.order,- prompt_name: params.prompt_name,- search: params.search,- status: params.status,- tags: params.tags,- },- })- const filtered = {- ...result,- results: (result.results ?? []).map((item: any) =>- pickResponseFields(item, [- 'id',- 'name',- 'description',- 'feature_flag_key',- 'feature_flag',- 'start_date',- 'end_date',- 'archived',- 'type',- 'status',- 'created_at',- 'updated_at',- 'tags',- ])- ),- } as typeof result- return await withPostHogUrl(- context,- {- ...filtered,- results: await Promise.all(- (filtered.results ?? []).map((item) => withPostHogUrl(context, item, `/experiments/${item.id}`))+ handler: withToolHooks(+ hooks_experimentList,+ async (context: Context, params: z.infer<ReturnType<typeof ExperimentListSchema>>) => {+ const projectId = await context.stateManager.getProjectId()+ const result = await context.api.request<Schemas.PaginatedExperimentBasicList>({+ method: 'GET',+ path: `/api/projects/${encodeURIComponent(String(projectId))}/experiments/`,+ query: {+ archived: params.archived,+ created_by_id: params.created_by_id,+ event: params.event,+ excluded_tags: params.excluded_tags,+ feature_flag_id: params.feature_flag_id,+ limit: params.limit,+ offset: params.offset,+ order: params.order,+ prompt_name: params.prompt_name,+ search: params.search,+ status: params.status,+ tags: params.tags,+ },+ })+ const filtered = {+ ...result,+ results: (result.results ?? []).map((item: any) =>+ pickResponseFields(item, [+ 'id',+ 'name',+ 'description',+ 'feature_flag_key',+ 'feature_flag',+ 'start_date',+ 'end_date',+ 'archived',+ 'type',+ 'status',+ 'created_at',+ 'updated_at',+ 'tags',+ 'parameters.variant_notes',+ 'parameters.variant_screenshot_media_ids',+ ])),- },- '/experiments'- )- },+ } as typeof result+ return await withPostHogUrl(+ context,+ {+ ...filtered,+ results: await Promise.all(+ (filtered.results ?? []).map((item) =>+ withPostHogUrl(context, item, `/experiments/${item.id}`)+ )+ ),+ },+ '/experiments'+ )+ }+ ),})const ExperimentMetricsRecalculationCreateSchema = () => {@@ -1471,6 +1499,8 @@ const ExperimentUpdateSchema = () => {"Persist a running-time / sample-size plan onto the experiment (the planning target shown in the experiment's running-time panel). Object with optional keys: minimum_detectable_effect (percentage, e.g. 20 for a 20% lift), recommended_sample_size (total across all variants), recommended_running_time (days), and exposure_estimate_config."),saved_metrics_ids: SavedMetricsAttachSchema.optional(),+ variant_notes: ExperimentVariantNotesSchema.optional(),+ variant_screenshot_media_ids: ExperimentVariantScreenshotMediaIdsSchema.optional(),}))}@@ -1479,93 +1509,104 @@ const experimentUpdate = (): ToolBase<ReturnType<typeof ExperimentUpdateSchema>,withUiApp('experiment', {name: 'experiment-update',schema: ExperimentUpdateSchema(),- handler: async (context: Context, params: z.infer<ReturnType<typeof ExperimentUpdateSchema>>) => {- const projectId = await context.stateManager.getProjectId()- const body: Record<string, unknown> = {}- if (params.name !== undefined) {- body['name'] = params.name- }- if (params.description !== undefined) {- body['description'] = params.description- }- if (params.feature_flag !== undefined) {- body['feature_flag'] = params.feature_flag- }- if (params.holdout_id !== undefined) {- body['holdout_id'] = params.holdout_id- }- if (params.running_time_calculation !== undefined) {- body['running_time_calculation'] = params.running_time_calculation- }- if (params.excluded_variants !== undefined) {- body['excluded_variants'] = params.excluded_variants- }- if (params.saved_metrics_ids !== undefined) {- body['saved_metrics_ids'] = params.saved_metrics_ids- }- if (params.archived !== undefined) {- body['archived'] = params.archived- }- if (params.exposure_criteria !== undefined) {- body['exposure_criteria'] = params.exposure_criteria- }- if (params.metrics !== undefined) {- body['metrics'] = params.metrics- }- if (params.metrics_secondary !== undefined) {- body['metrics_secondary'] = params.metrics_secondary- }- if (params.stats_config !== undefined) {- body['stats_config'] = params.stats_config- }- if (params.allow_unknown_events !== undefined) {- body['allow_unknown_events'] = params.allow_unknown_events- }- if (params.conclusion !== undefined) {- body['conclusion'] = params.conclusion- }- if (params.conclusion_comment !== undefined) {- body['conclusion_comment'] = params.conclusion_comment- }- if (params.update_feature_flag_params !== undefined) {- body['update_feature_flag_params'] = params.update_feature_flag_params+ handler: withToolHooks(+ hooks_experimentUpdate,+ async (context: Context, params: z.infer<ReturnType<typeof ExperimentUpdateSchema>>) => {+ const projectId = await context.stateManager.getProjectId()+ const body: Record<string, unknown> = {}+ if (params.name !== undefined) {+ body['name'] = params.name+ }+ if (params.description !== undefined) {+ body['description'] = params.description+ }+ if (params.feature_flag !== undefined) {+ body['feature_flag'] = params.feature_flag+ }+ if (params.holdout_id !== undefined) {+ body['holdout_id'] = params.holdout_id+ }+ if (params.running_time_calculation !== undefined) {+ body['running_time_calculation'] = params.running_time_calculation+ }+ if (params.excluded_variants !== undefined) {+ body['excluded_variants'] = params.excluded_variants+ }+ if (params.saved_metrics_ids !== undefined) {+ body['saved_metrics_ids'] = params.saved_metrics_ids+ }+ if (params.archived !== undefined) {+ body['archived'] = params.archived+ }+ if (params.exposure_criteria !== undefined) {+ body['exposure_criteria'] = params.exposure_criteria+ }+ if (params.metrics !== undefined) {+ body['metrics'] = params.metrics+ }+ if (params.metrics_secondary !== undefined) {+ body['metrics_secondary'] = params.metrics_secondary+ }+ if (params.stats_config !== undefined) {+ body['stats_config'] = params.stats_config+ }+ if (params.allow_unknown_events !== undefined) {+ body['allow_unknown_events'] = params.allow_unknown_events+ }+ if (params.conclusion !== undefined) {+ body['conclusion'] = params.conclusion+ }+ if (params.conclusion_comment !== undefined) {+ body['conclusion_comment'] = params.conclusion_comment+ }+ if (params.update_feature_flag_params !== undefined) {+ body['update_feature_flag_params'] = params.update_feature_flag_params+ }+ if (params.tags !== undefined) {+ body['tags'] = params.tags+ }+ if (params.variant_notes !== undefined) {+ body['variant_notes'] = params.variant_notes+ }+ if (params.variant_screenshot_media_ids !== undefined) {+ body['variant_screenshot_media_ids'] = params.variant_screenshot_media_ids+ }+ const result = await context.api.request<Schemas.Experiment>({+ method: 'PATCH',+ path: `/api/projects/${encodeURIComponent(String(projectId))}/experiments/${encodeURIComponent(String(params.id))}/`,+ body: await transformRequestBody(hooks_experimentUpdate, context, params, body),+ })+ const filtered = pickResponseFields(result, [+ 'id',+ 'name',+ 'description',+ 'type',+ 'feature_flag_key',+ 'status',+ 'archived',+ 'start_date',+ 'end_date',+ 'created_at',+ 'running_time_calculation',+ 'parameters.variant_notes',+ 'parameters.variant_screenshot_media_ids',+ 'excluded_variants',+ 'metrics',+ 'metrics_secondary',+ 'saved_metrics.*.id',+ 'saved_metrics.*.experiment',+ 'saved_metrics.*.saved_metric',+ 'saved_metrics.*.metadata',+ 'saved_metrics.*.created_at',+ 'saved_metrics.*.query',+ 'saved_metrics.*.name',+ 'conclusion',+ 'conclusion_comment',+ 'tags',+ ]) as typeof result+ return await withPostHogUrl(context, filtered, `/experiments/${filtered.id}`)}- if (params.tags !== undefined) {- body['tags'] = params.tags- }- const result = await context.api.request<Schemas.Experiment>({- method: 'PATCH',- path: `/api/projects/${encodeURIComponent(String(projectId))}/experiments/${encodeURIComponent(String(params.id))}/`,- body,- })- const filtered = pickResponseFields(result, [- 'id',- 'name',- 'description',- 'type',- 'feature_flag_key',- 'status',- 'archived',- 'start_date',- 'end_date',- 'created_at',- 'running_time_calculation',- 'excluded_variants',- 'metrics',- 'metrics_secondary',- 'saved_metrics.*.id',- 'saved_metrics.*.experiment',- 'saved_metrics.*.saved_metric',- 'saved_metrics.*.metadata',- 'saved_metrics.*.created_at',- 'saved_metrics.*.query',- 'saved_metrics.*.name',- 'conclusion',- 'conclusion_comment',- 'tags',- ]) as typeof result- return await withPostHogUrl(context, filtered, `/experiments/${filtered.id}`)- },+ ),})const ExperimentsBulkUpdateTagsCreateSchema = () => {diff --git a/services/mcp/src/tools/generated/feature_flags.ts b/services/mcp/src/tools/generated/feature_flags.tsindex d467ece9ad21..655256703789 100644--- a/services/mcp/src/tools/generated/feature_flags.ts+++ b/services/mcp/src/tools/generated/feature_flags.ts@@ -7,7 +7,7 @@ import { withUiApp } from '@/resources/ui-apps'import { validateDistinctIdPersonIdExclusive } from '@/schema/tool-inputs'import { castStringToInt, normalizeParamAliases } from '@/tools/cast-helpers'import hooks_updateFeatureFlag from '@/tools/featureFlags/updateFeatureFlagHooks'-import { withToolHooks } from '@/tools/tool-hooks'+import { transformRequestBody, withToolHooks } from '@/tools/tool-hooks'import { withPostHogUrl, pickResponseFields, type WithPostHogUrl } from '@/tools/tool-utils'import type { Context, ToolBase, ZodObjectAny } from '@/tools/types'@@ -1050,7 +1050,7 @@ const updateFeatureFlag = (): ToolBase<const result = await context.api.request<Schemas.FeatureFlag>({method: 'PATCH',path: `/api/projects/${encodeURIComponent(String(projectId))}/feature_flags/${encodeURIComponent(String(params.id))}/`,- body,+ body: await transformRequestBody(hooks_updateFeatureFlag, context, params, body),})return await withPostHogUrl(context, result, `/feature-flags/${result.id}`)}diff --git a/services/mcp/src/tools/generated/logs.ts b/services/mcp/src/tools/generated/logs.tsindex 663a902e499e..a4c2f5a7ee90 100644--- a/services/mcp/src/tools/generated/logs.ts+++ b/services/mcp/src/tools/generated/logs.ts@@ -8,7 +8,7 @@ import hooks_logsFacetValuesCreate from '@/tools/logs/redactCredentialsHooks'import hooks_logsPatterns from '@/tools/logs/redactCredentialsHooks'import hooks_logsPatternsDiff from '@/tools/logs/redactCredentialsHooks'import hooks_queryLogs from '@/tools/logs/redactCredentialsHooks'-import { withToolHooks } from '@/tools/tool-hooks'+import { transformRequestBody, withToolHooks } from '@/tools/tool-hooks'import { withPostHogUrl, pickResponseFields, omitResponseFields, type WithPostHogUrl } from '@/tools/tool-utils'import type { Context, ToolBase, ZodObjectAny } from '@/tools/types'@@ -690,7 +690,7 @@ const logsFacetValuesCreate = (): ToolBase<const result = await context.api.request<Schemas._LogsFacetValuesResponse>({method: 'POST',path: `/api/projects/${encodeURIComponent(String(projectId))}/logs/facet_values/`,- body,+ body: await transformRequestBody(hooks_logsFacetValuesCreate, context, params, body),})const filtered = pickResponseFields(result, ['results']) as typeof resultreturn filtered@@ -741,7 +741,7 @@ const logsPatterns = (): ToolBase<ReturnType<typeof LogsPatternsSchema>, Schemasconst result = await context.api.request<Schemas._LogsPatternsResponse>({method: 'POST',path: `/api/projects/${encodeURIComponent(String(projectId))}/logs/patterns/`,- body,+ body: await transformRequestBody(hooks_logsPatterns, context, params, body),})const filtered = omitResponseFields(result, ['patterns.*.examples',@@ -780,7 +780,7 @@ const logsPatternsDiff = (): ToolBase<const result = await context.api.request<Schemas._LogsPatternsDiffResponse>({method: 'POST',path: `/api/projects/${encodeURIComponent(String(projectId))}/logs/patterns_diff/`,- body,+ body: await transformRequestBody(hooks_logsPatternsDiff, context, params, body),})const filtered = omitResponseFields(result, ['entries.*.pattern.pattern',@@ -876,7 +876,7 @@ const queryLogs = (): ToolBase<ReturnType<typeof QueryLogsSchema>, Schemas._Logsconst result = await context.api.request<Schemas._LogsQueryResponse>({method: 'POST',path: `/api/projects/${encodeURIComponent(String(projectId))}/logs/query/`,- body,+ body: await transformRequestBody(hooks_queryLogs, context, params, body),})const filtered = pickResponseFields(result, ['results']) as typeof resultreturn filtereddiff --git a/services/mcp/src/tools/generated/workflows.ts b/services/mcp/src/tools/generated/workflows.tsindex 508f5dd4becd..fad7f4dc2794 100644--- a/services/mcp/src/tools/generated/workflows.ts+++ b/services/mcp/src/tools/generated/workflows.ts@@ -5,7 +5,7 @@ import type { Schemas } from '@/api/generated'import * as orvalSchemas from '@/generated/workflows/api'import { withUiApp } from '@/resources/ui-apps'import { WorkflowActionEmailPatchSchema, WorkflowGraphPatchSchema } from '@/schema/tool-inputs'-import { withToolHooks } from '@/tools/tool-hooks'+import { transformRequestBody, withToolHooks } from '@/tools/tool-hooks'import { withPostHogUrl, pickResponseFields, type WithPostHogUrl } from '@/tools/tool-utils'import type { Context, ToolBase, ZodObjectAny } from '@/tools/types'import hooks_workflowsCreate from '@/tools/workflows/broadcastLinkHooks'@@ -144,7 +144,7 @@ const workflowsCreate = (): ToolBase<ReturnType<typeof WorkflowsCreateSchema>, Wconst result = await context.api.request<Schemas.HogFlow>({method: 'POST',path: `/api/projects/${encodeURIComponent(String(projectId))}/hog_flows/`,- body,+ body: await transformRequestBody(hooks_workflowsCreate, context, params, body),})return await withPostHogUrl(context, result, `/workflows/${result.id}/workflow`)}@@ -178,7 +178,7 @@ const workflowsDataSuggestionsCreate = (): ToolBase<const result = await context.api.request<Schemas.DataSuggestionBuildResponse>({method: 'POST',path: `/api/projects/${encodeURIComponent(String(projectId))}/workflow_data_suggestions/build/`,- body,+ body: await transformRequestBody(hooks_workflowsDataSuggestionsCreate, context, params, body),})const filtered = pickResponseFields(result, ['status',@@ -874,7 +874,7 @@ const workflowsUpdate = (): ToolBase<ReturnType<typeof WorkflowsUpdateSchema>, Wconst result = await context.api.request<Schemas.HogFlowUpdate>({method: 'PATCH',path: `/api/projects/${encodeURIComponent(String(projectId))}/hog_flows/${encodeURIComponent(String(params.id))}/`,- body,+ body: await transformRequestBody(hooks_workflowsUpdate, context, params, body),})return await withPostHogUrl(context, result, `/workflows/${result.id}/workflow`)}diff --git a/services/mcp/src/tools/tool-hooks.ts b/services/mcp/src/tools/tool-hooks.tsindex bf6f00b6cf7d..91c6585077a9 100644--- a/services/mcp/src/tools/tool-hooks.ts+++ b/services/mcp/src/tools/tool-hooks.ts@@ -11,6 +11,12 @@ import type { Context } from '@/tools/types'export interface ToolHooks<TParams = never> {/** Runs before the request. Return the params the request should use. */beforeRequest?(context: Context, params: TParams): TParams | Promise<TParams>+ /** Runs after the generated handler builds the request body. Return the body to send. */+ transformBody?(+ context: Context,+ params: TParams,+ body: Record<string, unknown>+ ): Record<string, unknown> | Promise<Record<string, unknown>>/** Runs after a successful request. Return the result to send to the client. */afterResponse?(context: Context, params: TParams, result: unknown): unknown/** Runs when the request fails. Return a result to handle the error, or rethrow it to keep it. */@@ -40,3 +46,13 @@ export function withToolHooks<TParams, TResult>(return hooks.afterResponse ? ((await hooks.afterResponse(context, requestParams, result)) as TResult) : result}}++/** Applies the transformBody hook to a generated request body, or returns the body unchanged. */+export async function transformRequestBody<TParams>(+ hooks: ToolHooks<TParams>,+ context: Context,+ params: TParams,+ body: Record<string, unknown>+): Promise<Record<string, unknown>> {+ return hooks.transformBody ? await hooks.transformBody(context, params, body) : body+}diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/experiment-create.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/experiment-create.jsonindex 42d699e38ef5..3798f3601df9 100644--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/experiment-create.json+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/experiment-create.json@@ -5999,6 +5999,29 @@},"maxItems": 100,"type": "array"+ },+ "variant_notes": {+ "additionalProperties": {+ "type": "string"+ },+ "description": "Free-text notes per variant, keyed by variant key, shown under each variant in the experiment view. Use them to document what each variant changes. On update, only the variants you pass change and the notes of other variants stay. Pass an empty string to clear the note of a variant.",+ "propertyNames": {+ "type": "string"+ },+ "type": "object"+ },+ "variant_screenshot_media_ids": {+ "additionalProperties": {+ "items": {+ "type": "string"+ },+ "type": "array"+ },+ "description": "Screenshot media IDs per variant, keyed by variant key, shown under each variant in the experiment view. Each value is the complete list of uploaded media IDs for that variant. On update, only the variants you pass change and the screenshots of other variants stay. Pass an empty list to remove all screenshots of a variant.",+ "propertyNames": {+ "type": "string"+ },+ "type": "object"}},"required": ["name", "feature_flag_key"],diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/experiment-update.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/experiment-update.jsonindex 1ecc543bdabe..180b96607900 100644--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/experiment-update.json+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/experiment-update.json@@ -9739,6 +9739,29 @@"update_feature_flag_params": {"description": "When true, sync the flag config sent in this request (via the `feature_flag` object) to the linked feature flag. Draft experiments always sync regardless. On a running experiment, `feature_flag` config without this flag is rejected.","type": "boolean"+ },+ "variant_notes": {+ "additionalProperties": {+ "type": "string"+ },+ "description": "Free-text notes per variant, keyed by variant key, shown under each variant in the experiment view. Use them to document what each variant changes. On update, only the variants you pass change and the notes of other variants stay. Pass an empty string to clear the note of a variant.",+ "propertyNames": {+ "type": "string"+ },+ "type": "object"+ },+ "variant_screenshot_media_ids": {+ "additionalProperties": {+ "items": {+ "type": "string"+ },+ "type": "array"+ },+ "description": "Screenshot media IDs per variant, keyed by variant key, shown under each variant in the experiment view. Each value is the complete list of uploaded media IDs for that variant. On update, only the variants you pass change and the screenshots of other variants stay. Pass an empty list to remove all screenshots of a variant.",+ "propertyNames": {+ "type": "string"+ },+ "type": "object"}},"required": ["id"],diff --git a/services/mcp/tests/unit/experiment-variant-details.test.ts b/services/mcp/tests/unit/experiment-variant-details.test.tsnew file mode 100644index 000000000000..62e641f9922b--- /dev/null+++ b/services/mcp/tests/unit/experiment-variant-details.test.ts@@ -0,0 +1,163 @@+import { describe, expect, it, vi } from 'vitest'++import { PostHogApiError } from '@/lib/errors'+import { GENERATED_TOOLS } from '@/tools/generated/experiments'+import type { Context, ToolBase, ZodObjectAny } from '@/tools/types'++const STORED_PARAMETERS = {+ // Reads project the flag config into `parameters`; writes must not send it back.+ feature_flag_variants: [{ key: 'control', rollout_percentage: 50 }],+ rollout_percentage: 100,+ prompt_metadata: { name: 'greeting', templates: [], versions: [1, 2] },+ variant_notes: { control: 'baseline', test: 'old copy' },+ variant_screenshot_media_ids: { control: ['media-1'] },+}++function contextWith(responses: Record<string, unknown>): { context: Context; request: ReturnType<typeof vi.fn> } {+ const request = vi.fn(async ({ method }: { method: string }) => responses[method])+ const context = {+ stateManager: { getProjectId: async () => '7' },+ api: { request, getProjectBaseUrl: () => 'https://app.example.com/project/7' },+ } as unknown as Context+ return { context, request }+}++async function run(toolName: string, context: Context, args: Record<string, unknown>): Promise<unknown> {+ const tool = (GENERATED_TOOLS[toolName] as () => ToolBase<ZodObjectAny>)()+ return tool.handler(context, tool.schema.parse(args))+}++function sentBody(request: ReturnType<typeof vi.fn>, method: string): Record<string, unknown> | undefined {+ return request.mock.calls.map(([options]) => options).find((options) => options.method === method)?.body+}++describe('experiment variant notes and screenshots', () => {+ it('experiment-create sends the variant inputs inside parameters', async () => {+ const { context, request } = contextWith({ POST: { id: 1 } })++ await run('experiment-create', context, {+ name: 'Checkout',+ feature_flag_key: 'checkout',+ variant_notes: { test: 'one-page checkout' },+ variant_screenshot_media_ids: { test: ['media-2'] },+ })++ const body = sentBody(request, 'POST')+ expect(body).not.toHaveProperty('variant_notes')+ expect(body?.parameters).toEqual({+ variant_notes: { test: 'one-page checkout' },+ variant_screenshot_media_ids: { test: ['media-2'] },+ })+ })++ it.each([4, null])('experiment-update preserves parameters and the read version %s', async (version) => {+ const { context, request } = contextWith({+ GET: { id: 1, version, parameters: STORED_PARAMETERS },+ PATCH: { id: 1 },+ })++ await run('experiment-update', context, { id: '1', name: 'Renamed', variant_notes: { test: 'new copy' } })++ expect(sentBody(request, 'PATCH')).toEqual({+ name: 'Renamed',+ version: version ?? 0,+ parameters: {+ prompt_metadata: STORED_PARAMETERS.prompt_metadata,+ variant_notes: { control: 'baseline', test: 'new copy' },+ variant_screenshot_media_ids: { control: ['media-1'] },+ },+ })+ })++ it('refuses an interleaved edit and preserves both changes on a fresh retry', async () => {+ let stored = { id: 1, version: 4, parameters: STORED_PARAMETERS }+ const { context, request } = contextWith({})+ request.mockImplementation(async ({ method, body }: { method: string; body?: Record<string, unknown> }) => {+ if (method === 'GET') {+ return { ...stored }+ }+ if (body?.version !== undefined && body.version !== stored.version) {+ throw new PostHogApiError({+ status: 409,+ statusText: 'Conflict',+ body: 'This experiment changed since you loaded it. Review the latest changes and try again.',+ url: 'https://app.example.com/api/projects/7/experiments/1/',+ method,+ })+ }+ stored = {+ ...stored,+ version: stored.version + 1,+ parameters: body?.parameters as typeof STORED_PARAMETERS,+ }+ return stored+ })++ const results = await Promise.allSettled([+ run('experiment-update', context, { id: 1, variant_notes: { control: 'first edit' } }),+ run('experiment-update', context, { id: 1, variant_notes: { test: 'second edit' } }),+ ])++ expect(results[0]?.status).toBe('fulfilled')+ expect(results[1]).toMatchObject({ status: 'rejected', reason: { status: 409 } })+ expect(stored.parameters.variant_notes).toEqual({ control: 'first edit', test: 'old copy' })++ await run('experiment-update', context, { id: 1, variant_notes: { test: 'second edit' } })++ expect(stored.parameters.variant_notes).toEqual({ control: 'first edit', test: 'second edit' })+ })++ it('experiment-update does not read or send parameters without variant inputs', async () => {+ const { context, request } = contextWith({ PATCH: { id: 1 } })++ await run('experiment-update', context, { id: 1, name: 'Renamed' })++ expect(request.mock.calls.map(([options]) => options.method)).toEqual(['PATCH'])+ expect(sentBody(request, 'PATCH')).toEqual({ name: 'Renamed' })+ })++ it('experiment-list reports which variants have notes or screenshots', async () => {+ const { context } = contextWith({+ GET: {+ count: 2,+ results: [+ {+ id: 1,+ name: 'Checkout',+ parameters: {+ ...STORED_PARAMETERS,+ variant_notes: { control: 'baseline', test: '' },+ variant_screenshot_media_ids: {+ control: ['media-1'],+ test: [],+ legacy: 'media-3',+ empty: '',+ blank: [''],+ },+ },+ },+ { id: 2, name: 'Pricing', parameters: null },+ ],+ },+ })++ const result = (await run('experiment-list', context, {})) as { results: Record<string, unknown>[] }++ expect(+ result.results.map(({ id, parameters, variants_with_notes, variants_with_screenshots }) => ({+ id,+ parameters,+ variants_with_notes,+ variants_with_screenshots,+ }))+ ).toEqual([+ {+ id: 1,+ parameters: undefined,+ variants_with_notes: ['control'],+ variants_with_screenshots: ['control', 'legacy'],+ },+ { id: 2, parameters: undefined, variants_with_notes: [], variants_with_screenshots: [] },+ ])+ })+})diff --git a/services/mcp/tests/unit/experiments-results-transform.test.ts b/services/mcp/tests/unit/experiments-results-transform.test.tsindex a95fc24a033d..decfe43c05c9 100644--- a/services/mcp/tests/unit/experiments-results-transform.test.ts+++ b/services/mcp/tests/unit/experiments-results-transform.test.ts@@ -90,6 +90,7 @@ describe('transformExperimentResults', () => {it('reads variants from the linked flag', () => {const experiment = makeExperiment({+ parameters: { variant_screenshot_media_ids: { control: 'legacy-media' } },feature_flag: {id: 9,key: 'k',diff --git a/services/mcp/tests/unit/generate-tools.test.ts b/services/mcp/tests/unit/generate-tools.test.tsindex d7e48440231c..f87bb4d6265d 100644--- a/services/mcp/tests/unit/generate-tools.test.ts+++ b/services/mcp/tests/unit/generate-tools.test.ts@@ -2762,6 +2762,32 @@ describe('hooks', () => {expect(code).toMatch(/handler: withToolHooks\(\s*hooks_thingList,\s*async \(context: Context/)})+ it('passes the built request body through transformRequestBody', () => {+ const resolved = makeResolved({+ method: 'POST',+ operation: {+ operationId: 'things_create',+ parameters: [],+ requestBody: {+ content: { 'application/json': { schema: { properties: { name: { type: 'string' } } } } },+ },+ },+ })+ const config: ToolConfig = { operation: 'things_create', enabled: true, hooks: 'tool-hooks' }++ const { code } = generateToolCode(+ 'things-create',+ config,+ resolved,+ defaultCategory,+ makeSpec(),+ new Set<string>(),+ stubGetQuerySchema+ )++ expect(code).toContain('body: await transformRequestBody(hooks_thingsCreate, context, params, body)')+ })+it('leaves tools without hooks unwrapped', () => {const { code } = generate({})