# datahub-cm-mcp

Read-only **Cloudera Manager metrics** for a **CDP Public Cloud DataHub**, over Knox.
Sibling to `cdp-pc` in this suite — a *separate process with its own auth plane*
(the suite's design rule). Where `cdp-pc` is the **control plane** (list/describe via
the `cdp` CLI + `~/.cdp` API key), this is the **data plane**: each DataHub's own
Cloudera Manager, read via `cdp-proxy-api/cm-api` with **workload user + password**.

> Why this exists: in CDP Public Cloud **every DataHub runs its own Cloudera Manager**,
> reachable through Knox. So "CM = private-cloud only" is not true for PC. This MCP
> turns the infra team's manual `top` / `free` / `df` round into natural-language questions.

## Tools (all read-only, GET only)

| Tool | Answers | CM source |
|---|---|---|
| `datahub_host_status(cluster_name)` | per-host cores, RAM, health, roles | `/hosts?view=full` |
| `datahub_resource_usage(cluster_name, hours=1)` | per-host **CPU% + memory%** (latest) — the `top`/`free` replacement | `/timeseries` cpu_percent, physical_memory_used/total |
| `datahub_disk_usage(cluster_name)` | per-filesystem **capacity/used/%** — the `df` replacement | `/timeseries … WHERE category=FILESYSTEM` |
| `datahub_metric_timeseries(cluster_name, metric, hours=3)` | per-host trend for one whitelisted metric (spikes) | `/timeseries SELECT <metric>` |

`cluster_name` comes from `cdp-pc`'s `list_datahubs`. The CM endpoint is **auto-discovered**
from `describe-cluster` (no registry table).

## Auth (how credentials are given)

- **Discovery** (control plane): `cdp datahub describe-cluster` → reads the `CM-API`
  endpoint URL. Reuses `~/.cdp/credentials`.
- **CM REST** (data plane): HTTP Basic over Knox = **CDP workload username + workload password**
  (Knox mode `PAM`). Username: `CDP_WORKLOAD_USER` env, else `cdp iam get-user`
  `workloadUsername`, else `$USER`. Password: `CM_PASSWORD` / `CDP_WORKLOAD_PASSWORD`
  env, else macOS Keychain (`account=zzeng`, `service=cdp-workload-impala`).
  **No password is stored on disk.**
- TLS verified by default; `CM_INSECURE=true` to skip (corp MITM).

## Setup

```bash
cd tools/datahub-cm-mcp
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt   # minimcp + mcp<2
# workload password already in Keychain? (shared with Impala)
security find-generic-password -a zzeng -s cdp-workload-impala -w >/dev/null && echo "pw ok"
```

Register into Claude (from the suite): `tools/cdp-pc-mcp/register-all.sh` already lists
`datahub-cm`. Or manually:
```bash
claude mcp add datahub-cm -e "PYTHONPATH=$PWD/src" -- "$PWD/.venv/bin/python" -m datahub_cm_mcp.stdio_main
```

## Smoke test (no Claude)

```bash
export PATH="$HOME/.local/bin:$PATH"   # cdp CLI
PYTHONPATH=src .venv/bin/python -c "
from datahub_cm_mcp import cm
import json; print(json.dumps(cm.resource_usage('zzengaws732-dm'), indent=2, ensure_ascii=False))"
```
Expected: per-host `cpu_pct` / `mem_pct` from live Cloudera Manager.

Demo talk track (JP, copy-paste): `demo-scenario-jp.md`.

## Notes / limits

- Prereq: the DataHub (and its environment) must be **AVAILABLE**. Stopped → discovery
  errors clearly (no CM-API endpoint).
- The CM `/clusters` list can be empty through the PC Knox proxy; all tools here work at
  **host level**, which is what infra monitoring needs.
- Read-only: no config-change / command tools. Adding those would need a deliberate,
  separately-scoped write plane.