query-analytics-dashboard
Read-only
Analyze Microsoft Clarity data by asking natural language questions about user behavior, session metrics, and device performance with specific time ranges.
Instructions
Fetch Microsoft Clarity analytics data using a simplified natural language search query. The query should be focused on one specific data retrieval or aggregation task. Avoid complex multi-purpose queries. Time ranges should be explicitly specified when possible. If no time range is provided, prompt the user to specify one.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | A natural language search query string for filtering and shaping analytics data. The query should be specific and include temporal constraints when available. (e.g., 'Top browsers last 3 days', 'The active time duration for mobile devices in United States last week'). Time ranges should be explicitly specified when possible. If no time range is provided, prompt the user to specify one. |
Implementation Reference
- src/index.ts:43-57 (registration)Registers the 'query-analytics-dashboard' tool (via ANALYTICS_DASHBOARD_TOOL constant) on the MCP server. Specifies description, input schema (SearchRequest), metadata, and an inline async handler function that extracts the query parameter, determines the local timezone, and delegates to the queryAnalyticsDashboardAsync helper function.
// Register the query-analytics-data tool server.tool( ANALYTICS_DASHBOARD_TOOL, /* Name */ ANALYTICS_DASHBOARD_DESCRIPTION, /* Description */ SearchRequest, /* Parameter Schema */ { /* Metadata & Annotations */ title: "Query Analytics Dashboard", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ query }) => { return await queryAnalyticsDashboardAsync(query, Intl.DateTimeFormat().resolvedOptions().timeZone); } ); - src/tools.ts:14-29 (handler)Core handler implementation for the 'query-analytics-dashboard' tool. Performs an authenticated POST request to the Microsoft Clarity analytics dashboard API endpoint (ANALYTICS_DASHBOARD_URL) with the provided query and timezone, using the tryAsync utility.
export async function queryAnalyticsDashboardAsync( query: string, timezone: string, ): Promise<any> { return await tryAsync(ANALYTICS_DASHBOARD_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', ...(CLARITY_API_TOKEN ? { 'Authorization': `Bearer ${CLARITY_API_TOKEN}` } : {}), }, body: JSON.stringify({ query: query, timezone: timezone, }) }); } - src/types.ts:110-112 (schema)Zod-based input schema (SearchRequest) for the 'query-analytics-dashboard' tool, consisting of a single 'query' field validated against SearchQuery (a descriptive string for natural language analytics queries).
export const SearchRequest = { query: SearchQuery, }; - src/constants.ts:11-19 (helper)Defines essential constants for the 'query-analytics-dashboard' tool: the tool name (ANALYTICS_DASHBOARD_TOOL), description (ANALYTICS_DASHBOARD_DESCRIPTION), API endpoint URL (ANALYTICS_DASHBOARD_URL), and optional auth token (CLARITY_API_TOKEN). Used across registration, handler, and schema.
// Tool names. export const ANALYTICS_DASHBOARD_TOOL = "query-analytics-dashboard"; export const DOCUMENTATION_TOOL = "query-documentation-resources"; export const SESSION_RECORDINGS_TOOL = "list-session-recordings"; // Tool descriptions. export const ANALYTICS_DASHBOARD_DESCRIPTION = "Fetch Microsoft Clarity analytics data using a simplified natural language search query. The query should be focused on one specific data retrieval or aggregation task. Avoid complex multi-purpose queries. Time ranges should be explicitly specified when possible. If no time range is provided, prompt the user to specify one."; export const DOCUMENTATION_DESCRIPTION = "Retrieve Microsoft Clarity documentation snippets for finding answers to user questions including step-by-step screenshots for setup guides, features, usage, troubleshooting, and integration instructions. The query should be focused on one specific documentation topic or question. Avoid complex multi-purpose queries."; export const SESSION_RECORDINGS_DESCRIPTION = "List Microsoft Clarity session recordings based on specified filters. The filters allow you to narrow down the recordings by various criteria such as URLs, device types, browser, OS, country, city, and more. The date filter is required and must be in UTC ISO 8601 format.";