DC Member API

DC 官方客户端

Dynamite Circle Member API 的官方客户端——可访问你自己的个人资料、行程、活动、线上活动、门票、邀请、收件箱、聊天室、分会、地点查询，以及每周定位摘要。

Python 客户端是一个独立的单文件程序。零依赖（仅使用标准库）。既可作为命令行工具和 Python 库使用，也可作为 Model Context Protocol 服务。兼容 Claude Code、Claude Desktop、Codex CLI、Gemini CLI、Cursor、GitHub Copilot，以及所有其他兼容 Agent Skills / MCP 的工具。

TypeScript 客户端是一个 npm 库，供可信的服务端 TypeScript 项目使用。它不是命令行工具，也不是 MCP 服务。

py/dc.py       ← Python: CLI + library + MCP server
ts/src/        ← TypeScript: npm library
contracts/     ← pinned OpenAPI contract shared by both clients

关于 Dynamite Circle

Dynamite Circle 是全球创业者寻找同路人的地方——一个经过筛选、仅限会员加入的社群，成员是在世界各地经营盈利企业、可自由选择工作地点的企业主。DC 于 2011 年创立（最初只有 20 位听众聚集在一座偏远的热带岛屿上），如今已发展成一个由约 1,500 位活跃创业者组成的精选网络。成员会参加经过审核的线下活动，例如 DCBKK 和 DCMEX，在私人聊天室中交流经验，并常年走访彼此所在的城市。

DC 是一个私人社群，但面向年收入超过 10 万美元、经营可自由选择工作地点的企业的创业者开放申请。团队成员会在 48 个工作小时内亲自审核每份申请——如果你符合条件，请在此开始申请。

快速入门

没用过 Claude Code、Codex 或 git？下面介绍如何在 5 分钟内从零开始，让“Claude 能读取我的 DC 个人资料”。

1. 安装基础工具（仅需一次）

你的电脑上需要安装以下三款免费工具：

• Python 3.9+——本客户端使用的编程语言。在此下载（提供 Mac/Windows/Linux 安装程序；在 Windows 上请勾选 “Add Python to PATH”）。
• Git——用于从 GitHub 下载代码的工具。在此下载。
• AI 助手——任选其一：
  • Claude Code ← 推荐——本仓库就是围绕它构建的
  • Codex CLI——也能用，只是命令略有不同
  • Claude Desktop——聊天应用，可使用 MCP 服务，但没有命令行工具

安装过程中如果出现“是否要添加到 PATH？”之类的提示，请选择“是”。

2. 获取代码

打开终端：

• Mac：Spotlight →“Terminal”
• Windows：开始 →“Terminal”（或“PowerShell”）
• Linux：你知道该怎么做

然后粘贴：

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

现在你有了一个名为 dc 的文件夹，里面包含所有代码。

3. 获取 DC API 密钥

在浏览器中访问 https://dc.dynamitecircle.com 并登录，点击你的个人资料照片（右上角），然后选择 DC Member API Key。复制以 dk_… 开头的长字符串。

4. 告诉客户端你的密钥

回到终端（仍在 dc 文件夹内）：

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

5. 试用

打开 Claude Code，并确保它指向刚才下载的 dc 文件夹。（Claude 通常会打开你上次使用的项目——如果打开的是其他位置，点击文件夹图标并选择 dc。）

然后询问：

“显示我的 DC 个人资料”

Claude 会运行相应的命令，并向你显示个人资料。还可以试试下面这些：

“DC 最新公告是什么？” “我会参加哪些活动？” “显示 DCMEX 日程，并收藏所有与营销相关的内容” “我的分会里还有谁会去 DCBKK？”

大功告成。本 README 的其余部分会更详细地介绍各种功能；py/SKILL.md 列出了 Claude 可以运行的所有命令。

如果遇到问题

症状	尝试方法
python3: command not found	Python 未安装，或未添加到 PATH。重新安装，并在 Windows 上勾选 “Add to PATH”；在 Mac 上，尝试使用 python 而不是 python3。
git: command not found	同理——重新安装 Git。
Claude 提示“我找不到 dc skill”	确保 Claude Code 打开的是 dc 文件夹，而不是你的主目录或其他项目。或者直接问 Claude：“你现在在 dc 文件夹里吗？”
其他问题	在 dc 文件夹中运行 python3 py/dc.py self-test——它会准确指出哪个步骤出了问题。

---

如何接入

同一个 dc.py 文件提供了 四 种集成方式——根据你的工具与它交互的方式选择合适的一种：

集成方式	说明	调用方式	依赖项
Agent Skill	通过 SKILL.md frontmatter 自动发现（Claude Code、Codex、Gemini CLI、Cursor、Copilot）	只需用工具打开仓库——它会读取 py/SKILL.md 并提供相关命令	仅标准库
CLI	直接从 shell 或脚本运行命令	python3 py/dc.py <command>	仅标准库
Python 库	在自己的 Python 代码中导入	from dc import DC; DC().profile()	仅标准库
MCP 服务	通过 stdio 使用 Model Context Protocol（Claude Desktop、Cursor、Codex MCP、Cline 等）	python3 py/dc.py --mcp	pip install mcp（可选）

mcp 包采用 延迟导入——Agent Skill、CLI 和 Python 库用户都不需要安装它。

TypeScript npm 库

对于 TypeScript 项目，请使用 ts/ 下的包：

import { DC } from "@dynamitecircle/dc";

const dc = new DC({ apiKey: process.env.DC_API_KEY! });

const profile = await dc.profile.get();
const trips = await dc.trips.list({ limit: 10 });

请将 dk_... API 密钥保留在服务端。不要在浏览器 JavaScript 中发送成员 API 密钥。

不想安装任何东西？使用托管 MCP

DC Member API 也提供托管 MCP 服务——只需将你的 AI 应用指向一个远程端点，无需克隆、安装或更新：

https://api.dynamitecircle.com/mcp        (Streamable HTTP)

 

• Claude Code： claude mcp add --transport http dc https://api.dynamitecircle.com/mcp
• Claude（网页版 / Desktop / 移动版）： 设置 → 连接器 → 添加自定义连接器 → 粘贴 URL → 连接
• VS Code： 点击上方徽章，或运行 code --add-mcp '{"name":"dc","url":"https://api.dynamitecircle.com/mcp"}'
• Cursor： 点击上方徽章，或添加指向该 URL 的自定义 MCP 连接器
• ChatGPT / 其他 MCP 应用： 添加指向上方 URL 的自定义 / 远程 MCP 连接器

出现提示时，使用你的 DC 账号登录（一键 OAuth）——或者将 dk_ 密钥作为 Authorization: Bearer 发送。该服务始终使用当前 API 版本，因此无需手动更新。

托管 MCP 和此客户端——我该选哪个？

你想要……	使用
无需安装、始终保持最新，只需在聊天应用中使用 MCP 工具	托管 MCP（上方 URL）
在自己的 Python 代码中调用 DC（from dynamitecircle import DC）	此客户端（库）
使用本地 CLI（dc profile）或编写 shell 脚本	此客户端（CLI）
使用本地 stdio MCP 服务（支持离线、固定版本、针对 localhost 开发）	此客户端（dc --mcp）

本 README 的其余部分介绍的是此客户端。使用托管 MCP 时，只需使用上方的 URL。

功能

• 完整覆盖 Member API — 在每个公开端点上进行读取和写入（运行 python3 py/dc.py help 查看实时列表）
• 设置命令 — 将 API 密钥保存到技能目录下的 .env.dc，权限设为 600
• 自检命令 — 端到端验证环境变量、网络、密钥格式以及实时 /profile 调用
• 游标分页 — 每个返回列表的命令都使用相同的 [--limit N] [--cursor TOKEN] 格式，并返回标准信封 {items, count, cursor, has_more}
• 三种输出格式 — text（默认，格式化 JSON）、--json、--python
• 支持 MCP — 同一技能会自动将所有命令公开为 MCP 工具
• 已为 Claude Code 预配置 — 仓库自带 .mcp.json，只需 cd 并运行 claude

CLI 快速入门（已熟悉终端？）

如果你跳过上面的快速入门，只想了解 CLI 的使用流程，这里提供精简版。

1. 获取 API 密钥

DC 个人资料下拉菜单 → DC Member API Key（仅管理员/测试人员可用）。密钥格式为 dk_<api-key>，可在同一下拉菜单中撤销。

2. 保存密钥

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

这会写入 py/.env.dc（权限为 600，且已加入 gitignore）。

3. 验证连接

python3 py/dc.py self-test

预期输出：

{
  "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. 试用几个命令

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

运行 python3 py/dc.py help 查看完整命令列表。

按 AI 工具进行设置

托管 MCP（无需安装，始终保持最新）

无需克隆或更新 — 将工具连接到远程端点即可：

# Claude Code
claude mcp add --transport http dc https://api.dynamitecircle.com/mcp

对于 Claude 网页版 / Desktop、Cursor、ChatGPT 和其他 MCP 应用，请添加一个自定义 / 远程连接器，指向 https://api.dynamitecircle.com/mcp（Streamable HTTP）。使用你的 DC 账户登录（OAuth），或通过 Bearer 标头发送 dk_ 密钥。发现信息发布于 /.well-known/mcp.json。这是最省力的方式；以下所有方式都会在本地运行客户端。

Claude Code（本地客户端）

此仓库已自带 .mcp.json。使用 claude 打开仓库：

cd dc
claude

工具将以 mcp__dc__* 的形式提供。首次安装可选 MCP 依赖：

pip install -r py/requirements.txt

技能发现（CLI + 导入）会通过 py/SKILL.md 自动生效。

通过 uvx 自动更新本地 MCP（PyPI）

想要使用本地 stdio 服务，并在每次启动时拉取最新发布的客户端，无需维护克隆副本？使用 uv 的 uvx，并在 env 块中传入密钥：

{
  "mcpServers": {
    "dc": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--refresh", "--from", "dynamitecircle[mcp]", "dc", "--mcp"],
      "env": { "DC_API_KEY": "dk_<api-key>" }
    }
  }
}

说明：控制台脚本名称为 dc（而非 dynamitecircle），因此需要使用 --from dynamitecircle[mcp] — 它既指定了软件包，也会拉取可选的 mcp 扩展。--refresh 用于自动更新；移除它则让 uvx 使用缓存。env 中的 DC_API_KEY 优先于任何 .env.dc（临时的 uvx 安装没有此文件）。

Claude Desktop

最简单的方式 — 一键安装 .mcpb： 从最新 GitHub 版本下载 dc.mcpb 并双击。Claude Desktop 会安装 dc 服务并提示输入 DC_API_KEY（无需编辑 JSON）。需要 Python 3.9+，且机器上可使用 mcp 包（pip install 'dynamitecircle[mcp]'）。（也可以完全跳过本地安装，改用上面的托管 MCP 连接器。）

手动 — 编辑配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

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

重启 Claude Desktop。

Codex CLI

编辑 ~/.codex/config.toml：

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

Codex 会自动发现 AGENTS.md（符号链接到 CLAUDE.md）和 .agents/skills/（符号链接到 .claude/skills/）。

Gemini CLI

读取 GEMINI.md（符号链接到 CLAUDE.md）获取上下文。要使用 MCP，请在 Gemini CLI 设置中进行配置：

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

Cursor

设置 → MCP → 添加服务，然后指向同一个 dc.py --mcp。

GitHub Copilot

读取 .github/copilot-instructions.md 以获取上下文。Copilot 目前还不支持原生 MCP；开发时可用它在编辑器中获取建议。

其他 MCP 客户端

配置方法相同：命令为 python3，参数为 ["/path/to/dc.py", "--mcp"]。该协议是标准协议。

输出格式

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)

全局标志可放在命令名称之前或之后：

python3 dc.py --json profile
python3 dc.py profile --json

游标分页

所有返回列表的命令都接受相同的标志：

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

标准封装格式：

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

未分页的额外字段（例如 inbox 中的 totalUnread）会通过 extra 键传递。

作为 Python 库使用

从 PyPI 安装（pip install dynamitecircle）后，通过包名导入：

from dynamitecircle import DC

dc = DC()

如果是在克隆的仓库中操作，则将 sys.path 指向 py/ 文件夹，并以 dc 导入：

import sys
sys.path.insert(0, "py")
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="[email protected]", full_name="New Friend")

覆盖 API URL（例如用于本地开发服务器）：

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

API 参考

DC Member API 的完整在线参考文档——包括每个端点、参数和响应结构——请访问 **https://www.dynamitecircle.com/developers/**。该页面会在每次部署时重新生成，因此始终保持最新。

保持更新

DC Member API 会定期推出新端点和改进。本工具是官方客户端，我们会在 API 变更时同步更新。请做好更新准备——首次请求返回的 X-API-Version 高于 DC_API_VERSION 时，该工具会在 stderr 上发出警告；主要版本升级可能会导致旧客户端无法使用。

无需维护的选项：使用托管 MCP（https://api.dynamitecircle.com/mcp）即可，无需更新——该服务始终运行当前 API 版本。以下策略仅适用于本地客户端。

请选择适合项目的集成方式。按从最简单到最隔离的顺序排列：

0. PyPI — pip / uvx

pip install dynamitecircle              # CLI + library
pip install 'dynamitecircle[mcp]'       # + local MCP server (dc --mcp)

然后运行 dc setup --api-key dk_<api-key> 和 dc self-test。使用 pip install --upgrade dynamitecircle 更新。要使用每次启动时自动更新的本地 MCP，请使用上方的 uvx 配置。

适用场景：最快速的本地安装，以及自动更新的 uvx MCP 配置。

1. 普通 git clone — 快速本地使用

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

更新方法：运行 cd dc && git pull。之后运行 self-test。

适用场景：试用、手动运行的脚本，以及无需涉及其他仓库的情况。

2. Git 子模块 — 固定到特定提交

如果你有自己的项目仓库，并希望将 dc 仓库版本一并纳入管理：

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

之后更新：

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

然后在代码中：

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

适用场景：接近生产环境的代码，需要显式且可审查的版本升级。

3. Git subtree — 更新方式相同，无需子模块间接引用

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

使用以下命令更新：

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

适用场景：不熟悉子模块的团队成员——文件会直接出现在你的仓库中。

4. 符号链接 — 在多个项目间共享一个克隆

如果你将所有项目都放在 ~/code/ 中：

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

现在运行 cd ~/code/dc && git pull 即可一次更新所有使用该仓库的项目。项目级 .mcp.json / .codex/config.toml 条目可以使用 vendor/dc/py/dc.py，路径会通过符号链接解析。

适用场景：在一台机器上管理多个个人项目的高级用户。

5. 可通过 Pip 安装的 Git 引用 — 一次性安装到虚拟环境

该工具是一个无需 setup.py 的单文件，但你可以安装 MCP 服务所需的包，并将文件检出到同级目录：

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

适用场景：CI 环境、临时容器和脚本化配置。

更新规范

• 保持最新。 DC Member API 会定期推出新端点，客户端也会同步更新；使用过时版本意味着错过新功能，并且（最终）会在 stderr 上收到兼容性警告。
• 每次更新后运行 self-test。 只需五秒，即可发现问题。
• 更新后首次调用任何命令时，留意 stderr。 如果 API 使用的是更新的次要版本或主要版本，版本不匹配警告会在每个进程中打印一次。
• 主要版本升级可能不向后兼容。 跨越主要版本边界拉取更新前，请先阅读 GitHub 仓库中的发布说明。

速率限制

等级	每分钟	每天
DC Community	10	300
DC BLACK	60	3,000

每个响应都包含以下标头：X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset、X-RateLimit-Daily-Remaining。

平台支持

已在 macOS、Linux 和 Windows 10/11 上测试。需要 Python 3.9+（使用 pathlib、Path.replace、inspect.signature、contextvars、urllib）。

Windows 说明

• 该技能会在启动时自动将 stdout 和 stderr 重新配置为 UTF-8，因此即使在默认使用 cp1252 的旧版 cmd.exe 中，表情符号和破折号也能正确显示。如果你仍在非常旧的终端中看到乱码，请设置一次 PYTHONIOENCODING=utf-8：运行 setx PYTHONIOENCODING utf-8，然后重启 shell。
• setup 会写入 .env.dc 并尝试将其权限设置为 600。在 Windows 上，此操作无效——文件会继承其父目录的 NTFS 权限。运行 setup 时，该技能会就此提示一次。请确保你的仓库不在共享驱动器上。
• 请使用 python 或 python3.exe 调用；Windows 会忽略 #!/usr/bin/env python3 shebang。

项目布局

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`)
│
├── ts/                                # ← TypeScript npm library (@dynamitecircle/dc)
│   ├── src/                           # hand-written SDK surface
│   ├── tests/                         # contract + request behavior tests
│   ├── examples/                      # TypeScript usage examples
│   ├── package.json
│   └── tsconfig.json
│
├── contracts/                         # pinned API contract shared by clients
│   ├── openapi.json                   # committed snapshot of /openapi.json
│   └── operation-map.json             # OpenAPI op → Python command → TS method
│
├── DC/
│   └── SKILL.md     → ../py/SKILL.md  # human-friendly skill path (symlink)
│
├── 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

关于布局

这是一个单体仓库。Python 客户端位于 /py/；TypeScript 客户端位于 /ts/。两者都封装同一个 DC Member API，并根据 /contracts/ 中固定的契约进行验证。/docs/ 为共享目录。以点号开头的目录（.claude/、.agents/、.gemini/）存在的原因是，AI 工具会从这些特定路径自动发现技能——这些目录会隐藏起来，但每个目录都直接符号链接（或指向）规范文件夹，因此你只需在一个位置编辑文件。编辑 py/dc.py 后，Claude Code、Codex 和 Gemini CLI 都能通过各自的发现目录看到同一个文件。Gemini CLI 还会将 .agents/skills/ 作为别名读取，因此我们不需要再创建一个多余的 .gemini/skills/ 符号链接。

如果你要添加 Python 代码或技能文档，请直接编辑 py/（或 docs/）。如果要添加 TypeScript 库代码，请编辑 ts/。发现目录会自动处理。

开箱即用的预先批准

.claude/settings.json、.codex/config.toml 和 .gemini/settings.json 都会自动批准 dc MCP 服务的工具，因此用户使用 AI 工具打开此仓库时，不会每次调用都收到批准提示。对此感到不放心的用户可以通过个人的 .claude/settings.local.json、~/.codex/config.toml 或 ~/.gemini/settings.json 覆盖设置。每个 dc 写入工具都通过用户个人的 API 密钥限定为只能操作其自己的 DC 账户——预先批准不会扩大影响范围，只是免去每次调用时的确认步骤。

维护

此仓库由 Dynamite Circle 团队维护。仓库对公众只读——你可以克隆并使用，但请勿提交 PR。如果发现错误或希望添加新功能，请通过 DC 官方渠道联系我们。

许可证

MIT — 完整文本请参阅 LICENSE 文件。