Bvcc Agent Wallet

@bvcc/agent-mcp

BVCC Agent Wallet 用の Model Context Protocol サーバーです。 MCP 対応の AI ランタイム（Claude Code、Cursor、Claude デスクトップアプリ）から、オンチェーンで BVCC Agent Wallet を操作できます。残高と上限の確認、スワップの計画とシミュレーション、トークンの送金、Uniswap v3/v4 でのスワップ（ネイティブ ETH との交換を含む）、Uniswap v3/v4 での流動性の提供（ネイティブ ETH プールを含む）、さらに Aave v3 でのポジションの貸し出し、借り入れ、解消（ポジションの決済やデレバレッジを安全な手順で自動実行する機能を含む）が可能です。また、エージェントが必要に応じて各機能の使い方を学べるよう、組み込みの操作ガイド（listGuides / getGuide。プロンプトとしても公開）も備えています。

各ツールは、@bvcc/agent-sdk の機能カタログから生成されます。ここにツールごとのコードはありません。SDK カタログに機能を追加すると、自動的にここにも反映されます。

初めての方は、まず QUICKSTART.md をご覧ください。 — ウォレットの作成 → オンチェーンでのエージェント認証 → ガスの入金 → 設定 → 動作確認まで、エンドツーエンドのセットアップを説明しています。エージェントが何もできなくなる、見落としがちな2つの手順も解説しています。

セキュリティ

このサーバーが権限を追加することはありません。支出上限（ネイティブ通貨およびトークンごとの上限、日次上限および総額上限）、許可するトークン、許可するプロトコル、送信先のホワイトリスト、グローバル一時停止など、すべての制限は Agent Wallet コントラクトによってオンチェーンで適用されます。各ツールで実行できる操作は、BVCC ダッシュボードでエージェントに許可した範囲内に限られます。

• エージェントの秘密鍵は環境から読み込まれ、ローカルでの署名にのみ使われ、送信されることはありません。BVCC が秘密鍵を受け取ったり、保存したり、管理したりすることはありません。
• ツールは SDK カタログを通じて明示的に公開されます。自動検出されることはありません。
• BVCC_MCP_READONLY=true を設定すると、読み取り／シミュレーション用ツールのみが公開されます（書き込み操作はありません）。

ツール

カタログから生成され、クラス別に分類されています。

コア（ウォレット、送金、スワップ）：

クラス	ツール
🟢 読み取り	getAgentStatus, getCapabilities, getNativeBalance, getTokenBalances, getRemaining, needsApproval
🟡 シミュレーション	buildSwapPlan, dryRunSendNative, dryRunSendToken, dryRunSwapV3, dryRunSwapV4
🔴 書き込み	sendNative, sendToken, approve, swapV3, swapV4, swapToNative, swapFromNative

エージェントの操作には、ガス代および利用可能な支出予算とは別に、0.15% の BVCC エージェント手数料がオンチェーンで自動的に課されます。

Aave v3 レンディング（aave モジュール — Arbitrum、Ethereum、BNB、Base、Polygon）：

クラス	ツール
🟢 読み取り	getAavePositions, getAaveMarket
🟡 シミュレーション	dryRunAaveSupply, dryRunAaveBorrow, aavePlanClosePosition, aavePlanDeleverage, aavePlanCollateralSwap, aavePlanDebtSwap
🔴 書き込み	aaveSupply, aaveWithdraw, aaveBorrow, aaveRepay, aaveRepayWithATokens, aaveSetCollateral, aaveSetEMode, aaveClosePosition, aaveDeleverage, aaveCollateralSwap, aaveDebtSwap

預け入れと借り入れは常にウォレット自身に対して行われます。ウォレットのオンチェーン呼び出しポリシーで受取人が固定されているため、to または onBehalfOf パラメーターはありません。

⚠️ 4 つの aave* ポジション解消ツールは、1 回の呼び出しで複数のトランザクションを送信することがあります。 aaveClosePosition、aaveDeleverage、aaveCollateralSwap、aaveDebtSwap は、チャンク単位のループを実行し、ライブ状態から各ステップを再導出して再シミュレーションします。まず対応する aavePlan* ツールを呼び出して、実行予定の内容を確認してください。ヘルスファクターが hfFloor（デフォルトは 1.05）を下回る場合、スワップ価格が Aave のオラクル価格から大きく乖離している場合、ループが進展しなくなった場合、またはエージェントの予算が尽きる場合は、処理を続行せずに停止します。

Uniswap 流動性（lp モジュール — v3 および v4 でポジションを開く、手数料を回収する、ポジションを閉じる）：

クラス	ツール
🟢 読み取り	getV3Position, getV4Position
🟡 シミュレーション	dryRunAddLiquidityV3, dryRunRemoveLiquidityV3, dryRunAddLiquidityV4, dryRunRemoveLiquidityV4
🔴 書き込み	addLiquidityV3, removeLiquidityV3, collectFeesV3, burnV3, addLiquidityV4, removeLiquidityV4, collectFeesV4, burnV4

ポジション NFT はウォレット宛てにミントされ、処理の続行後はすべてウォレットに戻ります。これはオンチェーンで固定されています。addLiquidityV3 はプールの現在価格に合わせて両方の資産の数量を調整します（デフォルトは全価格範囲。ティックを渡すこともできます）。v4 はネイティブ ETH プールに対応しています。v4 のツールを使うには、オンチェーンでエージェントに対して v4 PositionManager の DEEP バリデーターが有効になっている必要があります。そうでない場合、アクションは安全のため実行されません。v3 には increaseLiquidity がありません（NFPM では所有者による制限がないため、新しいポジションをミントして追加します）。

ガイド（meta モジュール — 常時公開、ヘルプ用）：

クラス	ツール
🟢 読み取り	listGuides, getGuide

listGuides はハウツーガイドの名前を返します。getGuide({ area }) は、1 つの分野について、推奨ワークフローと注意点、および使用する正確なツールを記載したプレイブックを返します。対象は getting-started、swaps、lending、liquidity です。モジュールでフィルターした場合も利用できるため、1 つの機能に制限されたエージェントでも、その機能の使い方を学べます。同じガイドはプロンプト（guide-<area>）としても公開されており、人間がスラッシュコマンドとして呼び出せます。

書き込みには MCP の destructiveHint アノテーションが付いているため、クライアントで確認を必須にできます。推奨される運用ワークフローについては、GUIDE.md を参照してください。

設定

推奨： 値、特に AGENT_PRIVATE_KEY は専用の env ファイルに保存し、キーを MCP ホストの設定に直接記述するのではなく、BVCC_ENV_FILE でそのファイルをサーバーに指定してください（ホストの設定は共有、同期され、スクリーンショットに写る可能性があります）。そのファイルに chmod 600 を設定し、クラウド同期フォルダーの外に保管してください。必要であれば、ホストの env ブロックに変数を直接記述することもできます。その場合、ホストの env がファイルより優先されます。.env.example を参照してください。

agent.env の例（BVCC_ENV_FILE で渡すパス）：

AGENT_PRIVATE_KEY=0xYOUR_AGENT_KEY
WALLET_ADDRESS=0xYOUR_WALLET
CHAIN_ID=42161

変数	必須	説明
AGENT_PRIVATE_KEY	はい	エージェントの EOA 秘密鍵（0x + 64 桁の 16 進数）。ローカルでのみ使用されます。
WALLET_ADDRESS	はい	このエージェントが操作する BVCC Agent Wallet。
CHAIN_ID	はい	デフォルトのチェーン：42161 Arbitrum One · 56 BNB · 1 Ethereum · 8453 Base · 137 Polygon · 421614 Arbitrum Sepolia。
RPC_URL	いいえ	デフォルトのチェーン用のカスタム RPC（指定しない場合はパブリックのデフォルト）。
RPC_URL_<chainId>	いいえ	チェーンごとの RPC 上書き設定。例：RPC_URL_56。
BVCC_ENV_FILE	いいえ	読み込む専用 env ファイルへのパス（ホストの設定からキーを分離できます）。ホストの env が優先されます。
BVCC_MCP_READONLY	いいえ	true にすると、読み取り／シミュレーションツールのみが公開されます。
BVCC_MCP_MODULES	いいえ	公開する機能グループをカンマ区切りで指定します：core、aave、lp。未設定の場合はすべて公開されます。

エージェントがアクセスできる範囲を絞る。 BVCC_MCP_READONLY と BVCC_MCP_MODULES は独立しており、組み合わせて使用できます。エージェントがレンディングを利用しないのであれば、 そのツールを除外することで、エージェントが誤った操作をする可能性を一つ減らせます。

BVCC_MCP_MODULES=core              # wallet + swaps    (18 + 2 guides = 20)
BVCC_MCP_MODULES=aave              # Aave lending      (19 + 2 = 21)
BVCC_MCP_MODULES=lp                # Uniswap liquidity (14 + 2 = 16)
BVCC_MCP_MODULES=core,aave,lp      # everything (= unset)  (51 + 2 = 53)
BVCC_MCP_MODULES=core
BVCC_MCP_READONLY=true             # read-only wallet  (11 + 2 = 13)

2 つのガイドツール（listGuides、getGuide、モジュール meta）は、これらに加えて常に公開されます。これが + 2 の意味です。そのため、1 つの機能に制限されたエージェントでも、その使い方を確認できます。

認識されないモジュール名は無視されるため、入力ミスがあっても公開範囲は広がらず、狭くなります。どちらの設定もセキュリティ境界ではありません。セキュリティ境界となるのはコントラクトです。ただし、公開範囲を狭めれば、判断に迷ったエージェントが操作を誤る可能性も減ります。

マルチネットワーク： 1 つのサーバーで、サポート対象の任意のチェーン上のエージェントを操作できます。各ツールでは network（チェーン ID または名前：ethereum、bsc、arbitrum、base、polygon、arbitrum-sepolia）を任意で指定できます。省略した場合は CHAIN_ID が使われるため、再起動せずに「bsc でスワップして」と指示できます。ウォレットアドレスはすべてのチェーンで共通です（CREATE2）。エージェントは、使用する各チェーンで認可されている必要があります。

インストールとビルド

npm install
npm run build
npm test          # builds + stdio smoke test (no chain calls)

クライアントに接続する

Claude Code

claude mcp add bvcc-agent-wallet \
  --env BVCC_ENV_FILE=/secure/agent.env \
  -- npx -y @bvcc/agent-mcp

Cursor / Claude app（mcp.json）

{
  "mcpServers": {
    "bvcc-agent-wallet": {
      "command": "npx",
      "args": ["-y", "@bvcc/agent-mcp"],
      "env": { "BVCC_ENV_FILE": "/secure/agent.env" }
    }
  }
}

キーは上記の設定ではなく、agent.env に保存されています。キーを直接記述する場合は、env ブロックを AGENT_PRIVATE_KEY／WALLET_ADDRESS／CHAIN_ID に置き換えてください（安全性は低下します。キーがホストの設定に保存されます）。再現性を確保するため、バージョンを固定してください。例：@bvcc/[email protected]（アップグレードを参照）。

アップグレード

SDK はこのパッケージに同梱されているため、新しい機能を利用するにはMCP を更新するだけで十分です（Aave のレンディングは 0.2.0 でこの方法で提供されました）。@bvcc/agent-sdk を別途インストールまたは更新する必要はありません。

1. 再現性を確保するため、設定でバージョンを固定します。

   "args": ["-y", "@bvcc/[email protected]"]
   

   npx はキャッシュするため、@bvcc/agent-mcp のバージョンを固定していないと、古いビルドが実行され続ける場合があります。 アップグレードするには、番号を上げる（例：@0.2.1）か、希望に応じて @latest を使用してください。 グローバルにインストールする場合：npm i -g @bvcc/agent-mcp@latest。
2. MCP クライアントを再起動します。 カタログの新しいツールは自動的に表示されます。 設定のほかの項目を変更する必要はありません。起動時のバナーに実行中の バージョンが表示されます（[bvcc-agent-mcp vX.Y.Z]）。
3. ⚠️ 新しいプロトコルはオンチェーンで承認します。 新しいプロトコル（例：Aave）を追加するリリースでは、そのツールがすぐに利用可能になりますが、エージェントの allowedProtocols にそのプロトコルのコントラクトが含まれていない場合、アクションは ProtocolNotAllowed で失敗します。ルーターと同様に、ダッシュボードから承認してください。

各バージョンの変更点については、CHANGELOG.md を参照してください。バージョン管理には SemVer を採用しています。patch は修正、minor は互換性のある新機能を表し、0.x は API が 今後変更される可能性があることを意味します。

仕組み

@bvcc/agent-sdk  ──catalog──►  @bvcc/agent-mcp  ──MCP──►  Claude Code / Cursor / Claude
   (on-chain limits live in the Agent Wallet contract, not here)

サーバーはカタログを読み込み、機能ごとに 1 つの MCP ツールを登録します（Zod スキーマ → ツールの入力スキーマ、kind → ツールのアノテーション）。各呼び出しは SDK にルーティングされ、 SDK がエージェントキーで署名し、executeAsAgent を送信します。

ライセンス

MIT © BlockVenture Chain Capital (BVCC)