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.

42.0 KB
Raw Blame
import json
from datetime import datetime
from typing import TYPE_CHECKING, Any

from django.core.exceptions import ValidationError as DjangoValidationError
from django.db import IntegrityError, transaction

import pydantic
from rest_framework import serializers

from posthog.schema import (
    AnyPropertyFilterDiscriminated,
    EventPropertyFilter,
    PersonPropertyFilter,
    SessionPropertyFilter,
)

from products.mcp_analytics.backend.facade.constants import (
    HARNESS_LABELS,
    MARKED_CLIENT_NAMES,
    MAX_CUSTOM_HARNESSES,
    UNIDENTIFIED_HARNESS_LABEL,
)
from products.mcp_analytics.backend.models import MCPAnalyticsSubmission, MCPCustomHarness

if TYPE_CHECKING:
    from django.db.models import QuerySet

_PROPERTY_FILTERS_ADAPTER: pydantic.TypeAdapter[list[AnyPropertyFilterDiscriminated]] = pydantic.TypeAdapter(
    list[AnyPropertyFilterDiscriminated]
)
_ALLOWED_PROPERTY_FILTERS = (EventPropertyFilter, PersonPropertyFilter, SessionPropertyFilter)

PROPERTIES_HELP_TEXT = (
    "Property filters that narrow the underlying $mcp_tool_call events, JSON-encoded. A list of "
    "event, person, or session property filters, each with key, value, operator, and type. Example: "
    '[{"key": "$mcp_tool_name", "value": ["query_run"], "operator": "exact", '
    '"type": "event"}]'
)

FILTER_TEST_ACCOUNTS_HELP_TEXT = (
    "Whether to also apply the project's internal and test user filters (its test_account_filters "
    "setting) on top of `properties`."
)


class PropertyFiltersField(serializers.CharField):
    """A JSON-encoded list of property filters in a query string, validated into schema types.

    Follows the `properties` query-param convention of the person and cohort actor endpoints.
    Subclasses CharField so drf-spectacular keeps advertising the plain string a query string can
    carry, while the view receives the parsed filters.
    """

    def run_validation(self, data: Any = serializers.empty) -> list[AnyPropertyFilterDiscriminated]:
        raw = super().run_validation(data)
        if not raw:
            return []
        try:
            filters = _PROPERTY_FILTERS_ADAPTER.validate_python(json.loads(raw))
        except (json.JSONDecodeError, ValueError, pydantic.ValidationError) as error:
            raise serializers.ValidationError(f"Properties are unparsable: {error}")
        if any(not isinstance(property_filter, _ALLOWED_PROPERTY_FILTERS) for property_filter in filters):
            raise serializers.ValidationError("Only event, person, and session property filters are supported.")
        return filters


MAX_GOAL_LENGTH = 500
MAX_SUMMARY_LENGTH = 5_000

# Single source of truth for session-list pagination bounds. Referenced by the query serializer
# (which enforces + advertises them in the OpenAPI spec, so the MCP Zod schema inherits the same
# limits) and by MCPSessionPagination for its response envelope.
MCP_SESSION_LIST_DEFAULT_LIMIT = 100
MCP_SESSION_LIST_MAX_LIMIT = 500

# Same, for a single session's tool-call list. Default == max: this endpoint returns a
# session's whole call list by default (sessions rarely exceed the cap), so callers that
# omit limit get everything; the max doubles as the safety cap on the ClickHouse scan
# (previously a hardcoded LIMIT in the query).
MCP_TOOL_CALLS_DEFAULT_LIMIT = 500
MCP_TOOL_CALLS_MAX_LIMIT = 500


class MCPAnalyticsSubmissionSerializer(serializers.Serializer):
    id = serializers.UUIDField(read_only=True, help_text="Unique identifier for this submission.")
    kind = serializers.ChoiceField(
        choices=MCPAnalyticsSubmission.Kind.choices,
        read_only=True,
        help_text="Whether this submission is general feedback or a missing capability report.",
    )
    goal = serializers.CharField(help_text="The user's goal in plain language.")
    summary = serializers.CharField(help_text="The core feedback or missing capability request.")
    category = serializers.CharField(
        read_only=True,
        help_text="Feedback category when present. Empty for submissions that do not use categories.",
    )
    blocked = serializers.BooleanField(
        allow_null=True,
        read_only=True,
        help_text="Whether the missing capability blocked progress. Null when not provided.",
    )
    attempted_tool = serializers.CharField(
        read_only=True,
        help_text="The tool the user tried before submitting this feedback, if known.",
    )
    mcp_client_name = serializers.CharField(
        read_only=True,
        help_text="MCP client name captured alongside the submission when available.",
    )
    mcp_client_version = serializers.CharField(
        read_only=True,
        help_text="MCP client version captured alongside the submission when available.",
    )
    mcp_protocol_version = serializers.CharField(
        read_only=True,
        help_text="MCP protocol version captured alongside the submission when available.",
    )
    mcp_transport = serializers.CharField(
        read_only=True,
        help_text="MCP transport captured alongside the submission when available.",
    )
    mcp_session_id = serializers.CharField(
        read_only=True,
        help_text="MCP session identifier captured alongside the submission when available.",
    )
    mcp_trace_id = serializers.CharField(
        read_only=True,
        help_text="MCP trace identifier captured alongside the submission when available.",
    )
    created_at = serializers.DateTimeField(read_only=True, help_text="When this submission was created.")
    updated_at = serializers.DateTimeField(read_only=True, help_text="When this submission was last updated.")


class MCPAnalyticsSubmissionContextSerializer(serializers.Serializer):
    attempted_tool = serializers.CharField(
        required=False,
        allow_blank=True,
        default="",
        max_length=200,
        help_text="The tool the user tried before leaving feedback, if known.",
    )
    mcp_client_name = serializers.CharField(
        required=False,
        allow_blank=True,
        default="",
        max_length=200,
        help_text="MCP client name, for example Claude Desktop or Cursor.",
    )
    mcp_client_version = serializers.CharField(
        required=False,
        allow_blank=True,
        default="",
        max_length=100,
        help_text="Version string for the MCP client when available.",
    )
    mcp_protocol_version = serializers.CharField(
        required=False,
        allow_blank=True,
        default="",
        max_length=50,
        help_text="MCP protocol version negotiated for the session when available.",
    )
    mcp_transport = serializers.CharField(
        required=False,
        allow_blank=True,
        default="",
        max_length=50,
        help_text="Transport used for the MCP session, for example streamable_http or sse.",
    )
    mcp_session_id = serializers.CharField(
        required=False,
        allow_blank=True,
        default="",
        max_length=200,
        help_text="Stable MCP session identifier when available.",
    )
    mcp_trace_id = serializers.CharField(
        required=False,
        allow_blank=True,
        default="",
        max_length=200,
        help_text="Trace identifier for the surrounding MCP workflow when available.",
    )


class MCPFeedbackCreateSerializer(MCPAnalyticsSubmissionContextSerializer):
    goal = serializers.CharField(max_length=MAX_GOAL_LENGTH, help_text="The user's intended outcome when using MCP.")
    feedback = serializers.CharField(
        max_length=MAX_SUMMARY_LENGTH,
        help_text="Concrete feedback about the MCP experience, tool result, or workflow friction.",
    )
    category = serializers.ChoiceField(
        choices=MCPAnalyticsSubmission.FeedbackCategory.choices,
        required=False,
        default=MCPAnalyticsSubmission.FeedbackCategory.OTHER,
        help_text="High-level category for the feedback.",
    )


class MCPToolCallSerializer(serializers.Serializer):
    event_id = serializers.CharField(read_only=True, help_text="ClickHouse uuid of the $mcp_tool_call event.")
    timestamp = serializers.DateTimeField(read_only=True, help_text="When the tool call was captured.")
    tool_name = serializers.CharField(read_only=True, help_text="Tool that was invoked ($mcp_tool_name).")
    intent = serializers.CharField(
        read_only=True,
        help_text="Agent intent for this tool call ($mcp_intent). Empty when the SDK did not capture context.",
    )
    is_error = serializers.BooleanField(read_only=True, help_text="Whether the tool call resulted in an error.")
    error_message = serializers.CharField(
        read_only=True, help_text="Error message when is_error is true, otherwise empty."
    )
    duration_ms = serializers.IntegerField(
        read_only=True, allow_null=True, help_text="Duration of the tool call in milliseconds when captured."
    )


class MCPSessionListQuerySerializer(serializers.Serializer):
    search = serializers.CharField(
        required=False,
        allow_blank=True,
        default="",
        help_text="Case-insensitive substring filter matched against session_id, distinct_id, mcp_client_name, and tools_used.",
    )
    order_by = serializers.CharField(
        required=False,
        allow_blank=True,
        default="",
        help_text=(
            "Sort column. Allowed: session_id, session_start, session_end, duration_seconds, "
            "tool_call_count, mcp_client_name, distinct_id. Prefix with '-' for descending. "
            "Defaults to '-session_start' (newest sessions first)."
        ),
    )
    date_from = serializers.CharField(
        required=False,
        allow_blank=True,
        help_text=(
            "Start of the window to aggregate sessions over. PostHog date string — relative "
            "(e.g. '-7d', '-24h') or an absolute ISO timestamp. Defaults to '-7d'."
        ),
    )
    date_to = serializers.CharField(
        required=False,
        allow_blank=True,
        help_text="End of the window. PostHog date string or absolute ISO timestamp. Defaults to now.",
    )
    has_errors = serializers.BooleanField(
        required=False,
        allow_null=True,
        default=None,
        help_text=(
            "Filter by session outcome. true keeps sessions with at least one errored tool call "
            "($mcp_is_error), false keeps sessions with none. Omit to list both."
        ),
    )
    properties = PropertyFiltersField(
        required=False,
        allow_blank=True,
        default="",
        help_text=PROPERTIES_HELP_TEXT,
    )
    filter_test_accounts = serializers.BooleanField(
        required=False,
        default=False,
        help_text=FILTER_TEST_ACCOUNTS_HELP_TEXT,
    )
    limit = serializers.IntegerField(
        required=False,
        default=MCP_SESSION_LIST_DEFAULT_LIMIT,
        min_value=1,
        max_value=MCP_SESSION_LIST_MAX_LIMIT,
        help_text=(
            f"Maximum number of sessions to return per page. Defaults to {MCP_SESSION_LIST_DEFAULT_LIMIT}; "
            f"values above {MCP_SESSION_LIST_MAX_LIMIT} are rejected."
        ),
    )
    offset = serializers.IntegerField(
        required=False,
        default=0,
        min_value=0,
        help_text=(
            "Number of sessions to skip before returning results. Combine with limit to page through "
            "sessions; the response's has_next flag indicates whether more remain."
        ),
    )


class LenientDateTimeField(serializers.DateTimeField):
    """A DateTimeField that treats an unparseable value as absent (None) rather than raising.

    ``date_from`` on the tool-calls endpoint is only a scan-pruning hint, never a filter — a
    bad value should fall back to the default lookback instead of 400-ing the request. Keeps
    the ``date-time`` OpenAPI type (drf-spectacular reads the DateTimeField base class).
    """

    def run_validation(self, *args: Any, **kwargs: Any) -> datetime | None:
        try:
            return super().run_validation(*args, **kwargs)
        except serializers.ValidationError:
            return None


class MCPSessionToolCallsQuerySerializer(serializers.Serializer):
    date_from = LenientDateTimeField(
        required=False,
        help_text=(
            "Absolute ISO timestamp lower bound for the event scan — pass the session's start so "
            "older sessions resolve. Defaults to a 7-day lookback when omitted or unparseable."
        ),
    )
    properties = PropertyFiltersField(
        required=False,
        allow_blank=True,
        default="",
        help_text=PROPERTIES_HELP_TEXT,
    )
    filter_test_accounts = serializers.BooleanField(
        required=False,
        default=False,
        help_text=FILTER_TEST_ACCOUNTS_HELP_TEXT,
    )
    limit = serializers.IntegerField(
        required=False,
        default=MCP_TOOL_CALLS_DEFAULT_LIMIT,
        min_value=1,
        max_value=MCP_TOOL_CALLS_MAX_LIMIT,
        help_text=(
            f"Maximum tool calls to return per page (1–{MCP_TOOL_CALLS_MAX_LIMIT}). Defaults to "
            f"{MCP_TOOL_CALLS_DEFAULT_LIMIT} — the whole page — so a session's calls come back in one "
            f"request; pass a smaller value for a lighter response. Values above the cap are rejected."
        ),
    )
    offset = serializers.IntegerField(
        required=False,
        default=0,
        min_value=0,
        help_text=(
            "Number of tool calls to skip before returning results. Combine with limit to page through "
            "a session's calls; the response's has_next flag indicates whether more remain."
        ),
    )


class MCPSessionSerializer(serializers.Serializer):
    session_id = serializers.CharField(
        read_only=True, help_text="$mcp_session_id grouping all $mcp_tool_call events in the session."
    )
    tool_calls = serializers.IntegerField(
        read_only=True, help_text="Total number of $mcp_tool_call events in the session."
    )
    error_calls = serializers.IntegerField(
        read_only=True,
        help_text=(
            "Number of the session's $mcp_tool_call events with $mcp_is_error true, "
            "counted over the same properties / filter_test_accounts matches as tool_calls."
        ),
    )
    session_start = serializers.DateTimeField(
        read_only=True, help_text="Timestamp of the first $mcp_tool_call event in the session."
    )
    session_end = serializers.DateTimeField(
        read_only=True, help_text="Timestamp of the most recent $mcp_tool_call event in the session."
    )
    distinct_id_count = serializers.IntegerField(
        read_only=True, help_text="Number of distinct PostHog distinct_ids that produced events in the session."
    )
    tools_used = serializers.ListField(
        child=serializers.CharField(),
        read_only=True,
        help_text="Distinct $mcp_tool_name values seen in the session.",
    )
    mcp_client_name = serializers.CharField(
        read_only=True, help_text="Most recent $mcp_client_name observed in the session."
    )
    distinct_id = serializers.CharField(
        read_only=True,
        help_text="Most recent distinct_id observed for the session. Stable identifier the SDK tagged the events with.",
    )
    person_email = serializers.CharField(
        read_only=True,
        help_text="email property of the Person resolved from distinct_id; empty when no Person is mapped.",
    )
    person_name = serializers.CharField(
        read_only=True,
        help_text="name property of the Person resolved from distinct_id; empty when no Person is mapped.",
    )
    intent = serializers.CharField(
        read_only=True,
        help_text="LLM-generated summary (at most two sentences) of the agent's overall goal for the session. Empty until generated on demand via the generate_intent endpoint.",
    )


class MCPSessionIntentSerializer(serializers.Serializer):
    session_id = serializers.CharField(
        read_only=True, help_text="$mcp_session_id the intent summary was generated for."
    )
    intent = serializers.CharField(
        read_only=True,
        help_text="LLM-generated summary (at most two sentences) of the agent's overall goal for the session.",
    )


class MCPIntentThemeSerializer(serializers.Serializer):
    name = serializers.CharField(read_only=True, help_text="Short sentence-case name for this group of intents.")
    description = serializers.CharField(
        read_only=True, help_text="One concrete sentence describing what agents in this theme are doing."
    )
    intent_count = serializers.IntegerField(
        read_only=True,
        help_text=(
            "How many of the analysed intents the LLM assigned to this theme, counted from the corpus rather "
            "than reported by the LLM. Each intent belongs to at most one theme, so these never sum to more "
            "than the digest's intent_count."
        ),
    )
    example_intent = serializers.CharField(
        read_only=True,
        help_text="One of this theme's intents, verbatim from the corpus.",
    )
    tools = serializers.ListField(
        child=serializers.CharField(),
        read_only=True,
        help_text="The MCP tool names recorded alongside this theme's intents, sorted, taken from the corpus.",
    )


class MCPIntentDigestSerializer(serializers.Serializer):
    digest = serializers.CharField(
        read_only=True,
        allow_null=True,
        help_text=(
            "LLM-generated one-sentence summary of what agents are trying to do with this MCP server, "
            "derived from the most recent recorded $mcp_intents across all sessions. Null when the "
            "project has no recorded intents yet."
        ),
    )
    intent_count = serializers.IntegerField(
        read_only=True,
        help_text="How many recorded intents (the most recent, capped at 100) the digest was derived from.",
    )
    themes = MCPIntentThemeSerializer(
        many=True,
        read_only=True,
        help_text=(
            "Up to 5 semantic groupings of the analysed intents, largest first. May be empty when the digest "
            "is null, or when none of the LLM's groupings resolved to recorded intents."
        ),
    )


class MCPActivityStatsSerializer(serializers.Serializer):
    total_calls = serializers.IntegerField(
        read_only=True, help_text="$mcp_tool_call events captured in the last 30 days."
    )
    distinct_tools = serializers.IntegerField(
        read_only=True, help_text="Distinct tools ($mcp_tool_name) called in the window."
    )
    distinct_sessions = serializers.IntegerField(
        read_only=True, help_text="Distinct $session_ids seen on tool calls in the window."
    )
    distinct_clients = serializers.IntegerField(
        read_only=True, help_text="Distinct agent clients ($mcp_client_name) seen in the window."
    )
    calls_with_intent = serializers.IntegerField(
        read_only=True, help_text="Tool calls that carried an $mcp_intent, for intent-coverage checks."
    )
    error_calls = serializers.IntegerField(
        read_only=True, help_text="Tool calls flagged as errors ($mcp_is_error) in the window."
    )
    missing_capability_reports = serializers.IntegerField(
        read_only=True, help_text="$mcp_missing_capability events captured in the window."
    )


class MCPActivityToolRowSerializer(serializers.Serializer):
    tool = serializers.CharField(read_only=True, help_text="MCP tool name ($mcp_tool_name).")
    calls = serializers.IntegerField(read_only=True, help_text="Tool calls in the window.")
    # The name shadows Serializer.errors, which is fine for a read-only output field.
    errors = serializers.IntegerField(  # type: ignore[assignment]
        read_only=True, help_text="Of those calls, how many errored."
    )


class MCPActivityClientRowSerializer(serializers.Serializer):
    client = serializers.CharField(
        read_only=True,
        allow_blank=True,
        help_text="Agent client name ($mcp_client_name). Empty when the SDK did not capture it.",
    )
    calls = serializers.IntegerField(read_only=True, help_text="Tool calls from this client in the window.")


class MCPActivityRecentCallSerializer(serializers.Serializer):
    timestamp = serializers.DateTimeField(read_only=True, help_text="When the tool call was captured.")
    tool = serializers.CharField(read_only=True, help_text="Tool that was invoked ($mcp_tool_name).")
    intent = serializers.CharField(
        read_only=True,
        allow_null=True,
        help_text="Agent intent for this tool call ($mcp_intent). Null when the SDK did not capture context.",
    )
    is_error = serializers.BooleanField(read_only=True, help_text="Whether the tool call resulted in an error.")
    error_message = serializers.CharField(
        read_only=True,
        allow_null=True,
        help_text="Human-readable error extracted from the tool's response when is_error is true, otherwise null.",
    )
    duration_ms = serializers.FloatField(
        read_only=True, allow_null=True, help_text="Duration of the tool call in milliseconds when captured."
    )
    client_name = serializers.CharField(
        read_only=True, allow_null=True, help_text="Agent client name ($mcp_client_name) when captured."
    )


class MCPActivityOverviewQuerySerializer(serializers.Serializer):
    properties = PropertyFiltersField(
        required=False,
        allow_blank=True,
        default="",
        help_text=PROPERTIES_HELP_TEXT,
    )
    filter_test_accounts = serializers.BooleanField(
        required=False,
        default=False,
        help_text=FILTER_TEST_ACCOUNTS_HELP_TEXT,
    )
    refresh = serializers.BooleanField(
        required=False,
        default=False,
        help_text="Compute the overview again instead of serving the cached result, at most once every 5 seconds. The fresh result replaces the cached one.",
    )


class MCPActivityOverviewSerializer(serializers.Serializer):
    stats = MCPActivityStatsSerializer(read_only=True, help_text="Aggregate counters over the last 30 days.")
    top_tools = MCPActivityToolRowSerializer(
        many=True, read_only=True, help_text="Most-called tools in the window, top 5 by call count."
    )
    clients = MCPActivityClientRowSerializer(
        many=True, read_only=True, help_text="Agent clients in the window, top 6 by call count."
    )
    recent_calls = MCPActivityRecentCallSerializer(
        many=True, read_only=True, help_text="The 20 most recent tool calls, newest first."
    )


class MCPIntentClusterToolEntrySerializer(serializers.Serializer):
    tool = serializers.CharField(read_only=True, help_text="MCP tool name that received calls for this cluster.")
    count = serializers.IntegerField(
        read_only=True, help_text="Number of tool calls routed to this tool across the cluster."
    )
    pct = serializers.FloatField(
        read_only=True, help_text="Percentage of the cluster's calls that went to this tool, 0–100."
    )
    errors = serializers.IntegerField(  # type: ignore[assignment]
        read_only=True, help_text="Number of error responses observed for this tool within the cluster."
    )
    error_rate_pct = serializers.FloatField(
        read_only=True, help_text="Error rate for this tool within the cluster, 0–100."
    )


class MCPIntentClusterJourneyPathSerializer(serializers.Serializer):
    steps = serializers.ListField(
        child=serializers.CharField(allow_null=True),
        read_only=True,
        help_text=(
            "Ordered tool names called during the path. Length is fixed; null entries "
            "indicate the session ended before this step."
        ),
    )
    outcome = serializers.ChoiceField(
        choices=[("completed", "Completed"), ("error", "Error")],
        read_only=True,
        help_text="Terminal outcome of the sessions following this path.",
    )
    count = serializers.IntegerField(
        read_only=True, help_text="Number of sessions in this cluster that followed this exact path."
    )


class MCPIntentClusterJourneySerializer(serializers.Serializer):
    paths = MCPIntentClusterJourneyPathSerializer(
        many=True,
        read_only=True,
        help_text="Top paths by session count, capped at MAX_JOURNEY_PATHS_PER_CLUSTER.",
    )
    total_sessions = serializers.IntegerField(
        read_only=True, help_text="Total session count represented across all paths in this cluster."
    )
    leak = MCPIntentClusterJourneyPathSerializer(
        read_only=True,
        allow_null=True,
        help_text="Highest-volume non-completed path. Null when every path completed successfully.",
    )


class MCPClusterSwitchSerializer(serializers.Serializer):
    from_tool = serializers.CharField(read_only=True, help_text="Tool whose errored call the agent abandoned.")
    to_tool = serializers.CharField(read_only=True, help_text="Different tool the agent tried immediately after.")
    count = serializers.IntegerField(
        read_only=True, help_text="How many times this exact error-then-switch happened within the cluster."
    )


class MCPClusterSelfRetrySerializer(serializers.Serializer):
    tool = serializers.CharField(read_only=True, help_text="Tool the agent retried immediately after its own error.")
    count = serializers.IntegerField(read_only=True, help_text="Number of immediate same-tool retries after an error.")


class MCPToolPivotCompetitorSerializer(serializers.Serializer):
    tool = serializers.CharField(
        read_only=True, help_text="The other tool with the largest share of this cluster's calls."
    )
    pct = serializers.FloatField(read_only=True, help_text="That competitor's share of the cluster's calls, 0-100.")


class MCPToolPivotClusterEntrySerializer(serializers.Serializer):
    cluster_id = serializers.IntegerField(
        read_only=True,
        help_text="Cluster this entry refers to, within the snapshot. The cluster's own label, totals, and entropy live on that cluster — join on this id rather than expecting them here.",
    )
    calls = serializers.IntegerField(read_only=True, help_text="Calls routed to this tool for this intent cluster.")
    capture_pct = serializers.FloatField(
        read_only=True,
        help_text="Share of the cluster's calls this tool captured, 0-100. Low capture on a well-fitting description suggests agents are not finding the tool for this intent.",
    )
    rank = serializers.IntegerField(
        read_only=True,
        help_text="This tool's position in the cluster's tool distribution; 1 is the cluster's top tool.",
    )
    description_fit = serializers.FloatField(
        read_only=True,
        allow_null=True,
        help_text="Cosine similarity between the tool's description embedding and the cluster centroid, -1 to 1. Null when no description has been captured for the tool.",
    )
    top_competitor = MCPToolPivotCompetitorSerializer(
        read_only=True,
        allow_null=True,
        help_text="The strongest other tool in this cluster. Null when this tool is the only one.",
    )


class MCPToolPivotSerializer(serializers.Serializer):
    tool = serializers.CharField(read_only=True, help_text="Effective MCP tool name.")
    call_count = serializers.IntegerField(
        read_only=True,
        help_text="Intent-attributed calls to this tool across the sampled corpus, counting every cluster the run produced — including clusters the snapshot's cluster cap left out.",
    )
    error_count = serializers.IntegerField(read_only=True, help_text="Errored attributed calls across the corpus.")
    session_count = serializers.IntegerField(
        read_only=True,
        help_text="Sampled sessions with at least one intent-attributed call to this tool. Same population as call_count.",
    )
    contested_score = serializers.FloatField(
        read_only=True,
        allow_null=True,
        help_text="Call-weighted mean routing entropy of the clusters this tool serves, 0-1. High means the tool's intents are regularly split with other tools. Null when the tool has no attributed calls.",
    )
    advertised_sessions = serializers.IntegerField(
        read_only=True,
        help_text="Sampled sessions whose tools-list catalog included this tool. Only sessions with an observed $mcp_tools_list event count.",
    )
    called_when_advertised = serializers.IntegerField(
        read_only=True, help_text="Of the advertised sessions, how many actually called the tool."
    )
    discovery_rate_pct = serializers.FloatField(
        read_only=True,
        allow_null=True,
        help_text="called_when_advertised / advertised_sessions as a percentage. Null when the tool was advertised in fewer than 5 sampled sessions, which is not enough signal to compute a rate.",
    )
    description = serializers.CharField(
        read_only=True,
        allow_null=True,
        help_text="Latest description observed for the tool (clipped to 512 characters). Null when calls never carried one.",
    )
    n_clusters_served = serializers.IntegerField(
        read_only=True,
        help_text="How many intent clusters this tool serves in total, before the per-tool entry cap. Compare against len(clusters) to tell whether the entry list below is complete.",
    )
    clusters = MCPToolPivotClusterEntrySerializer(
        many=True,
        read_only=True,
        help_text="Intent clusters this tool serves, by call volume desc, capped at 20 and limited to clusters the snapshot carries. Use n_clusters_served for the true count.",
    )


class MCPToolOverlapSerializer(serializers.Serializer):
    tool_a = serializers.CharField(read_only=True, help_text="First tool of the pair (lexicographic order).")
    tool_b = serializers.CharField(read_only=True, help_text="Second tool of the pair.")
    contested_calls = serializers.IntegerField(
        read_only=True,
        help_text="Sum over shared clusters of the smaller tool's calls: the volume both tools plausibly compete for.",
    )
    sessions_with_both = serializers.IntegerField(
        read_only=True,
        help_text="Sampled sessions that called both tools. High relative to sessions_with_either suggests the pair is a workflow, not confusion.",
    )
    sessions_with_either = serializers.IntegerField(
        read_only=True, help_text="Sampled sessions that called at least one of the pair."
    )
    top_cluster_id = serializers.IntegerField(
        read_only=True, help_text="The cluster contributing the most contested calls for this pair."
    )


class MCPIntentClusterSerializer(serializers.Serializer):
    id = serializers.IntegerField(read_only=True, help_text="Stable cluster identifier within this snapshot.")
    label = serializers.CharField(  # type: ignore[assignment]
        read_only=True,
        help_text="Representative intent text for the cluster (the medoid intent closest to the cluster centroid).",
    )
    intent_count = serializers.IntegerField(
        read_only=True, help_text="Number of distinct intent texts that belong to this cluster."
    )
    session_count = serializers.IntegerField(
        read_only=True, help_text="Number of MCP sessions whose summarised intent belongs to this cluster."
    )
    call_count = serializers.IntegerField(
        read_only=True, help_text="Total number of $mcp_tool_call events represented by this cluster."
    )
    error_count = serializers.IntegerField(
        read_only=True, help_text="Total number of error responses observed across the cluster."
    )
    error_rate_pct = serializers.FloatField(
        read_only=True, help_text="Aggregate error rate across all tool calls in the cluster, 0–100."
    )
    routing_entropy = serializers.FloatField(
        read_only=True,
        help_text=(
            "Normalised Shannon entropy of the tool distribution. 0 means perfectly consistent routing "
            "(one tool dominates); 1 means uniformly spread across all tools called for this intent cluster."
        ),
    )
    tool_distribution = MCPIntentClusterToolEntrySerializer(
        many=True, read_only=True, help_text="Per-tool breakdown of calls and errors within the cluster."
    )
    sample_intents = serializers.ListField(
        child=serializers.CharField(),
        read_only=True,
        help_text="Up to three representative intent strings from the cluster, ordered by frequency desc.",
    )
    journey = MCPIntentClusterJourneySerializer(
        read_only=True,
        allow_null=True,
        help_text=(
            "Top Sankey-shaped paths the agents took within this cluster. Each path is up to "
            "four ordered tool calls plus a completed/error outcome. Null when journey data is unavailable."
        ),
    )
    switches = MCPClusterSwitchSerializer(
        many=True,
        read_only=True,
        help_text="Errored call immediately followed by a different tool for the same intent: the strongest evidence agents mix the tools up. Top 10 by count.",
    )
    self_retries = MCPClusterSelfRetrySerializer(
        many=True,
        read_only=True,
        help_text="Errored call immediately retried with the same tool. Top 5 by count.",
    )


class MCPIntentClusterSnapshotMetaSerializer(serializers.Serializer):
    distance_threshold = serializers.FloatField(
        read_only=True, help_text="Cosine distance threshold used by the clustering algorithm."
    )
    embedding_model = serializers.CharField(read_only=True, help_text="Embedding model used to vectorise intents.")
    n_intents = serializers.IntegerField(
        read_only=True, help_text="Number of distinct intents that fed into the clustering run."
    )
    n_clusters = serializers.IntegerField(read_only=True, help_text="Number of clusters produced by the run.")
    corpus = serializers.CharField(
        read_only=True,
        allow_null=True,
        help_text="Corpus granularity. 'per_call' when each call was attributed to its own intent; null on snapshots computed before the per-call pipeline.",
    )
    sampled_sessions = serializers.IntegerField(
        read_only=True, allow_null=True, help_text="Sessions sampled into the corpus. Null on pre-v2 snapshots."
    )
    window_sessions = serializers.IntegerField(
        read_only=True,
        allow_null=True,
        help_text="Total sessions with tool calls in the lookback window (unsampled).",
    )
    session_coverage_pct = serializers.FloatField(
        read_only=True,
        allow_null=True,
        help_text="sampled_sessions / window_sessions as a percentage: how much of the window the corpus represents.",
    )
    intent_coverage_pct = serializers.FloatField(
        read_only=True,
        allow_null=True,
        help_text="Share of the window's calls that carried an $mcp_intent. Low coverage makes capture rates less reliable.",
    )
    imputed_call_pct = serializers.FloatField(
        read_only=True,
        allow_null=True,
        help_text="Share of attributed calls whose intent was carried forward from an earlier call in the session rather than stated on the call itself.",
    )
    unattributed_call_pct = serializers.FloatField(
        read_only=True,
        allow_null=True,
        help_text="Share of sampled calls with no attributable intent (before the session's first stated intent). These calls are excluded from clusters.",
    )
    corpus_call_coverage_pct = serializers.FloatField(
        read_only=True,
        allow_null=True,
        help_text="Share of attributed calls whose intent made the top-N cut that feeds clustering.",
    )
    advertisement_coverage_pct = serializers.FloatField(
        read_only=True,
        allow_null=True,
        help_text="Share of sampled sessions with an observed $mcp_tools_list catalog. Discovery rates only draw on those sessions.",
    )
    n_tools = serializers.IntegerField(read_only=True, allow_null=True, help_text="Tools included in the tool pivot.")
    dropped_tools = serializers.IntegerField(
        read_only=True,
        allow_null=True,
        help_text="Tools dropped from the pivot by the volume cap. Zero means the pivot is complete.",
    )
    dropped_overlap_pairs = serializers.IntegerField(
        read_only=True, allow_null=True, help_text="Overlap pairs dropped by the pair cap."
    )
    description_coverage_pct = serializers.FloatField(
        read_only=True,
        allow_null=True,
        help_text="Share of pivot tools with a captured description. Description fit is only available for those.",
    )


class MCPIntentClusterSnapshotSerializer(serializers.Serializer):
    status = serializers.ChoiceField(
        choices=[("idle", "Idle"), ("computing", "Computing"), ("error", "Error")],
        read_only=True,
        help_text="Whether a snapshot is current (idle), being recomputed (computing), or failed (error).",
    )
    error_message = serializers.CharField(
        read_only=True, allow_blank=True, help_text="Error message from the most recent failed run, otherwise empty."
    )
    last_computed_at = serializers.DateTimeField(
        read_only=True, allow_null=True, help_text="When the latest snapshot finished computing."
    )
    last_computed_by_email = serializers.CharField(
        read_only=True,
        allow_blank=True,
        help_text="Email of the user who triggered the latest recompute, empty for system-triggered runs.",
    )
    clusters = MCPIntentClusterSerializer(many=True, read_only=True, help_text="All clusters in the snapshot.")
    tools = MCPToolPivotSerializer(
        many=True,
        read_only=True,
        help_text="Tool-centric pivot of the clusters: per tool, the intents it serves, capture per cluster, contested score, discovery rate, and description fit. Empty on snapshots computed before the per-call pipeline; recompute to populate.",
    )
    tool_overlaps = MCPToolOverlapSerializer(
        many=True,
        read_only=True,
        help_text="Tool pairs competing for the same intent clusters, by contested call volume desc, capped at 50.",
    )
    computed_with = MCPIntentClusterSnapshotMetaSerializer(
        read_only=True,
        allow_null=True,
        help_text="Settings and coverage of the snapshot's corpus. Null when no snapshot has been computed yet.",
    )


class MCPMissingCapabilityCreateSerializer(MCPAnalyticsSubmissionContextSerializer):
    goal = serializers.CharField(max_length=MAX_GOAL_LENGTH, help_text="The user's intended outcome when using MCP.")
    missing_capability = serializers.CharField(
        max_length=MAX_SUMMARY_LENGTH,
        help_text="Capability, tool, or workflow support that is currently missing.",
    )
    blocked = serializers.BooleanField(
        required=False,
        default=True,
        help_text="Whether the missing capability blocked the user's progress.",
    )


DUPLICATE_MATCH_PATTERN_ERROR = "A custom harness already uses this pattern."
_BUILT_IN_HARNESS_LABELS = frozenset(
    label.lower() for label in (*HARNESS_LABELS, *MARKED_CLIENT_NAMES, UNIDENTIFIED_HARNESS_LABEL)
)


class MCPCustomHarnessSerializer(serializers.ModelSerializer):
    match_pattern = serializers.CharField(
        max_length=100,
        help_text=(
            "Text to look for in the client name or User-Agent product that the harness reports. "
            "Matching ignores case and finds the text anywhere in the name, so `acme-agent` matches `Acme-Agent/1.2`."
        ),
    )

    class Meta:
        model = MCPCustomHarness
        fields = ["id", "name", "match_pattern", "icon", "created_at", "updated_at"]
        read_only_fields = ["id", "created_at", "updated_at"]
        extra_kwargs = {
            "name": {"help_text": "Name to show for calls from this harness."},
            "icon": {
                "help_text": (
                    "Optional icon shown next to the harness name. A base64 data URI of a PNG, GIF or WebP image "
                    "with a transparent background, 16 KB or smaller and at most 256 by 256 pixels. The icon shows "
                    "in one color, like the built-in harness logos. An empty string means no icon."
                )
            },
        }

    def _other_team_harnesses(self) -> "QuerySet[MCPCustomHarness]":
        others = MCPCustomHarness.objects.for_team(self.context["get_team"]().id)
        return others.exclude(pk=self.instance.pk) if self.instance is not None else others

    def validate_name(self, value: str) -> str:
        name = value.strip()
        if self.instance is not None and name == self.instance.name:
            return name
        # The dashboard shows its own logo for a built-in label, so a team rule with that name would lose its icon.
        if name.lower() in _BUILT_IN_HARNESS_LABELS:
            raise serializers.ValidationError(f"{name} is a built-in label. Choose another name.")
        # The dashboard finds a harness icon by name, so two rules with one name would share one icon.
        if self._other_team_harnesses().filter(name__iexact=name).exists():
            raise serializers.ValidationError("Another custom harness already uses this name.")
        return name

    def validate_match_pattern(self, value: str) -> str:
        pattern = value.strip().lower()
        try:
            MCPCustomHarness._meta.get_field("match_pattern").run_validators(pattern)
        except DjangoValidationError as error:
            raise serializers.ValidationError(error.messages)
        return pattern

    def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
        others = self._other_team_harnesses()
        if "match_pattern" in attrs and others.filter(match_pattern=attrs["match_pattern"]).exists():
            raise serializers.ValidationError({"match_pattern": DUPLICATE_MATCH_PATTERN_ERROR})
        if self.instance is None and others.count() >= MAX_CUSTOM_HARNESSES:
            raise serializers.ValidationError(f"A project can have at most {MAX_CUSTOM_HARNESSES} custom harnesses.")
        return attrs

    def create(self, validated_data: dict[str, Any]) -> MCPCustomHarness:
        # validate() already checked for a duplicate pattern, but a concurrent request can still
        # win the race and insert first. The atomic block keeps the IntegrityError from poisoning
        # an outer transaction, so the view can still return a normal 400.
        try:
            with transaction.atomic():
                return MCPCustomHarness.objects.create(team_id=self.context["get_team"]().id, **validated_data)
        except IntegrityError:
            raise serializers.ValidationError({"match_pattern": DUPLICATE_MATCH_PATTERN_ERROR})

    def update(self, instance: MCPCustomHarness, validated_data: dict[str, Any]) -> MCPCustomHarness:
        try:
            with transaction.atomic():
                return super().update(instance, validated_data)
        except IntegrityError:
            raise serializers.ValidationError({"match_pattern": DUPLICATE_MATCH_PATTERN_ERROR})