Skip to content

: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.

feat(mcp): add inbox reviewer update tool (#122388)

Dylan Martine426eda7dc96
diff --git a/products/signals/mcp/tools.yaml b/products/signals/mcp/tools.yaml
index d3b96c999ad5..5376ed6b212f 100644
--- a/products/signals/mcp/tools.yaml
+++ b/products/signals/mcp/tools.yaml
@@ -187,7 +187,9 @@ tools:
description: >
Replace the `content` of an existing artefact, addressed by its id, when new information supersedes it. The
new content is validated against the artefact type's schema. Editing the latest row of a status type changes
- the report's canonical status; to re-assess while keeping history, append a new artefact instead.
+ the report's canonical status; to re-assess while keeping history, append a new artefact instead. Do not use
+ this tool to change suggested reviewers. Use `inbox-report-reviewers-update` so reviewer corrections and
+ stale-write protection are preserved.
inbox-report-checks-create:
operation: signals_scout_report_check_create
enabled: true
@@ -256,6 +258,22 @@ tools:
description: >
Get one check on a report by its id, with its full config, schedule, status, and last outcome. The verdicts
themselves are `check_result` artefacts on the report, so read those through the artefact list.
+ inbox-report-reviewers-update:
+ operation: signals_reports_reviewers_update
+ enabled: true
+ scopes:
+ - task:write
+ annotations:
+ readOnly: false
+ destructive: false
+ idempotent: true
+ enrich_url: '{params.id}'
+ title: Update a report's suggested reviewers
+ description: >
+ Add or remove specific people from a report's suggested reviewers, replace the complete list, or confirm the
+ current list. For add or remove, pass the changed people in `targets` and the full list in `content` for
+ compatibility with older servers. For replace or confirm, first read the report and pass
+ `reviewer_assignment.state` as `expected_reviewers`.
inbox-reports-bulk-set-state:
operation: signals_reports_bulk_state_create
enabled: true
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index 581951450852..50a467137c62 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -7639,7 +7639,7 @@
}
},
"inbox-report-artefacts-update": {
- "description": "Replace the `content` of an existing artefact, addressed by its id, when new information supersedes it. The new content is validated against the artefact type's schema. Editing the latest row of a status type changes the report's canonical status; to re-assess while keeping history, append a new artefact instead.",
+ "description": "Replace the `content` of an existing artefact, addressed by its id, when new information supersedes it. The new content is validated against the artefact type's schema. Editing the latest row of a status type changes the report's canonical status; to re-assess while keeping history, append a new artefact instead. Do not use this tool to change suggested reviewers. Use `inbox-report-reviewers-update` so reviewer corrections and stale-write protection are preserved.",
"category": "Signals",
"feature": "signals",
"summary": "Replace an artefact's content",
@@ -7715,6 +7715,21 @@
"readOnlyHint": true
}
},
+ "inbox-report-reviewers-update": {
+ "description": "Add or remove specific people from a report's suggested reviewers, replace the complete list, or confirm the current list. For add or remove, pass the changed people in `targets` and the full list in `content` for compatibility with older servers. For replace or confirm, first read the report and pass `reviewer_assignment.state` as `expected_reviewers`.",
+ "category": "Signals",
+ "feature": "signals",
+ "summary": "Update a report's suggested reviewers",
+ "title": "Update a report's suggested reviewers",
+ "required_scopes": ["task:write"],
+ "api_operations": ["PUT /api/projects/{project_id}/signals/reports/{id}/reviewers/"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": false
+ }
+ },
"inbox-reports-bulk-set-state": {
"description": "Transition many signal reports to the same state in one call — the bulk form of `inbox-reports-set-state`, for clearing, snoozing, or resolving a batch of inbox reports without one request per report. Pass `ids` (1–100 report ids) and a `state` ('resolved' when the requested work is done, 'suppressed' to dismiss, 'potential' to snooze/restore); the optional `dismissal_reason` (same canonical codes as the single-report tool, including `wrong_assignee` and `wrong_repo`), `dismissal_note`, `corrected_repository` (only with `wrong_repo`), and `snooze_for` apply to every id. Dismissing or resolving closes each report's open implementation PR, if it has one. Each id is processed independently, so the whole call returns 200 even on partial failure: inspect `results` (one entry per id, in request order) and the `transitioned_count` / `skipped_count` / `failed_count` / `not_found_count` summary. An id whose transition isn't allowed from its current status comes back as `skipped` (the single-report 409) while the rest still go through.",
"category": "Signals",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 07a98a946538..c4dfd2dbe13a 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -7841,7 +7841,7 @@
}
},
"inbox-report-artefacts-update": {
- "description": "Replace the `content` of an existing artefact, addressed by its id, when new information supersedes it. The new content is validated against the artefact type's schema. Editing the latest row of a status type changes the report's canonical status; to re-assess while keeping history, append a new artefact instead.",
+ "description": "Replace the `content` of an existing artefact, addressed by its id, when new information supersedes it. The new content is validated against the artefact type's schema. Editing the latest row of a status type changes the report's canonical status; to re-assess while keeping history, append a new artefact instead. Do not use this tool to change suggested reviewers. Use `inbox-report-reviewers-update` so reviewer corrections and stale-write protection are preserved.",
"category": "Signals",
"feature": "signals",
"summary": "Replace an artefact's content",
@@ -7917,6 +7917,21 @@
"readOnlyHint": true
}
},
+ "inbox-report-reviewers-update": {
+ "description": "Add or remove specific people from a report's suggested reviewers, replace the complete list, or confirm the current list. For add or remove, pass the changed people in `targets` and the full list in `content` for compatibility with older servers. For replace or confirm, first read the report and pass `reviewer_assignment.state` as `expected_reviewers`.",
+ "category": "Signals",
+ "feature": "signals",
+ "summary": "Update a report's suggested reviewers",
+ "title": "Update a report's suggested reviewers",
+ "required_scopes": ["task:write"],
+ "api_operations": ["PUT /api/projects/{project_id}/signals/reports/{id}/reviewers/"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": false
+ }
+ },
"inbox-reports-bulk-set-state": {
"description": "Transition many signal reports to the same state in one call — the bulk form of `inbox-reports-set-state`, for clearing, snoozing, or resolving a batch of inbox reports without one request per report. Pass `ids` (1–100 report ids) and a `state` ('resolved' when the requested work is done, 'suppressed' to dismiss, 'potential' to snooze/restore); the optional `dismissal_reason` (same canonical codes as the single-report tool, including `wrong_assignee` and `wrong_repo`), `dismissal_note`, `corrected_repository` (only with `wrong_repo`), and `snooze_for` apply to every id. Dismissing or resolving closes each report's open implementation PR, if it has one. Each id is processed independently, so the whole call returns 200 even on partial failure: inspect `results` (one entry per id, in request order) and the `transitioned_count` / `skipped_count` / `failed_count` / `not_found_count` summary. An id whose transition isn't allowed from its current status comes back as `skipped` (the single-report 409) while the rest still go through.",
"category": "Signals",
diff --git a/services/mcp/src/generated/signals/api.ts b/services/mcp/src/generated/signals/api.ts
index 88b072a72d94..ce187adbec12 100644
--- a/services/mcp/src/generated/signals/api.ts
+++ b/services/mcp/src/generated/signals/api.ts
@@ -3,7 +3,7 @@
* MCP service uses these Zod schemas for generated tool handlers.
* To regenerate: hogli build:openapi
*
- * PostHog API - MCP 70 enabled ops
+ * PostHog API - MCP 71 enabled ops
* OpenAPI spec version: 1.0.0
*/
import * as zod from 'zod'
@@ -554,6 +554,132 @@ export const SignalsReportsMergeCreateBody = () => zod.object({
),
})
+/**
+ * Apply a human reviewer edit, including on reports without a reviewer artefact.
+ * @summary Set a report's suggested reviewers
+ */
+export const SignalsReportsReviewersUpdateParams = () => zod.object({
+ id: zod.string().describe('A UUID string identifying this signal report.'),
+ project_id: zod
+ .string()
+ .describe(
+ "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
+ ),
+})
+
+export const signalsReportsReviewersUpdateBodyActionDefault = `replace`
+export const signalsReportsReviewersUpdateBodyContentItemGithubLoginMax = 200
+
+export const signalsReportsReviewersUpdateBodyContentItemGithubNameMax = 200
+
+export const signalsReportsReviewersUpdateBodyContentItemReasonMax = 500
+
+export const signalsReportsReviewersUpdateBodyContentMax = 10
+
+export const signalsReportsReviewersUpdateBodyTargetsItemGithubLoginMax = 200
+
+export const signalsReportsReviewersUpdateBodyTargetsItemGithubNameMax = 200
+
+export const signalsReportsReviewersUpdateBodyTargetsItemReasonMax = 500
+
+export const signalsReportsReviewersUpdateBodyTargetsMax = 10
+
+export const SignalsReportsReviewersUpdateBody = () => zod.object({
+ action: zod
+ .enum(['add', 'remove', 'replace', 'confirm'])
+ .describe('\* `add` - Add\n\* `remove` - Remove\n\* `replace` - Replace\n\* `confirm` - Confirm')
+ .default(signalsReportsReviewersUpdateBodyActionDefault)
+ .describe(
+ 'Add or remove only the supplied people, replace the list, or explicitly confirm it.\n\n\* `add` - Add\n\* `remove` - Remove\n\* `replace` - Replace\n\* `confirm` - Confirm'
+ ),
+ expected_reviewers: zod
+ .object({
+ reviewers_id: zod
+ .string()
+ .nullable()
+ .describe('Current reviewer artefact ID, or null before the first list.'),
+ corrections_id: zod
+ .string()
+ .nullable()
+ .describe('Current corrections artefact ID, or null before corrections are stored.'),
+ })
+ .optional()
+ .describe('State from the last read. Required for replacement and confirmation when corrections are enabled.'),
+ content: zod
+ .array(
+ zod
+ .object({
+ github_login: zod
+ .string()
+ .max(signalsReportsReviewersUpdateBodyContentItemGithubLoginMax)
+ .optional()
+ .describe(
+ 'GitHub login (case-insensitive). Stored lowercased. Required unless `user_uuid` is given.'
+ ),
+ user_uuid: zod
+ .string()
+ .optional()
+ .describe(
+ "PostHog user UUID. Must be an org member on this team; a linked GitHub account is not required. Required unless `github_login` is given. If supplied together with `github_login`, the user's own identity wins."
+ ),
+ github_name: zod
+ .string()
+ .max(signalsReportsReviewersUpdateBodyContentItemGithubNameMax)
+ .optional()
+ .describe('Optional human-readable display name. Not backfilled from GitHub by the server.'),
+ reason: zod
+ .string()
+ .max(signalsReportsReviewersUpdateBodyContentItemReasonMax)
+ .nullish()
+ .describe(
+ 'Optional short evidence for why this reviewer was chosen. Omitted entries keep the prior reason for reviewers already on the report.'
+ ),
+ })
+ .describe(
+ 'Single entry in a PUT body for a `suggested_reviewers` artefact.\n\nEach entry must identify a reviewer by at least one of `github_login` or `user_uuid`. A\n`user_uuid` only has to name an org member on this team — a member with no linked GitHub\naccount is stored by uuid and routes like any other reviewer.'
+ )
+ )
+ .max(signalsReportsReviewersUpdateBodyContentMax)
+ .describe('People to add, remove, or keep in a replacement. Send an empty list for confirmation.'),
+ targets: zod
+ .array(
+ zod
+ .object({
+ github_login: zod
+ .string()
+ .max(signalsReportsReviewersUpdateBodyTargetsItemGithubLoginMax)
+ .optional()
+ .describe(
+ 'GitHub login (case-insensitive). Stored lowercased. Required unless `user_uuid` is given.'
+ ),
+ user_uuid: zod
+ .string()
+ .optional()
+ .describe(
+ "PostHog user UUID. Must be an org member on this team; a linked GitHub account is not required. Required unless `github_login` is given. If supplied together with `github_login`, the user's own identity wins."
+ ),
+ github_name: zod
+ .string()
+ .max(signalsReportsReviewersUpdateBodyTargetsItemGithubNameMax)
+ .optional()
+ .describe('Optional human-readable display name. Not backfilled from GitHub by the server.'),
+ reason: zod
+ .string()
+ .max(signalsReportsReviewersUpdateBodyTargetsItemReasonMax)
+ .nullish()
+ .describe(
+ 'Optional short evidence for why this reviewer was chosen. Omitted entries keep the prior reason for reviewers already on the report.'
+ ),
+ })
+ .describe(
+ 'Single entry in a PUT body for a `suggested_reviewers` artefact.\n\nEach entry must identify a reviewer by at least one of `github_login` or `user_uuid`. A\n`user_uuid` only has to name an org member on this team — a member with no linked GitHub\naccount is stored by uuid and routes like any other reviewer.'
+ )
+ )
+ .max(signalsReportsReviewersUpdateBodyTargetsMax)
+ .optional()
+ .describe('Explicit add or remove targets. When supplied, content is only a fallback for older servers.'),
+})
+
/**
* Take the calling user off this report's suggested reviewers, leaving the other reviewers as they are. The report itself is untouched: it stays open for whoever is left, and for the project. Succeeds whether or not the caller was on the list.
* @summary Step off a report's suggested reviewers
diff --git a/services/mcp/src/tools/generated/signals.ts b/services/mcp/src/tools/generated/signals.ts
index 76c164149ed5..7f31fd6b3a44 100644
--- a/services/mcp/src/tools/generated/signals.ts
+++ b/services/mcp/src/tools/generated/signals.ts
@@ -390,6 +390,44 @@ const inboxReportChecksRetrieve = (): ToolBase<
},
})
+const InboxReportReviewersUpdateSchema = () => {
+ const SignalsReportsReviewersUpdateBody = orvalSchemas.SignalsReportsReviewersUpdateBody()
+ const SignalsReportsReviewersUpdateParams = orvalSchemas.SignalsReportsReviewersUpdateParams()
+ return SignalsReportsReviewersUpdateParams.omit({ project_id: true }).extend(
+ SignalsReportsReviewersUpdateBody.shape
+ )
+}
+
+const inboxReportReviewersUpdate = (): ToolBase<
+ ReturnType<typeof InboxReportReviewersUpdateSchema>,
+ WithPostHogUrl<Schemas.SignalReportSuggestedReviewersArtefact>
+> => ({
+ name: 'inbox-report-reviewers-update',
+ schema: InboxReportReviewersUpdateSchema(),
+ handler: async (context: Context, params: z.infer<ReturnType<typeof InboxReportReviewersUpdateSchema>>) => {
+ const projectId = await context.stateManager.getProjectId()
+ const body: Record<string, unknown> = {}
+ if (params.action !== undefined) {
+ body['action'] = params.action
+ }
+ if (params.expected_reviewers !== undefined) {
+ body['expected_reviewers'] = params.expected_reviewers
+ }
+ if (params.content !== undefined) {
+ body['content'] = params.content
+ }
+ if (params.targets !== undefined) {
+ body['targets'] = params.targets
+ }
+ const result = await context.api.request<Schemas.SignalReportSuggestedReviewersArtefact>({
+ method: 'PUT',
+ path: `/api/projects/${encodeURIComponent(String(projectId))}/signals/reports/${encodeURIComponent(String(params.id))}/reviewers/`,
+ body,
+ })
+ return await withPostHogUrl(context, result, `/inbox/${params.id}`)
+ },
+})
+
const InboxReportsBulkSetStateSchema = () => {
const SignalsReportsBulkStateCreateBody = orvalSchemas.SignalsReportsBulkStateCreateBody()
return SignalsReportsBulkStateCreateBody
@@ -3295,6 +3333,7 @@ export const GENERATED_TOOLS: Record<string, () => ToolBase<ZodObjectAny>> = {
'inbox-report-checks-list': inboxReportChecksList,
'inbox-report-checks-replace': inboxReportChecksReplace,
'inbox-report-checks-retrieve': inboxReportChecksRetrieve,
+ 'inbox-report-reviewers-update': inboxReportReviewersUpdate,
'inbox-reports-bulk-set-state': inboxReportsBulkSetState,
'inbox-reports-claim': inboxReportsClaim,
'inbox-reports-feedback-create': inboxReportsFeedbackCreate,
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-report-reviewers-update.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-report-reviewers-update.json
new file mode 100644
index 000000000000..05a8fad42613
--- /dev/null
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-report-reviewers-update.json
@@ -0,0 +1,120 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "properties": {
+ "action": {
+ "default": "replace",
+ "description": "Add or remove only the supplied people, replace the list, or explicitly confirm it.\n\n* `add` - Add\n* `remove` - Remove\n* `replace` - Replace\n* `confirm` - Confirm",
+ "enum": ["add", "remove", "replace", "confirm"],
+ "type": "string"
+ },
+ "content": {
+ "description": "People to add, remove, or keep in a replacement. Send an empty list for confirmation.",
+ "items": {
+ "description": "Single entry in a PUT body for a `suggested_reviewers` artefact.\n\nEach entry must identify a reviewer by at least one of `github_login` or `user_uuid`. A\n`user_uuid` only has to name an org member on this team — a member with no linked GitHub\naccount is stored by uuid and routes like any other reviewer.",
+ "properties": {
+ "github_login": {
+ "description": "GitHub login (case-insensitive). Stored lowercased. Required unless `user_uuid` is given.",
+ "maxLength": 200,
+ "type": "string"
+ },
+ "github_name": {
+ "description": "Optional human-readable display name. Not backfilled from GitHub by the server.",
+ "maxLength": 200,
+ "type": "string"
+ },
+ "reason": {
+ "anyOf": [
+ {
+ "maxLength": 500,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Optional short evidence for why this reviewer was chosen. Omitted entries keep the prior reason for reviewers already on the report."
+ },
+ "user_uuid": {
+ "description": "PostHog user UUID. Must be an org member on this team; a linked GitHub account is not required. Required unless `github_login` is given. If supplied together with `github_login`, the user's own identity wins.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "maxItems": 10,
+ "type": "array"
+ },
+ "expected_reviewers": {
+ "description": "State from the last read. Required for replacement and confirmation when corrections are enabled.",
+ "properties": {
+ "corrections_id": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Current corrections artefact ID, or null before corrections are stored."
+ },
+ "reviewers_id": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Current reviewer artefact ID, or null before the first list."
+ }
+ },
+ "required": ["reviewers_id", "corrections_id"],
+ "type": "object"
+ },
+ "id": {
+ "description": "A UUID string identifying this signal report.",
+ "type": "string"
+ },
+ "targets": {
+ "description": "Explicit add or remove targets. When supplied, content is only a fallback for older servers.",
+ "items": {
+ "description": "Single entry in a PUT body for a `suggested_reviewers` artefact.\n\nEach entry must identify a reviewer by at least one of `github_login` or `user_uuid`. A\n`user_uuid` only has to name an org member on this team — a member with no linked GitHub\naccount is stored by uuid and routes like any other reviewer.",
+ "properties": {
+ "github_login": {
+ "description": "GitHub login (case-insensitive). Stored lowercased. Required unless `user_uuid` is given.",
+ "maxLength": 200,
+ "type": "string"
+ },
+ "github_name": {
+ "description": "Optional human-readable display name. Not backfilled from GitHub by the server.",
+ "maxLength": 200,
+ "type": "string"
+ },
+ "reason": {
+ "anyOf": [
+ {
+ "maxLength": 500,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Optional short evidence for why this reviewer was chosen. Omitted entries keep the prior reason for reviewers already on the report."
+ },
+ "user_uuid": {
+ "description": "PostHog user UUID. Must be an org member on this team; a linked GitHub account is not required. Required unless `github_login` is given. If supplied together with `github_login`, the user's own identity wins.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "maxItems": 10,
+ "type": "array"
+ }
+ },
+ "required": ["id", "content"],
+ "type": "object"
+}