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.

21.5 KB
Raw Blame
from datetime import datetime
from typing import Any, cast

from django.db.models import QuerySet
from django.utils.dateparse import parse_datetime

from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema
from rest_framework import status, viewsets
from rest_framework.decorators import action
from rest_framework.request import Request
from rest_framework.response import Response
from rest_framework.serializers import BaseSerializer

from posthog.api.mixins import ValidatedRequest, validated_request
from posthog.api.pagination import BoundedLimitOffsetPagination, page_link, previous_offset
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.event_usage import report_user_action
from posthog.models.user import User
from posthog.permissions import PostHogFeatureFlagPermission

from products.mcp_analytics.backend import logic
from products.mcp_analytics.backend.facade import api, contracts, enums
from products.mcp_analytics.backend.models import MCPAnalyticsSubmission, MCPCustomHarness

from .serializers import (
    MCP_SESSION_LIST_DEFAULT_LIMIT,
    MCP_SESSION_LIST_MAX_LIMIT,
    MCPActivityOverviewQuerySerializer,
    MCPActivityOverviewSerializer,
    MCPAnalyticsSubmissionSerializer,
    MCPCustomHarnessSerializer,
    MCPFeedbackCreateSerializer,
    MCPIntentClusterSnapshotSerializer,
    MCPIntentDigestSerializer,
    MCPMissingCapabilityCreateSerializer,
    MCPSessionIntentSerializer,
    MCPSessionListQuerySerializer,
    MCPSessionSerializer,
    MCPSessionToolCallsQuerySerializer,
    MCPToolCallSerializer,
)


def _parse_detail_date_from(raw: str | None) -> datetime | None:
    """Parse the optional session-start bound for detail queries (an absolute ISO timestamp).

    Returns None on missing or unparseable input so the logic layer falls back to its default
    lookback rather than 400-ing — the bound is only a scan-pruning hint, never a filter.
    """
    return parse_datetime(raw) if raw else None


class MCPAnalyticsPagination(BoundedLimitOffsetPagination):
    default_limit = 100
    max_limit = 500


class MCPSessionPagination(BoundedLimitOffsetPagination):
    """Returns ``{next, previous, results, has_next}`` without a ``count``. The list is an
    on-the-fly ClickHouse aggregate with no cheap total, so ``has_next`` comes from the
    logic layer over-fetching one row rather than a count query.
    """

    default_limit = MCP_SESSION_LIST_DEFAULT_LIMIT
    max_limit = MCP_SESSION_LIST_MAX_LIMIT

    def get_page_response(self, request: Request, data: Any, *, offset: int, limit: int, has_next: bool) -> Response:
        return Response(
            {
                "next": page_link(request, self.offset_query_param, offset + limit) if has_next else None,
                "previous": page_link(request, self.offset_query_param, previous_offset(offset, limit)),
                "results": data,
                "has_next": has_next,
            }
        )

    def get_paginated_response_schema(self, schema: dict) -> dict:
        return {
            "type": "object",
            "required": ["next", "previous", "results", "has_next"],
            "properties": {
                "next": {
                    "type": "string",
                    "format": "uri",
                    "nullable": True,
                    "description": "URL of the next page, or null on the last page.",
                },
                "previous": {
                    "type": "string",
                    "format": "uri",
                    "nullable": True,
                    "description": "URL of the previous page, or null on the first page.",
                },
                "results": schema,
                "has_next": {
                    "type": "boolean",
                    "description": "Whether more results exist beyond this page; the client fetches the next page with a larger offset.",
                },
            },
        }


class BaseMCPAnalyticsSubmissionViewSet(TeamAndOrgViewSetMixin, viewsets.GenericViewSet):
    serializer_class = MCPAnalyticsSubmissionSerializer
    # create -> write, list -> read map to the default scope actions.
    scope_object = "mcp_analytics"
    pagination_class = MCPAnalyticsPagination
    user_action_name: str = ""

    def _submission_context(self, validated_data: dict[str, Any]) -> contracts.SubmissionContext:
        return contracts.SubmissionContext(
            attempted_tool=validated_data.get("attempted_tool", ""),
            mcp_client_name=validated_data.get("mcp_client_name", ""),
            mcp_client_version=validated_data.get("mcp_client_version", ""),
            mcp_protocol_version=validated_data.get("mcp_protocol_version", ""),
            mcp_transport=validated_data.get("mcp_transport", ""),
            mcp_session_id=validated_data.get("mcp_session_id", ""),
            mcp_trace_id=validated_data.get("mcp_trace_id", ""),
        )

    def _report_submission_created(self, request: Request, submission: contracts.Submission) -> None:
        report_user_action(
            cast(User, request.user),
            self.user_action_name,
            self._submission_event_properties(submission),
            team=self.team,
            request=request,
        )

    def _submission_event_properties(self, submission: contracts.Submission) -> dict[str, Any]:
        return {
            "submission_id": str(submission.id),
            "kind": submission.kind,
            "attempted_tool": submission.attempted_tool,
            "mcp_client_name": submission.mcp_client_name,
            "mcp_session_id_present": bool(submission.mcp_session_id),
            "mcp_trace_id_present": bool(submission.mcp_trace_id),
        }

    def _list_response(self, request: Request, kind: enums.SubmissionKind) -> Response:
        paginator = self.pagination_class()
        page = paginator.paginate_queryset(logic.list_submissions(self.team, kind), request, view=self)
        assert page is not None
        serializer = self.get_serializer(page, many=True)
        return paginator.get_paginated_response(serializer.data)


class MCPFeedbackViewSet(BaseMCPAnalyticsSubmissionViewSet):
    user_action_name = "mcp analytics feedback created"

    @validated_request(
        request_serializer=MCPFeedbackCreateSerializer,
        responses={201: OpenApiResponse(response=MCPAnalyticsSubmissionSerializer)},
        operation_id="mcp_analytics_feedback_create",
        description="Create a new MCP feedback submission for the current project.",
    )
    def create(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:
        submission = api.create_feedback_submission(
            self.team,
            cast(User, request.user),
            contracts.CreateFeedbackSubmission(
                goal=request.validated_data["goal"],
                feedback=request.validated_data["feedback"],
                category=request.validated_data["category"],
                context=self._submission_context(request.validated_data),
            ),
        )
        self._report_submission_created(request, submission)
        return Response(self.get_serializer(submission).data, status=status.HTTP_201_CREATED)

    @extend_schema(
        operation_id="mcp_analytics_feedback_list",
        description="List MCP feedback submissions for the current project, newest first.",
    )
    def list(self, request: Request, *args: Any, **kwargs: Any) -> Response:
        return self._list_response(request, enums.SubmissionKind.FEEDBACK)


class MCPSessionViewSet(TeamAndOrgViewSetMixin, viewsets.GenericViewSet):
    serializer_class = MCPSessionSerializer
    scope_object = "mcp_analytics"
    # tool_calls, activity_overview, and intent_digest are GETs in spirit (they just read/compute
    # cached data, not persist a mutation the caller controls) even though intent_digest is wired
    # as a POST; generate_intent actually persists a per-session summary, so it maps to the write
    # scope. The default read/write action lists don't cover custom @action names, so
    # APIScopePermission/AccessControlPermission would otherwise reject viewer-level access.
    scope_object_read_actions = ["list", "retrieve", "tool_calls", "activity_overview", "intent_digest"]
    scope_object_write_actions = ["generate_intent"]
    pagination_class = MCPSessionPagination

    def dangerously_get_queryset(self) -> QuerySet:
        # Sessions live in ClickHouse, not a Django model, but GenericViewSet still needs a
        # queryset for its plumbing. The model is arbitrary — we borrow MCPAnalyticsSubmission
        # (a plain manager) so .none() can't trip a team-scoped manager's guard.
        return MCPAnalyticsSubmission.objects.none()

    @validated_request(
        query_serializer=MCPSessionListQuerySerializer,
        responses={200: OpenApiResponse(response=MCPSessionSerializer(many=True))},
        operation_id="mcp_analytics_sessions_list",
        description="List MCP sessions for the current project, derived by grouping $mcp_tool_call events by $mcp_session_id. Ordered by newest session start first by default.",
    )
    def list(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:
        params = request.validated_query_data
        page = api.list_mcp_sessions(
            self.team,
            limit=params["limit"],
            offset=params["offset"],
            search=params["search"],
            order_by=params["order_by"],
            date_from=params.get("date_from") or None,
            date_to=params.get("date_to") or None,
            has_errors=params["has_errors"],
            properties=params["properties"],
            filter_test_accounts=params["filter_test_accounts"],
            user=cast(User, request.user),
        )
        serializer = self.get_serializer(page.results, many=True)
        # Instantiate the concrete class (not self.pagination_class()) so the typed
        # get_page_response(...) is visible to the type checker.
        return MCPSessionPagination().get_page_response(
            request, serializer.data, offset=params["offset"], limit=params["limit"], has_next=page.has_next
        )

    @validated_request(
        query_serializer=MCPSessionToolCallsQuerySerializer,
        responses={200: OpenApiResponse(response=MCPToolCallSerializer(many=True))},
        operation_id="mcp_analytics_sessions_tool_calls",
        description="List a page of the $mcp_tool_call events that belong to a given $session_id, in chronological order.",
    )
    @action(detail=True, methods=["get"], url_path="tool_calls")
    def tool_calls(self, request: ValidatedRequest, pk: str | None = None, *args: Any, **kwargs: Any) -> Response:
        params = request.validated_query_data
        page = api.list_mcp_tool_calls(
            self.team,
            session_id=str(pk or ""),
            limit=params["limit"],
            offset=params["offset"],
            date_from=params.get("date_from"),
            properties=params["properties"],
            filter_test_accounts=params["filter_test_accounts"],
            user=cast(User, request.user),
        )
        serializer = MCPToolCallSerializer(page.results, many=True)
        return MCPSessionPagination().get_page_response(
            request, serializer.data, offset=params["offset"], limit=params["limit"], has_next=page.has_next
        )

    @extend_schema(
        operation_id="mcp_analytics_sessions_generate_intent",
        description=(
            "Generate (or return the cached) LLM summary of the agent's goal for a session, derived from its "
            "recorded $mcp_intents. The first call summarises and persists the result; subsequent calls return "
            "the stored summary."
        ),
        request=None,
        parameters=[
            OpenApiParameter(
                name="date_from",
                type=OpenApiTypes.DATETIME,
                location=OpenApiParameter.QUERY,
                required=False,
                description=(
                    "Absolute ISO timestamp lower bound for the intent scan — pass the session's "
                    "start so older sessions resolve. Defaults to a 7-day lookback when omitted."
                ),
            ),
        ],
        responses={200: MCPSessionIntentSerializer},
    )
    @action(detail=True, methods=["post"], url_path="generate_intent")
    def generate_intent(self, request: Request, pk: str | None = None, *args: Any, **kwargs: Any) -> Response:
        session_id = str(pk or "")
        if not session_id:
            return Response({"detail": "session_id is required."}, status=status.HTTP_400_BAD_REQUEST)
        date_from = _parse_detail_date_from(request.query_params.get("date_from"))
        try:
            intent = api.generate_session_intent(self.team, session_id=session_id, date_from=date_from)
        except contracts.IntentGenerationUnavailable:
            return Response(
                {"detail": "Intent generation is unavailable (LLM not configured)."},
                status=status.HTTP_503_SERVICE_UNAVAILABLE,
            )
        serializer = MCPSessionIntentSerializer({"session_id": session_id, "intent": intent})
        return Response(serializer.data)

    @extend_schema(
        operation_id="mcp_analytics_sessions_intent_digest",
        description=(
            "Generate (or return the cached) LLM digest of what agents are trying to do with this MCP server, "
            "derived from the most recent recorded $mcp_intents across all sessions: a one-sentence summary "
            "plus semantic themes, each sized and attributed to tools from the intents themselves. Cached by "
            "intent corpus and by recency, so repeated calls are cheap and a busy server regenerates at a "
            "bounded rate. Powers the dashboard's activity tab."
        ),
        request=None,
        responses={
            200: MCPIntentDigestSerializer,
            503: OpenApiResponse(description="Intent digest generation is unavailable (LLM not configured)."),
        },
    )
    @action(detail=False, methods=["post"], url_path="intent_digest")
    def intent_digest(self, request: Request, *args: Any, **kwargs: Any) -> Response:
        try:
            digest = api.generate_intent_digest(self.team)
        except contracts.IntentGenerationUnavailable:
            return Response(
                {"detail": "Intent digest generation is unavailable (LLM not configured)."},
                status=status.HTTP_503_SERVICE_UNAVAILABLE,
            )
        return Response(MCPIntentDigestSerializer(digest).data)

    @validated_request(
        query_serializer=MCPActivityOverviewQuerySerializer,
        responses={200: OpenApiResponse(response=MCPActivityOverviewSerializer)},
        operation_id="mcp_analytics_sessions_activity_overview",
        description=(
            "Aggregate counters, top tools, agent clients, and the most recent tool calls for the last 30 days, "
            "computed in one request. Powers the dashboard's activity view. Results are cached for up to 5 minutes, "
            "or 20 seconds when the caller has property restrictions. An empty result is never cached. "
            "Pass refresh to skip the cache."
        ),
    )
    @action(detail=False, methods=["get"], url_path="activity_overview", pagination_class=None)
    def activity_overview(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:
        params = request.validated_query_data
        overview = api.get_activity_overview(
            self.team,
            properties=params["properties"],
            filter_test_accounts=params["filter_test_accounts"],
            user=cast(User, request.user),
            refresh=params["refresh"],
        )
        return Response(MCPActivityOverviewSerializer(overview).data)


class MCPIntentClusterViewSet(TeamAndOrgViewSetMixin, viewsets.GenericViewSet):
    serializer_class = MCPIntentClusterSnapshotSerializer
    scope_object = "mcp_analytics"
    # recompute is a POST that kicks off the async clustering task (a state change), so it maps to
    # the write scope; the snapshot read stays on the read scope.
    scope_object_read_actions = ["list", "retrieve"]
    scope_object_write_actions = ["recompute"]
    posthog_feature_flag = contracts.MCP_ANALYTICS_INTENT_ROUTING_FEATURE_FLAG
    permission_classes = [PostHogFeatureFlagPermission]
    pagination_class = None

    def dangerously_get_queryset(self) -> QuerySet:
        # Snapshots are read directly via the facade; this satisfies GenericViewSet plumbing.
        return MCPAnalyticsSubmission.objects.none()

    @extend_schema(
        operation_id="mcp_analytics_intent_clusters_retrieve",
        description=(
            "Return the most recent intent cluster snapshot for the current project. "
            "Returns an empty IDLE snapshot when no clustering run has happened yet."
        ),
        parameters=[
            OpenApiParameter(
                name="tool",
                type=str,
                location=OpenApiParameter.QUERY,
                required=False,
                description=(
                    "Narrow the response to one tool: its pivot entry, the clusters it serves or switches "
                    "with, and the overlap pairs it belongs to. Coverage meta stays whole-snapshot. Use "
                    "this for single-tool views so they don't download every cluster and pivot to render "
                    "one row. An unknown tool returns empty sections, not a 404."
                ),
            )
        ],
        responses={200: MCPIntentClusterSnapshotSerializer},
    )
    def list(self, request: Request, *args: Any, **kwargs: Any) -> Response:
        snapshot = api.get_intent_cluster_snapshot(self.team, tool=request.query_params.get("tool") or None)
        serializer = self.get_serializer(snapshot)
        return Response(serializer.data)

    @extend_schema(
        operation_id="mcp_analytics_intent_clusters_recompute",
        description=(
            "Trigger an asynchronous recompute of the intent cluster snapshot. The task runs in the "
            "background; poll the GET endpoint for progress (status transitions to 'idle' or 'error')."
        ),
        request=None,
        responses={202: MCPIntentClusterSnapshotSerializer},
    )
    @action(detail=False, methods=["post"], url_path="recompute")
    def recompute(self, request: Request, *args: Any, **kwargs: Any) -> Response:
        api.trigger_intent_cluster_recompute(self.team, cast(User, request.user))
        snapshot = api.get_intent_cluster_snapshot(self.team)
        serializer = self.get_serializer(snapshot)
        return Response(serializer.data, status=status.HTTP_202_ACCEPTED)


class MCPMissingCapabilityViewSet(BaseMCPAnalyticsSubmissionViewSet):
    def _report_submission_created(self, request: Request, submission: contracts.Submission) -> None:
        distinct_id = str(getattr(request.user, "distinct_id", "") or f"mcp-missing-capability-{self.team.id}")
        api.capture_missing_capability_event(self.team, distinct_id, submission)

    @validated_request(
        request_serializer=MCPMissingCapabilityCreateSerializer,
        responses={201: OpenApiResponse(response=MCPAnalyticsSubmissionSerializer)},
        operation_id="mcp_analytics_missing_capabilities_create",
        description="Create a new missing capability report for the current project.",
    )
    def create(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:
        submission = api.create_missing_capability_submission(
            self.team,
            cast(User, request.user),
            contracts.CreateMissingCapabilitySubmission(
                goal=request.validated_data["goal"],
                missing_capability=request.validated_data["missing_capability"],
                blocked=request.validated_data["blocked"],
                context=self._submission_context(request.validated_data),
            ),
        )
        self._report_submission_created(request, submission)
        return Response(self.get_serializer(submission).data, status=status.HTTP_201_CREATED)

    @extend_schema(
        operation_id="mcp_analytics_missing_capabilities_list",
        description="List missing capability reports for the current project, newest first.",
    )
    def list(self, request: Request, *args: Any, **kwargs: Any) -> Response:
        return self._list_response(request, enums.SubmissionKind.MISSING_CAPABILITY)


class MCPCustomHarnessViewSet(TeamAndOrgViewSetMixin, viewsets.ModelViewSet):
    """A team's own harness names, shown in place of "Other" in MCP analytics."""

    serializer_class = MCPCustomHarnessSerializer
    scope_object = "mcp_analytics"
    queryset = MCPCustomHarness.objects.unscoped()
    pagination_class = None

    def safely_get_queryset(self, queryset: QuerySet[MCPCustomHarness]) -> QuerySet[MCPCustomHarness]:
        # Rows save under the parent team (`TeamScopedRootMixin.save()`), so a child environment filters on it too.
        return queryset.filter(team_id=self.team.parent_team_id or self.team.pk)

    def _should_skip_parents_filter(self) -> bool:
        # The default parent-lookup filter adds the raw URL team id, which hides the rows a child environment
        # saved under its parent. safely_get_queryset already scopes every read.
        return True

    def perform_create(self, serializer: BaseSerializer[Any]) -> None:
        super().perform_create(serializer)
        api.invalidate_custom_harness_rules(self.team)

    def perform_update(self, serializer: BaseSerializer[Any]) -> None:
        super().perform_update(serializer)
        api.invalidate_custom_harness_rules(self.team)

    def perform_destroy(self, instance: MCPCustomHarness) -> None:
        super().perform_destroy(instance)
        api.invalidate_custom_harness_rules(self.team)