# CleverTap MCP

Read-only AI analytics assistant for CleverTap over the [Model Context Protocol](https://modelcontextprotocol.io). Live public CleverTap APIs only — no mocks, no write endpoints.

## Stack

- Bun + TypeScript + Zod
- `@modelcontextprotocol/sdk` (stable, Cursor-fit)
- `@modelcontextprotocol/ext-apps` (Claude.ai in-chat chart widgets)
- Dual transport: **stdio** (Cursor) and **Streamable HTTP `/mcp`** (hosted Claude.ai / remote Cursor)

## Setup

```bash
bun install
cp .env.example .env
# Fill CLEVERTAP_ACCOUNT_ID, CLEVERTAP_PASSCODE, CLEVERTAP_REGION
```

Regions: `in1` | `us1` | `sg1` | `eu1` | `aps3` | `mec1` | `eu`

## Cursor (local stdio)

Copy [`.cursor/mcp.json.example`](.cursor/mcp.json.example) to `.cursor/mcp.json` and set your credentials:

```json
{
  "mcpServers": {
    "clevertap": {
      "command": "bun",
      "args": ["run", "D:/clevertap/src/index.ts"],
      "env": {
        "CLEVERTAP_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
        "CLEVERTAP_PASSCODE": "YOUR_PASSCODE",
        "CLEVERTAP_REGION": "in1",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

Restart Cursor MCP (or reload the window). Tools appear under the CleverTap server. Chart tools return **markdown tables** in Cursor.

## Hosted `/mcp` (Claude.ai / remote Cursor)

```bash
MCP_TRANSPORT=http PORT=3000 bun run src/index.ts
# optional: MCP_AUTH_TOKEN=secret
```

- MCP endpoint: `http://HOST:3000/mcp`
- Health: `http://HOST:3000/health`

Point Claude.ai custom MCP / remote Cursor at that URL. Same tool surface as stdio. On Claude.ai, tools with `_meta.ui.resourceUri` render **MCP App chart widgets** in chat.

## Tool groups

| Group | Examples |
| --- | --- |
| workspace | `health_check`, `account_region`, `workspace_summary`, `realtime_dashboard` |
| events | `event_count`, `event_trends`, `compare_events`, `event_search`, … |
| profiles | `profile_count`, `profile_lookup`, `profiles_by_event`, … |
| properties | `top_property_values`, `property_distribution`, `property_trend`, … |
| campaigns | `campaign_report`, `campaign_ctr`, `campaign_channel_breakdown`, … |
| realtime | `realtime_active_users`, `realtime_breakdown`, `live_dashboard` |
| query | `run_query`, `validate_query`, `query_builder`, … |
| metadata | `list_events`, `discover_workspace`, `schema_summary`, … |
| charts | `line_chart`, `bar_chart`, `pie_chart`, `table`, `metric_card`, … |

APIs used: `/1/counts/events.json`, `/1/counts/trends.json`, `/1/counts/top.json`, `/1/counts/profiles.json`, `/1/events.json`, `/1/profiles.json`, `/1/profile.json`, `/1/message/report.json`, `/1/now.json`.

## Scripts

```bash
bun run start          # stdio
bun run start:http     # HTTP /mcp
bun run typecheck
```

## Notes

- Read-only: no upload, campaign create, or segment write tools.
- Some named tools (e.g. `returning_users`, `top_events`) are honest proxies over public endpoints — they error clearly when CleverTap cannot return the metric.
- Internal queue / poll / pagination are shared client helpers, not separate MCP tools.