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.

16.5 KB
Raw Blame
from collections.abc import Sequence
from datetime import datetime

from django.db import transaction
from django.utils import timezone

from posthog.schema import AnyPropertyFilterDiscriminated

from posthog.hogql import ast
from posthog.hogql.parser import CacheOrigin, parse_expr

from posthog.api.capture import capture_internal
from posthog.models.team.team import Team
from posthog.models.user import User

from products.mcp_analytics.backend import custom_harnesses, logic
from products.mcp_analytics.backend.hogql_queries.base import (
    EFFECTIVE_DESCRIPTION_SQL,
    EFFECTIVE_TOOL_SQL,
    NEW_SDK_SOURCE,
)
from products.mcp_analytics.backend.mcp_harness import HARNESS_TOKEN_SQL, custom_arms_sql, harness_label_sql
from products.mcp_analytics.backend.models import MCPAnalyticsSubmission

from . import contracts
from .constants import MCP_MISSING_CAPABILITY_EVENT
from .enums import SubmissionKind


def custom_harness_rules(team: Team) -> tuple[contracts.CustomHarnessRule, ...]:
    return custom_harnesses.custom_harness_rules(team)


def invalidate_custom_harness_rules(team: Team) -> None:
    custom_harnesses.invalidate_custom_harness_rules(team)


_VIRTUAL_FIELD_SQL = (
    f"if(startsWith(event, '$mcp_'), arrayMap(h -> {harness_label_sql('h')}, [{HARNESS_TOKEN_SQL}])[1], NULL)"
)


def mcp_harness_virtual_field_expr(custom_rules: Sequence[contracts.CustomHarnessRule] = ()) -> ast.Expr:
    # The fixed body is too long for the user parse cache, so only the short team rules parse as user input.
    expr = parse_expr(_VIRTUAL_FIELD_SQL, cache_origin=CacheOrigin.BUILTIN)
    if custom_rules:
        # nosemgrep: hogql-fstring-audit (the rule fields are escaped and character-restricted)
        rule_arms = parse_expr(f"multiIf({custom_arms_sql('h', custom_rules)}NULL)", cache_origin=CacheOrigin.USER)
        assert isinstance(rule_arms, ast.Call)
        _harness_label_call(expr).args[:0] = rule_arms.args[:-1]
    return expr


def _harness_label_call(virtual_field: ast.Expr) -> ast.Call:
    assert isinstance(virtual_field, ast.Call)
    label_access = virtual_field.args[1]
    assert isinstance(label_access, ast.ArrayAccess) and isinstance(label_access.array, ast.Call)
    label_lambda = label_access.array.args[0]
    assert isinstance(label_lambda, ast.Lambda) and isinstance(label_lambda.expr, ast.Call)
    return label_lambda.expr


def _to_submission(instance: MCPAnalyticsSubmission) -> contracts.Submission:
    return contracts.Submission(
        id=instance.id,
        kind=SubmissionKind(instance.kind),
        goal=instance.goal,
        summary=instance.summary,
        category=instance.category,
        blocked=instance.blocked,
        attempted_tool=instance.attempted_tool,
        mcp_client_name=instance.mcp_client_name,
        mcp_client_version=instance.mcp_client_version,
        mcp_protocol_version=instance.mcp_protocol_version,
        mcp_transport=instance.mcp_transport,
        mcp_session_id=instance.mcp_session_id,
        mcp_trace_id=instance.mcp_trace_id,
        created_at=instance.created_at,
        updated_at=instance.updated_at,
    )


def list_feedback_submissions(team: Team) -> list[contracts.Submission]:
    return [_to_submission(instance) for instance in logic.list_submissions(team, SubmissionKind.FEEDBACK)]


def list_missing_capability_submissions(team: Team) -> list[contracts.Submission]:
    return [_to_submission(instance) for instance in logic.list_submissions(team, SubmissionKind.MISSING_CAPABILITY)]


def create_feedback_submission(
    team: Team, created_by: User | None, submission: contracts.CreateFeedbackSubmission
) -> contracts.Submission:
    return _to_submission(logic.create_feedback_submission(team, created_by, submission))


def create_missing_capability_submission(
    team: Team, created_by: User | None, submission: contracts.CreateMissingCapabilitySubmission
) -> contracts.Submission:
    return _to_submission(logic.create_missing_capability_submission(team, created_by, submission))


def capture_missing_capability_event(team: Team, distinct_id: str, submission: contracts.Submission) -> None:
    properties: dict[str, object] = {
        "submission_id": str(submission.id),
        "kind": submission.kind,
        "attempted_tool_present": bool(submission.attempted_tool),
        "mcp_client_name_present": bool(submission.mcp_client_name),
        "mcp_session_id_present": bool(submission.mcp_session_id),
        "mcp_trace_id_present": bool(submission.mcp_trace_id),
        "$mcp_source": "posthog_mcp_analytics",
        "$mcp_tool_name": "mcp-missing-capability-report",
        "missing_capability_blocked": submission.blocked,
    }
    if submission.mcp_session_id:
        properties["$mcp_session_id"] = submission.mcp_session_id
    if submission.mcp_trace_id:
        properties["$mcp_trace_id"] = submission.mcp_trace_id

    capture_internal(
        token=team.api_token,
        event_name=MCP_MISSING_CAPABILITY_EVENT,
        event_source="mcp_analytics_missing_capability",
        distinct_id=distinct_id,
        properties=properties,
        event_uuid=str(submission.id),
        process_person_profile=False,
    )


def list_mcp_sessions(
    team: Team,
    limit: int,
    offset: int,
    search: str = "",
    order_by: str = "",
    date_from: str | None = None,
    date_to: str | None = None,
    has_errors: bool | None = None,
    properties: list[AnyPropertyFilterDiscriminated] | None = None,
    filter_test_accounts: bool = False,
    user: User | None = None,
) -> contracts.MCPSessionsPage:
    return logic.list_mcp_sessions(
        team,
        limit=limit,
        offset=offset,
        search=search,
        order_by=order_by,
        date_from=date_from,
        date_to=date_to,
        has_errors=has_errors,
        properties=properties,
        filter_test_accounts=filter_test_accounts,
        user=user,
    )


def list_mcp_tool_calls(
    team: Team,
    session_id: str,
    limit: int,
    offset: int,
    date_from: datetime | None = None,
    properties: list[AnyPropertyFilterDiscriminated] | None = None,
    filter_test_accounts: bool = False,
    user: User | None = None,
) -> contracts.MCPToolCallsPage:
    return logic.list_mcp_tool_calls(
        team,
        session_id=session_id,
        limit=limit,
        offset=offset,
        date_from=date_from,
        properties=properties,
        filter_test_accounts=filter_test_accounts,
        user=user,
    )


def generate_session_intent(team: Team, session_id: str, date_from: datetime | None = None) -> str:
    """Generate (or return the cached) intent summary for an MCP session.

    Shared entry point for the UI's on-demand button and any future caller
    (e.g. clustering). Persists the result to ``MCPSession.intent``. ``date_from``
    bounds the event scan to keep older sessions summarisable (same bound as
    ``list_mcp_tool_calls``).
    """
    return logic.generate_session_intent(team, session_id=session_id, date_from=date_from)


def generate_intent_digest(team: Team) -> contracts.IntentDigest:
    """Generate (or return the cached) project-level digest of what agents are trying to do.

    Powers the dashboard's activity tab: a one-sentence summary plus semantic themes. Cached
    both by intent corpus and by recency, so a quiet project regenerates only when its intents
    change and a busy one regenerates at a bounded rate.
    """
    return logic.generate_intent_digest(team)


def get_activity_overview(
    team: Team,
    properties: list[AnyPropertyFilterDiscriminated] | None = None,
    filter_test_accounts: bool = False,
    user: User | None = None,
    refresh: bool = False,
) -> contracts.ActivityOverview:
    """Compute the activity view's aggregates and recent-call feed in one pass.

    Bounded to the last 30 days. Cached by the filters and the caller's property restrictions:
    for 5 minutes without restrictions, for less than one poll interval with them.
    ``refresh`` skips a cached entry older than a few seconds and stores the fresh result in its place.

    ``properties`` and ``filter_test_accounts`` are the tabs' shared filters.
    """
    return logic.get_activity_overview(
        team, properties=properties, filter_test_accounts=filter_test_accounts, user=user, refresh=refresh
    )


def get_intent_cluster_snapshot(team: Team, tool: str | None = None) -> contracts.IntentClusterSnapshot:
    """The latest snapshot, optionally narrowed to one tool's slice of it."""
    return logic.get_intent_cluster_snapshot(team, tool=tool)


def trigger_intent_cluster_recompute(team: Team, user: User | None) -> None:
    """Kick off the intent cluster recompute Temporal workflow.

    Returns immediately. Use ``get_intent_cluster_snapshot`` to poll status —
    the workflow's compute activity writes the snapshot status (COMPUTING →
    IDLE/ERROR) as it runs.
    """
    import asyncio

    from django.conf import settings

    from temporalio.exceptions import WorkflowAlreadyStartedError

    from posthog.temporal.common.client import async_connect
    from posthog.temporal.mcp_analytics.intent_clustering.constants import (
        CHILD_WORKFLOW_ID_PREFIX,
        WORKFLOW_EXECUTION_TIMEOUT,
        WORKFLOW_NAME,
    )
    from posthog.temporal.mcp_analytics.intent_clustering.models import IntentClusteringWorkflowInputs

    from products.mcp_analytics.backend.models import MCPIntentClusterSnapshot

    # One run at a time per team: while a fresh run holds the snapshot in
    # COMPUTING, another dispatch would only stack a duplicate workflow on the
    # queue behind it. A run stuck past STALE_COMPUTING_THRESHOLD is presumed
    # dead (same rule as the sweep in get_intent_cluster_snapshot), so a
    # retry is allowed through. The row lock serialises concurrent triggers so
    # they can't all pass the freshness check before any of them claims the
    # snapshot; the Temporal dispatch stays outside the transaction.
    # Claiming COMPUTING before dispatching also means the 202 response and
    # any immediate poll see consistent state — the workflow's activity
    # re-asserts COMPUTING on pickup, and both writes are idempotent.
    with transaction.atomic():
        snapshot, created = MCPIntentClusterSnapshot.objects.select_for_update().get_or_create(
            team=team,
            defaults={
                "status": MCPIntentClusterSnapshot.Status.COMPUTING,
                "error_message": "",
                "last_computed_by": user,
            },
        )
        if not created:
            if (
                snapshot.status == MCPIntentClusterSnapshot.Status.COMPUTING
                and snapshot.updated_at >= timezone.now() - logic.STALE_COMPUTING_THRESHOLD
            ):
                return
            snapshot.status = MCPIntentClusterSnapshot.Status.COMPUTING
            snapshot.error_message = ""
            snapshot.last_computed_by = user
            snapshot.save(update_fields=["status", "error_message", "last_computed_by", "updated_at"])

    # Deterministic per team: Temporal refuses a second start while a run with
    # this id is live, so even a run that outlives STALE_COMPUTING_THRESHOLD
    # (which is shorter than the 20-minute execution timeout) can't be
    # overlapped by a retry — the id frees up once the previous run closes.
    workflow_id = f"{CHILD_WORKFLOW_ID_PREFIX}-{team.id}-adhoc"

    # Create + use the Temporal client inside one event loop. sync_connect()
    # would build the client in asgiref's managed loop and then asyncio.run()
    # would call start_workflow in a different loop; the temporalio Rust
    # bridge is currently loop-agnostic but the inconsistency is fragile.
    # Matches the cluster_mcp_intents management command pattern.
    async def _start() -> None:
        client = await async_connect()
        # execution_timeout bounds the whole run *including* queue wait: with
        # no worker polling the task queue, an unbounded workflow sits pending
        # forever and every recompute click stacks another one behind it.
        await client.start_workflow(
            WORKFLOW_NAME,
            IntentClusteringWorkflowInputs(team_id=team.id, user_id=user.id if user else None),
            id=workflow_id,
            task_queue=settings.MCPA_TASK_QUEUE,
            execution_timeout=WORKFLOW_EXECUTION_TIMEOUT,
        )

    try:
        asyncio.run(_start())
    except WorkflowAlreadyStartedError:
        # The previous run outlived the stale threshold but is genuinely still
        # running — leave the snapshot in COMPUTING; the live run flips the
        # status when it finishes.
        return
    except Exception:
        # Dispatch failed, so no activity will ever flip the status — revert
        # the optimistic COMPUTING write instead of leaving the snapshot stuck
        # until the stale-COMPUTING sweep in get_intent_cluster_snapshot.
        MCPIntentClusterSnapshot.objects.filter(team=team).update(
            status=MCPIntentClusterSnapshot.Status.ERROR,
            error_message="Failed to start the intent clustering workflow",
            updated_at=timezone.now(),
        )
        raise


# ---------------------------------------------------------------------------
# Measured-server aggregation surface (consumed by mcp_registry).
#
# mcp_registry's measured-server pipeline aggregates one project's new-SDK
# $mcp_tool_call events into per-server and per-tool stats. It needs the same
# exec-coalescing rules this product's own query runners use, so single-exec
# servers don't collapse into one `exec` bucket. Those rules live in
# hogql_queries/base; these helpers return them as parsed HogQL placeholders
# (and a HogQL fragment for the one cross-team discovery question) so the
# consumer never handles raw SQL text.
# ---------------------------------------------------------------------------

_SERVER_STATS_SELECT = """
    SELECT
        toString(properties.$mcp_server_name) AS server_name,
        count() AS calls,
        uniq(toString(properties.$mcp_session_id)) AS sessions,
        countIf(toString(properties.$mcp_is_error) IN ('true', '1')) AS errors,
        countIf(notEmpty(toString(properties.$mcp_intent))) AS calls_with_intent,
        uniq({effective_tool}) AS distinct_tools,
        uniq(toString(properties.$mcp_client_name)) AS client_names
    FROM events
    WHERE event = '$mcp_tool_call'
        AND timestamp >= {date_from}
        AND properties.$mcp_source = {source}
        AND notEmpty(toString(properties.$mcp_server_name))
    GROUP BY server_name
    ORDER BY calls DESC
"""

_TOOL_STATS_SELECT = """
    SELECT
        {effective_tool} AS tool_name,
        any({effective_description}) AS description,
        count() AS calls,
        countIf(toString(properties.$mcp_is_error) IN ('true', '1')) AS errors
    FROM events
    WHERE event = '$mcp_tool_call'
        AND timestamp >= {date_from}
        AND properties.$mcp_source = {source}
        AND toString(properties.$mcp_server_name) = {server_name}
        AND notEmpty({effective_tool})
    GROUP BY tool_name
    ORDER BY calls DESC
    LIMIT {tool_limit}
"""

# Only the deploy-configured database name is interpolated, never caller input.
_DISCOVERY_SQL = """
    SELECT DISTINCT team_id
    FROM {database}.events
    WHERE event = '$mcp_tool_call'
        AND timestamp >= now() - INTERVAL %(window_days)s DAY
        AND JSONExtractString(properties, '$mcp_source') = %(source)s
    ORDER BY team_id
    LIMIT %(limit)s
"""


def measured_server_stats_select() -> str:
    """HogQL select for per-server measured aggregates. Placeholders: date_from, source."""
    return _SERVER_STATS_SELECT


def measured_tool_stats_select() -> str:
    """HogQL select for per-tool measured aggregates. Placeholders: date_from, source, server_name, tool_limit."""
    return _TOOL_STATS_SELECT


def measured_discovery_sql(database: str) -> str:
    """ClickHouse SQL listing teams with recent new-SDK $mcp_tool_call traffic.

    Raw ClickHouse rather than HogQL because HogQL execution is scoped to one team and
    this is the one cross-team question the pipeline asks. Only the deploy-configured
    database name is interpolated; the rest is parameterised by the caller.
    """
    return _DISCOVERY_SQL.format(database=database)


def measured_query_placeholders(date_from: datetime) -> dict[str, ast.Expr]:
    """The placeholder values the measured-server selects share."""
    return {
        "effective_tool": parse_expr(EFFECTIVE_TOOL_SQL),
        "effective_description": parse_expr(EFFECTIVE_DESCRIPTION_SQL),
        "date_from": ast.Constant(value=date_from),
        "source": ast.Constant(value=NEW_SDK_SOURCE),
    }


def measured_source() -> str:
    """The source marker new-SDK $mcp_tool_call events carry."""
    return NEW_SDK_SOURCE