supstack

@supstack/cli

ターミナルで利用できるエビデンスに基づくサプリメント情報ツール — AI エージェント向けの MCP サーバーでもあります。

公開されている SupStack API を利用するシンクライアントです。読み取り専用で、アカウントは不要です。CLI と MCP サーバーの両方で、1つの機能レジストリを使用します。

ステータス：アカウント機能のフェーズ 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

続いて、シェル補完を有効にします：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 を実行すると、1回限りのコードが表示され、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

これにより、エージェントは 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）は、エージェント向けに readOnlyHint: false として設定されています。

Claude Code（コマンド1つで設定）：

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	レスポンスキャッシュの有効期間（秒）
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 レスポンスは、同じデータの再取得を 60 回／分のレート制限内に十分収めるため、デフォルトで 1 時間、~/.supstack/cache/ にキャッシュされます。コマンドごとに --no-cache でキャッシュを回避するか、supstack cache clear／supstack cache path で管理できます。キャッシュのサイズには上限があり、上限を超えると古いエントリーが削除されます。

シェル補完

現在のシェルにワンステップでインストールします（スクリプトを書き込み、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）
• スラッグが必要な箇所でのサプリメントのスラッグ（research <TAB>、compare a <TAB>、stack add <TAB>、track log <TAB>）
• search --goal <TAB> の後の目標 ID

スラッグと目標のリストは 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