Metadata-Version: 2.5
Name: compethic-mcp
Version: 0.1.1
Summary: Compethic MCP server: org-scoped feedback and taxonomy reads via the datalayer.
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx
Requires-Dist: pydantic-settings
Requires-Dist: pyjwt
Description-Content-Type: text/markdown

# Compethic MCP Server

Cursor and Claude Desktop MCP server that reads Compethic feedback, taxonomy, and analytics through the Compethic API. Tools mint a gateway-client JWT and call product GETs with `organization_id` taken from that JWT.

## Prerequisites: install uv

The package runs via **`uvx`** (part of [uv](https://docs.astral.sh/uv/)). Install uv using the official installer — see [Installation](https://docs.astral.sh/uv/getting-started/installation/).

**macOS and Linux:**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows (PowerShell):**

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

After install, open a new terminal and confirm:

```bash
uvx --version
```

## Preferred setup (dashboard)

1. In the Compethic dashboard: **Settings → Data Analysis → MCP**.
2. **Create client** — read-only scopes are applied by default. The secret is shown **once**.
3. Click **Add to MCP** (Cursor / generic hosts) or **Add to Claude** (inner entry for merging).
4. Restart the MCP connection in that host.

If the secret is lost, revoke the client and create a new one. The hashed secret cannot be shown again.

## Manual host config

Use gateway-client credentials from the dashboard. Set **`DATALAYER_API_URL`** to `https://api.compethic.no` (no trailing slash).

Args use **`compethic-mcp`** without a version pin so `uvx` resolves the latest release on PyPI.

### Claude Desktop

Edit `claude_desktop_config.json` and add the `compethic` entry under `mcpServers`:

```json
{
  "mcpServers": {
    "compethic": {
      "command": "uvx",
      "args": ["compethic-mcp"],
      "env": {
        "DATALAYER_API_URL": "https://api.compethic.no",
        "COMPETHIC_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "COMPETHIC_CLIENT_SECRET": "ce_live_..."
      }
    }
  }
}
```

If you already have other servers, merge only the `compethic` object into your existing `mcpServers` block — do not nest a second `mcpServers` key.

### Cursor (and other stdio hosts)

`.cursor/mcp.json` (or equivalent) — include `"type": "stdio"` so URL-based defaults do not override the command:

```json
{
  "mcpServers": {
    "compethic": {
      "type": "stdio",
      "command": "uvx",
      "args": ["compethic-mcp"],
      "env": {
        "DATALAYER_API_URL": "https://api.compethic.no",
        "COMPETHIC_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "COMPETHIC_CLIENT_SECRET": "ce_live_..."
      }
    }
  }
}
```

Do not put a personal session token or service key in these files.

## Environment

| Variable | Required | Notes |
|---|---|---|
| `DATALAYER_API_URL` | yes | `https://api.compethic.no` (no trailing slash). |
| `COMPETHIC_CLIENT_ID` | yes | UUID from **Create client** in the dashboard. |
| `COMPETHIC_CLIENT_SECRET` | yes | Must start with `ce_live_`. |
| `COMPETHIC_HTTP_TIMEOUT_SECONDS` | no | Default `30`. |
| `COMPETHIC_TOKEN_REFRESH_SKEW_SECONDS` | no | Default `60`. Remint when `exp - skew` has passed. |
| `COMPETHIC_MCP_CATEGORIES` | no | Comma-separated subset of `org,entities,taxonomy,feedback,analytics,customers,nps,summaries`. Unset = all 8. |

## Transport

Hosts spawn **`uvx compethic-mcp`** as a stdio subprocess with the env vars above. Use the JSON config blocks in this README or the dashboard copy buttons — do not paste stdio JSON into a URL-only MCP field.

## Tools (11)

`org_get`, `entities_list`, `taxonomy_list`, `taxonomy_mentions`, `feedback_list`, `feedback_aggregates`, `analytics_get`, `customers_list`, `customers_churn`, `nps_get`, `summaries_get`.

OAuth, writes, and internal admin surfaces are not exposed through this server.

## Smoke

After wiring, call `org_get` with `view=info`, then `taxonomy_list` with `type=strategic-themes`.
