bitbank-lab-mcp 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +72 -425
  2. package/lib/fees.ts +21 -6
  3. package/lib/formatter.ts +6 -0
  4. package/lib/get-depth.ts +9 -4
  5. package/lib/price.ts +9 -0
  6. package/lib/tickers.ts +28 -4
  7. package/lib/trigger-price.ts +18 -27
  8. package/package.json +1 -1
  9. package/src/handlers/analyzeMyPortfolioHandler.ts +118 -47
  10. package/src/handlers/portfolio/calc.ts +114 -23
  11. package/src/handlers/portfolio/fetch.ts +32 -64
  12. package/src/handlers/portfolio/pagination.ts +70 -42
  13. package/src/handlers/portfolio/types.ts +8 -3
  14. package/src/handlers/runBacktestHandler.ts +1 -0
  15. package/src/mcp-apps-hydration.ts +74 -0
  16. package/src/mcp-apps-meta.ts +12 -0
  17. package/src/private/confirmation.ts +10 -2
  18. package/src/private/elicitation.ts +59 -15
  19. package/src/private/preview-confirmation.ts +4 -1
  20. package/src/private/schemas.ts +103 -31
  21. package/src/private/shared-confirm-state.ts +281 -0
  22. package/src/private/trade-history.ts +164 -0
  23. package/src/resources/confirmation-resource.ts +50 -0
  24. package/src/schema/backtest.ts +55 -9
  25. package/src/schema/market-data.ts +3 -1
  26. package/src/schema/ui.ts +4 -0
  27. package/src/server.ts +28 -4
  28. package/src/ui-snapshot-cache.ts +118 -13
  29. package/tools/detect_whale_events.ts +4 -1
  30. package/tools/get_orderbook.ts +38 -18
  31. package/tools/get_tickers_jpy.ts +1 -41
  32. package/tools/get_ui_snapshot.ts +8 -9
  33. package/tools/prepare_depth_data.ts +10 -6
  34. package/tools/private/get_margin_positions.ts +14 -13
  35. package/tools/private/get_margin_status.ts +5 -4
  36. package/tools/private/get_margin_trade_history.ts +48 -78
  37. package/tools/private/get_my_deposit_withdrawal.ts +147 -42
  38. package/tools/private/get_my_orders.ts +3 -6
  39. package/tools/private/get_my_trade_history.ts +39 -34
  40. package/tools/private/get_orders_info.ts +6 -2
  41. package/tools/private/preview_order.ts +36 -8
  42. package/tools/trading_process/lib/backtest_engine.ts +38 -4
  43. package/tools/trading_process/lib/equity.ts +10 -11
  44. package/tools/trading_process/lib/resolve_fee.ts +10 -4
  45. package/tools/trading_process/lib/strategies/bb_breakout.ts +4 -1
  46. package/tools/trading_process/lib/strategies/filters.ts +4 -1
  47. package/tools/trading_process/lib/strategies/macd_cross.ts +8 -3
  48. package/tools/trading_process/lib/strategies/params.ts +21 -0
  49. package/tools/trading_process/lib/strategies/rsi.ts +7 -3
  50. package/tools/trading_process/lib/strategies/sma_cross.ts +4 -1
  51. package/tools/trading_process/lib/strategies/warmup.ts +15 -0
  52. package/tools/trading_process/run_backtest.ts +75 -28
  53. package/ui/cancel-confirm/dist/cancel-confirm.html +39 -39
  54. package/ui/order-confirm/dist/order-confirm.html +39 -39
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  [![npm](https://img.shields.io/npm/v/bitbank-lab-mcp.svg)](https://www.npmjs.com/package/bitbank-lab-mcp)
6
6
  [![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/tjackiet/bitbank-lab-mcp?utm_source=oss&utm_medium=github&utm_campaign=tjackiet%2Fbitbank-lab-mcp&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)](https://coderabbit.ai)
7
7
 
8
- > bitbank API のデータを使った暗号資産市場分析を、Claude / Cursor / Codex / Antigravity CLI など各種 AI クライアントから簡単に実行できる MCP サーバーです。
8
+ > bitbank API のデータで暗号資産の市場分析をする MCP サーバーです。Claude / Cursor / Codex / Antigravity CLI などから使えます。
9
9
 
10
10
  ## はじめにお読みください
11
11
 
@@ -13,73 +13,27 @@
13
13
  - ご利用の前に必ず [⚠️ 免責事項](#免責事項) をお読みください。
14
14
  - 本リポジトリは **bitbank バグバウンティプログラムの対象範囲外** です。
15
15
 
16
- ## 本 MCP サーバーについて
16
+ ## できること
17
17
 
18
- bitbank の公開 API から取得した価格・取引データを、指標計算・統合・可視化用データの整形まで行った上で LLM に渡します(必要に応じてサーバー側で SVG 描画も可能)。生データを渡すだけのサーバーとは異なり、各ツールの description に「いつ使うべきか」「他ツールとの使い分け」を明示しているため、LLM が自律的に適切なツールを選択できます。
18
+ - **データ**:ティッカー・板・約定履歴・ローソク足(1 分足〜月足)
19
+ - **分析**:テクニカル指標(SMA / RSI / ボリンジャーバンド / 一目均衡表 / MACD)・フロー・ボラティリティ・板の圧力・パターン検出・総合スコア
20
+ - **可視化**:Claude.ai の Visualizer 向けデータ(`prepare_chart_data` ほか)、SVG / PNG(`render_chart_svg` ほか)
21
+ - **口座(API キーが必要)**:資産・注文・約定・入出金・信用・損益の分析、確認つきの発注・取消
19
22
 
20
- 姉妹プロジェクトとして、同じ bitbank API に対する真逆のアプローチを提供する **CLI** ([bitbank-lab-cli](https://github.com/bitbankinc/bitbank-lab-cli)) もあります。
21
-
22
- - **この MCP サーバー** はサーバー側で計算済みの結論を LLM に渡す
23
- - **CLI** は生データを高速に取得し、LLM 自身に計算させる
24
-
25
- 指標のパラメータやロジックを完全にカスタマイズしたい場合は CLI 側を、すぐに使えるテクニカル分析・可視化を求める場合は MCP サーバー側を選んでください。
26
-
27
- ## 概要
28
- bitbank の公開 API から価格・板情報・約定履歴・ローソク足データを取得し、以下の分析を実行できます。
29
- → 全ツールの一覧と使い分けは [docs/tools.md](docs/tools.md) を参照。
30
-
31
- #### 取得できるデータ
32
- - リアルタイム価格(ティッカー)
33
- - 板情報(オーダーブック)
34
- - 約定履歴(売買方向・時刻)
35
- - ローソク足(1分足〜月足)
36
-
37
- #### 実行できる分析
38
- - テクニカル指標(SMA/RSI/ボリンジャーバンド/一目均衡表/MACD)
39
- - フロー分析(買い/売りの勢い・CVD・スパイク検出)
40
- - ボラティリティ分析(RV/ATR)
41
- - 板の圧力分析(価格帯ごとの買い/売り圧力)
42
- - パターン検出(ダブルトップ/ヘッドアンドショルダーズ等)
43
- - 総合スコア判定(複数指標を統合した強弱判定)
44
- - 長期パターンの現在地関連検出(detect_patterns: requireCurrentInPattern/currentRelevanceDays)
45
-
46
- #### 視覚化
47
- - Claude.ai の Visualizer で描画するためのコンパクトな整形データを返すツール群
48
- - `prepare_chart_data`: ローソク足 + 指標の時系列データ
49
- - `prepare_depth_data`: 板の累積 volume 階段データ
50
- - ファイル保存・Cursor 等の非 Visualizer 環境向けに SVG/PNG 形式のチャートも生成可能
51
- - `render_chart_svg` / `render_depth_svg` / `render_candle_pattern_diagram`
23
+ 指標の計算までサーバーで行い、結果を LLM に渡します。生データを LLM に計算させたいときは、姉妹プロジェクトの [bitbank-lab-cli](https://github.com/bitbankinc/bitbank-lab-cli) を使ってください。ツールの一覧は [docs/tools.md](docs/tools.md)。
52
24
 
53
25
  ## クイックスタート
54
26
 
55
- ### 前提条件
56
- - **Node.js 22 以上**(24 推奨)
57
- - `node -v` で確認できます
58
- - [公式サイト](https://nodejs.org/) からインストール
59
- - npm(Node.js に同梱されています)
60
- - 対応 OS: macOS / Linux / Windows(WSL 含む)
61
- - **Claude Desktop** アプリを [Claude 公式サイト](https://claude.com/ja/download) からダウンロードしてください
27
+ Node.js 22 以上(24 推奨)が必要です。npm の [`bitbank-lab-mcp`](https://www.npmjs.com/package/bitbank-lab-mcp) を `npx` で起動するので、clone は要りません。
62
28
 
63
- > 本プロジェクトは npm に [`bitbank-lab-mcp`](https://www.npmjs.com/package/bitbank-lab-mcp) として公開されています。
64
- > **ソースコードのクローンは不要**です(開発したい方向けの手順は[末尾の開発者向けセクション](#開発者向けソースから起動)を参照)。
29
+ ### 1. Claude Desktop に登録
65
30
 
66
- ### 1. Claude Desktop に登録(推奨)
31
+ 設定ファイルに追加し、Claude Desktop を再起動します(macOS は `Cmd+Q`、Windows は完全終了)。
67
32
 
68
- Claude Desktop が最も多くの方が使う想定の MCP クライアントです。
69
- `~/Library/Application Support/Claude/claude_desktop_config.json` に設定を追加します。
70
-
71
- 登録方法は2通りあります。**まず npx 方式を試し、動かない場合に絶対パス方式をお試しください。**
72
-
73
- #### npx 方式(推奨)
74
-
75
- Node.js のバージョンアップで設定を書き換える必要がないため、こちらを推奨します。
76
- nvm/volta などのバージョン管理ツールをお使いの方には特におすすめです。
77
-
78
- 用途に応じて **A〜C の 3 段階**から選びます。
79
-
80
- **A. Public データのみ:**
33
+ - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
34
+ - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
81
35
 
82
- 価格・板・ローソク足などの公開市場データの取得と分析。API キー不要。
36
+ **A. 公開データだけ(API キー不要)**
83
37
 
84
38
  ```json
85
39
  {
@@ -92,9 +46,9 @@ nvm/volta などのバージョン管理ツールをお使いの方には特に
92
46
  }
93
47
  ```
94
48
 
95
- **B. Private データ参照系(要 API キー):**
49
+ **B. 口座の参照(API キーが必要)**
96
50
 
97
- 資産残高・約定履歴・注文照会・ポートフォリオ分析などの読み取り専用。発注はできません。
51
+ キーの権限を「参照」だけにすれば、発注はできません。
98
52
 
99
53
  ```json
100
54
  {
@@ -111,13 +65,9 @@ nvm/volta などのバージョン管理ツールをお使いの方には特に
111
65
  }
112
66
  ```
113
67
 
114
- > ✅ **bitbank API の権限は「参照」のみ設定することを推奨**
115
-
116
- **C. 取引注文・注文キャンセル実行(要 API キー):**
117
-
118
- B に加えて、発注・注文キャンセルまで実行。実行前に必ず確認ステップ(preview → ユーザーの明示確認)が入ります。
68
+ **C. 発注・取消まで(API キーが必要)**
119
69
 
120
- Claude Desktop では確認カードのボタンから実行するため、B の設定に **`BITBANK_MCP_APPS_EXECUTE=1` を追加**してオプトインします(**既定は無効**。設定する前に下の「⚠️ `BITBANK_MCP_APPS_EXECUTE=1` を設定する前に読んでください」を確認してください)。
70
+ B に `BITBANK_MCP_APPS_EXECUTE=1` を足すと、確認カードのボタンで発注・取消できます(既定は無効)。
121
71
 
122
72
  ```json
123
73
  {
@@ -135,401 +85,98 @@ Claude Desktop では確認カードのボタンから実行するため、B の
135
85
  }
136
86
  ```
137
87
 
138
- > ✅ **bitbank API の権限は「参照」および「取引」のみ設定することを推奨**
139
- >
140
- > ※ **「出金」権限は有効化しないことを強く推奨します**。本サーバーは出金系ツール未実装のため不要です。
141
-
142
- 発注・取消の実行には**ユーザーの明示確認が必須**です。確認トークンは `content` / `structuredContent` には載りません。`BITBANK_MCP_APPS_EXECUTE=1` を設定し、かつクライアントが elicitation 非対応で MCP Apps UI を宣言している場合(Claude Desktop 等)に限り、確認カードに渡すためツール結果の `_meta` に載ります。この場合の安全性は「ホストが `_meta` を LLM に渡さない」ことに依存し、仕様上の保証はありません(下の「⚠️ `BITBANK_MCP_APPS_EXECUTE=1` を設定する前に読んでください」)。
143
-
144
- 確認の経路はクライアントによって変わります。
145
-
146
- | クライアント | 実行経路 |
147
- |---|---|
148
- | elicitation / MRTR 対応 | ネイティブ確認ダイアログで完結(**第一選択**。追加設定不要) |
149
- | MCP Apps UI 対応(Claude Desktop 等) | `BITBANK_MCP_APPS_EXECUTE=1` を設定した場合のみ、確認カードのボタンで実行(**既定は無効**) |
150
- | どちらも非対応 | プレビューのみ。実行は bitbank アプリ/ウェブで |
151
-
152
88
  <details>
153
89
  <summary><b>⚠️ <code>BITBANK_MCP_APPS_EXECUTE=1</code> を設定する前に読んでください</b></summary>
154
90
 
155
- このオプションは、確認トークンをツール結果の `_meta` にのみ載せて iframe へ渡し、確認カードのボタンからの実行を許可します。安全性は「**ホストが `_meta` をモデル(LLM)に渡さない**」という前提に依存します。
156
-
157
- * **仕様上の保証ではありません。** MCP Apps 仕様の該当記述は "Best Practices" の箇条書きで、MUST / SHOULD を伴いません。適合要件ではなく意図の説明です
158
- * **ホストのアップデートで壊れても、サーバー側では検知できません。** ホストが `_meta` をモデルコンテキストに含めるようになった瞬間に前提は崩れますが、その変化はサーバーから観測できません。**壊れ方は静かです**
159
- * この領域は実装が流動的です(`structuredContent` の喪失回帰など、関連トラッカーに 2026-05〜08 の issue が複数)
91
+ 確認トークンを、ツール結果の `_meta` と、一覧に出さないリソース `bitbank-confirmation://{app}` に載せてカードへ渡します。安全性は「**ホストが `_meta` をモデルに渡さず、MCP リソースもモデルに読ませない**」ことに依存します。
160
92
 
161
- 万一トークンが漏れた場合でも、被害は **「直前にプレビューした注文 1 件(一括取消ならプレビュー済みの注文 ID 集合 1 セット)が、60 秒以内に 1 回だけ実行される」** に限定されます。トークンは注文内容に HMAC で束縛されており、攻撃者が金額・数量・ペア・方向を選ぶことはできません。
93
+ * **仕様上の保証ではありません**(MCP Apps 仕様の "Best Practices" の記述で、MUST / SHOULD ではない)
94
+ * **ホストの更新で前提が崩れても、サーバーは検知できません**
95
+ * 確認の状態(トークンと注文内容)を `~/.bitbank-lab-mcp/confirm` に置きます。**ファイルを読める AI エージェントには、このフォルダを許可しないでください**
96
+ * Windows では、Claude Desktop のボタンが出ない見込みです(未確認)
162
97
 
163
- **以上を理解したうえで有効化してください。既定では無効です。** 詳細は [ADR-0007](docs/adr/0007-hitl-confirmation-token-delivery.md)。
98
+ トークンが漏れた場合の被害は、**直前にプレビューした注文 1 件(一括取消なら 1 セット)が、期限(既定 60 秒、最長 5 分)内に 1 回実行されること**に限られます。金額・数量・ペア・方向は変えられません。詳細は [ADR-0007](docs/adr/0007-hitl-confirmation-token-delivery.md)。
164
99
 
165
100
  </details>
166
101
 
167
- 詳細: [ADR-0007](docs/adr/0007-hitl-confirmation-token-delivery.md) / [Private API ガイド](docs/private-api.md)。
168
-
169
- B / C の API キーは [bitbank 設定画面](https://app.bitbank.cc/account/api) で発行し、**必要最小限の権限のみ**を付与、可能なら **IP 制限**も設定してください(最小権限の原則)。
170
-
171
- 詳細: [Private API ガイド](docs/private-api.md)。
172
-
173
- #### 絶対パス方式(フォールバック)
174
-
175
- npx 方式で「サーバーに接続できません」エラーが出る場合、Claude Desktop から `npx` コマンドが見つけられていない可能性があります。
176
- その場合は、`npx` の絶対パスを指定してください。
177
-
178
- まずターミナルで自分の環境の `npx` パスを確認します:
179
-
180
- ```bash
181
- which npx
182
- ```
183
-
184
- 出力例と対応するインストール方法:
185
-
186
- | `which npx` の出力 | インストール方法 |
187
- |---|---|
188
- | `/opt/homebrew/bin/npx` | Homebrew(Apple Silicon Mac) |
189
- | `/usr/local/bin/npx` | Homebrew(Intel Mac)または公式インストーラ |
190
- | `/Users/XXX/.nvm/versions/node/vXX.XX.X/bin/npx` | nvm |
191
- | `/Users/XXX/.volta/bin/npx` | volta |
192
-
193
- `which npx` の結果を `command` に指定:
194
-
195
- ```json
196
- {
197
- "mcpServers": {
198
- "bitbank-lab": {
199
- "command": "<which npx の出力>",
200
- "args": ["-y", "bitbank-lab-mcp"]
201
- }
202
- }
203
- }
204
- ```
205
-
206
- > ⚠️ **nvm/volta ユーザーへの注意**: この方式では Node.js をバージョンアップするたびに `command` のパスの書き換えが必要です(例: `v24.0.0` → `v24.1.0`)。アップデート後に `which npx` を再確認してください。
207
-
208
- #### Windows の場合
209
-
210
- Windows でも npx 方式がそのまま使えます:
211
-
212
- ```json
213
- {
214
- "mcpServers": {
215
- "bitbank-lab": {
216
- "command": "npx",
217
- "args": ["-y", "bitbank-lab-mcp"]
218
- }
219
- }
220
- }
221
- ```
222
-
223
- 設定ファイルの場所: `%APPDATA%\Claude\claude_desktop_config.json`
224
-
225
- `npx` が見つからない場合は `where npx`(Windows 版の `which`)で絶対パスを確認して指定してください。
226
-
227
- #### 表示名のカスタマイズ
228
-
229
- Claude Desktop の UI に表示される名前は `claude_desktop_config.json` のキー名で決まります:
230
-
231
- ```json
232
- {
233
- "mcpServers": {
234
- "bitbank-lab-mcp": {
235
- "command": "npx",
236
- "args": ["-y", "bitbank-lab-mcp"]
237
- }
238
- }
239
- }
240
- ```
241
-
242
- > ⚠️ `bitbank-lab-mcp` のような ASCII(英数字)の名前を推奨します。環境によって、日本語などの非 ASCII 名だと Chat でツールが見つからない事例があります。
243
-
244
- #### 共通の注意事項
245
-
246
- - 追加後、Claude Desktop を `Cmd+Q`(Windows は完全終了)で再起動してください
247
- - ⚠️ macOS で `claude_desktop_config.json` が見つからない場合は、ホームディレクトリ直下から開いてください
248
-
249
- 設定ファイルの場所:
250
- - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
251
- - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
252
-
253
- ### 2. その他の MCP クライアント(手動 `.json` 編集)
254
-
255
- #### Cursor(`.cursor/mcp.json`)
256
-
257
- ```json
258
- {
259
- "mcpServers": {
260
- "bitbank-lab": {
261
- "command": "npx",
262
- "args": ["-y", "bitbank-lab-mcp"],
263
- "env": {
264
- "BITBANK_API_KEY": "your_api_key",
265
- "BITBANK_API_SECRET": "your_api_secret"
266
- }
267
- }
268
- }
269
- }
270
- ```
271
-
272
- API キーが不要な場合は `env` ブロックごと削除して OK。セクション 1 の A〜C と同様に、取引実行まで使う場合は確認フローに対応したクライアントが必要です。
273
-
274
- #### Claude Code(CLI から登録する場合)
102
+ API キーの権限は「[API キー](#api-キー)」を参照してください(**「出金」は付けない**)。
275
103
 
276
- ```bash
277
- claude mcp add --transport stdio bitbank-lab -- npx -y bitbank-lab-mcp
278
- ```
279
-
280
- 同梱 Skill も一緒に使いたい場合は、[セクション 3](#3-オプションplugin-として-install同梱-skill-を使う) の plugin install が便利です。
281
-
282
- #### Windsurf / その他の汎用 MCP クライアント
283
-
284
- Cursor と同じ JSON 形式で登録できます。クライアント固有の設定ファイルパスについては各クライアントのドキュメントを参照してください。
285
-
286
- ### 3. (オプション)Plugin として install(同梱 Skill を使う)
104
+ ### 2. ほかのクライアント
287
105
 
288
- 通常の利用はセクション 1〜2 の登録だけで完結します。Plugin install は、**Claude Code などの AI コーディングツールで、MCP サーバーに加えて同梱 Skill(`plugins/bitbank-lab-mcp/skills/` 配下)も使いたい方向け**のオプションです。
106
+ - **Claude Code**:`claude mcp add --transport stdio bitbank-lab -- npx -y bitbank-lab-mcp`
107
+ - **Cursor**(`.cursor/mcp.json`)・**Windsurf** など:上と同じ JSON で登録します。
289
108
 
290
- - Plugin として install すると、MCP ツールと同時に同梱 Skill(例: `investment-onboarding`)が有効化されます。今後 Skill を追加した場合も、plugin のアップデートでまとめて届きます。
291
- - Skill を自作してワークフローをカスタマイズしたい方は、[`plugins/bitbank-lab-mcp/skills/INDEX.md`](plugins/bitbank-lab-mcp/skills/INDEX.md) の構成が参考になります。
292
- - **Claude Desktop は plugin / Skill の読み込みに未対応**です。Claude Desktop で使う場合は[セクション 1](#1-claude-desktop-に登録推奨) の方法で登録してください(MCP ツールの機能は同じで、Skill が使えるかどうかだけの違いです)。
109
+ ### 3. Plugin として入れる(同梱 Skill も使う)
293
110
 
294
- | クライアント | manifest | API キーの渡し方 |
295
- |---|---|---|
296
- | Claude Code | `plugins/bitbank-lab-mcp/.claude-plugin/plugin.json` | ✅ **GUI で入力**: `/plugin install` 直後に `userConfig` UI が表示され、OS キーチェーンに保管 |
297
- | Antigravity CLI(旧 Gemini CLI) | `gemini-extension.json` | ✅ **対話 prompt**: `settings` 配列で対話的に入力、`.env` に保管 |
298
- | Cursor | `.cursor-plugin/plugin.json` | ⚙️ **シェル環境変数のみ**: `BITBANK_API_KEY` / `BITBANK_API_SECRET` を環境変数に設定(Cursor は plugin 経由の prompt 未対応) |
299
- | Codex | `.codex-plugin/plugin.json` | ⚙️ **シェル環境変数のみ**: `BITBANK_API_KEY` / `BITBANK_API_SECRET` を環境変数に設定 |
300
-
301
- > いずれの manifest も npm registry の [`bitbank-lab-mcp`](https://www.npmjs.com/package/bitbank-lab-mcp) を `npx -y` 経由で起動します。
302
- >
303
- > Gemini CLI は 2026-06-18 に個人アカウント向け提供を終了し、Antigravity CLI(`agy`)に移行しました。Antigravity CLI は旧 Gemini CLI 拡張(`gemini-extension.json`)を後方互換で読み込みます(`agy plugin import gemini` でネイティブ plugin へ変換も可能)。
304
-
305
- **Claude Code の例**:
111
+ Claude Code では、同梱の Skill(`investment-onboarding` など)も一緒に入ります。Claude Desktop は plugin に未対応です。
306
112
 
307
113
  ```bash
308
- # 1. このリポジトリを marketplace として登録(初回のみ)
309
114
  /plugin marketplace add bitbankinc/bitbank-lab-mcp
310
-
311
- # 2. plugin を install
312
115
  /plugin install bitbank-lab-mcp@bitbank-lab
313
-
314
- # 3. plugin を有効化
315
116
  /reload-plugins
316
117
  ```
317
118
 
318
- `bitbank-lab` はこのリポが提供する marketplace 名(`.claude-plugin/marketplace.json` の `name` フィールド)、`bitbank-lab-mcp` は plugin 名です。
319
-
320
- 実行後、bitbank API key / API secret の入力 UI が表示されます。**Public ツールだけで使う場合は両方とも空欄で OK** — Private API ツールは API キーを入力したときだけ自動的に有効化されます。
321
-
322
- > API キーを後から追加・変更したい場合は `/plugin` から該当 plugin の設定を開き、`api_key` / `api_secret` を更新してください。Claude Code では `sensitive: true` のため OS のキーチェーンに保管されます。
323
-
324
- **Cursor / Codex の場合(環境変数経由)**:
325
-
326
- `/plugin install` 実行後、シェルで以下のように環境変数を設定してから Cursor / Codex を起動してください(Public ツールだけ使う場合は不要):
327
-
328
- ```bash
329
- export BITBANK_API_KEY="your_api_key"
330
- export BITBANK_API_SECRET="your_api_secret"
331
- ```
332
-
333
- macOS / Linux では `~/.zshrc` や `~/.bashrc` に書いておくと永続化されます。Windows は環境変数の管理画面 or `setx` を使用してください。
119
+ API キーは install 後の画面で入力します(公開データだけなら空欄で OK)。Cursor・Codex・Antigravity CLI 向けの manifest もあります(Cursor・Codex は環境変数でキーを渡します)。
334
120
 
335
121
  ### 4. 使ってみる
336
- AI クライアントにそのまま話しかけます:
122
+
337
123
  ```
338
124
  BTCの今の市場状況を分析して
339
125
  ビットコインは買いと売りどちらが優勢?
340
126
  直近 1 週間でテクニカル的に上向きの仮想通貨を 3 つ教えて
341
127
  ```
342
128
 
343
- 💡 **何を聞けばいいかわからない場合**: [用意されたプロンプト集](docs/prompts-table.md) をご覧ください。初心者向け(🔰)から中級者向けまで、9種類の分析プロンプトを用意しています。
344
-
345
- 🌅 **朝のルーティンに**: 「おはようレポート」で、寝ている間の相場変動をすばやくキャッチアップできます。
346
-
347
-
348
- ## Private API(取引機能)
349
-
350
- API キーの有無でサーバーが公開する機能が自動的に切り替わります。
351
-
352
- | 設定 | ツール数 | プロンプト数 | 使える機能 |
353
- |------|---------|------------|-----------|
354
- | キー未設定 | 33(Public のみ) | 8 | 価格取得・テクニカル分析・チャート生成・バックテスト |
355
- | キー設定済み | 33 + 16 = **49** | 8 + 1 = **9** | 上記 + 資産確認・注文・ポートフォリオ分析 |
129
+ 何を聞けばよいか迷ったら、[プロンプト集](docs/prompts-table.md) を見てください。
356
130
 
357
- キー未設定時、Private ツール・プロンプトは MCP クライアントに一切表示されません(エラーではなく、そもそも登録されません)。公開データの取得・分析だけなら設定不要で、そのまま使えます。
131
+ ## API キー
358
132
 
359
- ### 環境変数の設定方法
133
+ キーを設定すると、口座のツールとプロンプトが使えるようになります(未設定なら表示されません)。
360
134
 
361
- **ターミナルから起動する場合:**
362
- ```bash
363
- export BITBANK_API_KEY="your_api_key"
364
- export BITBANK_API_SECRET="your_api_secret"
365
- ```
366
-
367
- **Plugin install を使った場合** — `/plugin` から該当 plugin の設定を開き、`api_key` / `api_secret` を入力すれば完了です(手動編集は不要)。
368
-
369
- **Claude Desktop で手動設定している場合** — `claude_desktop_config.json` の `env` に追加([セクション 1](#1-claude-desktop-に登録推奨) で設定した npx 方式/絶対パス方式のいずれかに、以下のように `BITBANK_API_KEY` と `BITBANK_API_SECRET` を追加するだけです):
370
- ```json
371
- {
372
- "mcpServers": {
373
- "bitbank-lab": {
374
- "command": "npx",
375
- "args": ["-y", "bitbank-lab-mcp"],
376
- "env": {
377
- "BITBANK_API_KEY": "your_api_key",
378
- "BITBANK_API_SECRET": "your_api_secret"
379
- }
380
- }
381
- }
382
- }
383
- ```
135
+ [bitbank の設定画面](https://app.bitbank.cc/account/api) で発行し、必要な権限だけを付けてください。可能なら IP 制限も設定してください。
384
136
 
385
- API キーは [bitbank 設定画面](https://app.bitbank.cc/account/api) で発行してください。**必要最小限の権限のみ付与する**ことを強く推奨します(最小権限の原則)。
386
-
387
- | やりたいこと | 必要な権限 |
137
+ | 使い方 | 権限 |
388
138
  |---|---|
389
- | 資産確認・ポートフォリオ分析(読み取り専用) | **「参照」のみ** ← 最も安全、迷ったらこちら |
390
- | 上記 + AI に発注・キャンセル操作も任せたい | 「参照」+「取引」 |
391
-
392
- ⚠️ **「出金」権限は絶対に有効化しないでください**。本 MCP サーバーは出金系ツールを実装していないため、この権限を付ける必要は一切ありません。漏洩時の資産流出を避けるためです。
393
-
394
- **IP 制限**: bitbank 側で API キーに IP 制限を設定できる場合は、可能な限り設定を推奨します。
395
-
396
- | カテゴリ | ツール | 説明 | 必要な権限 |
397
- |---|---|---|---|
398
- | 口座情報 | `get_my_assets` | 保有資産一覧 | 参照 |
399
- | 注文照会 | `get_my_orders`, `get_order`, `get_orders_info` | 注文の照会 | 参照 |
400
- | 約定履歴 | `get_my_trade_history` | 約定履歴の取得 | 参照 |
401
- | ポートフォリオ | `analyze_my_portfolio` | 損益分析・パフォーマンス | 参照 |
402
- | 入出金 | `get_my_deposit_withdrawal` | 入出金履歴 | 参照 |
403
- | 信用取引 | `get_margin_status`, `get_margin_positions`, `get_margin_trade_history` | 証拠金・ポジション・約定履歴 | 参照 |
404
- | 発注 | `preview_order`(→ ユーザー確認) | ユーザー明示確認後に発注 | 取引 |
405
- | キャンセル | `preview_cancel_order`(→ ユーザー確認) | ユーザー明示確認後にキャンセル | 取引 |
406
- | 一括キャンセル | `preview_cancel_orders`(→ ユーザー確認) | ユーザー明示確認後に一括キャンセル | 取引 |
407
-
408
- 取引操作(発注・キャンセル)は **preview → ユーザーの明示確認**が必須です。確認トークンは `content` / `structuredContent` に載らず、`create_order` / `cancel_order` / `cancel_orders` を MCP `tools/call` から直接呼んでもサーバー側で拒否されます。
409
-
410
- 詳細: [docs/private-api.md](docs/private-api.md)
139
+ | 資産・注文・損益を見るだけ | 「参照」 |
140
+ | 発注・取消もする | 「参照」+「取引」 |
411
141
 
412
- ## 使用例(会話の型)
413
- - 「今、BTC は買いですか?」→ `analyze_market_signal`: 総合スコア + 寄与度・根拠
414
- - 「直近で MACD クロスした銘柄は?」→ `detect_macd_cross`: スクリーニング結果
415
- - 「ここ 30 日のボラ推移を見たい」→ `get_volatility_metrics` + `render_chart_svg`
142
+ ⚠️ **「出金」権限は付けないでください**。出金のツールはありません。
416
143
 
417
- ## チャート表示(SVG)
418
- - MCP クライアント(Claude)では、アーティファクトとして `data.svg` を表示するようにお願いしてください。
419
- - Claude で LLM がうまくアーティファクトを出力できない場合は、以下のプロンプトを加えるのがおすすめです。
420
- - 「identifier と title を追加して、アーティファクトとして表示して」
421
- - 既定の描画は「ロウソク足のみ」。ボリンジャーバンド等のオーバーレイは明示指定時に追加されます(BBは `--bb-mode=default` 指定時に ±2σ がデフォルト)。
144
+ キーの渡し方:Claude Desktop は設定の `env`(上の B / C)、Claude Code の plugin は install 後の画面、それ以外は環境変数 `BITBANK_API_KEY` / `BITBANK_API_SECRET`。
422
145
 
423
- ## 詳細ドキュメント
424
- - プロンプト集(初心者〜中級者向け): [docs/prompts-table.md](docs/prompts-table.md)
425
- - ツール一覧と使い分け: [docs/tools.md](docs/tools.md)
426
- - Private API ガイド: [docs/private-api.md](docs/private-api.md)
427
- - 変更履歴: [CHANGELOG.md](CHANGELOG.md)
428
- - 開発者向けガイド(型生成・CI など): [CLAUDE.md](CLAUDE.md)
429
- - 運用・監視(ログ集計/Docker起動 ほか): [docs/ops.md](docs/ops.md)
146
+ ### 発注・取消の確認
430
147
 
431
- ## よくある質問(FAQ)
432
- **Q. 何を聞けばいいかわからない** [プロンプト集](docs/prompts-table.md) を参照してください。初心者向け🔰から中級者向けまで9種類の分析プロンプトを用意しています。
148
+ 発注・取消は、プレビューのあとにユーザーの確認が要ります。確認トークンなしで `create_order` などを呼んでも拒否されます。
433
149
 
434
- **Q. Docker は必須?** いいえ。Node 18+ でローカル実行できます(最短は Claude Desktop 登録)。
435
-
436
- **Q. API キーは必要?** 公開データの取得・分析には不要です。自分の資産確認や注文操作(Private API)を使う場合は [Private API ガイド](docs/private-api.md) を参照してください。
437
-
438
- **Q. どのツールを使えばよい?** まず `analyze_market_signal` で全体を把握 → 必要に応じて各専門ツールへ。
439
-
440
- **Q. 対応銘柄は固定?** 固定ではありません。上流の公開 API が返す銘柄に自動追随します(追加/廃止も自動反映)。参考: [bitbank 公開API仕様](https://github.com/bitbankinc/bitbank-api-docs/blob/master/public-api.md)
441
-
442
- **Q. MCP Inspector でも試せる?** はい。次で実行できます(npm 公開版に対する動作確認)。
443
- ```bash
444
- npx @modelcontextprotocol/inspector -- npx -y bitbank-lab-mcp
445
- ```
446
- ソースコードから動かす場合は `npx @modelcontextprotocol/inspector -- tsx src/server.ts`([開発者向け](#開発者向けソースから起動) を参照)。
447
-
448
- **Q. 当日の約定(フロー)データが少ない・古い時間帯が取れない** bitbank 側の仕様です。約定履歴の日付アーカイブ(`/transactions/{YYYYMMDD}`)は **UTC 暦日単位**で、当該 UTC 日の完了後(日本時間 9:00 以降、さらに公開遅延あり)にのみ公開されます。進行中の UTC 日の約定は直近約 60 件(latest)しか取得できないため、`get_flow_metrics` 等では当日区間のカバレッジが限定的になります(結果に warning として明示されます)。ローソク足(`get_candles`)は進行中の UTC 日でもリアルタイムで取得できます。<br>なお**公開済みの過去区間**であれば、`get_flow_metrics` / `analyze_volume_profile` の `since` / `until`(オフセット付き ISO8601、最大 7 日)でその区間の**全件**を集計できます(例: `since=2026-08-01T00:00:00Z`, `until=2026-08-02T00:00:00Z` で UTC 8/1 の 1 日ぶん)。件数上限による切り捨ては起きません。
449
-
450
- ## トラブルシューティング
451
-
452
- | 症状 | 原因・対処 |
453
- |------|-----------|
454
- | Claude Desktop にツールが表示されない | `claude_desktop_config.json` の JSON 構文が壊れている / Claude Desktop を `Cmd+Q`(Windows は完全終了)で再起動していない |
455
- | 「サーバーに接続できません」エラー(npx 方式) | Claude Desktop から `npx` が見つからない可能性。[絶対パス方式](#絶対パス方式フォールバック)に切り替える |
456
- | `spawn npx ENOENT` エラー | `which npx` の結果が異なるパスを指している。`command` を正しいパスに書き換える |
457
- | Node.js アップデート後に MCP が動かなくなった | nvm/volta の場合、Node.js バージョンが変わると絶対パスも変わる。`which npx` を再確認して `command` を更新するか、npx 方式(`npx` 名指し)に切り替える |
458
- | `Cannot find package 'tsx'` エラー | `bitbank-lab-mcp` の古い版(v0.1.0)でこの問題が発生。`npx -y bitbank-lab-mcp@latest` で最新版に更新するか、設定を再起動 |
459
- | ツール実行時にタイムアウト | ネットワーク接続を確認 / [bitbank API の状態](https://status.bitbank.cc/)を確認 |
460
- | Private API ツールが表示されない | `BITBANK_API_KEY` と `BITBANK_API_SECRET` の両方が設定されているか確認(→ [docs/private-api.md](docs/private-api.md)) |
461
- | ログを確認したい | `env` に `"LOG_LEVEL": "debug"` を追加して再起動 |
462
- | Plugin install で「Marketplace not found」 | `/plugin marketplace add bitbankinc/bitbank-lab-mcp` を先に実行してから `/plugin install bitbank-lab-mcp@bitbank-lab` |
463
-
464
- ---
465
-
466
- ## 開発者向け(ソースから起動)
467
-
468
- このセクションは「自分で MCP サーバーをいじりたい」「PR を送りたい」という開発者向けです。**通常の利用者は[セクション 1](#1-claude-desktop-に登録推奨) の `npx -y bitbank-lab-mcp` 方式で OK** です(こちらは clone 不要)。
469
-
470
- ### セットアップ
471
-
472
- ```bash
473
- git clone https://github.com/bitbankinc/bitbank-lab-mcp.git
474
- cd bitbank-lab-mcp
475
- npm ci
476
- ```
477
-
478
- `package-lock.json` 通りに依存をインストールするため、ローカル開発でも `npm install` ではなく `npm ci` を推奨します(CI も `npm ci` を使用)。
479
-
480
- ビルドステップは不要です(tsx で TypeScript を直接実行します)。
481
-
482
- ### STDIO モード(Claude Desktop / Claude Code 向け)
483
-
484
- ローカルの開発版を Claude Desktop から使いたい場合、`claude_desktop_config.json` に絶対パス指定で登録します:
485
-
486
- ```json
487
- {
488
- "mcpServers": {
489
- "bitbank-dev": {
490
- "command": "npx",
491
- "args": ["tsx", "/ABS/PATH/to/src/server.ts"],
492
- "workingDirectory": "/ABS/PATH/to/project",
493
- "env": { "LOG_LEVEL": "debug", "NO_COLOR": "1" }
494
- }
495
- }
496
- }
497
- ```
498
-
499
- `/ABS/PATH/to/` を実際のクローン先パス(`pwd` で確認)に置き換えてください。**npm 公開版(`bitbank-lab`)と区別するため、サーバー名は `bitbank-dev` 等にしておくと両立できます**。
500
-
501
- Inspector で動作確認する場合:
502
- ```bash
503
- npx @modelcontextprotocol/inspector -- tsx src/server.ts
504
- ```
505
-
506
- ### Windows でローカル開発する場合
507
-
508
- `npx` が PATH 解決できない環境では、`node` の絶対パスと `tsx` の CLI を直接指定します:
509
-
510
- ```json
511
- {
512
- "mcpServers": {
513
- "bitbank-dev": {
514
- "command": "node",
515
- "args": [
516
- "C:\\Users\\<USERNAME>\\bitbank-lab-mcp\\node_modules\\tsx\\dist\\cli.mjs",
517
- "C:\\Users\\<USERNAME>\\bitbank-lab-mcp\\src\\server.ts"
518
- ],
519
- "workingDirectory": "C:\\Users\\<USERNAME>\\bitbank-lab-mcp",
520
- "env": { "LOG_LEVEL": "debug", "NO_COLOR": "1" }
521
- }
522
- }
523
- }
524
- ```
525
-
526
- ### CI / 型生成 / リンター
527
-
528
- 開発時のコマンド一覧は [CLAUDE.md](CLAUDE.md) を参照してください(`npm test` / `npm run lint:fix` / `npm run gen:types` 等)。
529
-
530
- ## フィードバック・バグ報告
531
-
532
- バグ報告や機能要望は [GitHub Issues](https://github.com/bitbankinc/bitbank-lab-mcp/issues) からお願いします。Issue テンプレートを用意していますので、用途に合ったものを選択してください。
150
+ | クライアント | 実行のしかた |
151
+ |---|---|
152
+ | elicitation 対応 | 確認ダイアログ(追加の設定なし) |
153
+ | MCP Apps UI 対応(Claude Desktop など) | `BITBANK_MCP_APPS_EXECUTE=1` のときだけ、確認カードのボタン |
154
+ | どちらも非対応 | プレビューだけ(実行は bitbank のアプリ・ウェブで) |
155
+
156
+ 詳細は [Private API ガイド](docs/private-api.md)。
157
+
158
+ ## 困ったとき
159
+
160
+ - **「サーバーに接続できません」・`spawn npx ENOENT`**:Claude Desktop が `npx` を見つけられていません。`which npx`(Windows は `where.exe npx`)の出力を `command` に書きます。nvm / volta では `node` も見つからないことがあるので、`env` に `"PATH": "<which node のフォルダ>:/usr/bin:/bin"` も足します(Node.js を更新するとパスが変わります)。
161
+ - **ツールが表示されない**:JSON の構文と再起動を確認します。`mcpServers` のキー(サーバー名)は英数字にしてください(日本語だとツールが見つからないことがあります)。
162
+ - **口座のツールが表示されない**:`BITBANK_API_KEY` と `BITBANK_API_SECRET` の両方を設定しているか確認します。
163
+ - **タイムアウトする**:ネットワークと [bitbank API の状態](https://status.bitbank.cc/) を確認します。
164
+ - **`Cannot find package 'tsx'`**:古い版(v0.1.0)の問題です。`npx -y bitbank-lab-mcp@latest` にします。
165
+ - **チャートが表示されない**:「identifier と title を追加して、アーティファクトとして表示して」と頼んでください。
166
+ - **当日の約定データが少ない**:bitbank の仕様です。日ごとの約定履歴は UTC の 1 日が終わってから(日本時間 9:00 以降)公開されるので、当日分は直近の約 60 件しか取れません(結果に warning が出ます)。公開済みの期間は、`get_flow_metrics` / `analyze_volume_profile` の `since` / `until`(最大 7 日)で全件を集計できます。
167
+ - **ログを見たい**:`env` に `"LOG_LEVEL": "debug"` を足して再起動します。
168
+ - **MCP Inspector で試したい**:`npx @modelcontextprotocol/inspector -- npx -y bitbank-lab-mcp`
169
+
170
+ ## ドキュメント
171
+
172
+ - [プロンプト集](docs/prompts-table.md)
173
+ - [ツール一覧](docs/tools.md)
174
+ - [Private API ガイド](docs/private-api.md)
175
+ - [変更履歴](CHANGELOG.md)
176
+ - [開発者向け(ソースから起動)](docs/development.md) / [開発コマンド](CLAUDE.md)
177
+ - [運用・監視](docs/ops.md)
178
+
179
+ バグ報告や要望は [GitHub Issues](https://github.com/bitbankinc/bitbank-lab-mcp/issues) へ。
533
180
 
534
181
  ## 免責事項
535
182