Metadata-Version: 2.4
Name: clarity-mcp
Version: 0.2.4
Summary: A Model Context Protocol (MCP) server for interacting with the Clarity API
Project-URL: Homepage, https://www.withclarity.dev/
Project-URL: Documentation, https://github.com/Clarity-DevOrg/clarity-mcp-server#readme
Project-URL: Repository, https://github.com/Clarity-DevOrg/clarity-mcp-server
Author-email: Mahi Kolla <mahi@withclarity.dev>
Maintainer-email: Mahi Kolla <mahi@withclarity.dev>
License: MIT
License-File: LICENSE
Keywords: ai,api,clarity,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: fastmcp<3.0,>=0.1.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# Clarity MCP Server

A Model Context Protocol (MCP) server for interacting with the Clarity API. This server enables Cursor and other MCP-compatible clients to access Clarity backend services.

## Installation

### Prerequisites

- Python 3.10 or higher (required for `fastmcp`)
- `uv` package manager (recommended for this project)

### Installing uv

**On macOS (using Homebrew):**
```bash
brew install uv
```

**On Linux/macOS (using curl):**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**On Windows:**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### Setting up the project

Once `uv` is installed, it will automatically manage Python versions. You can install dependencies and run the server:

```bash
# Install dependencies (uv will automatically use Python 3.10+)
# IMPORTANT: Run this WITHOUT activating any venv - just run it directly
uv sync

# Install the package in editable mode so the 'clarity-mcp' command is available
# This makes the entrypoint script available
uv pip install -e .

# Verify the installation worked
uv run which clarity-mcp

# Run the server locally (for development)
uv run clarity-mcp
```

**Important Notes**: 
- **Never activate the venv manually** - just run `uv sync` and `uv run` directly in your shell
- `uv sync` creates a `.venv` directory automatically, but you never need to activate/deactivate it
- `uv pip install -e .` installs the package in editable mode, making the `clarity-mcp` command available
- `uv run` automatically uses the venv that `uv` manages - this is "no manual virtualenv management"
- `uvx clarity-mcp` will only work after the package is published to PyPI. For local development, use `uv run clarity-mcp` after running `uv sync` and `uv pip install -e .`

The server will run over stdio and communicate with MCP clients.

## Configuration

The server requires the following environment variables:

- `CLARITY_EMAIL` (required): Your Clarity account email address
- `CLARITY_PASSWORD` (required): Your Clarity account password
- `CLARITY_BASE_URL` (optional): Base URL for the Clarity API (defaults to `https://clarity-backend.up.railway.app/`)
- `CLARITY_FRONTEND_URL` (optional): Frontend URL for the Clarity Chat API (defaults to `https://clarity-frontend.up.railway.app`)

### Setting Environment Variables

You can set environment variables in several ways:

**Option 1: Export in your shell**
```bash
export CLARITY_EMAIL=your_email@example.com
export CLARITY_PASSWORD=your_password
uv run clarity-mcp
```

**Option 2: Use a .env file (with python-dotenv)**
Create a `.env` file in your working directory:
```
CLARITY_EMAIL=your_email@example.com
CLARITY_PASSWORD=your_password
CLARITY_BASE_URL=https://clarity-backend.up.railway.app/
CLARITY_FRONTEND_URL=https://clarity-frontend.up.railway.app
```

**Option 3: Inline with the command**
```bash
CLARITY_EMAIL=your_email@example.com CLARITY_PASSWORD=your_password uv run clarity-mcp
```

### Cursor MCP Configuration

Add the following entry to your Cursor `mcp.json` configuration file:

```json
{
  "mcpServers": {
    "clarity": {
      "command": "uvx",
      "args": ["clarity-mcp"],
      "env": {
        "CLARITY_EMAIL": "your_email@example.com",
        "CLARITY_PASSWORD": "your_password",
        "CLARITY_BASE_URL": "https://clarity-backend.up.railway.app/",
        "CLARITY_FRONTEND_URL": "https://clarity-frontend.up.railway.app"
      }
    }
  }
}
```

**Note**: 
- Replace `your_email@example.com` and `your_password` with your actual Clarity credentials
- The `CLARITY_BASE_URL` and `CLARITY_FRONTEND_URL` are optional

After adding this configuration, restart Cursor to load the MCP server.

## Available Tools

### clarity_ping

Health check tool for the Clarity MCP server.

- **Input**: None
- **Output**: `{"status": "ok"}`

### get_company_info

Get company information from the Clarity API.

- **Input**: None
- **Output**: Dictionary containing company information
- **Errors**: Raises `ClarityAPIError` if the API request fails

### get_insights

Get insights from the Clarity API.

- **Input**: 
  - `status` (optional): Status filter. Can be a single status (e.g., `"new"`) or comma-separated multiple statuses (e.g., `"new,ticket_created"`). If not provided, returns all insights.
- **Output**: Dictionary containing insights data
- **Errors**: Raises `ClarityAPIError` if the API request fails

**Examples**:
- Get all insights: `get_insights()`
- Get only new insights: `get_insights(status="new")`
- Get new and ticket_created insights: `get_insights(status="new,ticket_created")`

### chat

Ask questions about your users and their feedback using natural language.

- **Input**: 
  - `query` (required): Natural language question about user feedback
- **Output**: Dictionary containing the chat response with a `response` field
- **Errors**: Raises `ClarityAPIError` if the API request fails

Use this tool when you need to understand what users are saying about specific topics, find related feedback, or explore user sentiment.

**Examples**:
- `chat(query="What are users saying about onboarding?")`
- `chat(query="Where else are users reporting this problem?")`
- `chat(query="What are the main complaints about the mobile app?")`
- `chat(query="How do users feel about the new pricing?")`

## Authentication

**Note**: This server currently uses email/password authentication, which is a temporary MVP approach. The architecture is designed to allow swapping authentication methods (e.g., API keys or OAuth) in the future without changing the MCP tool interface.