# CHEQ Ticket Intelligence MCP

Local setup instructions for the customer-support ticket MCP server.

## Requirements

- macOS or Linux.
- [uv](https://docs.astral.sh/uv/getting-started/installation/). The project uses
  Python 3.12 from `.python-version` and supports Python 3.11-3.13.
- An OpenAI Platform API key with embedding access.
- Codex CLI and/or Claude Code CLI.
- Network access and at least 2 GB of free space for dependencies, the dataset
  cache, and about 891 MB of generated SQLite/LanceDB artifacts.

`uv sync --locked` installs the locked runtime packages: `datasets`, `lancedb`,
`mcp`, `openai`, `pyarrow`, and `pydantic`. It also installs the development
packages `pytest` and `mcp[cli]`.

## Dataset and license

This project uses the synthetic
[Customer Support Tickets](https://huggingface.co/datasets/Tobi-Bueck/customer-support-tickets)
dataset by Tobi Bueck. Ingestion is pinned to the `train` split at revision
`ddf1c81a5475992c4fa6752bf1e8b4e31f07bbeb`, which contains 61,765 tickets.

The dataset is licensed under
[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/). Its use is
limited to non-commercial purposes and requires attribution. This dataset
license is separate from the repository's MIT code license. The repository does
not redistribute the source dataset or generated SQLite, LanceDB, or embedding
artifacts; the documented ingestion command builds them locally from the pinned
source.

## 1. Install

Install `uv` if needed:

```bash
# macOS
brew install uv

# Or macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

From a fresh clone:

```bash
git clone https://github.com/GalDaich/cheq-cs-tickets-mcp.git
cd cheq-cs-tickets-mcp
uv sync --locked
```

## 2. Configure the API key

This server uses OpenAI `text-embedding-3-large` for ticket and query embeddings
only. Codex or Claude Code selects the MCP tool and writes the final answer.

The only environment variable is `OPENAI_API_KEY`. It is required for ingestion
and semantic search. Exact analytics and ticket lookup remain local after the
data has been built.

Create the ignored local environment file and add the key:

```bash
cp .env.example .env.local
chmod 600 .env.local
${EDITOR:-vi} .env.local
```

`.env.local` should contain:

```dotenv
OPENAI_API_KEY=your_openai_api_key
```

Never commit `.env.local` or place the API key directly in an MCP registration
command.

## 3. Build the local data

The first build downloads the pinned 61,765-row dataset and creates the local
SQLite and LanceDB artifacts. Embedding the dataset uses the OpenAI API and may
incur cost.

```bash
set -a
. ./.env.local
set +a
uv run --locked cheq-tickets-ingest
```

If the local artifacts are stale or incompatible, rebuild explicitly:

```bash
uv run --locked cheq-tickets-ingest --rebuild
```

## 4. Run the server directly

```bash
set -a
. ./.env.local
set +a
uv run --locked cheq-tickets-mcp
```

A silent, blocked process is expected: stdio is the MCP protocol transport. Stop
the direct process with `Ctrl-C`; normally Codex or Claude Code starts it.

## 5. Connect Codex CLI

Run from the repository root. The saved command uses absolute paths and loads
`.env.local` without copying its values into Codex configuration.

```bash
PROJECT_ROOT="$(pwd)"

codex mcp add cheq-tickets -- \
  /bin/sh -c "set -a; . \"$PROJECT_ROOT/.env.local\"; set +a; exec \"$PROJECT_ROOT/.venv/bin/cheq-tickets-mcp\""

codex mcp get cheq-tickets --json
codex mcp list
```

Start a new `codex` session and run `/mcp` to confirm that `cheq-tickets` exposes
`search_tickets`, `analyze_dataset`, and `get_ticket`. See the official
[Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

## 6. Connect Claude Code CLI

Run from the repository root. Local scope keeps the registration private to the
current user and project.

```bash
PROJECT_ROOT="$(pwd)"

claude mcp add --transport stdio --scope local cheq-tickets -- \
  /bin/sh -c "set -a; . \"$PROJECT_ROOT/.env.local\"; set +a; exec \"$PROJECT_ROOT/.venv/bin/cheq-tickets-mcp\""

claude mcp get cheq-tickets
claude mcp list
```

Start a new `claude` session and run `/mcp` to confirm the three tools. See the
official [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).

## 7. Verify

In either connected host, ask:

> How many tickets are in the pinned dataset, grouped by language?

The counts should total `61,765`. Then verify semantic search:

> Find three tickets about VPN connection failures and cite each TKT ID.

For local deterministic checks:

```bash
uv run --locked pytest
```