# tribe-mcp

Standalone MCP server that exposes **TRIBE** brand data — neural fingerprints,
organic posts, and brands — from a [Turso](https://turso.tech) (libsql) database to
MCP clients like Claude. Lets you do brand-grounded analysis over real data. No app
or dashboard required; it only needs a Turso DB with the expected tables.

## Tools

| Tool | What it does |
|---|---|
| `list_brands` | Discover brand IDs to use with the other tools. |
| `list_fingerprints` | List TRIBE fingerprints (filter by brand / label). |
| `get_fingerprint` | Pull a full fingerprint with channels + timeline by ID. |
| `compare_fingerprints` | Pull two fingerprints side-by-side for A/B analysis. |
| `list_organic_posts` | List Instagram + TikTok posts logged for a brand. |
| `get_organic_post` | Pull a single organic post with its retention curve. |
| `write_insight` | Persist an analysis back to the DB so other tools/UIs can read it. |

## Setup

Requires Node 18+ and a Turso database (the tables are defined in `src/db.ts`).

```bash
git clone https://github.com/<you>/tribe-mcp.git
cd tribe-mcp
npm install
cp .env.example .env          # fill in TURSO_DATABASE_URL + TURSO_AUTH_TOKEN
npm run build
```

Smoke-test:

```bash
TURSO_DATABASE_URL=... TURSO_AUTH_TOKEN=... npm start
# prints "tribe-mcp ready (stdio)" then waits for MCP messages; Ctrl-C to exit.
```

## Connect to Claude

**Claude Code** (available in every project):

```bash
claude mcp add tribe -s user \
  -e TURSO_DATABASE_URL="libsql://<your-db>.turso.io" \
  -e TURSO_AUTH_TOKEN="<your-token>" \
  -- node /ABSOLUTE/PATH/TO/tribe-mcp/dist/index.js
```

**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tribe": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/tribe-mcp/dist/index.js"],
      "env": {
        "TURSO_DATABASE_URL": "libsql://<your-db>.turso.io",
        "TURSO_AUTH_TOKEN": "<your-token>"
      }
    }
  }
}
```

Restart the client; the `tribe` tools appear in conversation.

## The model (Modal) — `modal_app.py`

`modal_app.py` is the inference backend that **produces** the fingerprints this MCP
reads. It runs **Meta FAIR's TRIBE v2** brain-encoding pipeline on a Modal GPU:

```
video URL / upload
  → yt-dlp + ffmpeg
  → V-JEPA2 (video) + Wav2Vec2 (audio) + LLaMA (transcript text)  features per fMRI TR
  → TRIBE v2 brain encoder → Schaefer-400 / 7-network parcel time-series (T × 400)
  → reduce to 9 channels + global stats + nilearn 3D brain + Whisper transcript
  → Fingerprint JSON  (stored in Turso → served by this MCP)
```

Endpoints (deployed at `https://<workspace>--api.modal.run`): `POST /start` → `job_id`,
`GET /poll?job_id=…` → `running|complete|error`, `GET /health`, plus `/serve_brain`,
`/serve_video`, `/predictions`.

### Deploy

```bash
pip install modal && modal token new          # one-time
# optional Bearer auth (recommended for a public endpoint):
modal secret create tribe-api-key TRIBE_API_KEY="$(openssl rand -base64 32)"
modal deploy modal_app.py
curl https://<workspace>--api.modal.run/health   # {"status":"ok","atlas":"schaefer_400_7networks_v1",...}
```

### TRIBE weights

Set `TRIBE_CKPT` (a path baked into the image or on the mounted Volume) to Meta's
trained TRIBE v2 brain-encoder checkpoint. **Without it, a deterministic placeholder
encoder runs** so the whole app is end-to-end testable — its numbers are structurally
valid but **not** real brain predictions.

> ⚠️ **Reconstruction + license.** The original `tribev2-by-meta/modal_app.py` was lost;
> this file is reconstructed from the dashboard's exact API contract + design doc — the
> serving contract and feature pipeline are faithful; supply the checkpoint for real
> predictions. **TRIBE v2 is CC BY-NC (research only)** — this wrapper is MIT, but the
> model weights are not; don't ship client-facing deliverables from its outputs without
> a commercial license from Meta.

## License

MIT — see [LICENSE](LICENSE). (Applies to this wrapper code, not the TRIBE v2 weights.)