# CUT Clarity MCP Server

`cut-clarity-mcp-server` is a small, deployable, read-only Model Context Protocol server for exposing Microsoft Clarity export data to ChatGPT Agent Builder.

The intended architecture is:

```text
ChatGPT Agent Builder
-> your public MCP server URL
-> Microsoft Clarity API/export data
```

This is intentionally separate from the WordPress plugin `AI Laser Studio`. Do not put this server inside WordPress, and do not point ChatGPT Agent Builder at WordPress for Clarity data. WordPress can later show status or link to this external MCP server, but secrets and analytics middleware stay outside WordPress.

## What It Exposes

The server registers five MCP tools:

- `list_available_exports`
- `get_project_live_insights`
- `export_project_summary`
- `export_page_metrics`
- `export_event_metrics`

All tools are read-only. There are no write, mutation, CRUD, or frontend features.

Microsoft Clarity endpoint paths are centralized in [src/config/clarityEndpoints.ts](src/config/clarityEndpoints.ts). The server uses the confirmed Microsoft Clarity Data Export API endpoint:

```text
GET https://www.clarity.ms/export-data/api/v1/project-live-insights
```

Clarity's Data Export API supports `numOfDays=1`, `2`, or `3`; it does not support arbitrary historical date ranges. Tools that accept `start_date` and `end_date` convert ranges ending today into `numOfDays`. Unsupported historical ranges return a structured `unsupported_date_range` error instead of pretending to fetch data.

## Transport

This project uses the official/broadly used Node MCP SDK package `@modelcontextprotocol/sdk`.

The remote transport endpoint is:

```text
/mcp
```

Use your own deployed MCP server URL in ChatGPT Agent Builder, for example:

```text
https://cut-clarity-mcp.your-domain.com/mcp
```

Do not enter `https://www.clarity.ms` in ChatGPT Agent Builder. ChatGPT Agent Builder should call your MCP server, and this server calls Clarity server-side with the Bearer token.

## Environment Variables

Copy `.env.example` to `.env` for local development.

```bash
npm install
cp .env.example .env
npm run dev
```

Variables:

- `PORT`: local/server port, default `3000`
- `NODE_ENV`: `development` or `production`
- `CLARITY_API_TOKEN`: Microsoft Clarity Bearer token
- `CLARITY_BASE_URL`: defaults to `https://www.clarity.ms`
- `CLARITY_HTTP_TIMEOUT_MS`: timeout for each upstream Clarity HTTP request, default `15000`
- `MCP_TOOL_TIMEOUT_MS`: hard timeout for each MCP tool call, default `20000`
- `MCP_TOP_PAGES_LIMIT`: maximum page rows returned to the MCP client, default `25`
- `MCP_TOP_SIGNALS_LIMIT`: maximum signal/friction rows returned to the MCP client, default `25`
- `MCP_SAMPLE_ROWS_LIMIT`: maximum sample rows returned to the MCP client, default `10`
- `MCP_INCLUDE_RAW_DEFAULT`: whether bounded raw samples are included by default, default `false`
- `MCP_MAX_RESPONSE_MODE`: response mode, currently `compact`
- `DEFAULT_PROJECT_ID`: optional fallback project id for tool calls
- `DEFAULT_TIMEZONE`: defaults to `Europe/Amsterdam`
- `LOG_LEVEL`: `debug`, `info`, `warn`, or `error`
- `MCP_SERVER_API_KEY`: optional auth key for MCP requests

No secrets are committed. Tokens are only read from environment variables and are never returned in tool responses or logs.

## Optional MCP Server Auth

If `MCP_SERVER_API_KEY` is set, every request to `/mcp` must include:

```text
Authorization: Bearer <MCP_SERVER_API_KEY>
```

`GET /health` remains public, but only returns boolean configuration status. If your ChatGPT Agent Builder setup cannot send an extra Authorization header, leave `MCP_SERVER_API_KEY` empty and avoid broadly sharing the MCP URL. The Clarity token still remains server-side.

## Local Development

```bash
npm install
cp .env.example .env
npm run dev
```

Health check:

```bash
curl http://localhost:3000/health
```

MCP endpoint:

```text
http://localhost:3000/mcp
```

Production build:

```bash
npm run build
npm start
```

Typecheck and smoke tests:

```bash
npm run typecheck
npm test
npm run smoke-test
```

## Health Check

`GET /health` returns:

```json
{
  "ok": true,
  "service": "cut-clarity-mcp-server",
  "version": "0.1.0",
  "clarity_configured": true,
  "default_project_configured": true
}
```

The health endpoint does not call Microsoft Clarity. It is intentionally fast and does not expose secrets.

## Clarity Endpoint Configuration

Endpoint strings are defined only in [src/config/clarityEndpoints.ts](src/config/clarityEndpoints.ts).

Each endpoint has:

- `enabled`
- `path`
- `method`
- `confirmed`
- `note`

The current mappings are:

- `get_project_live_insights`: confirmed endpoint with `numOfDays=1`
- `export_project_summary`: confirmed endpoint without dimensions
- `export_page_metrics`: confirmed endpoint with `dimension1=URL`
- `export_event_metrics`: confirmed endpoint with `dimension1=URL`, normalized for friction metrics

Endpoint strings should not be scattered through the codebase. If Microsoft adds more granular export endpoints later, update this single file and the matching tool handler.

## Compact MCP Responses

The server fetches the full Clarity response from Microsoft and keeps it in memory long enough to normalize, aggregate, and build top lists. The default MCP response sent back to ChatGPT Agent Builder is compact and does not include full raw arrays.

Default tool responses include:

- `tool`
- `project_id`
- `period` when applicable
- `row_count`
- `summary`
- top rows such as `top_pages`, `top_signals`, or `top_friction_pages`
- `sample_rows`
- `raw_retained: true`
- `raw_included: false`
- warnings such as `raw_not_included`, `limited_to_top_n`, and `sample_rows_limited`

Every tool accepts optional `include_raw: true`. Even then, the server returns only a bounded `raw_sample`, not an uncontrolled multi-megabyte raw export. Full raw payloads are never logged.

## Local Tool Smoke Checks

Run static checks and unit smoke tests:

```bash
npm run typecheck
npm test
npm run smoke-test
```

`npm run smoke-test` calls each MCP tool handler with the local environment and prints a compact table with `status`, `duration_ms`, and any structured `error_code`. It is designed to prove tools return quickly. If `DEFAULT_PROJECT_ID` or `CLARITY_API_TOKEN` is missing, the smoke test should show structured errors such as `missing_project_id` or `missing_clarity_token`, not hang.

When Clarity does not respond within `CLARITY_HTTP_TIMEOUT_MS`, tools return:

```json
{
  "ok": false,
  "error": {
    "code": "clarity_upstream_timeout",
    "message": "The Clarity API did not respond within 15000 ms",
    "status": 504
  }
}
```

To verify the deployed service is configured:

```bash
curl https://your-cloud-run-url/health
```

Expected:

```json
{
  "ok": true,
  "clarity_configured": true,
  "default_project_configured": true
}
```

In ChatGPT Agent Builder, call `list_available_exports` first. It should show configured and confirmed exports, not placeholder `not_configured` mappings.

## Deployment: Railway

1. Push this repository to GitHub.
2. Create a Railway project from the GitHub repo.
3. Set environment variables in Railway:
   - `CLARITY_API_TOKEN`
   - `CLARITY_BASE_URL`
   - `DEFAULT_PROJECT_ID` if desired
   - `DEFAULT_TIMEZONE`
   - `MCP_SERVER_API_KEY` if your MCP client supports it
4. Use start command:

```bash
npm start
```

5. Use the public Railway URL plus `/mcp` in ChatGPT Agent Builder.

## Deployment: Render

1. Create a Render Web Service.
2. Use build command:

```bash
npm install && npm run build
```

3. Use start command:

```bash
npm start
```

4. Set the same environment variables listed above.
5. Use the public Render URL plus `/mcp` in ChatGPT Agent Builder.

`render.yaml` is included as a starting point. It does not contain secrets.

## Deployment: Google Cloud Run

Build and push an image:

```bash
gcloud builds submit --tag gcr.io/PROJECT_ID/cut-clarity-mcp-server
```

Deploy:

```bash
gcloud run deploy cut-clarity-mcp-server \
  --source . \
  --region europe-west1 \
  --allow-unauthenticated \
  --set-env-vars NODE_ENV=production,CLARITY_BASE_URL=https://www.clarity.ms,CLARITY_HTTP_TIMEOUT_MS=15000,MCP_TOOL_TIMEOUT_MS=20000,MCP_TOP_PAGES_LIMIT=25,MCP_TOP_SIGNALS_LIMIT=25,MCP_SAMPLE_ROWS_LIMIT=10,MCP_INCLUDE_RAW_DEFAULT=false,MCP_MAX_RESPONSE_MODE=compact,DEFAULT_TIMEZONE=Europe/Amsterdam,DEFAULT_PROJECT_ID=YOUR_CLARITY_PROJECT_ID
```

Do not pass `PORT` as an environment variable on Cloud Run; Cloud Run reserves and sets it automatically. Set `CLARITY_API_TOKEN` and optional `MCP_SERVER_API_KEY` with Google Cloud Secret Manager or your preferred Cloud Run secret workflow.

Use:

```text
https://your-cloud-run-url/mcp
```

in ChatGPT Agent Builder.

## Safety Notes

- All MCP tools are read-only.
- Authorization headers and tokens are never logged.
- Raw Clarity payloads can be returned by tools, but environment secrets are not included.
- Logs contain only safe metadata such as tool name, project id, dates, status-like metadata, row count, and duration.
- Inputs are validated with `zod` plus explicit date range checks.
- Requests to Clarity use a timeout, limited retries, and exponential backoff for `429` and `5xx` failures.