# cfm-dwh-mcp

Python MCP server for Coffeemania DWH: lets an LLM client query ClickHouse `analytics` tables (read-only).

Linear: **NIK-15** (scaffold), **NIK-16** (auth/guards), **NIK-17** (query tools), **NIK-26** (Docker).

Stack: Python 3.11+ / [FastMCP](https://gofastmcp.com/) / clickhouse-connect.

## Setup

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env
# fill host, port, database, user, password
```

## Start / stop

MCP over stdio (Cursor / Claude Desktop / etc.):

```bash
cfm-dwh-mcp
# or: python -m cfm_dwh_mcp.server
# stop: Ctrl+C
```

Optional HTTP healthcheck:

```bash
cfm-dwh-mcp-health
curl -s http://127.0.0.1:8787/health
```

## Docker

Runs `cfm-dwh-mcp-health` (HTTP on 8787) against **existing** ClickHouse. This compose file does **not** start ClickHouse or Qwen.

```bash
cp .env.example .env
# fill host, port, database, user, password
# if ClickHouse is on the Docker host, use host=host.docker.internal (not localhost)

docker compose up --build
# logs should show: health listening on http://0.0.0.0:8787/health
curl -s http://127.0.0.1:8787/health

docker compose down
```

Credentials come from `.env` (`env_file` + read-only mount). They are not baked into the image.

Stdio MCP (`cfm-dwh-mcp`) is for a local MCP client, not the Compose service.

## Config

Loaded from `.env` (exact lowercase keys; `CLICKHOUSE_*` aliases also work). Never commit `.env`.

| Key | Meaning |
| --- | --- |
| `host` | ClickHouse host |
| `port` | HTTP port (usually `8123`) |
| `database` | default `analytics` |
| `user` | CH user |
| `password` | CH password |

## Allowlist (NIK-17)

- `analytics.f_kafka_mobile_events`
- `analytics.f_logistics`

## Verify

1. Fill `.env`
2. `cfm-dwh-mcp-health` then `curl -s http://127.0.0.1:8787/health`
3. Point your MCP client at `cfm-dwh-mcp`; tools should include `ping` and `list_allowed_tables`. `query_clickhouse` is a stub until NIK-17.