Metadata-Version: 2.5
Name: compethic-mcp
Version: 0.1.0
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 datalayer. It is not the in-app agent (`compethic-agent`). Tools mint a gateway-client JWT and call product GETs with `organization_id` taken from that JWT.

## Preferred setup

1. In the dashboard: **Settings → Data Analysis → MCP**.
2. **Create client** (viewer, `feedback:read` / `taxonomy:read` / `org:read`). The secret is shown **once**.
3. **Add to Cursor** or **Add to Claude** copies stdio JSON. Replace `<path-to-apps/compethic-mcp>` with the absolute path to this directory.
4. Restart the host's MCP process.

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

## Environment

| Variable | Required | Notes |
|---|---|---|
| `DATALAYER_API_URL` | yes | Copied from the dashboard's `VITE_DATALAYER_URL` (no trailing slash). Local default is `http://localhost:8000`; staging URLs are valid because MCP is a local process, not a browser. |
| `COMPETHIC_CLIENT_ID` | yes | UUID from create-client. |
| `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. `chatbot`, `voice`, `keywords`, `competitors`, `severity` are not legal names. |

Do not put a human Supabase JWT or `X-Service-Key` in mcp.json.

## Transports

stdio is the default and what the copy buttons emit. Cursor JSON includes `"type": "stdio"` so a URL-default form cannot swallow it. Claude Desktop JSON is the same command/args/env **without** `type`.

```bash
uv run --directory /absolute/path/to/apps/compethic-mcp compethic-mcp
```

`compethic-mcp --http` serves Streamable HTTP on `127.0.0.1:8765/mcp` for a local URL-only adder. You start that process yourself; credentials still come from process env, not request headers. There is no hosted MCP URL in v1. Do not paste stdio JSON into a Server URL 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`.

Not included: OAuth, writes, HITL, `/internal/*`, analysis jobs, chatbot analytics, voice analytics, competitors, severity / industry-risk, keywords ranking, CLTV, upsell. `chatbot` and `voice_calls` remain legal **source_category** filters. Keyword *definitions* stay on `taxonomy_list`. Churn `issue-severity-counts` stays on `customers_churn`.

## Smoke

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

## Dev

```bash
uv sync --group test
uv run pytest tests/ -q
uv run ruff check .
```

Optional toolset: `COMPETHIC_MCP_CATEGORIES=nps,summaries` loads only those categories.
