MangroveAI

---

これは何か

次の機能を備えたローカル AI 取引エージェントです。

• 自然言語の目標（「ETH のモメンタム」など）を、MangroveAI API を通じてバックテスト済みのランキング付き取引戦略に変換します。
• APScheduler の cron ジョブでライブ戦略を実行します。ペーパー取引とライブ取引で同じ評価経路を使います。
• MangroveMarkets を通じてライブ DEX スワップを実行します。10 の EVM チェーン（Ethereum、Base、Arbitrum、Polygon、Optimism、BNB、Avalanche、zkSync Era、Gnosis、Linea）で 1inch によるルーティングを行います（エージェントのデフォルトは Base です）。署名はクライアント側で行い、ルーティングサーバーがキーに触れることはありません。
• Kraken での取引にも対応し、2 つの接続モードがあります。独自のキーを使用（/setup-kraken — 最小限の権限を持ち、マシン内に保持して Kraken と直接通信する API キーを使用）する方法と、キー不要の OAuth（/connect-kraken — ブラウザーで一度同意するだけで、キーの管理は不要）を利用できます。
• DEX と CEX のすべての評価と取引をローカルの SQLite に記録し、完全な監査証跡を残します。

利用できる機能

• 119 個のツール（2026 年 10 月時点。2026-10-20 に Claude Code の /mcp で 119 個と表示）。エージェントが中継するホスト型 MangroveAI カタログと、ローカルツールを合わせた数です。最新のカタログを確認するには、エンドポイントに対して list_tools を実行してください。
• .claude/skills に 7 個のエージェントスキルがあります：audit-security、check-alignment、connect-kraken、setup-kraken、setup-robinhood、tool-spec、trading-bot。Claude Code プラグインでは、そのうち 4 個が組み込まれています。
• MCP サーバーと同じエージェントに REST API（FastAPI）があります。
• Claude Code プラグインとしてインストールできます。詳しくはClaude Code プラグインとしてインストールをご覧ください。
• **Codex およびあらゆる MCP クライアントで動作します。**ローカルの MCP エンドポイントは http://127.0.0.1:9080/mcp/ です。Codex から使用するをご覧ください。
• https://api.mangrovedeveloper.ai/mcp/ に ホスト型 MangroveAI MCP サーバーがあります（ストリーミング可能な HTTP を使用し、認証なしで initialize に応答します）。
• **料金：**https://mangrovedeveloper.ai で無料の API キーを取得するか、USDC による x402 の従量課金をご利用ください。
• **ノンカストディアル：**Kraken（独自のキーを使用、または OAuth）、Robinhood、10 の EVM チェーンに対応した 1inch で取引を実行します。キーとウォレットはお使いのマシン上に保持されます。

エージェント開発者向けの詳細：https://mangrove.ai/agents/ および https://mangrove.ai/llms.txt

プラットフォームの全ドキュメントと取引ナレッジベースは **https://mangrove.io/docs**（KB：https://mangrove.io/knowledge-base）にあります。エージェントの kb_search ツールは同じコーパスを検索します。

エージェントによる実際のメインネットスワップ（2026 年 4 月に検証済み）：0x5c126e...c5565

---

AI クライアントで Mangrove エージェントを使う

インストール、名前の設定、後からの再開、クライアントの切り替えについては、まずユーザーガイドをご覧ください。

Claude Code、Codex、Grok Build、または Perplexity Computerに次のように伝えてください。

Install https://github.com/MangroveTechnologies/mangrove-agent and follow its AI client installation instructions.

インストールを行うエージェント向け：AI クライアントのセットアップに従ってください。実行環境にサーバーをインストールし、エージェントの完全な指示を読み込み、ツールを検出して、成功を報告する前に無料の status ツールを呼び出してください。Perplexity Computer では、付属のコマンドクライアントを使用できます。このインストールでは、Perplexity Project の作成、カスタムクラウドコネクターの設定、別のデスクトップアプリのインストールは必要ありません。

エージェントの共通のアイデンティティと操作手順は SAGE.md にあります。初回起動時に、エージェントの名前を尋ねます。この名前はローカルに保存され、クライアント間で再利用されます。個人名のデフォルトはありません。 AGENTS.md は Codex と互換性のあるクライアントをそこへ誘導し、CLAUDE.md は Claude Code 用にそのファイルを読み込みます。Codex と Grok Build の起動ヘルパー、MCP 設定テンプレート、Perplexity／Web 用の完全な指示一式については、AI クライアントのセットアップに記載されています。ツールへのアクセスは、各クライアントで個別に設定し、確認します。

setup.sh でインストールする（API キーまたは x402）

リポジトリをクローンして、./scripts/setup.sh を実行してください。既存の MangroveAI API キーを使うか、ウォレット決済（x402、登録不要）を選択します。このスクリプトはローカルアクセスを保護し、エージェントを起動して、CLI が利用可能な場合は Claude を登録します。x402 の場合は、最後のメニューにウォレットの手順が表示されるので、ご自身で実行してください。ウォレットの作成・インポートや支払いが自動的に行われることはありません。セットアップとウォレットの流れの詳細をご覧ください。

Claude Code プラグインとしてインストールする（API キーが必要です）

既存の API キーを使うプラグインの手順では、Claude Code エージェントに 「このトレーディングボットをインストールして：https://github.com/MangroveTechnologies/mangrove-agent」 と伝えるか、次のコマンドを自分で実行します。

claude plugin marketplace add MangroveTechnologies/mangrove-agent
claude plugin install mangrove-agent@mangrove

Claude Code のセッション中は、同じ操作を /plugin marketplace add MangroveTechnologies/mangrove-agent、続けて /plugin install mangrove-agent@mangrove と実行します。Claude Code は MangroveAI API キー（https://mangrovedeveloper.ai で無料）を求め、機密設定として保存します。キーをチャットに貼り付けないでください。

新しいセッションを開始します。初回起動時に、プラグインが Python の依存関係をインストールし、エージェントをバックグラウンドで起動します（約1～3分）。その後、「使い方を案内して」 または 「ETH のモメンタム戦略を作って」 と伝えます。

• 必要なもの： Python 3.11 以降と bash シェル（macOS、Linux、または Windows 上の WSL / Git Bash）。
• データの保存場所： ~/.mangrove-agent/ に、設定、SQLite DB（ウォレット、戦略、取引）、ウォレットのマスターキーが保存されます。プラグインを更新しても保持されます。資金を保有したらバックアップを取り、ウォレットに資金がある間は削除しないでください。
• ネットワーク： エージェントは 127.0.0.1:9080 のみでリッスンします。9080 で git clone 版のエージェントも実行しないでください。
• ログ： ~/.mangrove-agent/agent-data/agent.log（サーバー）および bootstrap.log（インストール／起動）。

コードを変更しますか？ 代わりにリポジトリをクローンしてください（下記参照）。どちらの方法でも、同じエージェントが動作します。

Codex から使う

このリポジトリには、Codex マーケットプレイスファイル .agents/plugins/marketplace.json が含まれています。ターミナルからマーケットプレイスを追加します。

codex plugin marketplace add MangroveTechnologies/mangrove-agent

OpenAI の Codex プラグインのドキュメントによると、プラグインは ChatGPT デスクトップアプリの Plugins Directory からインストールします（アプリを再起動し、Plugins Directory を開いて、mangrove マーケットプレイスを選び、mangrove-agent をインストールします）。ドキュメントには CLI でのインストールコマンドは記載されていません。1つのプロジェクトで有効にするには、そのリポジトリの .codex/config.toml に次の内容を追加します。

[plugins."mangrove-agent@mangrove"]
enabled = true

マーケットプレイスを使わず、.codex/config.toml.example のテンプレートを使って、Codex からローカル MCP サーバー（http://127.0.0.1:9080/mcp/）を指定することもできます。AI クライアントのセットアップを参照してください。

はじめに（git clone）

このリポジトリは、自分専用のトレーディングエージェントです。自分のマシンで実行し、キーが外部に出ることはありません。また、Mangrove API のリファレンス実装でもあります。クローンして自分用に変更し、独自のトレーディングシステムへと拡張できます。

1. ユーザーガイドでAI クライアントを選びます。Claude Code、Codex、Grok Build、Perplexity Computer はインストールに対応しています。MangroveAI API キーは省略できます。新規の無人セットアップでは、ウォレット決済を設定するまで決済は保留されます。
2. 手動で必要なものを用意し、セットアップするには、SETUP.mdに従ってください。Claude の詳しい手順は任意です。Python エージェントの実行に、他のクライアントでは Claude も Node.js も必要ありません。
3. tutorials/trading-app/のガイド付きチュートリアルを進めてください。「クローンしたばかり」から「ペーパー戦略を実行中」、そして（任意で）「実際のスワップを実行した」まで、自分のペースで学べる章が用意されています。

第01～05章では、実際の取引資金を使いません。ただし、有料 API 呼び出しでは、ペーパーモードであっても API キーの利用枠を消費したり、x402 決済が必要になったりする場合があります。第06～08章では、任意で実取引を扱います。

すでに使い方をご存じですか？ このまま読み進めてください。README の残りはリファレンスです。

Kraken アカウントを接続する

エージェントはKraken（CEX）とオンチェーンの両方で取引します。接続方法は2通りあります。アクセス権の保管方法に応じて選んでください。

	自分のキーを使用 — /setup-kraken	キー不要のOAuth — /connect-kraken
仕組み	最小権限のKraken APIキー（取引と照会のみ、出金は無効）を作成します。SDKはお使いのマシンからapi.kraken.comに直接アクセスします	ブラウザーで一度承認します（Kraken Connect / OAuth2）。作成、コピー、保管が必要なAPIキーはありません
アクセス権の保管者	あなた — キーがマシンの外に出ることも、Mangroveサーバーに触れることもありません	MangroveプラットフォームがOAuthの許可を保持し、あなたに代わって送信します
おすすめの方	自己管理を重視する方、APIキーの作成に抵抗がない方	最も手早く接続したい方、キーを管理したくない方
取り消し方法	Krakenの設定でキーを削除します	Krakenの設定でアプリへの許可を取り消します

セッションで**「Krakenをセットアップして」または「キーなしでKrakenに接続して」**と言うと、該当するスキルが手順を案内します。BYOKキーに必要な正確な権限セットも説明します。約定は、DEXスワップと同じローカルSQLite取引ログ（cex_status、cex_balances、cex_sync_fills）に同期されます。

---

前提条件

マーケットプレイスへの出品など、所有権の確認が必要な操作については、 マーケットプレイスのウォレット承認をご覧ください。Claudeは操作を準備して承認のために表示し、その後、ローカルエージェントが署名してMangroveMarketsに送信できます。これには、マーケットプレイスの明示的な設定と、バックアップ済みのBaseまたはXRPLウォレットが必要です。決済処理は別の連携機能です。

ツール	インストール	用途
VSCode（任意）	https://code.visualstudio.com/download	ターミナルが統合されたエディターです。既存のターミナルやAIクライアントの実行環境も使用できます。
Python 3.11+	https://www.python.org/downloads/	エージェントはPython FastAPIプロセスです。最低バージョンは3.11です。
Git for Windows（Windowsのみ）	https://git-scm.com/download/win	Git Bashを利用できるため、このリポジトリの*.shスクリプトをmacOSやLinuxと同じように実行できます。コマンドパレットからVSCodeの既定のターミナルをGit Bashに設定してください。
AIクライアント	Claude、Codex、Grok、Perplexityのセットアップ	コマンド実行またはMCPアクセスに対応したクライアントです。Claude Codeは任意です。
MangroveAI APIキー	https://mangrovedeveloper.ai から無料で入手できます	setup.shでは任意です。APIキーでのアクセスか、x402ウォレット決済を選んでください。

Dockerは任意です。別のインストール方法については、以下をご覧ください。基本の方法はベアメタルです。エージェントをネイティブ実行すると、keyringライブラリからOSのキーリングに直接アクセスできるためです。

---

クイックスタート — ベアメタル（推奨）

1つのコマンドで、API キーまたは x402 によるアクセスを選択し、venv を作成して依存関係をインストールし、ローカルエージェントを起動します。利用可能な場合は Claude を登録し、認証済みのローカルアクセスを検証します。

git clone https://github.com/MangroveTechnologies/mangrove-agent.git mangrove-agent
cd mangrove-agent
./scripts/setup.sh

初回の実行では、依存関係のインストールとネットワークの検出に数分かかることがあります。再実行しても設定とローカル状態は保持されます。また、コードや設定の変更後にサーバーを再起動できます。実行中のエージェントに別のクライアントを接続する場合、セットアップを再実行する必要はありません。

完了すると、次の状態になります。

• エージェントは http://localhost:9080 で実行されます（PID は agent-data/bare.pid、ログは agent-data/bare.log）。:8080 は VSCode Helper などの開発ツールに占有されていることが多いため、外部向けには 9080 をバインドします。
• ./scripts/verify_quickstart.sh --bare が成功しました。ローカル認証と必須のローカルツールが確認されました。利用できないリモートツールは別途報告されます。
• Claude が利用可能で、登録がスキップされなかった場合、登録情報が保存されます。それ以外のクライアントでは、コマンドクライアントまたは各クライアント独自の MCP 接続を使用します。

セットアップ後は、選択したクライアントで続行してください。ユーザーガイドをご覧ください。Claude ユーザーは ./scripts/chat.sh を実行すると、シェル／ファイルツールを無効にし、Mangrove MCP のみを使用するセッションを開始できます。制限付きチャットをご覧ください。x402 モードでは、有料データやバックテストをリクエストする前に、表示された支払いウォレットの手順を完了してください。API キーを使用するユーザーは、支払いウォレットなしでペーパートレードを行えます。シミュレーション取引でも、上流 API の呼び出しが無料になるわけではありません。

./scripts/setup.sh の便利なフラグ

./scripts/setup.sh --yes                          # preserve settings; fresh install uses x402
./scripts/setup.sh --auth api-key                  # keep existing key or enter a new one (hidden)
./scripts/setup.sh --auth x402                     # explicitly switch to wallet payments
./scripts/setup.sh --foreground                    # run uvicorn in your terminal (Ctrl+C to stop)
./scripts/setup.sh --no-mcp                        # skip Claude Code registration
./scripts/setup.sh --no-verify                     # skip the post-start verify pass
./scripts/setup.sh --docker                        # use Docker instead of bare-metal
BARE_PORT=9085 ./scripts/setup.sh                  # use a different port (9080 busy/squatted)

BARE_PORT は全体（サーバー、ヘルスチェック、MCP 登録、検証）で反映されます。9080 が使用中の場合、setup.sh は起動を拒否し、ポートを解放するか BARE_PORT を設定するよう案内します。バインドの失敗を黙って見過ごしたり、誤って成功を報告したりすることはありません。

---

代替クイックスタート — Docker

ホスト上で Python を実行できない場合（企業による制限、再現性に関する要件など）は、Docker でも同じように動作します。その代わり、コンテナから OS のキーリングにはアクセスできないため、Fernet マスターキーは Keychain／Secret Service／Credential Manager ではなく、./agent-data/master.key（chmod 600、Git 管理対象外）に保存されます。

git clone https://github.com/MangroveTechnologies/mangrove-agent.git mangrove-agent
cd mangrove-agent
./scripts/setup.sh --docker

状態は ./agent-data/ ディレクトリ（コンテナ内にバインドマウント）に永続化されます。このディレクトリのマウントにより、以前は再ビルド後に DB の行が失われる原因となっていた macOS／Windows の単一ファイルのバインドマウントの古い状態を回避できます。

---

初めての取引

このセクションでは、概要を手早く紹介します。詳しい手順については tutorials/trading-app/ をご覧ください。短いリファレンスが必要な場合は、ここに戻ってきてください。

最初の接続。 選択したクライアントが共有ポリシーを読み込み、ツールを検出して、無料のステータスを呼び出します。インストール時に保存済みの名前がない場合は、名前を選ぶよう求められます。起動時に、有料の市場データを自動取得したり、バックテストを実行したり、ウォレットを設定したりすることはありません。概要を確認したい場合は、ツアーを依頼してください。有料の例を実行するには、事前に適切なアクセス権が必要です。

ペーパートレード（x402 モードで有料 API 呼び出しを行うには、支払い用ウォレットが必要です）。

「ETH の 1 時間足の戦略を作ってください。」

エージェントは MangroveAI の build_strategy_for_regime を呼び出します。サーバーは現在の市場レジームを読み取り、そのレジームで完了した Strategy Engine の実行結果から、固定の基準（取引数が 10 回超、シャープレシオが 1 以上、IRR が 10% 以上、ベンチマークを上回る）を満たすものを検索し、エントリー条件がそのレジームで許可されるものの中からランダムに 1 つ選び、下書きとして保存して、直近 90 日間を対象にバックテストします。レジームで許可されたシグナルから新たに構成した戦略が必要な場合は、「新しい」戦略を依頼してください。

「これをペーパーに昇格してください。」

戦略の時間枠に合わせた cron に戦略がスケジュールされます。評価が実行され、ペーパー取引の約定が記録されます。資金を失うリスクはありません。

ライブ取引（任意、資金が必要です）。

Robinhood を利用する場合は、同梱の setup-robinhood スキルと execution-venue setup を使用してください。ブローカーの OAuth を使用するため、 ローカルの取引用ウォレットは必要ありません。

DEX 取引のためのウォレット設定とライブ取引については、チュートリアルの第 06 章と第 07 章をご覧ください。

• create_wallet または stash-secret.sh と import_wallet を使ってウォレットを作成またはインポートします。
• ターミナルで ./scripts/reveal-secret.sh <vault_token> を実行してシークレットを保存します（チャットには絶対に貼り付けないでください）。
• ./scripts/confirm-backup.sh <address> を実行してバックアップゲートを解除します。
• Base で 1～5 USDC を入金します。
• アロケーションブロック（confirm=true、slippage_pct ≤ 0.0025）を指定して、戦略をライブに昇格します。
• ライブ評価は同じ cron で実行されます。戦略が取引すると判断すると、mangrovemarkets SDK が 1inch 経由でルーティングし、エージェントがローカルで署名してブロードキャストし、トランザクションを記録します。

安全モデルの概要

• 秘密鍵がこのチャットに入力されることはありません。 create_wallet が返すのは vault_token であり、平文の秘密鍵ではありません。秘密鍵の表示には別の CLI（reveal-secret.sh）を使用し、ターミナルにのみ出力します。
• ハーネスフックが鍵の貼り付けをブロックします。 Claude Code に鍵を貼り付けようとすると、.claude/hooks/block-wallet-secrets.sh が説明メッセージとともにプロンプトを拒否します。このフックは .claude/settings.json にあります。マシンの所有者はこの設定を変更できます。
• ライブ取引は明示的なバックアップ確認を必須とします。 エージェントの外部にウォレットの秘密鍵を保存した後、./scripts/confirm-backup.sh <addr> を実行してフラグを切り替えます。この確認が済んでいないウォレットでは、execute_swap と update_strategy_status → live は拒否されます。
• マスターキーはローカルに保管されます。 ベアメタル環境では OS キーチェーン、Docker では ./agent-data/master.key（chmod 600、Git の追跡対象外）に保管されます。

---

エージェントでできること

エージェントには2種類のツールがあります。最新の正式なカタログを確認するには、list_tools を実行してください。

1. MangroveAI ツール（唯一の信頼できる情報源）。 戦略、バックテスト、シグナル、市場データ、オンチェーンデータ、ナレッジベース、Strategy Engine に関するすべての情報は MangroveAI にあります。エージェントはこれらのツールを複製して保持しません。起動時に MangroveAI の最新 MCP カタログを読み込み、各呼び出しを MangroveAI の /mcp/ エンドポイントに転送します。x402 ウォレットモードでは呼び出しごとに支払うか、API キーを使用します。MangroveAI がツールを追加または変更すると、エージェントはコードの変更なしでその内容を取り込みます。

分野（例であり、固定リストではありません）	MangroveAI ツール
戦略の構築	load_skill、build_strategy_for_regime、list_backtest_markets、save_strategy、update_strategy、verify_strategy、list_strategies、get_strategy
バックテスト	run_backtest + get_backtest（保存済み戦略）、get_backtest_trades、list_backtests、get_benchmark、screen_candidates
スイープ結果	find_sweep_runs
シグナルとレジーム	list_signals、get_signal、search_signals、match_signals、query_signal_behavior、get_market_regime
市場、オンチェーン、DeFi、ソーシャル	get_ohlcv、get_market_data、get_trending、get_token_holders、get_smart_money_sentiment、get_chain_tvl、get_social_sentiment など
ナレッジベース	kb_search、kb_glossary_get、kb_get_document、query_knowledge
マーケットプレイス	search_marketplace、get_marketplace_strategy
お使いの MangroveAI のポジションと取引	list_positions、list_trades

2. ローカルツール（お使いのマシンでのみ実行できる処理）。 お使いのキー、ウォレット、またはローカルの記録が必要なため、これらはエージェント内にあります。

カテゴリー	ツール
検出（無料）	status、list_tools
名前設定（ローカル、認証が必要）	set_agent_name
決済デモ	hello_mangrove（x402）
ウォレットとポートフォリオ	create_wallet、import_wallet、list_wallets、get_balances、portfolio_value、portfolio_pnl、portfolio_tokens、portfolio_defi、portfolio_history
Kraken（CEX）	cex_status、cex_connect_kraken、cex_balances、cex_validate_order、cex_sync_fills
DEX（1inch）	list_dex_venues、get_swap_quote、execute_swap、get_tx_status、get_spot_price、get_gas_price、get_token_search、get_allowances、get_token_info、get_dex_chart
ローカルの実行記録	agent_list_strategies、agent_get_strategy、agent_update_strategy_status、agent_evaluate_strategy、agent_list_evaluations、agent_list_trades、agent_list_all_trades
x402 支出予算	x402_spend_status、x402_spend_reset

ローカルツールには、同じサービスレイヤーを呼び出す REST エンドポイント /api/v1/agent/* もあります。MangroveAI ツールにはローカルの REST コピーはありません。エージェントの MCP エンドポイント経由で呼び出すか、MangroveAI を直接呼び出してください。認証が必要なルートでは、server/src/config/local-config.json の API_KEYS の最初のエントリー（setup.sh が生成する一意のキー）を X-API-Key に設定します。これはエージェント独自のローカルキーであり、MangroveAI の API キーではありません。/health、status、list_tools はキーを必要としないため、最初の認証が必要な呼び出しで 401 が返るまで、間違ったキーでも問題ないように見えます。

バックテストと Strategy Engine。 バックテストは MangroveAI 上で実行され、エージェント内では実行されません。保存済みの戦略では、run_backtest で実行を送信し、完了後に get_backtest で結果を読み取ります。Strategy Engine がすでに測定した内容を検索するには、find_sweep_runs を使用してください。新しいスイープの作成と起動は、現在 MCP では提供されていません。詳細については、KB の SIEVE ガイドと実験リファレンスをご覧ください。

---

仕組み

┌─────────────────────────────────────────────────────────────┐
│  Your machine                                               │
│                                                             │
│  Claude Code ─MCP──┐                                        │
│  Python/curl ─REST─┤                                        │
│                    ▼                                        │
│  ┌─ mangrove-agent (single FastAPI process, port 9080) ──┐     │
│  │   • auth middleware (X-API-Key)                   │     │
│  │   • service layer (one for REST + MCP)            │     │
│  │   • APScheduler (in-process cron, SQLite jobstore)│     │
│  │   • local Fernet-encrypted wallets                │     │
│  └───────────────────────────────────────────────────┘     │
│           │                        │                        │
│           ▼                        ▼                        │
│  ┌── SQLite: agent.db ─┐  ┌── OS Keychain (Fernet key) ─┐  │
│  └─────────────────────┘  └──────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
              │                      │
              ▼                      ▼
    MangroveAI /mcp/ +        mangrovemarkets SDK
    mangroveai SDK            (DEX swap, portfolio,
    (every MangroveAI tool,    wallet)
     strategy evaluation)

戦略の評価は mangroveai.execution.evaluate() 内で行われます。エージェントがシグナルロジック、リスクゲート、ポジションサイジング、クールダウンを再実装することはありません。エージェントの役割は、戦略を取得 → SDK を呼び出す → 返された OrderIntent[] をエグゼキューターにディスパッチする → ログを記録する、という処理の統括です。

ライブ取引では、エージェントがプロセス内でウォレットのシークレットを復号し、mangrovemarkets から返された未署名トランザクションに署名して、署名済みバイト列をブロードキャストし、シークレットをゼロ化します。SDK がキーを参照することはありません。

---

アーキテクチャのドキュメント

ドキュメント	内容
docs/api-reference.md	呼び出す Mangrove API の概要
docs/user-stories.md	18 件のユーザーストーリーと 4 件のフロー図
docs/specification.md	API コントラクト、Pydantic モデル、SQLite スキーマ、エラーコード
docs/architecture.md	システム図、シーケンス図、ファイルツリー
docs/implementation-plan.md	24 タスクの段階的な構築計画

開発

エンドポイント、MCP ツール、シグナル、戦略を追加してエージェントを拡張する場合は、docs/contributing.md に記載されたサービスレイヤーパターンに従います。戦略の作成とバックテストの手順は、MCP の load_skill ツールを通じて MangroveAI から実行時に読み込まれます。エージェントには、サーバースキルや戦略ジェネレーターのコピーは含まれていません。コントリビューター向けスキルは .claude/skills/ にあります。

テスト

docker run --rm -v "$(pwd)/server:/app" -w /app -e ENVIRONMENT=test \
  $(docker compose build -q app && docker compose images -q app) \
  pytest tests/

または、実行中のコンテナ内から次のように実行します。

docker compose exec app pytest tests/

オプトイン方式のライブスワップテスト 2 件はスキップされ、それ以外はすべて合格する想定です。

オプトイン方式のライブスワップを実行するには、次のようにします。

# Testnet (Base Sepolia)
ENABLE_SEPOLIA_TEST=1 BASE_SEPOLIA_PRIVATE_KEY=0x... pytest tests/e2e/test_live_swap.py::test_sepolia_live_swap

# Mainnet — real funds; we tested at 0.10 USDC
ENABLE_MAINNET_TEST=1 BASE_MAINNET_PRIVATE_KEY=0x... pytest tests/e2e/test_live_swap.py::test_mainnet_live_swap

デプロイ

v1 ではローカルのみ（Docker Compose）です。クラウドへのデプロイ（永続ストレージを備えた Cloud Run、Cloud SQL）はロードマップ上の項目であり、まだ提供されていません。

プロジェクト構成

mangrove-agent/
├── .claude/                  # Claude Code framework (skills, agents, rules)
├── server/
│   ├── src/
│   │   ├── app.py            # FastAPI factory
│   │   ├── config/           # Per-env JSON configs
│   │   ├── api/routes/       # REST routes — one file per resource
│   │   ├── mcp/              # MCP tool registration
│   │   ├── models/           # Pydantic domain + DB models
│   │   ├── services/         # Business logic (wallet, strategy, executor, scheduler, trade_log, …)
│   │   └── shared/           # auth, db/sqlite.py, crypto/fernet.py, clients/mangrove.py, errors, logging
│   └── tests/                # unit / integration / e2e
├── docs/                     # Design docs (requirements, spec, architecture, plan)
├── scripts/verify_quickstart.sh
├── docker-compose.yml
├── .mcp.json.example         # Drop-in Claude Code MCP config
└── SAGE.md                   # Shared identity and operating instructions

ライセンス

MIT

Robinhood の執行先

Mangrove の戦略では、公式 MCP サービスを通じて、執行先ブローカーとして Robinhood を利用できます。接続、割り当て、復旧の手順を参照してください。