supstack

@supstack/cli

在终端中使用基于证据的补剂智能工具——也是供 AI Agent 使用的 MCP 服务。

这是公共 SupStack API 的轻量客户端。只读，无需账户。CLI 和 MCP 服务共用一个能力注册表。

状态：第 2 阶段（账户）进行中。 下方所有读取命令均可使用，另有 MCP 服务以及 login/whoami。使用 npm install -g @supstack/cli 安装。

安装

# Homebrew (macOS / Linux)
brew install drbaher/supstack/supstack

# or npm
npm install -g @supstack/cli

# or run without installing
npx -y @supstack/cli define adaptogen

然后启用 Shell 补全：supstack completion install。

从源代码安装（在此目录中）：npm install && npm run build && node dist/index.js define adaptogen。

用法

supstack research magnesium --protocol       # full evidence summary for one supplement
supstack search --goal deep-sleep -n 5       # search by name or filter
supstack compare magnesium glycine           # 2–3 head-to-head
supstack studies "sleep" --type rct          # research library
supstack interactions caffeine l-theanine --pathway   # interaction check (deep pair analysis)
supstack interactions magnesium potassium --medication lisinopril   # supplement × drug check
supstack stack add magnesium --dose 400mg --timing bedtime   # local stack (+ dose/timing/brand)
supstack stack sync                          # sync local ⇄ your account (login required)
supstack goals --category sleep              # list goal ids (for rate/recommend)
supstack rate --goals deep-sleep,sharpen-focus   # grade your stack A–F by goal coverage
supstack experiments start magnesium deep-sleep  # run an N-of-1 experiment (requires login)
supstack export --format md                  # export your stack
supstack define bioavailability              # glossary lookup
supstack <command> --json                    # machine-readable output on any command
supstack --help

账户（第 2 阶段）

supstack login          # sign in via device-code flow (opens the browser to confirm)
supstack whoami         # show the signed-in account
supstack logout         # sign out and revoke this device's token

login 会显示一次性验证码、打开 https://supstack.me/activate，并在你通过浏览器批准后完成登录。令牌保存在 ~/.supstack/config.json（权限为 0600）中。匿名即可完整使用读取功能——账户可解锁个性化功能。

登录后，将你的补剂方案同步到账户：

supstack stack pull     # local ← your account
supstack stack push     # local → your account (keeps dosage/timing/brand for kept items)
supstack stack sync     # additive merge of both; preserves existing cloud metadata

supstack profile                              # view your health profile
supstack profile set --age 35 --sex male --weight 80 --weight-unit kg
supstack recommend                            # personalized picks from your goals + stack
supstack experiments list                     # your N-of-1 experiments + verdicts
supstack track log                            # log today's stack as taken
supstack track adherence                      # your adherence rate, streak, per-supplement

作为 MCP 服务使用

supstack mcp   # stdio MCP server exposing all capabilities as tools

这会为 Agent 提供完整的 SupStack 工具集。只读（无需账户）： supstack_research、supstack_search、supstack_compare、supstack_studies、supstack_interactions、supstack_stack、supstack_rate_stack、supstack_export、 supstack_define。

同时也会提供账户范围内的工具——supstack_recommend、 supstack_profile_get / supstack_profile_set、supstack_experiments_list / supstack_experiments_get、supstack_track_log、supstack_track_adherence （以及云端 supstack_stack 拉取/推送/同步）。使用这些工具需要用户登录 （运行 supstack login，或设置 SUPSTACK_TOKEN）；没有令牌时，它们会返回明确的 “未登录”错误，而不会直接失败。会修改数据的工具（profile_set、 track_log）会向 Agent 标记 readOnlyHint: false。

Claude Code（一条命令）：

claude mcp add supstack -- supstack mcp

Claude Desktop——添加到 claude_desktop_config.json （macOS：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "supstack": {
      "command": "supstack",
      "args": ["mcp"]
    }
  }
}

也可以不进行全局安装，直接通过 "command": "npx", "args": ["-y", "@supstack/cli", "mcp"] 运行。 要使用本地检出版本，请指定构建后的入口文件—— "command": "node", "args": ["/absolute/path/to/supstack-cli/dist/index.js", "mcp"]（请先运行 npm run build）。

配置

环境变量	默认值	用途
SUPSTACK_API_URL	https://supstack.me/api/v1	API 基础 URL（可覆盖，用于本地开发）
SUPSTACK_API_KEY	—	可选 API 密钥（匿名访问的速率限制为每个 IP 每分钟 60 次）
SUPSTACK_CACHE_TTL	3600	响应缓存的 TTL（秒）
SUPSTACK_NO_CACHE	—	设置后禁用响应缓存
SUPSTACK_TIMEOUT	20	每次请求的超时时间（秒；也可使用 --timeout）
SUPSTACK_HOME	~/.supstack	配置、补剂方案和缓存的目录
SUPSTACK_TOKEN	—	覆盖已存储的账户令牌（通过 supstack login 获取）
SUPSTACK_NO_ANON_TOKEN	—	禁用匿名即时令牌的自动生成
SUPSTACK_NO_UPDATE_CHECK	—	禁用“有可用更新”通知（也会遵循 NO_UPDATE_NOTIFIER）
NO_COLOR	—	禁用 ANSI 颜色
FORCE_COLOR	—	强制启用 ANSI 颜色（即使输出经过管道传递）

所有命令均可使用的全局标志：--json、--no-cache、--timeout <seconds>、--color / --no-color、-q, --quiet。

supstack auth set-key <key> 会将密钥保存到 ~/.supstack/config.json（文件权限设为 0600）。

响应缓存

只读 API 响应会缓存在 ~/.supstack/cache/ 下（默认 TTL 为 1 小时），确保重复查询远低于每分钟 60 次的速率限制。可在单个命令中使用 --no-cache 绕过缓存，也可以通过 supstack cache clear / supstack cache path 管理缓存。缓存有容量上限（超出上限时会清理最旧的条目）。

Shell 补全

为当前 Shell 一键安装（写入脚本并幂等地配置 rc 文件；uninstall 可撤销安装）：

supstack completion install      # detects bash | zsh | fish from $SHELL

……或者自行生成脚本：

supstack completion bash >> ~/.bashrc
supstack completion zsh  > "${fpath[1]}/_supstack"
supstack completion fish > ~/.config/fish/completions/supstack.fish

补全是动态的——脚本会将你输入的内容转发给 supstack __complete，并根据当前位置提供合适的选项：

• 顶层命令和子操作（stack <TAB> → add remove list pull push sync）
• 在需要 slug 的位置补全 supplement slug（research <TAB>、compare a <TAB>、stack add <TAB>、track log <TAB>）
• search --goal <TAB> 后补全 goal id

slug/goal 列表会从 API 获取一次，并缓存在 ~/.supstack/completion/ 下（有效期为 24 小时）。使用以下命令预热或刷新缓存：

supstack completion refresh

退出码

命令会以语义化代码退出，让脚本和 MCP 封装程序可以根据失败类型采取不同操作：

代码	含义
0	成功
1	通用错误（包括 5xx）
2	需要/拒绝身份验证（未登录、401、403）
3	未找到（404）
4	请求过于频繁（429）
5	网络故障/超时
6	输入无效（参数或标志错误/缺失、未知命令、架构验证失败、400/422）

开发

npm test            # unit tests (mocked fetch)
npm run type-check  # tsc --noEmit
npm run build       # tsup → dist/

有关能力模式以及如何添加命令，请参阅 CLAUDE.md。

许可证

MIT