feat(clarity): initialize Microsoft Clarity MCP server

[yuriassuncx]

This pull request introduces a new Microsoft Clarity MCP server integration, providing tools for analytics, session recordings, and documentation access via the Model Context Protocol (MCP). It includes the initial implementation of the service, configuration files, and supporting documentation, enabling AI-driven access to Clarity analytics and user data. The changes are organized into new service setup, tool implementations, and supporting documentation/configuration.

Microsoft Clarity MCP Service Implementation

• Added a new MCP server under microsoft-clarity/, including the main entrypoint (server/main.ts), environment types, and runtime configuration to register and serve the Clarity tools.
• Implemented a shared API call utility (server/lib/clarity.ts) to securely interact with the Microsoft Clarity Data Export API, handling token management and error reporting.

Analytics, Recordings, and Documentation Tools

• Implemented three core MCP tools:
  • queryAnalyticsDashboard: Queries analytics dashboard data (traffic, engagement, technical metrics).
  • listSessionRecordings: Retrieves session recordings with flexible filtering and sorting.
  • queryDocumentationResources: Searches official Clarity documentation for answers.
• Registered these tools in a centralized export (server/tools/index.ts).
• Added detailed system instructions for tool usage and best practices (server/instructions.ts).

Configuration and Documentation

• Added service configuration files: app.json (service metadata and authentication), app.json.example (template for new MCPs), and .gitignore for development hygiene. [1] [2] [3]
• Provided a comprehensive README.md with installation, usage, API limits, and development instructions.
• Added a package.json with scripts and dependencies for building and running the MCP server.

Deployment Integration

• Updated deploy.json to register the new microsoft-clarity service for deployment, specifying entrypoint, platform, and file watch patterns.

Developer Examples

• Included an example tool implementation file (server/tools/example-tool.ts.example) demonstrating patterns for custom tools, API calls, database queries, and event publishing for future extensibility.

---

Summary by cubic

Initialize the Microsoft Clarity MCP server to provide analytics dashboard queries, session recording search, and documentation lookup, and register the service for deployment. This adds token-based access to Clarity data through new MCP tools.

• New Features
  • New microsoft-clarity/ MCP server with runtime config and build scripts; service registered in deploy.json for kubernetes-bun.
  • Tools: query-analytics-dashboard (dashboard metrics), list-session-recordings (filterable recordings), query-documentation-resources (docs search).
  • Shared Clarity API client with token handling and error reporting; supports per-call token override.
  • App config (app.json), README, types, and system instructions added to guide installation and usage.

^{Written for commit 2f57ac0. Summary will update on new commits.}

[cubic-dev-ai]

4 issues found across 17 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="microsoft-clarity/server/tools/recordings.ts">

<violation number="1" location="microsoft-clarity/server/tools/recordings.ts:30">
P2: Missing `start` date fallback is computed from `now` instead of `endDate`, causing incorrect cross-month/year date ranges.</violation>
</file>

<file name="microsoft-clarity/server/types/clarity.ts">

<violation number="1" location="microsoft-clarity/server/types/clarity.ts:324">
P2: `date.start`/`date.end` are documented as strict UTC ISO timestamps with milliseconds, but schema uses unconstrained `z.string()` and does not enforce datetime format.</violation>

<violation number="2" location="microsoft-clarity/server/types/clarity.ts:338">
P2: Schema documentation says date is required, but `date` is optional in validation and runtime code applies defaults when omitted.</violation>

<violation number="3" location="microsoft-clarity/server/types/clarity.ts:362">
P2: `SampleCount` validation is incomplete: it permits non-integer and non-positive values despite documented `1-250` constraints.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Missing start date fallback is computed from now instead of endDate, causing incorrect cross-month/year date ranges.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At microsoft-clarity/server/tools/recordings.ts, line 30:

<comment>Missing `start` date fallback is computed from `now` instead of `endDate`, causing incorrect cross-month/year date ranges.</comment>

<file context>
@@ -0,0 +1,47 @@
+      const startDate = new Date(startDateString);
+
+      if (!filters?.date?.start) {
+        startDate.setDate(endDate.getDate() - 2);
+      }
+
</file context>

[cubic-dev-ai]

P2: Schema documentation says date is required, but date is optional in validation and runtime code applies defaults when omitted.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At microsoft-clarity/server/types/clarity.ts, line 338:

<comment>Schema documentation says date is required, but `date` is optional in validation and runtime code applies defaults when omitted.</comment>

<file context>
@@ -0,0 +1,391 @@
+      .optional(),
+  })
+  .describe(
+    "A set of filters that can be applied to the Microsoft Clarity to session recordings. This allows you to filter recordings based on 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.",
+  );
+
</file context>

[cubic-dev-ai]

P2: date.start/date.end are documented as strict UTC ISO timestamps with milliseconds, but schema uses unconstrained z.string() and does not enforce datetime format.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At microsoft-clarity/server/types/clarity.ts, line 324:

<comment>`date.start`/`date.end` are documented as strict UTC ISO timestamps with milliseconds, but schema uses unconstrained `z.string()` and does not enforce datetime format.</comment>

<file context>
@@ -0,0 +1,391 @@
+      ),
+    date: z
+      .object({
+        start: z
+          .string()
+          .describe(
</file context>

[cubic-dev-ai]

P2: SampleCount validation is incomplete: it permits non-integer and non-positive values despite documented 1-250 constraints.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At microsoft-clarity/server/types/clarity.ts, line 362:

<comment>`SampleCount` validation is incomplete: it permits non-integer and non-positive values despite documented `1-250` constraints.</comment>

<file context>
@@ -0,0 +1,391 @@
+export type SortOptionsType = z.infer<typeof SortOptions>;
+
+export const SampleCount = z
+  .number()
+  .lte(250, "Maximum sample count is 250")
+  .default(100)
</file context>