dc

# DC Member API Skill

Read and act on your own Dynamite Circle membership data via the public DC
Member API at `https://api.dynamitecircle.com` — your profile, trips, events,
tickets, invites, inbox, rooms, chapters, announcements, and locator digest.
Reads and writes are always scoped to **you** (the owner of the API key).

There are two ways to use it, and **one of them needs nothing installed**:

| Path | What it is | Pick it when |
|---|---|---|
| **Local client** (this file) | One stdlib-only Python file: a CLI (`dc …`), a Python library (`from dynamitecircle import DC`), and a local stdio MCP server (`dc --mcp`) | You're an agent that can run Python or shell — you get a CLI, scriptable library calls, and a local server you can pin/run offline |
| **Hosted MCP** | A remote MCP endpoint: `https://api.dynamitecircle.com/mcp` (Streamable HTTP) | You're an MCP-capable chat app and want zero install + always-current tools (no updates to manage) |

**Rule of thumb for an agent:** if you can execute commands, prefer the local
client (richest: CLI + library + MCP, works offline, version-pinnable). If
you're a hosted assistant that only speaks MCP, use the hosted URL. Both
authenticate with the same `dk_` key.

## Install the local client

Three ways to get the client, from quickest to most isolated:

```bash
# A) PyPI — quickest. Gives you the `dc` command + the importable library.
pip install dynamitecircle            # CLI + library
pip install 'dynamitecircle[mcp]'     # + local MCP server (dc --mcp)

# B) uvx — no install, auto-updates on every run (great for an MCP config)
uvx --from 'dynamitecircle[mcp]' dc --help

# C) Clone — full repo (MCP config, docs, vendor via submodule/subtree)
git clone https://github.com/dynamitecircle/dc.git && cd dc
```

> **Command form in this doc:** examples use the installed `dc` command. From
> a clone, replace `dc` with `python3 py/dc.py` (e.g. `python3 py/dc.py profile`).

## Setup (get + save your key)

Each member needs their own personal API key. Generate one from the DC
profile dropdown → **DC Member API Key**. Keys look like `dk_<api-key>` and
are revocable from the same dropdown.

```bash
# Save it (writes .env.dc next to the client, chmod 600, gitignored)
dc setup --api-key dk_<api-key>

# Verify env, key shape, a live /profile call, and MCP schemas — all green
dc self-test
```

`self-test` should end with `connected as userID[<id>] <Your Name>`.

Alternatively, set `DC_API_KEY` in the environment instead of running `setup`
— an explicit env var always wins over `.env.dc`. This is how the hosted MCP
and ephemeral `uvx` installs receive the key (e.g. the `env` block of an MCP
server config).

## Discovering endpoints

You don't need to memorize the surface — discover it live:

```bash
# Every command + a one-line description
dc help

# Full detail for one command (flags, args, examples)
dc help trips

# Machine-readable recipes: ordered {method, path} steps for common goals
# (who's in <city>, plan together at an event, find DCers by description,
# manage inbox, refresh profile…). Best first call for an unfamiliar agent.
dc workflows
```

Authoritative references:

- **`https://www.dynamitecircle.com/developers/`** — full human reference, every endpoint/param/response, regenerated on every deploy (always current)
- **`https://api.dynamitecircle.com/openapi.json`** — the OpenAPI spec (machine-readable)
- **`https://api.dynamitecircle.com/.well-known/mcp.json`** — MCP discovery descriptor (transport, auth, install)

> **~80 commands.** That's a lot to scan, and some MCP clients cap how many
> tools they load. Don't read them all — call **`dc workflows`** first to get
> the handful of ordered recipes for common goals, then `dc help <command>`
> for the specific ones you need.

### Read vs. write (MCP annotations)

Every MCP tool is annotated: reads carry `readOnlyHint: true`; writes carry
`readOnlyHint: false` (and `destructiveHint: true` for `trip_delete`), plus a
"⚠️ Write operation" note in the description. Reads (`profile`, `trips`,
`search`, …) are safe to run freely; writes (`trip_create`, `profile_update`,
`event_rsvp`, …) mutate **your** account. Clients that honor annotations can
auto-approve reads and prompt on writes.

## Pagination

Every list-returning command takes the same cursor pagination flags:

```bash
<command> [--limit N] [--cursor TOKEN]
```

- `--limit N` — page size (1-100; default varies by endpoint)
- `--cursor TOKEN` — opaque continuation token from the previous response

Responses are wrapped in the standard envelope:

```json
{
  "items":    [...],
  "count":    42,
  "cursor":   "opaque-token-or-null",
  "has_more": true
}
```

Any non-paginated extras the API returned (e.g. `totalUnread` on `inbox`)
are passed through under an `extra` key.

## Output formats

```bash
dc profile             # text (pretty JSON)
dc profile --json      # explicit JSON
dc profile --python    # Python repr
dc --format python profile
```

## Version warnings

Every API response carries an `X-API-Version` header. The skill compares
it against its own `DC_API_VERSION` constant. When the **server's major or
minor** is ahead of the skill, you'll see a one-shot warning on stderr
prompting you to update:

```
⚠  DC API has new features available (server 1.3.0, this skill built for 1.2.0).
   Update the dc client: cd <your dc clone> && git pull
```

Patch differences (e.g. server 1.2.5 vs skill 1.2.0) are silent — they're
bug fixes only. The warning fires once per process so it doesn't spam
script users.

## Local development

Override the API base URL to test against a local server (e.g. when
running the API on `localhost:8083`):

```bash
# CLI
dc --api-url http://localhost:8083 profile

# Python
DC(api_url="http://localhost:8083")
```

## Commands

### Setup & diagnostics

```bash
# Save your DC API key to .env.dc
dc setup --api-key dk_<api-key>

# Validate env, network, and /profile end-to-end
dc self-test

# Machine-readable recipes — orde