Skip to content

feat(signals): expose the personal inbox ranking as an endpoint and mcp tool #126250

Closed

Description

@andrewm4894

Depends on #126249.

Problem

#126249 builds a personal ranked list of inbox reports, but only a management command can run it. People and their agents need to read their own list: in an MCP client first, then in product surfaces.

Proposed behavior

Endpoint

GET /api/projects/:project_id/signals/reports/for_me/, an @action(detail=False) on SignalReportViewSet.

  • Only the person the list is about can read it. Session, personal API key or OAuth token for that user. A project secret key, service auth or any non-user caller gets 404. Copy the rule in ActivitySummaryViewSet._own_user_id.
  • Scope: inbox:read, with the existing task:read fallback.
  • Gated by the personal-inbox-ranking flag for the requesting user; 404 when off.
  • Query parameters (validated, documented):
    • limit: default from config (25), max from config (50).
    • refresh: force a new build.
    • focus: optional free text passed to the builder. A focused request always builds and is not reused for unfocused calls.
  • Behavior: if the latest stored PersonalInboxRanking row for this user and team is newer than the freshness window (config, default 60 minutes) and its input_hash matches the current inputs, return it. Otherwise call build_personal_ranking synchronously and return the new row. A build can take tens of seconds; that is accepted for this stage.
  • Per-user throttle on builds, separate from reads (config, for example one forced rebuild per 5 minutes and a daily cap). A throttled caller gets the latest stored list with cached=true, or 429 when there is none.

Response

Typed serializer with help_text on every field (it feeds generated types and the MCP schema):

  • status (ready, unavailable), personalized, cached, fallback_reason, generated_at, build_ms, activity_summary_version, candidates_considered.
  • results: the top limit entries, each with rank, tier, reason, next_step, matched, ranked_by, and a compact report: id, title, priority, status, _posthogUrl, ranking, PR state.
  • ranked_count: how many candidates the stored list ranks in total (the full list stays in storage).
  • folded: report ids folded into a result, with the reason.

Compact rows on purpose: full list rows are several KB each, too heavy for an MCP response. Detail stays with the existing report retrieve endpoint.

MCP tool

Add inbox-reports-for-me to products/signals/mcp/tools.yaml with feature_flag: personal-inbox-ranking. Description: what the list is, that it is personal to the caller, that a build can be slow, what personalized: false means, and that refresh and focus cost a new build. Regenerate with hogli build:openapi.

Acceptance criteria

  • A user gets their own list; another user's credentials can never return it; a project secret key gets 404.
  • Flag off returns 404 and the MCP tool is hidden.
  • A fresh stored list with a matching input hash is returned without an LLM call; a changed input or refresh builds a new one.
  • The build throttle holds and returns the stored list when one exists.
  • focus builds are not reused for unfocused calls.
  • OpenAPI and generated types are regenerated; the MCP tool schema has descriptions for every parameter.
  • API tests with the builder mocked; no real LLM calls.

Scope

Endpoint, serializer, throttle and MCP tool only. No scheduled builds, no sort=personal, no frontend changes.

Activity

  1. posthog commented on Oct 30, 2026

    @posthog
    Contributor

    PostHog self-driving picked up this issue and researched it. Somebody may already be working on it, so ask before you start a fix.

    Report (team access only): https://us.posthog.com/project/2/inbox/reports/01a18cbe-079b-7b11-a4a5-2c4fcf8b9a4e?link_source=github_comment

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions