Clarity Data Export MCP Server

Instructions

Implementation Reference

• src/tools.ts:31-42 (handler)

  The main handler function `queryDocumentationAsync` that executes the tool's core logic: sends a POST request to the Microsoft Clarity documentation query API endpoint with the user-provided query, including optional authorization header.
  export async function queryDocumentationAsync(query: string): Promise<any> { return await tryAsync(DOCUMENTATION_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', ...(CLARITY_API_TOKEN ? { 'Authorization': `Bearer ${CLARITY_API_TOKEN}` } : {}) }, body: JSON.stringify({ query: query, }) }); }
• src/types.ts:102-112 (schema)

  The Zod-based input schema `SearchRequest` defining the tool's parameter: a single natural language `query` string.
  const SearchQuery = z.string().describe("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."); export const ListRequest = { filters: Filters, sortBy: SortOptions, count: SampleCount }; export const SearchRequest = { query: SearchQuery, };
• src/index.ts:85-99 (registration)

  Registers the tool with the MCP server using `server.tool()`, providing the tool name (DOCUMENTATION_TOOL), description, input schema (SearchRequest), metadata, and the handler function.
  // Register the query-documentation-resources tool server.tool( DOCUMENTATION_TOOL, /* Name */ DOCUMENTATION_DESCRIPTION, /* Description */ SearchRequest, /* Parameter Schema */ { /* Metadata & Annotations */ title: "Query Documentation Resources", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ query }) => { return await queryDocumentationAsync(query); } );
• src/constants.ts:6-19 (helper)

  Constants used by the tool including the tool name `DOCUMENTATION_TOOL = 'query-documentation-resources'`, description `DOCUMENTATION_DESCRIPTION`, API endpoint URL `DOCUMENTATION_URL`, and API token `CLARITY_API_TOKEN`.
  export const API_BASE_URL = `https://clarity.microsoft.com/mcp`; export const SESSION_RECORDINGS_URL = `${API_BASE_URL}/recordings/sample`; export const ANALYTICS_DASHBOARD_URL = `${API_BASE_URL}/dashboard/query`; export const DOCUMENTATION_URL = `${API_BASE_URL}/documentation/query`; // 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.";