Metadata-Version: 2.4
Name: dynamitecircle
Version: 1.9.1
Summary: Official Python client for the public Dynamite Circle Member API. CLI, library, Agent Skill, and MCP server in one file.
Project-URL: Homepage, https://github.com/dynamitecircle/dc
Project-URL: Repository, https://github.com/dynamitecircle/dc
Project-URL: Documentation, https://www.dynamitecircle.com/developers/
Project-URL: Changelog, https://github.com/dynamitecircle/dc/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/dynamitecircle/dc/issues
Project-URL: Apply to DC, https://dc.dynamitecircle.com/account/apply?utm_medium=pypi&utm_source=dynamitecircle&utm_campaign=client-package
Author-email: Dynamite Circle <team@dynamitecircle.com>
License: MIT License
        
        Copyright (c) 2026 Dynamite Circle
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent-skills,dc,dcbkk,dcmex,dynamite-circle,events,mcp,membership
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Provides-Extra: mcp
Requires-Dist: mcp>=0.9.0; extra == 'mcp'
Description-Content-Type: text/markdown

# DC Official Client

The official Python client for the [Dynamite Circle Member API](https://www.dynamitecircle.com/developers/) — your own profile, trips, events, virtual events, tickets, invites, inbox, rooms, chapters, places lookup, and the weekly locator digest.

A single self-contained file. Zero dependencies (stdlib only). Works as a CLI, a Python library, **and** a [Model Context Protocol](https://modelcontextprotocol.io) server. Compatible with Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Cursor, GitHub Copilot, and every other Agent Skills / MCP-compatible tool.

```
py/dc.py    ← one file, three integration modes
```

## About the Dynamite Circle

The [Dynamite Circle](https://www.dynamitecircle.com/?utm_medium=github&utm_source=dc-official&utm_campaign=client-repo) is **the place where global founders find their people** — a curated, members-only community of location-independent business owners running profitable companies around the world. Founded in 2011 (it started with twenty listeners on a remote tropical island), the DC has grown into a hand-selected network of ~1,500 active founders who meet at vetted in-person events like [DCBKK](https://www.dynamitecircle.com/dcbkk/) and DCMEX, swap notes in private rooms, and travel through each other's home cities year-round.

DC is a private community, but it's open to applications from founders running location-independent businesses doing $100k+ in annual revenue. Every application is personally reviewed by a team member within 48 business hours — [start an application here](https://dc.dynamitecircle.com/account/apply?utm_medium=github&utm_source=dc-official&utm_campaign=client-repo&referrer=github.com) if that sounds like you.

## Quick Start

Never used Claude Code, Codex, or git? Here's the 5-minute path from zero to "Claude can read my DC profile."

### 1. Install the basics (one-time)

You need three free things on your computer:

- **Python 3.9+** — the language this client is written in. [Download here](https://www.python.org/downloads/) (Mac/Windows/Linux installers; check **"Add Python to PATH"** on Windows).
- **Git** — the tool that downloads code from GitHub. [Download here](https://git-scm.com/downloads).
- **An AI assistant** — pick one:
  - **[Claude Code](https://claude.com/product/claude-code)** ← *recommended* — this repo is built around it
  - **[Codex CLI](https://github.com/openai/codex)** — works too, slightly different commands
  - **[Claude Desktop](https://claude.ai/download)** — the chat app, gets you the MCP server but no CLI

If anything during install asks "do you want to add to PATH?" — say yes.

### 2. Get the code

Open a terminal:
- **Mac**: Spotlight → "Terminal"
- **Windows**: Start → "Terminal" (or "PowerShell")
- **Linux**: you know what to do

Then paste:

```bash
git clone https://github.com/dynamitecircle/dc.git
cd dc
```

You now have a folder called `dc` with all the code in it.

### 3. Get your DC API key

In your browser: go to **https://dc.dynamitecircle.com**, log in, click your profile photo (top-right), and choose **DC Member API Key**. Copy the long string starting with `dk_…`.

### 4. Tell the client about your key

Back in your terminal (still inside the `dc` folder):

```bash
python3 py/dc.py setup --api-key dk_paste_your_key_here
```

### 5. Try it

Open **Claude Code** and make sure it's pointed at the `dc` folder you just downloaded. (Claude usually opens to your last project — if it's somewhere else, click the folder icon and pick `dc`.)

Then ask:

> "Show me my DC profile"

Claude runs the right command and shows you back your profile. A few more to try:

> "What's the latest in DC announcements?"
> "What events am I attending?"
> "Show me the DCMEX schedule and bookmark anything about marketing"
> "Who else from my chapter is going to DCBKK?"

You're done. The rest of this README explains what's possible in more detail; [`py/SKILL.md`](py/SKILL.md) lists every command Claude can run.

### If something didn't work

| Symptom | What to try |
|---|---|
| `python3: command not found` | Python didn't install or didn't get added to PATH. Re-install and check the **"Add to PATH"** box on Windows; on Mac, try `python` instead of `python3`. |
| `git: command not found` | Same idea — re-install Git. |
| Claude says "I don't see a `dc` skill" | Make sure Claude Code is opened to the `dc` folder, not your home directory or another project. Or just ask Claude: *"are you in the dc folder?"* |
| Anything else | Run `python3 py/dc.py self-test` from the `dc` folder — it tells you exactly which step is broken. |

---

## How it's exposed

The same `dc.py` file is shipped as **four** integrations — pick whichever fits how your tool talks to it:

| Integration | What it is | Invoke with | Dependencies |
|---|---|---|---|
| **Agent Skill** | Auto-discovered via `SKILL.md` frontmatter (Claude Code, Codex, Gemini CLI, Cursor, Copilot) | Just open the repo with the tool — it reads [`py/SKILL.md`](py/SKILL.md) and offers the commands | stdlib only |
| **CLI** | Run commands directly from the shell or scripts | `python3 py/dc.py <command>` | stdlib only |
| **Python library** | Import in your own Python code | `from dc import DC; DC().profile()` | stdlib only |
| **MCP server** | Speaks Model Context Protocol over stdio (Claude Desktop, Cursor, Codex MCP, Cline, etc.) | `python3 py/dc.py --mcp` | `pip install mcp` (optional) |

The `mcp` package is **lazy-imported** — Agent Skill / CLI / Python-library users never need it.

## Features

- **Full Member API coverage** — read + write across every public endpoint (run `python3 py/dc.py help` for the live list)
- **Setup command** — saves your API key to a chmod-600 `.env.dc` next to the skill
- **Self-test command** — validates env, network, key shape, and a live `/profile` call end-to-end
- **Cursor pagination** — every list-returning command uses the same `[--limit N] [--cursor TOKEN]` shape and returns the canonical envelope `{items, count, cursor, has_more}`
- **Three output formats** — text (default, pretty JSON), `--json`, `--python`
- **MCP-ready** — same skill auto-exposes all commands as MCP tools
- **Pre-configured for Claude Code** — repo ships an `.mcp.json`, just `cd` and `claude`

## CLI quickstart (already comfortable in a terminal?)

If you're skipping past the [Quick Start](#quick-start) above and just want the CLI flow, here's the condensed version.

### 1. Get an API key

DC profile dropdown → **DC Member API Key** (admins/testers only). Keys look like `dk_<api-key>` and are revocable from the same dropdown.

### 2. Save the key

```bash
python3 py/dc.py setup --api-key dk_<api-key>
```

This writes `py/.env.dc` (chmod 600, gitignored).

### 3. Verify the connection

```bash
python3 py/dc.py self-test
```

Expected output:

```json
{
  "ok": true,
  "userID": "<your-id>",
  "displayName": "<Your Name>",
  "checks": [
    { "step": "env",      "ok": true, "message": "DC_API_KEY loaded from ..." },
    { "step": "keyShape", "ok": true, "message": "Key prefix valid (expected userID: <id>)" },
    { "step": "profile",  "ok": true, "message": "connected as userID[<id>] <Your Name>" }
  ]
}
```

### 4. Try a few commands

```bash
python3 py/dc.py profile
python3 py/dc.py trips --limit 5
python3 py/dc.py events --past --limit 3
python3 py/dc.py chapters --limit 5
python3 py/dc.py permacode
```

Run `python3 py/dc.py help` for the full command list.

## Setup per AI tool

### Claude Code

`.mcp.json` is already shipped with this repo. Open the repo with `claude`:

```bash
cd dc
claude
```

Tools become available as `mcp__dc__*`. First-time install of the optional MCP dependency:

```bash
pip install -r py/requirements.txt
```

Skill discovery (CLI + import) works automatically via `py/SKILL.md`.

### Claude Desktop

Edit your config file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "dc": {
      "command": "python3",
      "args": ["/absolute/path/to/dc/py/dc.py", "--mcp"]
    }
  }
}
```

Restart Claude Desktop.

### Codex CLI

Edit `~/.codex/config.toml`:

```toml
[mcp_servers.dc]
command = "python3"
args = ["/absolute/path/to/dc/py/dc.py", "--mcp"]
```

Codex auto-discovers `AGENTS.md` (symlinked to `CLAUDE.md`) and `.agents/skills/` (symlinked to `.claude/skills/`).

### Gemini CLI

Reads `GEMINI.md` (symlinked to `CLAUDE.md`) for context. For MCP, configure in your Gemini CLI settings:

```yaml
mcp_servers:
  dc:
    command: python3
    args:
      - /absolute/path/to/dc/py/dc.py
      - --mcp
```

### Cursor

Settings → MCP → Add server, then point at the same `dc.py --mcp`.

### GitHub Copilot

Reads `.github/copilot-instructions.md` for context. Copilot doesn't have native MCP support yet — use it for in-editor suggestions while developing.

### Any other MCP client

Same recipe: command = `python3`, args = `["/path/to/dc.py", "--mcp"]`. The protocol is standard.

## Output formats

```bash
python3 dc.py profile             # text (pretty JSON for dicts/lists)
python3 dc.py profile --json      # explicit JSON
python3 dc.py profile --python    # Python repr (eval-safe)
```

Global flags work before or after the command name:

```bash
python3 dc.py --json profile
python3 dc.py profile --json
```

## Cursor pagination

All list-returning commands take the same flags:

```bash
python3 dc.py trips
python3 dc.py trips --limit 10
python3 dc.py trips --limit 10 --cursor <opaque-token-from-previous-response>
python3 dc.py trips --past --limit 5
```

Standard envelope:

```json
{
  "items":    [ /* page of records */ ],
  "count":    42,
  "cursor":   "opaque-token-or-null",
  "has_more": true
}
```

Non-paginated extras (e.g. `totalUnread` on `inbox`) are passed through under an `extra` key.

## Use as a Python library

```python
import sys
sys.path.insert(0, "dc")
from dc import DC

dc = DC()

# Reads
profile  = dc.profile()
trips    = dc.trips(past=True, limit=10)
events   = dc.events(past=True, limit=5)
chapters = dc.chapters()
overlaps = dc.overlaps()
locator  = dc.locator(sections="homeCity,favoriteCities")

# Writes
dc.profile_update({"headline": "CEO at Acme"})
dc.trip_create(start_date="2026-12-01", end_date="2026-12-05", place_id="ChIJ...")
dc.event_rsvp("<eventID>", "yes")
dc.invite_create(email="new@friend.com", full_name="New Friend")
```

Override the API URL (e.g. for a local dev server):

```python
dc = DC(api_url="http://localhost:8080")
```

## API reference

The full live reference for the DC Member API — every endpoint, parameter, and response shape — is at **https://www.dynamitecircle.com/developers/**. The page is regenerated on every deploy, so it's always current.

## Staying up to date

The DC Member API ships new endpoints and refinements regularly. This skill is the official client and we update it whenever the API changes. **Plan for updates** — the skill will warn you on stderr the first time a request returns a server `X-API-Version` newer than `DC_API_VERSION`, and major-version bumps may break older clients.

Pick whichever integration style fits your project. From simplest to most isolated:

### 1. Plain git clone — quick local use

```bash
git clone https://github.com/dynamitecircle/dc.git
cd dc
python3 py/dc.py setup --api-key dk_<api-key>
```

To update: `cd dc && git pull`. Run `self-test` afterwards.

Best for: trying things out, scripts you run by hand, no other repo involved.

### 2. Git submodule — pinned to a specific commit

If you have your own project repo and want the `dc` repo versioned alongside it:

```bash
cd your-project
git submodule add https://github.com/dynamitecircle/dc.git vendor/dc
git commit -m "Add dc client as submodule"
```

To update later:

```bash
cd vendor/dc
git pull origin main
cd ../..
git add vendor/dc
git commit -m "Bump dc client"
```

Then in your code:

```python
import sys
sys.path.insert(0, "vendor/dc/py")
from dc import DC
```

Best for: production-ish code where you want explicit, reviewable bumps.

### 3. Git subtree — same updates, no submodule indirection

```bash
cd your-project
git subtree add --prefix vendor/dc \
  https://github.com/dynamitecircle/dc.git main --squash
```

Update with:

```bash
git subtree pull --prefix vendor/dc \
  https://github.com/dynamitecircle/dc.git main --squash
```

Best for: teammates who don't know submodules — files just appear in your repo.

### 4. Symlink — share one clone across many projects

If you keep all your projects in `~/code/`:

```bash
git clone https://github.com/dynamitecircle/dc.git ~/code/dc

# In each project that uses it:
cd ~/code/your-project
ln -s ../dc vendor/dc
```

Now `cd ~/code/dc && git pull` updates every consumer at once. Project-level `.mcp.json` / `.codex/config.toml` entries can use `vendor/dc/py/dc.py` and they'll resolve through the symlink.

Best for: power users with multiple personal projects and one machine.

### 5. Pip-installable Git ref — one-shot for a virtualenv

The skill is one file with no setup.py, but you can install the package the MCP server needs and check the file out as a sibling:

```bash
pip install mcp
git clone https://github.com/dynamitecircle/dc.git
```

Best for: CI environments, ephemeral containers, scripted setups.

### Update etiquette

- **Stay current.** The DC Member API ships new endpoints regularly and the client mirrors them; running stale means missing features and (eventually) compatibility warnings on stderr.
- **Run `self-test` after every update.** Five seconds, catches breakage.
- **Watch stderr the first time you call any command after updating.** The version-mismatch warning prints once per process when the server is on a newer minor/major.
- **Major version bumps may be backwards-incompatible.** Read the release notes on the GitHub repo before pulling across a major boundary.

## Rate limits

| Tier              | Per minute | Per day |
|-------------------|------------|---------|
| DC Community      | 10         | 300     |
| DC BLACK          | 60         | 3,000   |

Headers on every response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Daily-Remaining`.

## Platform support

Tested on macOS, Linux, and Windows 10/11. Python 3.9+ required (uses `pathlib`, `Path.replace`, `inspect.signature`, `contextvars`, `urllib`).

### Windows notes

- The skill auto-reconfigures `stdout` and `stderr` to UTF-8 at startup, so emoji and em-dashes render correctly even on legacy `cmd.exe` (which defaults to cp1252). If you still see mojibake on a very old terminal, set `PYTHONIOENCODING=utf-8` once: `setx PYTHONIOENCODING utf-8` then restart your shell.
- `setup` writes `.env.dc` and tries to chmod 600 it. On Windows this is a no-op — the file inherits NTFS perms from its parent. The skill emits a one-time note about this when you run `setup`. Make sure your repo isn't on a shared drive.
- Use `python` or `python3.exe` to invoke; the `#!/usr/bin/env python3` shebang is ignored on Windows.

## Project layout

```
dc/
├── README.md                          # this file
├── CLAUDE.md                          # AI-tool guide (also linked as AGENTS.md, GEMINI.md)
├── AGENTS.md       → CLAUDE.md        # symlink (Codex)
├── GEMINI.md       → CLAUDE.md        # symlink (Gemini)
├── LICENSE                            # MIT
├── manifest.json                      # MCPB manifest (MCP 2025-11 spec)
├── .mcp.json                          # auto-registers `dc` MCP server in Claude Code
├── .codex/
│   └── config.toml                    # auto-registers `dc` for Codex CLI
├── .github/
│   └── copilot-instructions.md        # GitHub Copilot
│
├── py/                                # ← Python client (canonical)
│   ├── SKILL.md                       # Agent Skills frontmatter + usage
│   ├── config.json                    # name, version, env requirements
│   ├── dc.py                          # CLI + Python import + --mcp server
│   ├── requirements.txt               # optional MCP dep — skip for CLI/import
│   ├── .env.dc.example                # template
│   └── .env.dc                        # gitignored (created by `setup`)
│
│   (Future: go/, node/, rs/ folders for sister clients in other languages)
│
├── docs/                              # ← REAL design docs (canonical)
│   ├── skill-info.md                # design rules / architecture
│   └── mcp-info.md                    # MCP setup for every supported client
│
├── .claude/                           # Agent Skills discovery (Claude Code)
│   ├── skills/dc  → ../../py          # symlink to canonical Python client
│   └── docs       → ../docs           # symlink to canonical docs
│
├── .agents/                           # Agent Skills discovery (Codex CLI + Gemini CLI alias)
│   ├── skills/dc  → ../../py          # symlink to canonical Python client
│   └── docs       → ../docs           # symlink to canonical docs
│
├── .gemini/                           # Gemini CLI MCP config
│   └── settings.json                  # auto-approves dc MCP tools (trust: true)
│
├── .gitignore
└── .gitattributes
```

### About the layout

This is a **monorepo**. The Python client lives at `/py/` so we can add future sister clients (`go/`, `node/`, `rs/`) at the same level — they all wrap the same DC Member API. `/docs/` is shared. The dotfile-prefixed directories (`.claude/`, `.agents/`, `.gemini/`) exist because AI tools auto-discover skills from those specific paths — they're kept hidden but each one **symlinks (or points) straight to the canonical folder**, so you only edit files in one place. Edit `py/dc.py` and Claude Code, Codex, and Gemini CLI all see the same file via their respective discovery directories. Gemini CLI also reads `.agents/skills/` as an alias, so we don't need a redundant `.gemini/skills/` symlink.

If you're adding new code or docs, edit `py/` (or `docs/`) directly. The discovery folders take care of themselves.

### Pre-approval out of the box

`.claude/settings.json`, `.codex/config.toml`, and `.gemini/settings.json` all auto-approve the `dc` MCP server's tools so users don't get a per-call approval prompt when they open this repo with their AI tool. Anyone uncomfortable with that can override with their personal `.claude/settings.local.json`, `~/.codex/config.toml`, or `~/.gemini/settings.json`. Every dc write tool is scoped to the caller's own DC account via their personal API key — pre-approval doesn't widen any blast radius, just removes per-call friction.

## Maintenance

This repo is maintained by the Dynamite Circle team. It's read-only for the public — clone it and use it, but don't open PRs. If you spot a bug or want a new feature, contact us through the official DC channels.

## License

[MIT](LICENSE) — see the LICENSE file for the full text.

