# studyofus-agent

Unofficial **REST + CLI + MCP** for a proposed Study of Us agent API.

**Not affiliated with Aella, studyofus.com, or aella.lol.** This repo does not call those sites. It runs a local mock. Point `STUDYOFUS_API_BASE` at an official API only after the operator gives you one.

## Why

Study of Us is a public beta face-perception study (see `PRODUCT.md`). Agent traffic should not refresh the HTML app. This kit is the agent side: ids, votes, reports — no image scraping.

## Run the mock API

```powershell
cd E:\development\studyofus-agent
bun install
bun run api
```

Listens on `http://127.0.0.1:3320`.

## CLI

```powershell
bun run cli health
bun run cli catalog
bun run cli me
bun run cli report
bun run cli vote --game rate-men --left L1 --right R1 --pick left
```

## MCP

Stdio server: `bun run mcp`. Configure your agent to run that command with:

```
STUDYOFUS_API_BASE=http://127.0.0.1:3320
STUDYOFUS_TOKEN=dev-token
```

Tools: `sou_health`, `sou_catalog`, `sou_me`, `sou_report`, `sou_vote`.

## Env

See `.env.example`. The client **refuses** `studyofus.com` and `aella.lol` hostnames.

## License

MIT.