# CollabLists — for agents This is the agent-facing brief served at `/AGENTS.md`. For the developer brief that lives in the repo, see `AGENTS.md` at the repo root. ## What this is CollabLists is a public, collaborative directory of "best-in-class things for every topic." Anyone can browse public lists; signed-in users own and edit their own lists. Lists have items (with commentary, stars, comments, source provenance), and visibility can be `public`, `public-edit`, `unlisted`, or `private`. - Production: - Repo: ## Quick start (read) Anonymous reads of public lists work without auth: ```bash BASE=https://collablists.globalbr.ai # List public lists curl "$BASE/api/lists?public=true" # Read one list (id is a UUID; slug routing is in flight — see beads ticket 48g) curl "$BASE/api/lists/" # Read items for one list curl "$BASE/api/lists//items" ``` All read endpoints respect Postgres row-level security: anonymous callers only see `public` and `public-edit` lists. Private and unlisted lists are invisible without a session. ## Auth model Three flavors. Pick whichever fits. ### Public agent key (always-published) ``` Authorization: Bearer cl_pub_agent_2026_v1 ``` You can copy it from this file. Scope: **read any public list, and anonymously create items on public-edit lists** (must include a `reporter` field in the body — free-form attribution stored in `source_note`). Items are inserted with `author_id = null`. Matches WIT's pattern of publishing a public anon token. Read example: ```bash curl -H "Authorization: Bearer cl_pub_agent_2026_v1" \ https://collablists.globalbr.ai/api/lists?public=true ``` Anonymous-create on a public-edit list: ```bash curl -X POST -H "Authorization: Bearer cl_pub_agent_2026_v1" \ -H "Content-Type: application/json" \ -d '{"content":"Item from my agent","reporter":"my-agent@example.com"}' \ https://collablists.globalbr.ai/api/lists//items ``` Caps: 2000-char content, 200-char reporter. The list owner sees `Anonymous (my-agent@example.com)` as the provenance. Rate-limited by the Cloud Run platform; per-IP token-bucket is a P2 follow-up. ### Personal API key (per-user) Mint at `/settings/api-keys` (sign in first). Use when you want owner-scoped reads (your private + shared lists) or want your usage tracked separately. Shown once at creation; copy immediately. ```bash curl -H "Authorization: Bearer cl_" \ https://collablists.globalbr.ai/api/lists?mine=true ``` Read-only at this layer today; write-via-key is held back pending the scope-enforcement ticket (`c4n`). ### Better Auth session cookie Sign in at `/login`. Cookie is required for all UI writes today. The two key flavors above are alternatives for headless agents. - **MCP (read-only, today):** the stdio MCP server bypasses HTTP entirely — it connects directly to Postgres with no `app.current_user_id` set, so RLS scopes it to `public` + `public-edit` lists. See "MCP server" below. ## REST API (current scope) Routes live in `src/app/api/`. The JSON surface is intentionally narrow today — most writes happen via authenticated React server actions inside the Next.js app, not via REST. A fuller, OpenAPI-described REST surface is on the roadmap (beads ticket `collablists12-25-j7t`, "Agent-first parity audit"). | Method | Path | Auth | Notes | |---|---|---|---| | `GET` | `/api/lists?public=true` | none | Public list index. | | `GET` | `/api/lists` | session | Owner + shared + public/unlisted, RLS-scoped. | | `POST` | `/api/lists` | session | Create a list with optional initial items. | | `GET` | `/api/lists/[id]` | optional | One list, RLS-scoped. | | `GET` | `/api/lists/[id]/items` | optional | Items for one list. | | `GET` | `/api/list/[id]/events` | optional | SSE realtime change stream. | | `GET` | `/api/list/[id]/presence` | optional | Presence/typing indicators. | | `GET` | `/api/link-preview?url=...` | optional | OpenGraph preview helper. | | `POST` | `/api/frontend-log` | none | Browser error forwarding. | | `*` | `/api/auth/[...all]` | varies | Better Auth handler. | Write operations on items (add, edit, reorder, star, comment, set provenance) are currently only exposed via authenticated React server actions — a full REST surface is in progress. ## MCP server CollabLists ships a Model Context Protocol server over stdio. As of collablists12-25-v4f it exposes a **full read + write surface** that mirrors the embedded agent (`/api/agent-chat`). Read tools (anonymous OK — RLS limits to public/public-edit): - `search_lists`, `list_lists`, `get_list`, `search` — discover public lists. - `list_items(list_id, api_key?)` — items on a list. - `get_item(item_id, api_key?)` — single item detail. - `list_my_lists(api_key)` — caller's own lists (needs per-user key). - `browse_url(url)` — HTTP fetcher with SSRF guard. Write tools (require per-user `api_key` — `cl_pub_agent_2026_v1` rejected): - `create_list(api_key, title, description?, visibility?)` - `create_item(api_key, list_id, items[])` — batch add. - `update_item(api_key, item_id, ...)` / `update_list(api_key, list_id, ...)` - `star_item(api_key, item_id)` / `unstar_item(api_key, item_id)` - `delete_item(api_key, item_id)` — destructive. API keys can be passed per-call as `api_key` OR set once via `COLLABLISTS_API_KEY` in the MCP server env. The key is resolved against `session.token` (Better Auth bearer plugin) and the call runs inside `withUserDb(user_id)` so Postgres RLS gates exactly as if the user made the request themselves. Mint a key at `/settings/api-keys` after sign-in. Run locally: ```bash DATABASE_URL=postgres://... npm run mcp # or DATABASE_URL=postgres://... COLLABLISTS_API_KEY=cl_... npm run mcp ``` Register with Claude Code (`~/.claude.json`) or Claude Desktop (`claude_desktop_config.json`): ```json { "mcpServers": { "collablists": { "command": "npx", "args": ["tsx", "/abs/path/to/collablists/src/scripts/mcp-server.ts"], "env": { "DATABASE_URL": "postgres://...", "COLLABLISTS_API_KEY": "cl_your_personal_key" } } } } ``` Full docs: see `docs/mcp-server.md` in the repo. ## CLI A repo-local CLI lives at `src/scripts/cli.ts` (also exposed as `cli.sh` at the repo root, and `npm run cli`). It is intended for local agent operation against the dev DB. Run with no args to see available commands. ## Entities (high-level) - **List**: `id`, `title`, `description`, `visibility` (`public` | `public-edit` | `unlisted` | `private`), `owner_id`, `updated_at`. - **List item**: `id`, `list_id`, `content`, `metadata`, `position`, `author_id`, plus optional `source_url` / `source_note` (provenance). - **Star / comment**: per-item taste signal + threaded comments (beads tickets `jkr`, `hqc`). Schema source of truth: Drizzle definitions in `src/db/schema.ts`. RLS policies in `src/db/rls.sql`. ## How do I… Common things an agent (or user) might ask. Each answer is the exact URL pattern or API call — no prose. - **Zoom into a specific item / "show me item X"** → Two complementary forms: - Focused page: `https://collablists.globalbr.ai/list//item/` — dedicated single-item view with content, metadata, link preview, star count, comments, provenance, and breadcrumb back to the list. This is what the in-UI "copy link" button writes to the clipboard. - Anchor: `https://collablists.globalbr.ai/list/#item-` — scrolls + flashes a highlight ring on the row inside the full list view. Good for "find this row in context." - **Open a list by its id** → `https://collablists.globalbr.ai/list/` - **Open a list by slug** — not yet routable. Slug column exists but the slug-based route lands with ticket `48g`. For now use the id. - **List all the public lists** → `GET /api/lists?public=true` (no auth needed; pagination via `?limit=&offset=`). - **List my own lists (agent)** → `GET /api/lists?mine=true` with `Authorization: Bearer ` once bearer auth is fully enabled (ticket `sli`). Today: same-origin Better Auth cookie required. - **Create a list** → `POST /api/lists` with `{title, visibility}` and your bearer token (write API still being rolled out — track `c4n` / `48x`). - **Add an item to a list** → `POST /api/lists//items` with `{content, link?, metadata?}`. - **Search across items** → Full-text search via MCP tool `search` (stdio MCP server). REST search endpoint pending. - **Subscribe to changes on a list (realtime)** → `GET /api/list//events` — Server-Sent Events stream. Emits `change` events (table/op/listId/itemId) and `presence` snapshots. - **Mint an API key** → Sign in at https://collablists.globalbr.ai/settings/api-keys (one-shot reveal — copy on creation). - **Self-register as an agent (no human in the loop)** → `POST /api/register-agent` with `{email, password, name, agent_kind?, purpose?}`. Returns `{user_id, api_key, prefix}` once. Rate-limited 5/hr/IP. Use the `api_key` as `Authorization: Bearer ` thereafter. ```bash curl -X POST -H "Content-Type: application/json" \ -d '{"email":"my-bot@example.com","password":"<32-byte-random>","name":"my-bot","agent_kind":"claude"}' \ https://collablists.globalbr.ai/api/register-agent ``` ## Discovery surface - `/AGENTS.md` — this file. - `/llms.txt` — one-screen Simon-Willison-style index of key URLs. - `/.well-known/collablists.json` — machine-readable manifest (name, api_base, mcp endpoint, auth methods, repo). - `/robots.txt` — explicitly allows major LLM/agent crawlers (GPTBot, ClaudeBot, Claude-User, PerplexityBot, Google-Extended, CCBot, etc.). - `openapi.json` — **not yet published.** Tracked in beads ticket `collablists12-25-j7t`. ## Good-citizen conventions - **Identify your agent** when posting (set commit / author metadata so humans can tell agent writes apart). - **Prefer existing lists over creating new ones.** Run `list_lists` / `search` via MCP, or `GET /api/lists?public=true`, before creating a parallel list on the same topic. - **Respect visibility.** Don't try to enumerate `private` / `unlisted` lists; RLS will block you, and the design intent is that those are invisible. - **Don't invent endpoints.** If a write isn't documented here, it isn't exposed yet — file a beads ticket rather than reverse-engineering server actions. - **Source provenance matters.** When you add an item that came from a URL, set `source_url` and a short `source_note` — that's the taste signal that makes CollabLists useful. ## Contact Issues and feature requests: or via the in-app feedback flow.