mirror of
https://github.com/hanzoai/insights.git
synced 2026-11-02 14:32:45 +00:00
zeekay
1b367e2b62
The tree was a debranded snapshot of upstream taken around 2026-02-20, and upstream has moved about five months since. This replaces it with upstream master, mechanically re-derived: bin/debrand does the rename, and the pipeline and squashed migrations are restored from the shipped tree. Not a merge. The previous import replaced the tree wholesale in a single commit, so there is no shared content history to merge against. Reproducing the rename on the new tree is what actually converges. What survives: .hanzo/workflows, the Dockerfiles and bin/docker* entrypoints, compose files, LLM.md, and insights/migrations. The squashed initial migration is load-bearing — the live database records it by name, so upstream's ~918 individual migrations cannot come back. Nine products are dropped as unreferenced. Twenty-one more that we do not run are kept anyway because the core app still imports them; unpicking those is a refactor and does not belong in a rebase. This base does not build yet, and the reasons are not in the rename: upstream now wants Python 3.13.13 against our 3.12.12 and Django 5.2 against our 4.2, and the dependency manifests still name upstream packages that we republish under our own names. Those are decisions, not renames.
370 lines
17 KiB
YAML
370 lines
17 KiB
YAML
# MCP tool definition — tool entries are scaffolded from the OpenAPI schema.
|
|
# The tool list and operation IDs are kept in sync automatically:
|
|
# pnpm --filter=@hanzo/mcp run scaffold-yaml -- --sync-all
|
|
#
|
|
# To enable a tool, set enabled: true and add required scopes + annotations.
|
|
# All other fields (title, description, enrich_url, etc.) are yours to configure.
|
|
category: MCP analytics
|
|
feature: mcp_analytics
|
|
url_prefix: /mcp-analytics
|
|
ui_apps: {}
|
|
tools:
|
|
mcp-analytics-intent-clusters-recompute:
|
|
operation: mcp_analytics_intent_clusters_recompute
|
|
enabled: true
|
|
scopes:
|
|
- mcp_analytics:write
|
|
annotations:
|
|
readOnly: false
|
|
destructive: false
|
|
idempotent: false
|
|
title: Recompute intent clusters
|
|
description: >
|
|
Trigger an asynchronous recompute of the intent-cluster snapshot: sample recent sessions, attribute each
|
|
tool call to its own agent intent, embed and cluster the intents, and derive the tool pivot (capture rates,
|
|
discovery rates, description fit, overlaps). Returns immediately with status 'computing'; poll
|
|
mcp-analytics-intent-clusters-retrieve for progress (status becomes 'idle' or 'error').
|
|
requires_ai_consent: true
|
|
feature_flag: mcp-analytics
|
|
mcp-analytics-intent-clusters-retrieve:
|
|
operation: mcp_analytics_intent_clusters_retrieve
|
|
enabled: true
|
|
scopes:
|
|
- mcp_analytics:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
title: Get intent cluster snapshot
|
|
description: >
|
|
Return the most recent intent-clustering snapshot for the project: clusters of similar agent intents (tool
|
|
distribution, error rate, routing entropy, journey paths, error switches) plus a tool-centric pivot (per
|
|
tool: the intent clusters it serves with capture share and rank, discovery rate against the advertised
|
|
tools-list catalog, description-to-intent fit, contested score) and tool-overlap pairs competing for the
|
|
same intents. computed_with carries sample-coverage percentages; treat counts as sample statistics. Returns
|
|
an empty idle snapshot when no clustering run has happened yet — trigger one with
|
|
mcp-analytics-intent-clusters-recompute.
|
|
feature_flag: mcp-analytics
|
|
mcp-analytics-sessions-activity-overview:
|
|
operation: mcp_analytics_sessions_activity_overview
|
|
enabled: false
|
|
mcp-analytics-sessions-generate-intent:
|
|
operation: mcp_analytics_sessions_generate_intent
|
|
enabled: true
|
|
scopes:
|
|
- mcp_analytics:write
|
|
annotations:
|
|
readOnly: false
|
|
destructive: false
|
|
idempotent: true
|
|
title: Generate session intent summary
|
|
description: >
|
|
Generate (or return the cached) LLM summary of the agent's goal for a session, derived from the session's
|
|
recorded intents. The first call summarises and persists the result; subsequent calls return the stored
|
|
summary.
|
|
requires_ai_consent: true
|
|
feature_flag: mcp-analytics
|
|
mcp-analytics-sessions-intent-digest:
|
|
operation: mcp_analytics_sessions_intent_digest
|
|
enabled: false
|
|
mcp-analytics-sessions-list:
|
|
operation: mcp_analytics_sessions_list
|
|
enabled: true
|
|
scopes:
|
|
- mcp_analytics:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
list: true
|
|
title: List MCP sessions
|
|
description: >
|
|
List an MCP project's agent sessions — one row per $mcp_session_id, aggregated from that session's
|
|
$mcp_tool_call events. Use it to see who is connecting and how active, long-lived, and tool-heavy sessions
|
|
are: "which clients are most active this week?", "which sessions called tool X?", "how long do sessions
|
|
usually run?", "which person's sessions made the most calls?". Each row has session_id, tool_calls,
|
|
session_start, session_end, tools_used, mcp_client_name, distinct_id (plus the resolved person_email /
|
|
person_name when the distinct_id maps to a Person), distinct_id_count, and intent (empty until generated),
|
|
newest session first. Sort with `order_by`, but note its keys are the underlying column names: sort
|
|
tool_calls as `tool_call_count`, and `duration_seconds` (session length) is sortable even though it is not
|
|
returned as a field; an unrecognised key silently falls back to newest-first. Also supports a
|
|
case-insensitive `search`, a `date_from`/`date_to` window (default last 7 days), and `limit`/`offset` paging
|
|
— see each parameter for the specifics. To then summarise a single session's goal, follow up with
|
|
mcp-analytics-sessions-generate-intent.
|
|
feature_flag: mcp-analytics
|
|
mcp-analytics-sessions-tool-calls:
|
|
operation: mcp_analytics_sessions_tool_calls
|
|
enabled: true
|
|
scopes:
|
|
- mcp_analytics:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
list: true
|
|
title: List session tool calls
|
|
description: >
|
|
List a single session's $mcp_tool_call events in chronological order — the drill-down for a session found
|
|
via mcp-analytics-sessions-list. Pass the session's session_id (the {id} path param); for sessions older
|
|
than the default 7-day lookback, also pass its session_start as date_from so the event scan reaches them.
|
|
Each call has tool_name, intent, timestamp, duration_ms, and is_error / error_message. Pages with limit
|
|
(defaults to 500 — the whole page, since sessions rarely have more — max 500) and offset; the response's
|
|
has_next flag indicates whether more calls remain.
|
|
feature_flag: mcp-analytics
|
|
mcp-feedback-list:
|
|
operation: mcp_analytics_feedback_list
|
|
enabled: false
|
|
mcp-feedback-submit:
|
|
operation: mcp_analytics_feedback_create
|
|
enabled: true
|
|
scopes:
|
|
- mcp_analytics:write
|
|
annotations:
|
|
readOnly: false
|
|
destructive: false
|
|
idempotent: false
|
|
title: Submit MCP feedback
|
|
description: >
|
|
Submit qualitative feedback about the current MCP workflow, tool result, or product experience. Use this
|
|
when the available tools worked but the experience was confusing, incomplete, or could be improved.
|
|
include_params:
|
|
- goal
|
|
- feedback
|
|
- category
|
|
- attempted_tool
|
|
feature_flag: mcp-analytics
|
|
mcp-missing-capability-list:
|
|
operation: mcp_analytics_missing_capabilities_list
|
|
enabled: false
|
|
mcp-missing-capability-report:
|
|
operation: mcp_analytics_missing_capabilities_create
|
|
enabled: true
|
|
scopes:
|
|
- mcp_analytics:write
|
|
annotations:
|
|
readOnly: false
|
|
destructive: false
|
|
idempotent: false
|
|
title: Report missing capability
|
|
description: >
|
|
Report that the current MCP tools are insufficient for the user's goal. Use this when a missing tool,
|
|
missing workflow support, or missing explanation blocks progress.
|
|
include_params:
|
|
- goal
|
|
- missing_capability
|
|
- blocked
|
|
- attempted_tool
|
|
feature_flag: mcp-analytics
|
|
wrappers:
|
|
query-mcp-harness-breakdown:
|
|
schema_ref: MCPHarnessBreakdownQuery
|
|
enabled: true
|
|
scopes:
|
|
- query:read
|
|
- mcp_analytics:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
title: Break down MCP tool calls by harness
|
|
description: >
|
|
Group this project's MCP tool-call activity by the resolved client harness — the friendly product label for
|
|
the MCP client (Claude Agent SDK, Claude Code, OpenAI Codex, Cursor, Claude.ai, …). Returns calls, error
|
|
count, error rate, and session count per harness. Accepts the same dateRange / properties /
|
|
filterTestAccounts filters as the dashboard and resolves the harness server-side over the same query runner,
|
|
so results match the UI exactly. Use to answer "which harnesses use our MCP, and how reliably?".
|
|
system_prompt_hint: MCP client/harness breakdown — calls, error rate, sessions per harness
|
|
exclude_properties:
|
|
- response
|
|
- modifiers
|
|
- version
|
|
- tags
|
|
feature_flag: mcp-analytics
|
|
query-mcp-tool-stats:
|
|
schema_ref: MCPToolStatsQuery
|
|
enabled: true
|
|
scopes:
|
|
- query:read
|
|
- mcp_analytics:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
title: Summarise one MCP tool
|
|
description: >
|
|
Return the headline numbers for a single MCP tool over the window: total calls, error count, p50 and p95
|
|
latency, unique users, unique sessions, and how many calls carried an intent. Pass toolName (the effective
|
|
tool name — the inner tool is resolved server-side for single-exec wrapper calls, matching the tool-detail
|
|
UI). Use to answer "how is tool X doing overall?" before drilling into failures, users, or neighbours.
|
|
system_prompt_hint: One MCP tool's headline stats — calls, errors, p50/p95, users, sessions, intents
|
|
exclude_properties:
|
|
- response
|
|
- modifiers
|
|
- version
|
|
- tags
|
|
feature_flag: mcp-analytics
|
|
query-mcp-tool-daily-stats:
|
|
schema_ref: MCPToolDailyStatsQuery
|
|
enabled: true
|
|
scopes:
|
|
- query:read
|
|
- mcp_analytics:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
title: Daily trend for one MCP tool
|
|
description: >
|
|
Return a day-by-day time series for a single MCP tool: calls, errors, p50/p95 latency, unique users, and
|
|
unique sessions per day. Pass toolName (effective tool name, resolved server-side) and a dateRange. Use to
|
|
answer "how has tool X trended?" — spotting error spikes, latency regressions, or adoption changes over
|
|
time.
|
|
system_prompt_hint: One MCP tool's day-by-day series — calls, errors, p50/p95, users, sessions
|
|
exclude_properties:
|
|
- response
|
|
- modifiers
|
|
- version
|
|
- tags
|
|
feature_flag: mcp-analytics
|
|
query-mcp-tool-failures:
|
|
schema_ref: MCPToolFailuresQuery
|
|
enabled: true
|
|
scopes:
|
|
- query:read
|
|
- mcp_analytics:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
title: Top errors for one MCP tool
|
|
description: >
|
|
Return the most common failure buckets for a single MCP tool, each with the resolved client harness it came
|
|
from. Failures are the errored $mcp_tool_call events ($mcp_is_error = true) — the same source as the error
|
|
rate — grouped by $mcp_error_type and HTTP $mcp_error_status. Each bucket carries the raw error_type and
|
|
error_status, which you can pass to query-mcp-tool-failure-occurrences to see individual errored calls with
|
|
their error messages. Pass toolName (effective tool name, resolved server-side, matching the other
|
|
tool-detail tools) and a dateRange. Use to answer "why is tool X failing?" or "what errors does tool X
|
|
throw, and on which clients?".
|
|
system_prompt_hint: One MCP tool's top failure buckets, by harness (error type + HTTP status)
|
|
exclude_properties:
|
|
- response
|
|
- modifiers
|
|
- version
|
|
- tags
|
|
feature_flag: mcp-analytics
|
|
query-mcp-tool-failure-occurrences:
|
|
schema_ref: MCPToolFailureOccurrencesQuery
|
|
enabled: true
|
|
scopes:
|
|
- query:read
|
|
- mcp_analytics:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
title: Individual errored calls in one failure bucket
|
|
description: >
|
|
Return individual errored $mcp_tool_call events for a single MCP tool within one failure bucket, newest
|
|
first (up to 50). Each occurrence carries the timestamp, distinct_id, session id, resolved harness, the
|
|
agent's stated intent, the captured error message ($mcp_error_message — empty on events that predate message
|
|
capture), and the HTTP status. Pass toolName plus the errorType (raw $mcp_error_type; "unknown" for events
|
|
without one) and optional errorStatus exactly as returned by query-mcp-tool-failures — when errorStatus is
|
|
omitted, only events without a status match. Use to answer "show me the actual errors" after a failure
|
|
bucket looks suspicious.
|
|
system_prompt_hint: Individual errored calls (with error messages) for one MCP tool's failure bucket
|
|
exclude_properties:
|
|
- response
|
|
- modifiers
|
|
- version
|
|
- tags
|
|
feature_flag: mcp-analytics
|
|
query-mcp-tool-top-users:
|
|
schema_ref: MCPToolTopUsersQuery
|
|
enabled: true
|
|
scopes:
|
|
- query:read
|
|
- mcp_analytics:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
title: Top callers of one MCP tool
|
|
description: >
|
|
Return the top callers of a single MCP tool: per caller, the call count, error rate, resolved harness
|
|
labels, last-seen time, and the caller's display name and email. Pass toolName (effective tool name,
|
|
resolved server-side) and a dateRange. Use to answer "who uses tool X the most, and how reliably for them?".
|
|
system_prompt_hint: One MCP tool's top callers — calls, error rate, harnesses, person email/name
|
|
exclude_properties:
|
|
- response
|
|
- modifiers
|
|
- version
|
|
- tags
|
|
feature_flag: mcp-analytics
|
|
query-mcp-tool-neighbors:
|
|
schema_ref: MCPToolNeighborsQuery
|
|
enabled: true
|
|
scopes:
|
|
- query:read
|
|
- mcp_analytics:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
title: Tools called alongside one MCP tool
|
|
description: >
|
|
Return the tools most often called immediately before or after a single MCP tool within the same
|
|
conversation. Pass toolName (effective tool name, resolved server-side), a dateRange, and neighborDirection
|
|
('before' or 'after'). Use to answer "what does an agent call around tool X?" — revealing common tool
|
|
sequences and which tools pair up.
|
|
system_prompt_hint: Tools co-occurring before/after one MCP tool in a conversation
|
|
exclude_properties:
|
|
- response
|
|
- modifiers
|
|
- version
|
|
- tags
|
|
feature_flag: mcp-analytics
|
|
query-mcp-tool-sample-intents:
|
|
schema_ref: MCPToolSampleIntentsQuery
|
|
enabled: true
|
|
scopes:
|
|
- query:read
|
|
- mcp_analytics:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
title: Sample intents for one MCP tool
|
|
description: >
|
|
Return recent sample agent intents recorded for a single MCP tool, each with its resolved client harness.
|
|
Pass toolName (effective tool name, resolved server-side) and a dateRange. Use to answer "what are agents
|
|
actually trying to do when they call tool X?" — qualitative context behind the usage numbers.
|
|
system_prompt_hint: Recent sample agent intents for one MCP tool, with harness
|
|
exclude_properties:
|
|
- response
|
|
- modifiers
|
|
- version
|
|
- tags
|
|
feature_flag: mcp-analytics
|
|
query-mcp-tool-descriptions:
|
|
schema_ref: MCPToolDescriptionsQuery
|
|
enabled: true
|
|
scopes:
|
|
- query:read
|
|
- mcp_analytics:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
title: Descriptions seen for one MCP tool
|
|
description: >
|
|
Return the distinct effective tool-description strings seen for a single MCP tool over the window. Pass
|
|
toolName (effective tool name, resolved server-side) and a dateRange. Use to spot description drift or a
|
|
tool registered with more than one description across clients or versions.
|
|
system_prompt_hint: Distinct effective descriptions seen for one MCP tool
|
|
exclude_properties:
|
|
- response
|
|
- modifiers
|
|
- version
|
|
- tags
|
|
feature_flag: mcp-analytics
|