spectra-mcp-server

MetaVault MCP

AI エージェント向けのマルチプロトコル利回りインテリジェンス — Model Context Protocol を通じて、Spectra Finance、Pendle、Morpho に対応しています。

55 個のツール · 3 つのプロトコル · 10 以上のチェーン · 読み取り専用 · オープンエマージェンスアーキテクチャ · キャリブレーションインテリジェンス · オンチェーン Curve クオート · Pendle ロジット AMM モデリング · ERC-4626 ヘルスチェック · 利回り曲線の期間構造 · 履歴 eth_getLogs · Pendle プロトコルとの完全なパリティ（15 個のツール） · クロスプロトコルのポジションマップ · Spectra↔Pendle のクロスプロトコル比較 · veSPECTRA + vePENDLE ガバナンス · Pendle の過去の時系列データ · サプライヤーカスケードモデリングによる Morpho の供給側の可視化 · Morpho のユーザーポジションと過去のレート · Merkl のキャンペーン APR + 有効期限の統合 · エントリーパスの把握 · 規範的な観測境界 · キュレーターリスクのモニタリング · 出金ストレステスト · ロールオーバー計画 · 複数ボールトのポートフォリオ集計 · プールの有効期限モニタリング · web3 ライブラリへの依存ゼロ

これは何をするものですか

MCP に対応したあらゆる AI エージェント（Claude、GPT、オープンソース）は、統合インターフェースを通じて Spectra、Pendle、Morpho に問い合わせることができます。

• 10のチェーンを同時に対象として、最適な固定金利の利回り機会を発見します
• 特定のPT/YTポジションを、完全なデータ（APY、TVL、流動性、価格）で分析します
• 借入金利を自動検出して、レバレッジをかけたループ戦略（Spectra PT ＋ Morpho 担保）を計算します
• 固定利回りと変動利回りを比較し、十分な情報に基づいた判断を支援します
• Merkl報酬との統合により、すべてのSpectraポジション（PT、YT、LP）にまたがるウォレットポートフォリオを追跡し、損益全体を把握します
• SpectraとPendleの両方について、プールと市場のデータとあわせて、外部MerklキャンペーンのAPRを提示します
• プールの取引量、個別のトランザクション活動、プールをまたいだアドレス検索を監視します
• オンチェーンのCurve get_dy() を使用してPT取引の正確な出力額を見積もり、利用できない場合は数式による推定にフォールバックします
• 仮想取引後のポートフォリオ状態をシミュレーションします（取引前／取引／取引後とその差分）
• 価格インパクト、実効APY、Morphoのループ分析を考慮し、資金量に応じた最適な機会をすべてのチェーンから検索します
• IBTのAPRとYTのインプライドレートの乖離から、YTの裁定機会を検出します
• Baseのライブオンチェーンデータを使用してプールごとの実際のveSPECTRAブースト倍率を、EthereumメインネットのvePENDLE投票権を（sPENDLEへの移行を考慮して）算出します
• 1回の呼び出しで、Spectra ＋ Pendle ＋ Morpho ＋ ガバナンス（veSPECTRA ＋ vePENDLE）にまたがるポジション全体を可視化し、矛盾も検出します（未使用のブースト、レンディングと固定金利のスプレッド、集中、ルーパーの検出、プロトコルをまたいだ期限切れポジションなど）
• エントリー経路の複雑さを評価します。特殊な原資産、sw-wrapperの経由、メインネットのガス代による摩擦を自動的にフラグ付けし、提示された利回りを得るための実際のコストをエージェントが把握できるようにします
• すべてのチェーンにわたる稼働中のMetaVaultを発見します（キュレーター情報、TVL、APY、ポジション、エポック履歴）
• キュレーター向けにMetaVaultの「ダブルループ」戦略をモデル化します。キュレーターの経済条件を考慮し、Vaultの複利運用とMorphoのレバレッジを組み合わせ、ライブAPIデータまたは手動パラメーターからデータを自動入力します
• MetaVaultの運用状況を監視します。ポジションごとのVault配分、預入・引き出しフロー、手数料収益、ブリッジの動き、実行可能なアラートを含むキュレーター向けダッシュボードを提供します
• Morphoのレンディング市場を照会してPT担保の機会を調べ、レンディング流動性の供給者を特定し、市場をまたいだVaultの配分を発見します
• プロトコルの統計、トークノミクス、ガバナンスデータを照会します
• 重複するチェーンで満期を考慮したマッチングを行い、SpectraとPendleの利回り機会を並べて比較します
• SpectraとPendleの両方を検索し、資金量に応じた規模調整とプロトコル間のマッチタグ付けにより、最適なキュレーター向け機会を検索します
• Pendleがサポートするすべてのチェーン（Mantle、Berachain、HyperEVM、Cornなど、Pendleのみが対応するチェーンを含む）のPendle市場を閲覧します
• Pendle市場を詳細に分析します。市場の詳細、ポートフォリオ追跡、取引見積もり、取引シミュレーション、ループ戦略、YT裁定、満期監視、利回り曲線、容量分析、プロトコル全体の統計に対応します（Spectraのツールと完全に同等の機能）
• 複数サイズの容量曲線を使ってプールの深さを評価します。SpectraとPendleの両方で、幾何級数的な資金額の段階（$1K→$1M）にわたるPT取引を見積もり、最適な規模と流動性の枯渇点を特定します
• 資金投入前にIBTの健全性を確認します。オンチェーンのERC-4626変換レート、APRの持続可能性（自然発生かインセンティブによるものか）、プール残高、プロトコルでの認識状況、流動性を確認します
• すべてのチェーンを対象に、任意の原資産の利回り曲線（期間構造）を可視化します。すべての満期を時系列順に並べ、曲線の形状を分析します
• APIデータの保持期間を過ぎたオンチェーンの過去のプール活動を、動的なRPC URL対応により任意のチェーンで eth_getLogs を使用して取得します
• すべてのチェーンでキュレーターのMorphoポジションの健全性（清算までの距離、借入金利の変動、ヘルスファクター）を監視します
• MetaVaultの引き出しシナリオをストレステストします。市場ストレスのシミュレーションを用いて、流動性の段階的な利用順序（遊休資金 → 満期到来資産 → LPの解消 → PTの売却）を分析します
• 期限が迫るMetaVaultポジションのロールオーバーを計画します。エントリー時の価格インパクト、利回り差、重複期間を考慮して、プロトコルをまたぐ候補を順位付けします
• 複数のVaultにまたがるキュレーターのポートフォリオを集計します。総AUM、加重平均APY、手数料収益の予測、原資産／チェーン別の集中度を分析します
• すべてのチェーンでプールの満期を監視し、準備状況を評価します。後継プールの検出、ガバナンスAPIから取得したゲージの状態、オペレーター向けチェックリスト（プールのデプロイ／ゲージの申請／移行準備完了）を提供します
• mv_get_protocol_context を通じて、必要なときにプロトコルの仕組みを確認できます（PT/YTの識別、Routerのバッチ処理、入金経路、用語集、手数料とコスト、ワークフローの振り分け、externalPositionsレジストリ）
• プロトコルのYT手数料（Spectraは3%、Pendleは5%）とMerklキャンペーンの対象条件（POOLまたはHOLD）をツールの出力に直接表示し、エージェントが外部検索なしで適用できるようにします エージェントは PT/YT の仕組みを理解する必要はありません。資金量を指定して spectra_scan_opportunities または pendle_scan_opportunities を呼び出すだけで、順位付けされた実行可能なデータを取得できます。プロトコルを横断して比較する場合は、mv_scan_curator_opportunities が両方のプロトコルをまとめて順位付けします。なぜそのように機能するのかを理解する必要がある場合は、mv_get_protocol_context を呼び出します。

オープンエマージェンスアーキテクチャ

このサーバーは、AI エージェントが特定の戦略を教えられることなく、新しい戦略を発見できるように設計されています。戦略を特定するロジックをハードコードするのではなく、システムは 3 つの層でプロトコルの仕組みを教え、エージェントが構成要素を組み合わせて独自の分析を行えるようにします。

3 つの層

Layer 1: Protocol Context (mv_get_protocol_context tool + resources)
  → Teaches the "physics" of the protocol: PT/YT identity, Router batching, minting
  → Available as a callable tool (on-demand) and as MCP resources
  → Static knowledge — what CAN happen, not what IS happening

Layer 2: Tool Descriptions (every tool's description string)
  → Teaches domain-specific mechanics relevant to that tool's data
  → Cross-reference nudges: "use spectra_get_portfolio to check actual holdings"
  → Uses "could be" language, not "is" — preserves ambiguity where it exists
  → Calls out hidden mechanics that could mislead (e.g., AMM_ADD_LIQUIDITY can mint YT)

Layer 3: Structured Output Hints (computed at runtime in tool output)
  → Position Shape analysis in portfolio: balance ratios (e.g., "YT/PT 4:1")
  → Portfolio Signals: concentration, maturity alerts, strategy shape across positions
  → Volume Signals: volume/liquidity ratio, buy/sell skew, trend detection
  → Morpho Market Hints: capacity warnings, utilization alerts, spread analysis, reward incentives
  → Morpho Supply-Side Analysis: supplier identification (vault/EOA/looper), concentration metrics,
    supply gap warnings — surfaces where lending liquidity comes from and whether it's sufficient
  → Competing Interpretation Branches (A/B/C) in activity analysis per-address:
    multiple explanations for the same observable pattern, presented with equal weight.
    The agent must bring external evidence to collapse branches — the tension IS the info.
  → Statistical confidence boundaries: small-N cycle repetitions (≤5) flagged as
    insufficient for extrapolation, preventing false pattern-matching
  → Flow Accounting with competing hypotheses: YT-only, PT-only, fully exited positions
    each get multiple explanations that predict different future behavior
  → Address isolation mode: cycle detection, flow accounting, contract/EOA detection,
    pool impact warnings, gas estimates, pool context
  → Capital-aware warnings: short maturity, low liquidity, negative effective APY
  → Yield Dimensions in scan output: fixed, variable, LP, looping side-by-side
  → Strategy Tension: competing PT looping vs YT accumulation on same pool
  → On-chain quote source indicators: "(on-chain Curve get_dy)" vs "(estimated)"
  → Yield composition: IBT APR breakdown (organic base vs external incentives) in scans and quotes
  → Incentive sustainability: flags when >50% of IBT APR or LP APY comes from incentives,
    shows "organic only" APY so agents can assess yield durability without incentive assumptions
  → Pool reserves: IBT/PT amounts with ratio for AMM imbalance analysis
  → Merkl campaign APR: external incentive programs (e.g., KAT rewards) shown per-pool/market
    with double-counting avoidance (skips campaigns whose reward tokens are already displayed)
  → Merkl campaign eligibility: action type (POOL/HOLD) always shown, with explicit
    "[LP only — not for YT/PT holders]" flag on POOL campaigns to prevent misattribution
  → Protocol YT fees: Spectra 3% and Pendle 5% shown in every pool/market detail output
    so agents apply them to yield calculations without needing external lookups
  → Points multipliers: external programs (Drops, InfiniFi, Firelight) with amounts
  → "Could be" / "at current rates" language: preserves ambiguity in ranked output
  → Makes key signals SALIENT without prescribing interpretation

Layer 4: Observation Coverage (quantifies blind spots in tool output)
  → Value coverage: what % of an address's position is explained by observable activity.
    Low coverage means most behavior is invisible (direct mints, transfers, cross-chain).
  → Temporal coverage: active days vs dark periods with no observable events.
    Longest gap duration surfaced so the agent can reason about invisible activity.
  → Data source coverage: which of 5 available sources were consulted vs not.
    Explicitly lists what is invisible to the current analysis.
  → Activity diversity: single-type activity flagged as highest-ambiguity pattern.
  → Boundary marker: "Position sizing should assume this analysis is incomplete,
    not comprehensive." — a structural admission of domain-of-validity limits.
  → Coverage metrics bound ALL interpretations above them. High-confidence strategy
    assessment + low observation coverage = false confidence. The coverage section
    forces the agent to size its conviction to what it actually observed.

設計原則

• 結論ではなく、仕組みを教えます。 サーバーは、AMM_ADD_LIQUIDITY がミントと LP の一括操作である可能性があることを説明します。「このユーザーは YT を蓄積している」と結論付けることはありません。
• 単一の解釈ではなく、競合する解釈を提示します。 アクティビティ分析では、異なる将来の行動を予測する複数の解釈分岐（A/B/C）を出力します。分岐を絞り込むには、エージェントが外部の証拠を持ち込む必要があります。この摩擦面によって、ウォレット戦略分析で最もよくある失敗モードである、性急なパターン照合を防ぎます。
• 統計的なデータ不足を明示します。 繰り返しの回数が少ない場合（サイクル検出が 5 回以下）、外挿には不十分であることを明示します。エージェントは N=3 を確定したパターンとして扱うことはできません。
• すべてのツールは少なくとも 1 つの別のツールを相互参照します。 これにより、分析ワークフローを指示することなく生み出します。エージェントは、そうするよう指示されたからではなく、アクティビティのパターンを見た後に spectra_get_portfolio を確認することを学びます。
• 誤解を招く可能性のある隠れた仕組みを明示します。 Spectra Router は複数の操作をアトミックにまとめます。SELL_PT イベントは、実際にはフラッシュミントによる YT の取得である可能性があります。ツールの説明でこれを教えることで、プールデータだけから誤った結論を導かないようにします。
• 出力ではアドレスを省略せず、常に完全な形で示します。 アクティビティデータにアドレスが含まれる場合、エージェントがブロックエクスプローラーを使わずに spectra_get_portfolio へそのまま渡せるよう、全体を表示します。
• 発見ツールでは、資金量を考慮した分析に対応できない点を警告します。 spectra_get_best_fixed_yields は「これは未調整の APY による順位付けです。資金量を考慮した規模の評価には spectra_scan_opportunities を使用してください」と明示します。
• 解釈だけでなく、分析の死角も定量化します。 ツールは現在、観測範囲の指標を出力します。行動の何パーセントが可視化されているか、利用可能なデータソースのうちどれを参照したか、暗転期間がどれほど続いたかを示します。これらは解釈ではなく、分析そのものの不完全さを構造的に測定したものです。エージェントは、最も適合する解釈がどれほど筋の通ったものに見えても、価値のカバレッジが 35% であれば、それに応じて確信度を調整できます。

これが重要な理由

プロトコルに関する事前知識がまったくないコールドスタートのエージェントでも、次のことができます。

1. mv_scan_curator_opportunities を呼び出し、資金を考慮した指標を使って、プロトコル横断（Spectra + Pendle）の利回りランキングを確認する
2. spectra_get_pool_activity を呼び出し、曖昧なイベントについての⚠ヒントとともに、取引パターンを確認する
3. フラグが付いたアドレスに対して spectra_get_portfolio と pendle_get_portfolio を呼び出し、両方のプロトコルにおけるポジションの形状を確認する
4. 相互参照のヒントを読み、3つすべてのプロトコルにまたがる独自の分析ワークフローを組み立てる
5. サーバーが明示的に検出するようプログラムされていなかった、新しい戦略を特定する

これは検証済みです。事前情報なしで起動したサブエージェントは、説明で示された仕組みと出力に含まれる構造化ヒントだけを使い、3回のツール呼び出しで、ミント後にPTを売却するループ戦略（PTのディスカウントを利用したYTの蓄積）を正しく特定しました。

競合するブランチを設計したきっかけは、実際に発生した失敗でした。複数チェーンにまたがるウォレットを分析していたエージェントが、異なるプールで異なるパターン（スプレッド獲得、マーケットメイキング、LPの循環）が見られたにもかかわらず、すべてのアクティビティを「YT蓄積」としてまとめてしまったのです。単一の物語に固執する失敗モード、つまりエージェントが1つの解釈を選び、それを擁護する状態は、最も危険です。エージェント自身から見ると、適切な分析に見えるからです。

観測範囲レイヤーは、さらに根本的な問題に対処します。観測データを完璧に解釈しても、データが行動の一部しかカバーしていなければ、誤解を招きます。競合するブランチは、物語の問題（どの説明が当てはまるか？）を解決します。カバレッジ指標は、把握範囲の問題（全体像のどれだけを見ているか？）を解決します。最適な解釈のブランチを選んでも、見えないアクティビティの65%を無視するエージェントは、証拠ではなく一貫性に基づいて確信度を設定しています。

ツール

ツール	説明
spectra_get_best_fixed_yields	すべてのチェーンをスキャンし、最適な固定金利の機会を探します。主な探索ツールです。compact モードに対応しています。
spectra_list_pools	特定のチェーンにあるすべてのアクティブなプールを、APY／TVL／満期順に一覧表示します。プールの準備金、IBT APR の構成、maturityValue、マルチプライヤー、タグを表示します。compact モードと include_expired フラグに対応しています。
spectra_get_pt_details	特定の Principal Token を詳しく調査します。maturityValue、マルチプライヤー（ポイントプログラム）、タグ、プールの準備金、IBT APR の構成、ラッパートークンの baseIbt など、すべてのデータを取得します。
spectra_compare_yield	固定利回り（PT）と変動利回り（IBT）を比較し、スプレッドの仕組みとエントリーコストを分析します。
spectra_get_looping_strategy	PT と Morpho のループを利用したレバレッジ利回りを計算します。実効清算マージン、借入金利の感応度（+1／2／3％）、損益分岐期間、失敗シナリオのモデリングを含みます。該当する市場が存在する場合、Morpho のライブ金利を自動取得します。
morpho_list_markets	Spectra PT を担保として受け入れる Morpho の貸付市場を検索します。チェーンまたはシンボルで絞り込めます。報酬インセンティブと市場ごとのボールト供給者数を表示します。Spectra PT のアドレスと相互参照します。
morpho_get_rate	特定の Morpho 市場のライブ借入金利、状態、供給側のコンテキストを取得します。PT スプレッド分析、主要供給者の特定、ボールトの割り当て詳細（AUM に占める割合、上限利用率）を含みます。
morpho_get_market_suppliers	Morpho 市場の供給側を分析します。規模順の主要供給者、ボールトと EOA／ルーパーの識別、集中度分析、供給ギャップの警告を表示します。貸付流動性の供給元を明らかにします。
morpho_list_vaults	チェーン上の Morpho ボールトを、拡充された割り当て情報とともに一覧表示します。Spectra PT のタグ付け、割り当てごとのライブ借入金利と利用率、上限利用率を含みます。市場金利と PT アドレスを並行取得し、遅延なしで情報を拡充します。
morpho_get_positions	チェーン上（またはすべての Morpho チェーン上）の市場とボールトを横断して、ユーザーの Morpho ポジションを照会します。担保、借入、供給の USD 額、ボールト預入額、ヘルスファクター、ルーパーの検出、ポジションシグナルを表示します。
morpho_get_history	特定の Morpho 市場の過去の金利と成長を取得します。借入／供給 APY、利用率、TVL の推移を、最小／平均／最大／現在の統計とともに表示します。金利の安定性シグナル、急騰の検出、需給逼迫のアラートを含みます。
spectra_get_protocol_stats	SPECTRA のトークノミクス、排出スケジュール、手数料の分配、ガバナンス情報を取得します。
spectra_list_chains	利用可能なネットワーク（10 チェーン）を一覧表示します。
spectra_get_portfolio	PT、YT、LP にまたがるウォレットのポジションを、USD 額、請求可能な利回り、Merkl 報酬（SPECTRA ゲージ排出量とインセンティブプログラム）とともに表示します。理由キーの解析により、報酬を特定のプールに照合します。
spectra_get_pool_volume	特定のプールの過去の売買出来高を取得します。PT アドレスまたはプールアドレスを指定できます。
spectra_get_pool_activity	直近の個別トランザクション（売買、流動性イベント）をフィルタリングして表示します。アドレス分離モードでは、競合する解釈の分岐（A／B／C）、サイクルの統計的信頼境界、競合する仮説に基づくフロー計算、コントラクト／EOA の検出、ガス見積もりを提示します。PT またはプールアドレスを指定できます。
spectra_get_address_activity	クロスプールのアドレススキャナーです。1 回の呼び出しで、チェーン上（またはすべてのチェーン上）にあるアドレスが利用したすべてのプールを検索します。ポートフォリオ照会を通じて、期限切れ／満期済みのプールも含みます。プールごとの内訳とクロスプールの集計を表示します。
spectra_quote_trade	PT 取引の見積もりを行います。正確な出力額にはオンチェーンの Curve get_dy() を使用し、利用できない場合は数式による推定にフォールバックします。価格インパクト、スリッページ、minOut、比率を含むプール準備金、IBT APR の構成を表示します。
spectra_simulate_trade	仮想 PT 取引の前後におけるポートフォリオを、差分、警告、オンチェーン見積もりとともにプレビューします。
spectra_scan_opportunities	資金量を考慮した機会スキャナーです。指定した取引量での価格インパクト、実効 APY、Morpho のループ、プール容量、IBT APR の構成、ポイントマルチプライヤーを表示します。compact モードに対応しています。
spectra_scan_yt_arbitrage	YT 金利と IBT 金利の裁定機会をスキャンし、YT が原資産利回りに対して誤って価格付けされているプールを探します。スプレッドの持続可能性分析に役立つ IBT APR の構成も含みます。compact モードに対応しています。
spectra_get_ve_info	Base チェーンのライブ veSPECTRA データ（オンチェーン読み取りによる総供給量）と、プールごとのマルチプライヤーを用いたブースト計算機を取得します。
spectra_list_metavaults	すべてのチェーン（または指定したチェーン）のライブ MetaVault を一覧表示します。キュレーター情報、TVL、ライブ APY、シェア価格、アクティブなポジション、エポック履歴を返します。
spectra_model_metavault	キュレーター向けに MetaVault の「ダブルループ」戦略をモデリングします。ライブモード（chain + metavault_address）では API から APY を自動取得し、手動モードでは base_apy を直接指定します。キュレーターの経済性（手数料収入、TVL の創出、実効 ROI）をモデル化します。
spectra_get_curator_dashboard	MetaVault キュレーター向けの運用ダッシュボードです。ボールトの健全性、ボールトの割り当て（利用可能な場合）とプール TVL を比較したポジションの状態、預入者の資金フロー、手数料収入の推定、ブリッジのアクティビティ、実行可能なアラートを表示します。誤解を防ぐため、ボールトの割り当てとプールレベルの TVL を明確に区別します。
pendle_list_markets	指定したチェーンまたはすべての Pendle チェーン上のアクティブな Pendle 市場を一覧表示します。Pendle 専用チェーン（Mantle、Berachain、HyperEVM、Corn）に対応しています。compact モードに対応しています。
pendle_get_market_details	単一の Pendle 市場を詳しく調査します。インプライド APY、LP APY の内訳（スワップ手数料 + PENDLE インセンティブ + ブースト）、原資産の変動 APY、プール準備金、手数料率、Merkl キャンペーンを表示します。
pendle_get_best_fixed_yields	すべての Pendle チェーンをスキャンし、最適な固定金利の機会を探します。TVL／流動性のフィルターを適用し、インプライド APY 順に表示します。Pendle 版の spectra_get_best_fixed_yields です。
pendle_get_portfolio	すべての Pendle チェーンにまたがるウォレットのポジションを表示します。PT、YT、LP の残高を USD 額とポジションごとのインプライド APY とともに取得します。
pendle_scan_opportunities	資金量を考慮した Pendle の機会スキャナーです。logit AMM モデルを使用して指定した取引量での価格インパクト、実効 APY、Pendle PT の Morpho ループ、Merkl キャンペーンを表示します。compact モードに対応しています。
pendle_get_market_capacity	Pendle 市場の複数サイズにわたる容量曲線を取得します。logit AMM モデルを用いて幾何級数的な資金額の各段階で見積もり、最適な規模と枯渇点を探します。
pendle_get_yield_curve	Pendle チェーン全体で、指定した原資産の期間構造を取得します。すべての満期を時系列順に並べ、カーブ形状（通常／逆転／フラット）、最も傾斜の急な区間、チェーン間のペアを分析します。
pendle_list_expiring_markets	Pendle チェーンをスキャンし、満期が近づいている市場を探します。緊急度別（CRITICAL ≤7d、WARNING ≤14d、ALERT ≤threshold）に分類します。
pendle_scan_yt_arbitrage	YT の誤価格付けスキャナーです。原資産の変動 APY とインプライド金利を比較します。Pendle YT は AMM で直接取引されるため、Spectra の Router によるフラッシュミント／償還より執行が簡単です。
pendle_get_protocol_stats	Pendle の全チェーンを対象に、TVL 総額、市場数、出来高、平均 APY などのプロトコル全体の集計統計を、チェーンごとの内訳と Spectra との重複インジケーターとともに取得します。
pendle_get_looping_strategy	Pendle PT 向けのレバレッジ PT + Morpho ループ計算機です。借入金利の感応度、損益分岐分析、P(underwater) の確率を含む過去 30 日間のリスク評価を行います。Morpho 市場を自動検出します。
pendle_quote_trade	Pendle の logit AMM モデルを使用して PT 取引を見積もります。予想出力額、価格インパクト、エントリーコスト控除後の実効 APY、スリッページ許容度を反映した最小出力額を表示します。
pendle_simulate_trade	Pendle PT 取引のポートフォリオ影響をシミュレーションします。取引前後のポジション価値、加重平均 APY の変化、集中度分析を表示します。
mv_compare_yield	重複するチェーン（mainnet、base、arbitrum、optimism、sonic、bsc）上で、Pendle と Spectra の利回りを並べて比較します。設定可能な許容差（exact ≤7d、close ≤30d、loose ≤90d）で満期を考慮して照合します。
mv_scan_curator_opportunities	MetaVault キュレーター向けの、プロトコル横断（Spectra + Pendle）かつ資金量を考慮したスキャナーです。指定した取引量での価格インパクト、実効 APY、Morpho のループ（Spectra + Pendle）、プロトコル横断のマッチタグを表示します。compact モードに対応しています。
spectra_get_onchain_activity	eth_getLogs を通じて過去のオンチェーンアクティビティを取得します。API から取引データが失効した場合にデータを復元できます。任意のチェーンに対応する動的な rpc_url パラメーターと、正しい表示に使う token_decimals（USDC=6、WBTC=8）に対応しています。pool_address を通じてCurve プールのイベント（スワップ、LP の追加／削除）、pt_address を通じてSpectra PT ボールトのイベント（Mint、Redeem、YieldClaimed）をデコードします。統合結果を得るため、両方を同時に指定できます。
spectra_get_pool_capacity	複数サイズにわたる容量曲線を取得します。幾何級数的な資金額の各段階で PT 取引を見積もり、価格インパクトと実効 APY の低下を表示します。最適な規模と枯渇点を特定します。オンチェーンの Curve 見積もりに対応しています。
mv_check_ibt_health	複数のシグナルによる IBT 健全性評価です。オンチェーンの ERC-4626 換算レート、APR の構成（有機的な利回りとインセンティブ）、プール残高の比率、プロトコルによる認識、流動性レベルを評価します。HEALTHY／CAUTION／WARNING の判定を返します。
spectra_get_yield_curve	すべてのチェーンを対象に、指定した原資産の期間構造を取得します。すべての満期を時系列順に並べ、インプライド APY、TVL、流動性を表示します。カーブ形状（通常／逆転／フラット）、最も傾斜の急な区間、チェーン間のペアを分析します。
morpho_monitor_risk	キュレーターの Morpho ポジションの清算リスクを監視します。ヘルスファクター、清算価格、清算までの距離、借入金利の変動、アラートレベル（ok／watch／warning／critical）を表示します。
spectra_stress_test_vault	MetaVault の出金ストレステストです。流動性の取り崩し順序（アイドル → 満期到来 → LP の引き出し → PT の売却）、残存する預入者のコスト、安全に償還できる最大額を表示します。市場ストレスモード（インパクト 2 倍）に対応しています。
mv_plan_rollover	満期が近づいている MetaVault ポジションのロールオーバー計画ツールです。Spectra + Pendle をスキャンして代替候補を探し、エントリーインパクト、利回り差、重複期間、実効純 APY を計算します。
mv_get_curator_portfolio	複数のボールトを集約したポートフォリオを取得します。AUM 総額、加重平均 APY、手数料収入予測、原資産／チェーンごとの集中度、ボールト横断のアクション項目を表示します。キュレーターアドレスによる検出モードと明示指定モードに対応しています。
mv_get_calibration	キャリブレーションオラクルです。「通常」の状態を示します。任意の Morpho 市場、Pendle 市場、Spectra プールの過去データから、統計的な基準値（パーセンタイル、異常しきい値）を計算します。同業比較と、アサーションにそのまま使えるしきい値の記述を含みます。認識（監視）と仕様（セキュリティアサーション）をつなぐツールです。
mv_get_position_map	プロトコル横断のポジションマップです。1 回の並行呼び出しで、Spectra + Pendle + Morpho + ガバナンス（veSPECTRA + vePENDLE）にまたがるウォレット全体を把握します。矛盾を検出します。未使用のガバナンスブースト、固定金利が高い場合の貸付、集中リスク、ルーパーの検出、プロトコル横断の期限切れ間近のポジションなどです。不完全な場合は数値の後ではなく前に INCOMPLETE と表示し、失敗を正直に報告します。プロトコルだけでなく、ユーザーを見る初のツールです。
spectra_get_gauge_votes	veSPECTRA ガバナンスの総合ダッシュボードです。ゲージの投票分布、投票 APR、賄賂インセンティブ、プールごとの SPECTRA 排出量を表示します。veSPECTRA 保有者がどこに投票を誘導しているか、どの報酬を得ているか、排出量の集中度、賄賂の効率（投票 1 件あたりの $ 額）を確認できます。
pendle_get_market_history	任意の Pendle 市場の過去の時系列データを取得します。7d／30d／90d／1y 期間のインプライド APY、TVL、出来高、PT／YT 価格を表示します。トレンド分析、利回りの安定性評価、異常検出に向けて「時間の経過とともに何が起きたか」に答える初のツールです。
spectra_list_expiring_pools	すべてのチェーンをスキャンし、満期が近づいているプールを探します（デフォルトのしきい値は 21 日）。緊急度別（CRITICAL ≤7d、WARNING ≤14d、ALERT ≤21d）に分類します。期限切れ間近の各プールの IBT をすべてのアクティブなプールと照合し、後継プールを検出します。ガバナンス API からゲージの状態を取得します。プールごとの準備状況（OK／CAUTION／WARNING）を評価します。後継プールのデプロイ、ゲージ提案の提出、移行の準備に関する運用者向けチェックリストを表示します。
mv_get_protocol_context	12 のトピックにわたるプロトコルの仕組みを参照情報として返します。pt_yt_mechanics、router_batching、position_analysis、looping、networks、deposit_path、glossary、fees_and_costs、pendle_morpho、workflow_routing、protocol_pulse（ライブ TVL／排出量／満期が近いプール）、external_protocols（MetaVault が externalPositions を通じて保有できる Spectra 以外のプロトコルの一覧。各エントリーの決済期間、観測境界、緩和策を含む）です。手数料のトピックでは、Spectra の 3％／Pendle の 5％の YT 手数料、報酬の算定基準（保有額または想定元本）、Merkl キャンペーンの種類、外部ポイントプログラムの検出について説明します。

対応チェーン

Spectra：Ethereum（mainnet）、Base、Arbitrum、Optimism、Avalanche、Katana、Sonic、Flare、BSC、Monad、Hemi、HyperEVM、SEI

Pendle：Ethereum、Optimism、BSC、Sonic、Base、Arbitrum、Mantle、Berachain、HyperEVM、Corn

Morpho PT markets：Ethereum、Base、Arbitrum、Katana

チェーンリストのメンテナンス（手動）

3 つのリストはすべて src/config.ts にハードコードされており、プロトコルが新しいチェーンにデプロイされた際は手動で更新する必要があります。

• Spectra — SUPPORTED_CHAINS_INTERNAL（およびチェーンごとのテーブルである CHAIN_RPC_URLS、CHAIN_RPC_FALLBACKS、CHAIN_BLOCK_TIMES、CHAIN_GAS_ESTIMATES）を編集します。Spectra ネイティブのすべてのツール（メタボルト一覧、プール一覧、期限切れ間近のプール、プロトコルの動向、キュレーターダッシュボードなど）はこのリストを参照するため、1 か所の編集がすべてに反映されます。
• Pendle — PENDLE_CHAIN_IDS と PENDLE_CHAIN_NAMES を編集します。情報源：GET https://api-v2.pendle.finance/core/v1/chains。
• Morpho — MORPHO_CHAIN_IDS を編集します。情報源：チェーンごとの Morpho GraphQL morphoBlue クエリ。

自動カナリアはありません。config.ts の CONFIG_VERIFIED_DATES マップは、リストが 120 日を超えて古い場合に起動時に stderr へ警告を出しますが、これはカレンダー上のアラームであり、「新しいチェーンが追加された」ことを知らせるアラームではありません。実際的な頻度としては、毎月確認するか、プロトコルチームが新たなデプロイを発表したときに確認してください。

いずれ対応が必要な既知の不整合：MORPHO_CHAIN_IDS のコメントには hyperliquid(999) 上の Morpho markets が記載されています。これは新たに追加された hyperevm と同じチェーンです。Morpho が HyperEVM で PT markets を提供し、それらをスキャンする場合は、Morpho マップに hyperevm: 999 を追加してください。

veSPECTRA ブースト

サーバーは Base チェーンから eth_call を直接実行して veSPECTRA の総供給量をリアルタイムで読み取り（ethers/viem への依存なし）、実際の Spectra の計算式を使ってプールごとのブースト倍率を算出します。

B = min(2.5, 1.5 * (v/V) * (D/d) + 1)

v = your veSPECTRA balance
V = total veSPECTRA supply (read live from Base)
D = pool TVL
d = your deposit size

veSPECTRA の総量に対するシェアがプール TVL に対するシェア以上の場合、ブーストは最大の 2.5 倍になります。

ve_spectra_balance を受け取るツール（spectra_scan_opportunities、spectra_scan_yt_arbitrage、spectra_compare_yield、spectra_get_ve_info）は、プールごとのブーストを自動で計算します。veSPECTRA コントラクトは Base 上の NFT ベースの投票エスクロー（veNFT）で、アドレスは 0x6a89228055c7c28430692e342f149f37462b478b です。情報源：spectra-core。

MetaVault の検出と戦略モデリング

MetaVault は、LP のロールオーバーを自動化し、YT 利回りを LP ポジションに再投資する ERC-7540 のキュレーション型ボルトです。2 つのツールが連携して動作します。

spectra_list_metavaults — 検出ツールです。API（/v1/{network}/metavaults）から MetaVault の最新データを取得し、単一チェーンまたはすべてのチェーンを並列でスキャンします。キュレーター情報、TVL、リアルタイム APY、シェア価格、PT／プールの詳細を含む有効なポジション、エポックレートの履歴を返します。

spectra_model_metavault — 2 つのモードを備えた戦略モデラーです。

• ライブモード：chain と metavault_address を指定すると、ボルトのリアルタイム APY を自動取得して base_apy として設定します。借入レート、LTV、キュレーター手数料など、その他のパラメーターは引き続き上書きできます。
• 手動モード：仮定に基づくモデリングやローンチ前のモデリングでは、base_apy を直接指定します。

「ダブルループ」の仕組み：

Layer 1 (inside vault):  Deposit → PT/LP allocation → YT yield → more LP (compounding)
Layer 2 (on top):        MV shares → Morpho collateral → borrow → deposit back (leverage)

重要な点は、YT の複利運用によってボルトのベース APY が上昇し、レバレッジによってその上昇したベース APY がさらに増幅されることです。これにより、レバレッジに応じて拡大する、生の PT ループを上回る「ダブルループ・プレミアム」が生まれます。

キュレーターの収益性も組み込まれており、外部預入に対する手数料収入、ループ運用によって生じる追加 TVL、キュレーター自身の資本に対する実効 ROI をモデル化します。

セットアップ

npm からインストール（推奨）

npm install -g metavault-mcp

または、インストールせずに直接実行できます。

npx metavault-mcp

ソースからインストール

git clone https://github.com/Finanzgoblin/metavault-mcp.git
cd metavault-mcp
npm install
npm run build

Claude Desktop に接続する

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "metavault-mcp": {
      "command": "npx",
      "args": ["metavault-mcp"]
    }
  }
}

Claude Desktop を再起動します。55 個すべてのツール（Spectra、Pendle、Morpho、クロスプロトコル）が利用できるようになります。

Claude Code に接続する

claude mcp add metavault-mcp -- npx metavault-mcp

詳細分析用プロンプト

最初に提供するコンテキストが豊富であるほど、エージェントはより深く分析できます。入力ごとに、利用可能になるツールチェーンが異なります。

入力	利用可能になる機能
資金規模（$200K）	資金規模に応じた価格インパクト、プールの容量制限、実効 APY
ウォレットアドレス（0x...）	ポートフォリオのシミュレーション、既存ポジションのコンテキスト、Merkl 報酬
veSPECTRA 残高	プールごとの実際のブースト（最小／最大範囲ではありません）
資産の希望	絞り込んだ利回り曲線、対象を絞ったスキャン
戦略タイプ	LP、PT、ループ運用、MetaVault のいずれかを判定し、連携するツールを決定
満期期間	期間構造の分析、ロールオーバーのタイミング

理想的なプロンプトでは、これらすべてを組み合わせます。 8～10 個のツールチェーンを起動する例を紹介します。

• 利回りハンター：「USDC を 50,000 ドル、veSPECTRA を 10,000 保有しています。60～180 日の期間で、リスク調整後の最適な固定利回りを探してください。IBT の健全性を確認し、私が実際に参入する場合の正確な見積もりを出して、ほかに誰がプールにいるかも示してください。」
• キュレーター：「Base 上に USDC の MetaVault を構築しています。自己資金は 500,000 ドル、外部資金は 2,000,000 ドルを見込んでいます。ダブルループの経済性をモデル化し、Spectra と Pendle の LP 配分を比較してください。」
• 調査担当者：「ウォレット 0xABC... は Spectra メインネットでアクティブです。ポートフォリオ、全プールでのアクティビティ、シーケンス分析、運用中の戦略など、すべてを確認してください。」
• 期間構造：「全チェーンの ETH 利回り曲線を表示してください。期間プレミアムに異常があるのはどこですか？ 上位 3 件の価格の乖離について、200,000 ドルの場合のプール容量を見積もってください。」

真の分析の深さは、ツール同士を相互参照することで得られます。単一のツールだけでは全体像を把握できません。エージェントは実行時に mv_get_protocol_context(topic="workflow_routing") を呼び出し、こうした組み合わせを学習します。

質問例

接続後、Claude に次のような質問ができます。

• 「現在、USDC の最良の固定利回りはどれですか？」
• 「Base 上の TVL が 5 万ドルを超える Spectra プールをすべて表示してください」
• 「Morpho を使って、Base 上の PT-USDC の 3 倍ルーピング戦略を計算してください」
• 「stETH の固定金利は変動金利より有利ですか？」
• 「Spectra PT を担保として受け入れる Morpho マーケットはどれですか？」
• 「その Morpho PT-USDC マーケットの借入金利はいくらですか？」
• 「現在の SPECTRA の排出量とロック率を教えてください」
• 「すべてのチェーンにまたがる 0xABC...DEF のポートフォリオを表示してください。未請求の Merkl 報酬も含めてください」
• 「このプールの最近の取引状況はどうなっていますか？」
• 「mainnet 上のすべてのプールをスキャンして、アドレス 0xABC...DEF の取引状況を確認してください」
• 「アドレス 0xABC...DEF がコントラクトか EOA かを確認し、取引パターンを表示してください」
• 「このプールで 10,000 USDC 相当の PT を購入する見積もりを出してください」
• 「この PT を 5 万ドル分購入した場合、ポートフォリオはどうなりますか？」
• 「運用に回せる 10 万ドルがあります。すべてのチェーンをスキャンして、リスク調整後利回りが最も高い機会を探してください」
• 「最大 2％のエントリー時価格影響で、50 万ドル規模の USDC 運用機会を探してください」
• 「市場が利回りを誤って評価している YT の裁定機会を探してください」
• 「veSPECTRA を 10 万保有しています。このプールに 1 万ドルを預け入れると、どれくらいブーストされますか？」
• 「veSPECTRA の総供給量と、最大ブーストに必要な量を表示してください」
• 「現在稼働中の MetaVault はどれですか？すべてのチェーンにあるものをすべて表示してください」
• 「Base 上の MetaVault を表示してください。APY とキュレーターはどうなっていますか？」
• 「Base 上のこの MetaVault の戦略をモデル化してください」（ライブ APY を自動取得します）
• 「ベース APY が 12％、YT の複利運用が 3％、キュレーター手数料が 10％の MetaVault をモデル化してください。ルーピングはどのようになりますか？」
• 「ベース APY が 12％の場合、MetaVault のルーピングと通常の PT ルーピングを比較してください」
• 「自己資本 10 万ドル、外部預け入れ 100 万ドルでボールトを運用しています。実効 ROI はどれくらいですか？」
• 「Base 上の Spectra と Pendle の利回りを比較してください。USDC ではどちらのプロトコルの金利が高いですか？」
• 「50 万ドルの MetaVault を運用しています。Spectra と Pendle の両方をスキャンして、最良の機会を探してください」
• 「Arbitrum 上のアクティブな Pendle マーケットをすべて、TVL の高い順に表示してください」
• 「価格影響によって利回りが損なわれる前に、このプールにいくらまで資金を投入できますか？」
• 「この PT の裏付けとなる IBT は健全ですか？交換レートと APR の構成を確認してください」
• 「USDC のイールドカーブを表示してください。各満期でどのような金利が利用できますか？」
• 「すべてのチェーンにおける ETH の 30 日、90 日、180 日の金利を比較してください」
• 「このアドレスは数週間前に Katana で取引しましたが、spectra_get_pool_activity には何も表示されません。過去 7 日間のオンチェーンログを取得してください」
• 「このプールの過去のアクティビティを、私の RPC URL を使って取得してください：https://rpc.katana.network」
• 「清算リスクがないか、Morpho のポジションを監視してください。それぞれの清算までの距離を表示してください」
• 「Base 上の MetaVault のストレステストをしてください。1 エポック中に預け入れ者の 30％が償還した場合、どうなりますか？」
• 「MetaVault に 14 日後に満期を迎えるポジションがあります。ロールオーバーを計画し、最適な候補を表示してください」
• 「すべてのチェーンにまたがるキュレーターのポートフォリオを集計してください。運用資産総額、加重平均 APY、集中度を表示してください」

アーキテクチャ

Agent (Claude/GPT/etc)
  | MCP Protocol (stdio)
MetaVault MCP (this)
  | HTTP (15s timeout, 1 retry on 5xx/network errors)
  |
  +-- api.spectra.finance/v1/{chain}/pools
  +-- api.spectra.finance/v1/{chain}/pt/{address}
  +-- api.spectra.finance/v1/{chain}/portfolio/{wallet}
  +-- api.spectra.finance/v1/{chain}/pools/{pool}/volume
  +-- api.spectra.finance/v1/{chain}/pools/{pool}/activity
  +-- api.spectra.finance/v1/{chain}/metavaults
  +-- app.spectra.finance/api/v1/spectra/*
  +-- api.merkl.xyz/v3/userRewards (unclaimed Merkl rewards per wallet)
  +-- api.merkl.xyz/v4/opportunities (Merkl campaign APR per chain)
  +-- api.morpho.org/graphql (PT collateral markets, borrow rates)
  +-- api-v2.pendle.finance/core/* (Pendle market data for cross-protocol comparison)
  +-- mainnet.base.org (veSPECTRA on-chain reads via raw eth_call)
  +-- Chain RPCs: eth_call for Curve get_dy() quotes, eth_getCode for contract detection
  |   (mainnet, base, arbitrum, optimism, avalanche, sonic, bsc, flare)
  +-- Chain RPCs: eth_getLogs for historical pool activity (any chain via dynamic rpc_url)

モジュール式の TypeScript サーバーです。読み取り専用で、Spectra の既存 API、Morpho の GraphQL API、オンチェーンの Curve get_dy() 見積もりとコントラクト検出のためのチェーン RPC、veSPECTRA データ取得のための Base RPC に問い合わせます。ウォレット、トランザクション、キー、web3 ライブラリは不要です。

src/
  index.ts          Entry point, tool registration, Layer 1 resources (spectra-overview,
                      curator-strategy-guide), main(), graceful shutdown
  config.ts         Constants, chain config, Zod schemas, protocol parameters, veSPECTRA constants,
                      block time constants per chain, RPC URL resolution (hardcoded + dynamic override)
  types.ts          TypeScript interfaces (SpectraPt, MorphoMarket, ScanOpportunity, MerklTokenReward, MerklChainRewards, MerklCampaign, etc.)
  api.ts            Fetch helpers with retry, GraphQL sanitization, Morpho batch lookup,
                      veSPECTRA RPC with Promise-based dedup cache, 30s TTL pool data cache,
                      Curve get_dy() on-chain quoting, ERC-4626 convertToAssets() health check,
                      eth_getCode contract detection,
                      MetaVault multi-chain scanning, API response validation at system boundary,
                      chunked eth_getLogs with retry for historical event log fetching,
                      Merkl reward fetching and parsing (pool address extraction from reason keys,
                      BigInt wei→human conversion, matched/unmatched reward categorization),
                      Merkl v4 campaign APR fetching (60s TTL cache, inflight dedup, address-based lookup)
  primitives.ts     Format primitives (formatUsd, formatPct, formatDate, daysToMaturity,
                      estimatePriceImpact, chainIdToName) — HOME. Re-exported from formatters.ts
                      for backward compat with 42 consumer files.
  protocols/        externalPositions registry (plugin-style extension for Spectra's whitelisted
                      ERC-4626 modules). types.ts (SourcedValue/InterpretedValue/ProtocolMeta + zod),
                      metadata.ts (avant + pendle + _unknown), cost-models.ts (zero, lp_exit_samechain,
                      lp_exit_crosschain_cctp, liquidation), engine.ts (renderExternalPosition,
                      classifyForStress, generateActionItems, DriftCollector), registry.ts (getMeta +
                      freshness warnings), index.ts (barrel). Spec: docs/protocols-metadata-spec.md.
  formatters.ts     Formatting, BigInt LLTV parsing, closed-form leverage math,
                      price impact, fractional-day maturity, boost computation,
                      slim envelope helpers, token amount formatting (BigInt → human-readable),
                      cross-protocol maturity matching (normalizeUnderlyingSymbol, matchByAssetAndMaturity),
                      Layer 3 output hints (Position Shape, LP APY breakdown,
                      volume signals, Morpho market hints, portfolio signals,
                      competing interpretation branches, statistical confidence boundaries,
                      flow accounting with competing hypotheses),
                      Layer 4 observation coverage (value coverage, temporal gaps,
                      data source coverage, activity diversity, boundary markers),
                      Merkl reward display (per-position matched rewards, unmatched/exited rewards),
                      Merkl campaign APR display (formatMerklCampaignLines with double-counting avoidance)
  tools/            Layer 2: each tool description teaches domain-specific mechanics
    context.ts      mv_get_protocol_context (Layer 1 protocol mechanics, deposit paths, glossary, callable on-demand)
    pt.ts           spectra_get_pt_details, spectra_list_pools, spectra_get_best_fixed_yields, spectra_compare_yield
    looping.ts      spectra_get_looping_strategy
    portfolio.ts    spectra_get_portfolio (balance ratio strategy signals, portfolio-level hints, cross-ref nudges,
                      Merkl rewards integration — parallel fetch, per-position matching, unmatched rewards)
    pool.ts         spectra_get_pool_volume (with volume/liquidity hints), spectra_get_pool_activity (PT address resolution, Router batching,
                      address isolation w/ cycle detection, flow accounting, contract detection,
                      gas estimates, pool impact warnings, observation coverage metrics),
                      spectra_get_address_activity (cross-pool scanner with coverage boundary markers)
    morpho.ts       morpho_list_markets (with capacity/utilization hints), morpho_get_rate (with PT spread analysis)
    protocol.ts     spectra_get_protocol_stats, spectra_list_chains
    quote.ts        spectra_quote_trade (on-chain Curve get_dy() with math fallback)
    simulate.ts     spectra_simulate_trade (also uses on-chain quoting)
    strategy.ts     spectra_scan_opportunities (capital-aware, batch Morpho, negative-APY filtering, strategy tension)
    yt_arb.ts       spectra_scan_yt_arbitrage (YT execution mechanics, flash-mint/flash-redeem)
    ve.ts           spectra_get_ve_info
    metavault.ts    spectra_list_metavaults, spectra_model_metavault (live API + computational modeling),
                      spectra_get_curator_dashboard (vault allocation disambiguation, cross-chain position awareness)
    pendle.ts       pendle_list_markets, mv_compare_yield (maturity-aware cross-protocol yield comparison)
    curator_scan.ts mv_scan_curator_opportunities (cross-protocol capital-aware scanner for MetaVault curators)
    onchain.ts      spectra_get_onchain_activity (historical eth_getLogs, Curve pool + PT vault event decoding, dynamic RPC)
    capacity.ts     spectra_get_pool_capacity (multi-size quote ladder, sweet spot / exhaustion detection)
    ibt_health.ts   mv_check_ibt_health (ERC-4626 conversion rate, APR composition, pool balance, verdict)
    yield_curve.ts  spectra_get_yield_curve (term structure for a given underlying across all chains)
    risk_monitor.ts morpho_monitor_risk (liquidation distance, health factor, borrow rate drift, alert levels)
    stress_test.ts  spectra_stress_test_vault (withdrawal liquidity waterfall, market stress simulation)
    rollover.ts     mv_plan_rollover (expiring position rollover planner with cross-protocol candidates)
    curator_portfolio.ts mv_get_curator_portfolio (multi-vault aggregation, AUM, blended APY, concentration)
    expiry_monitor.ts spectra_list_expiring_pools (pool maturity monitoring, urgency grouping, successor cross-reference, gauge status, readiness assessment)
    gauge_votes.ts  spectra_get_gauge_votes (veSPECTRA governance: vote distribution, voting APRs, bribes, emissions)
    pendle_history.ts pendle_get_market_history (historical APY, TVL, volume, PT/YT prices time-series)
    position_map.ts mv_get_position_map (cross-protocol wallet view: Spectra + Pendle + Morpho + governance, contradiction detection)
test.cjs              Integration test suite (405 tests, McpTestClient over stdio)
test-agent.cjs        Agent reasoning test suite (82 assertions, McpTestClient over stdio)
AGENT-TESTS.md        38-question subjective test suite with grading rubrics (incl. open emergence, coverage, newcomer comprehension tiers)
EMERGENCE-AUDIT.md    Open Emergence audit — competing branches, observation coverage, anomaly detection gaps
CODE-REVIEW.md        Full codebase review (bugs, security, code quality, test coverage)
SECURITY-REVIEW.md    Security-focused review (SSRF, GraphQL injection, dependency vulnerabilities)
docs/
  recursive-meta-process.md    Open Emergence metaframework specification
  dissolution-conditions.md    Dissolution conditions for every structural decision
  architecture-review-agentic-accessibility.md    Agentic accessibility review with feature proposals

各ツールファイルは register(server) 関数をエクスポートします。新しいツールを追加するには、src/tools/newtool.ts を作成して register() をエクスポートし、index.ts でインポートして呼び出します。

すべてのアドレスパラメーターは検証されます（0x + 40 桁の 16 進数）。すべての API 呼び出しには 15 秒のタイムアウトが設定され、一時的な障害（5xx、ETIMEDOUT、ENETUNREACH、ENOTFOUND）の場合は自動的に再試行します。クロスチェーンのスキャンでは Promise.allSettled を使用するため、1 つのチェーンで障害が発生しても、ほかのチェーンの結果取得は妨げられません。GraphQL の入力はインジェクションを防ぐためにサニタイズされます。すべてのエラー応答は MCP の isError: true フラグを使用し、エージェントに適切にエラーを通知します。

型安全性

• API の戻り値の型：fetchSpectra() と fetchMorpho() は Promise<any> ではなく Promise<unknown> を返すため、呼び出し箇所ごとに明示的な型アサーションが必要です
• Null 合体演算子：小数桁数や残高のフォールバックにはすべて || ではなく ?? を使用し、小数桁数が 0 のトークンを正しく処理します
• Morpho の状態フィールド：実際の API の動作に合わせて number | null として型付けし、NaN が暗黙に伝播するのを防ぎます
• JSON の解析：本文をまずテキストとして読み取ってから JSON.parse() を実行し、エラー診断を妨げていたストリームの二重読み取りを回避します
• BigInt の精度：veSPECTRA の総供給量は 10n ** BigInt(18) を使って解析し、浮動小数点数を介した際のオーバーフローを防ぎます。取引の見積もりでは amountToBigInt()（文字列演算）を使い、amount * 10^decimals が MAX_SAFE_INTEGER を超えた場合の精度損失を回避します
• 入力検証：Zod スキーマで、すべての数値入力に .min() / .max() の境界を適用し、無効な GraphQL クエリを防ぎます

技術的な詳細

精度と正確性

• Morpho LLTV：18 桁の小数を持つ生の値（例：860000000000000000 → 正確に 0.86）での浮動小数点精度の損失を避けるため、BigInt 演算で解析します
• レバレッジ計算：反復ループによる累積計算を、閉形式の等比級数 (1 - ltv^(n+1)) / (1 - ltv) に置き換えます。数値的に正確で、計算量は O(1) です
• YT の裁定取引：インプライドレートの計算には満期までの日数を小数で使用し、満期間近の年率換算で生じる 1 日のずれによる誤差を回避します
• 価格インパクト：流動性がゼロのプールでは、誤って機会ありと判定されるのを防ぐため、インパクトを 0% ではなく 100% とします。取引見積もりで出力が負になるのを防ぐため、インパクトの上限は 99% に制限されます
• マイナス APY のフィルタリング：エントリーコストが利回りを上回る機会は、最下位に並べるのではなく、ランキングの前に除外します

耐障害性

• 再試行ロジック：ECONNRESET、ETIMEDOUT、ENETUNREACH、ENOTFOUND、EPIPE、EHOSTUNREACH、EAI_AGAIN、UND_ERR_SOCKET エラーに対応します
• プールデータキャッシュ：チェーンごとに TTL 30 秒で、進行中のリクエストを重複排除します。30 秒以内に繰り返しスキャンした場合、キャッシュデータを返します
• API 検証：validatePtEntries() がシステム境界で不正な API レスポンスを除外します（アドレス、満期、名前の各フィールドを検証）
• veSPECTRA キャッシュ：Promise ベースの重複排除により、複数のツールを同時に実行した際の RPC 呼び出しの重複を防ぎます（TTL 5 分）
• Morpho バッチ上限：GraphQL のレスポンス制限を避けるため、first パラメーターを min(addresses * 3, 500) 以下に制限します
• オンチェーンの価格見積もり：8 つのチェーンで、raw eth_call を介して Curve の get_dy() を実行します。RPC エラー時は数式による推定に自動でフォールバックします
• IBT ヘルスチェック：raw eth_call を介して ERC-4626 の convertToAssets() を実行します。RPC が利用できない場合は適切に機能を縮退し、ほかのヘルスチェックは引き続き実行します
• 過去のイベントログ：eth_getLogs をチャンク単位（1 チャンクあたり 2000 ブロック）で実行し、各チャンクごとに再試行します。失敗したチャンクをスキップして部分的な結果を返します。動的な rpc_url パラメーターにより、RPC がハードコードされていない任意のチェーンを利用できます
• コントラクト検出キャッシュ：eth_getCode の結果を永続的な Map キャッシュに保存します（コントラクトコードは変更されないため）
• Merkl 報酬：Merkl API からベストエフォートで並列取得します。失敗してもポートフォリオの表示は妨げられません。reason キーから正規表現でプールアドレスを抽出して照合します。安全に 18 桁の小数演算を行うため、BigInt の parseWei() 変換を使用します
• Merkl キャンペーン：チェーンごとに v4 キャンペーンの APR をベストエフォートで取得します（進行中のリクエストを重複排除する TTL 60 秒のキャッシュ）。失敗した場合は空のマップを返し、ツールの出力は変わりません。ネイティブ API データですでに表示されている報酬トークンを含むキャンペーンはスキップし、二重計上を防ぎます
• MCP エラー通知：すべてのエラー捕捉ブロックが isError: true を返すため、エージェントはエラーと空の結果を区別できます
• PT アドレスの解決：プールツール（spectra_get_pool_volume、spectra_get_pool_activity）はプールアドレスと PT アドレスのどちらも受け付け、自動的に解決します
• エラーログ：Morpho の検索におけるエラー捕捉ブロックは、失敗を黙って無視せず、標準エラー出力に記録します
• グレースフルシャットダウン：SIGTERM／SIGINT 時に process.exit() を実行する前に server.close() を呼び出します

テスト

ソースコードのチェックアウトから実行します：

# Full integration suite (405 tests, requires network)
npm test

# Schema/registration only (98 tests, no network)
npm run test:offline

# Unit tests (242 tests, no network)
npm run test:unit

# Agent reasoning tests (82 assertions, requires network)
npm run test:agent

ユニットテスト（api.test.ts、formatters.test.ts、config.test.ts）

純粋関数のロジックを対象とする 242 件のテストです。GraphQL のサニタイズ、Morpho のフィールド定数、Merkl 報酬の解析（reason キーからのプールアドレス抽出、wei から人間が読める値への変換、一致・不一致の分類）、Merkl 報酬のフォーマット、残高のフォーマット、プロトコル間の満期照合（normalizeUnderlyingSymbol、matchByAssetAndMaturity）、Pendle の logit AMM 価格インパクトモデル（estimatePendlePriceImpact）、Pendle の日数／満期ヘルパー（pendleDaysToMaturity）、Pendle 市場のフォーマッター（簡潔表示と要約）、設定の検証を対象とします。ネットワーク接続は不要です。

統合テスト（test.cjs）

ツール登録、スキーマ検証、API レスポンス、オンチェーンの Curve get_dy() による価格見積もり、プールをまたいだアドレススキャン、アドレス分離モード、プロトコルをまたいだキュレータースキャン、不正なアドレスに対するネガティブテストを対象とする 405 件のテストです。稼働中の API からプールアドレスと PT アドレスを動的に検出するため、プールの満期が過ぎてもテストが古くなりません。

エージェントの推論テスト（test-agent.cjs）

複数ツールを使うワークフローを対象とした82件のアサーションで、「推論の表層」を検証します。つまり、これらのツールを使うエージェントが異常を検出し、データを相互参照し、プロトコルの仕組みによる落とし穴を回避できるかをテストします。テスト内容は次のとおりです。

• プロトコルコンテキストの完全性 — すべてのトピックが含まれていること、Router のバッチ処理に関する曖昧さが説明されていること、相互参照の指針が含まれていること
• 異常検出 — 生の APY と資本を考慮したランキングでは結果が異なること（意図的な差異）
• ツール間のデータ整合性 — spectra_list_pools → spectra_get_pt_details → spectra_compare_yield の間で APY が一致すること
• Router の仕組み — プールのアクティビティからポートフォリオを相互参照し、ミントして売却するループを検出すること
• Router の制限 — eth_getLogs のアドレスフィルタリングでは取得できない Router のトランザクションを API が解決すること
• MetaVault のデータ整合性 — キュレーター情報、TVL、APY、ボールトの資金フロー、期限切れポジションのフラグ付け
• 期限切れプールの検出 — spectra_list_pools がアクティブなプールのみを返すこと、MetaVault が期限切れポジションを表示すること
• veSPECTRA のブースト計算 — 最大ブースト（1M veSPECTRA + $1K）と最小ブースト（100 veSPECTRA + $1M）
• Morpho のループ処理フォールバック — PT の Morpho マーケットが存在しない場合に適切に処理すること
• Morpho マーケットの分類 — Spectra と Pendle/Other のラベル、未対応チェーンの処理
• MetaVault スキャンの表示制御 — include_metavaults フラグによって MetaVault セクションが正しく表示・非表示になること
• Pendle との比較 — 差分を含む条件を揃えたペアごとの比較、Pendle のみのマーケット、集計値
• 表示される API フィールド — maturityValue、multiplier（ポイントプログラム）、tags、比率付きプールリザーブ、IBT APR の構成、ラッパートークンの baseIbt
• ポートフォリオ内の Merkl 報酬 — SPECTRA のゲージ排出量がポートフォリオ出力に表示されること、ウォレットが空の場合に適切に処理すること

主観評価テストスイート（AGENT-TESTS.md）

11段階（基本的なツールの使用 → オープンエマージェンス → 初心者の理解度）にわたる38件のコピーして貼り付け可能な質問と、MCP ツール使用時の LLM エージェントの品質を評価するための採点基準です。Tier 8 では「オープンエマージェンス」、つまり単一の説明に収束させず、競合する解釈を保つ能力をテストします。Tier 11 では初心者の理解度をテストします。エージェントが入金経路を説明し、保守的な影響推定を認識し、適切なスキャナーに誘導できるかを確認します。これらのテストは、サブエージェントを起動して回答を手動で、または LLM を判定役として採点するように設計されています。

API リファレンス

このサーバーは、以下のエンドポイントをラップします。

エンドポイント	使用するツール
GET /v1/{chain}/pools	spectra_list_pools、spectra_get_best_fixed_yields、spectra_scan_opportunities、spectra_scan_yt_arbitrage、spectra_get_yield_curve（TTL 30 秒のキャッシュ）
GET /v1/{chain}/pt/{address}	spectra_get_pt_details、spectra_compare_yield、spectra_get_looping_strategy、spectra_quote_trade、spectra_simulate_trade、spectra_get_pool_capacity、mv_check_ibt_health、spectra_get_pool_volume／spectra_get_pool_activity（PT からプールへの解決）
GET /v1/{chain}/portfolio/{wallet}	spectra_get_portfolio、spectra_simulate_trade、spectra_get_address_activity（期限切れプールの検出）
GET /v1/{chain}/pools/{pool}/volume	spectra_get_pool_volume
GET /v1/{chain}/pools/{pool}/activity	spectra_get_pool_activity、spectra_get_address_activity（アクティブおよび期限切れプール）
GET /v1/{chain}/metavaults	spectra_list_metavaults、spectra_model_metavault（ライブモード）
GET api.merkl.xyz/v3/userRewards?user={address}&chainId={chainId}	spectra_get_portfolio（Merkl 報酬の取得 — SPECTRA ゲージ排出量＋インセンティブプログラム）
GET api.merkl.xyz/v4/opportunities?chainId={chainId}	spectra_list_pools、spectra_get_pt_details、spectra_compare_yield、pendle_list_markets、mv_compare_yield、spectra_scan_opportunities、mv_scan_curator_opportunities、spectra_scan_yt_arbitrage（Merkl キャンペーン APR — TTL 60 秒のキャッシュ）
GET api.spectra.finance/v1/governance/voting-incentives	spectra_list_expiring_pools（ゲージの状態 — プールアドレスが存在する場合、ゲージあり）
GET app.spectra.finance/api/v1/spectra/circulating-supply	spectra_get_protocol_stats
GET app.spectra.finance/api/v1/spectra/total-supply	spectra_get_protocol_stats
POST api.morpho.org/graphql	morpho_list_markets、morpho_get_rate、spectra_get_looping_strategy（自動検出）、spectra_scan_opportunities（一括）
POST mainnet.base.org（eth_call）	spectra_get_ve_info、spectra_scan_opportunities、spectra_scan_yt_arbitrage、spectra_compare_yield（veSPECTRA の総供給量）
POST {chain RPC}（eth_call: get_dy）	spectra_quote_trade、spectra_simulate_trade、spectra_get_pool_capacity（Curve StableSwap-NG のオンチェーン見積もり）
POST {chain RPC}（eth_call: convertToAssets）	mv_check_ibt_health（ERC-4626 IBT の換算レート健全性チェック）
POST {chain RPC}（eth_call: eth_getCode）	spectra_get_pool_activity（アドレスモードでのコントラクトと EOA の判定）
POST {chain RPC}（eth_getLogs）	spectra_get_onchain_activity（過去の Curve プールイベント＋Spectra PT ボールトイベント — 動的な rpc_url の上書きに対応）
GET api-v2.pendle.finance/core/v2/{chainId}/markets/active	pendle_list_markets（Pendle マーケットの検出）
GET api-v2.pendle.finance/core/v2/{chainId}/markets/active	mv_compare_yield（満期を考慮したプロトコル横断の比較）
GET api-v2.pendle.finance/core/v2/{chainId}/markets/active	mv_scan_curator_opportunities（資本を考慮したプロトコル横断のスキャン — Spectra＋Pendle）

注：{chain} では Ethereum に mainnet スラッグを使用します（別名の ethereum もサーバーで受け付けられ、自動的にマッピングされます）。

Pendle プロトコルの統合

13 個の Pendle ツールは、Spectra ツールセットと完全な機能同等性を備え、さらに統合分析向けのプロトコル横断ツールを 2 個提供します。

Pendle ネイティブツール（13）

カテゴリ	Pendle ツール	Spectra 相当ツール
検出	pendle_list_markets	spectra_list_pools
検出	pendle_get_best_fixed_yields	spectra_get_best_fixed_yields
分析	pendle_get_market_details	spectra_get_pt_details
分析	pendle_get_market_capacity	spectra_get_pool_capacity
分析	pendle_get_yield_curve	spectra_get_yield_curve
ポートフォリオ	pendle_get_portfolio	spectra_get_portfolio
戦略	pendle_scan_opportunities	spectra_scan_opportunities
戦略	pendle_scan_yt_arbitrage	spectra_scan_yt_arbitrage
戦略	pendle_get_looping_strategy	spectra_get_looping_strategy
取引	pendle_quote_trade	spectra_quote_trade
取引	pendle_simulate_trade	spectra_simulate_trade
モニタリング	pendle_list_expiring_markets	spectra_list_expiring_pools
プロトコル	pendle_get_protocol_stats	spectra_get_protocol_stats

クロスプロトコルツール（2）

mv_compare_yield — 重複するチェーン上で、満期を考慮したマッチングによる並列比較を行います。基礎資産のシンボル（wstETH↔stETH、USDC.e↔USDC）を正規化し、設定可能な許容範囲内で最も近い満期と照合します（完全一致 ≤7日、近似 ≤30日、緩やかな一致 ≤90日）。各ペアのマッチ品質と満期の差を表示します。

mv_scan_curator_opportunities — MetaVault キュレーター向けの、クロスプロトコル対応で資本を考慮したスキャナーです。Spectra と Pendle の両方を並列にスキャンし、投入資本額に応じた価格インパクト、エントリーコスト控除後の実効 APY、Morpho のルーピング利用可否（Spectra と Pendle の両方の PT）、クロスプロトコルの一致タグを算出します。

Pendle 対応チェーン

Spectra と重複するチェーン：Ethereum、Base、Arbitrum、Optimism、Sonic、BSC Pendle のみ対応：Mantle、Berachain、HyperEVM、Corn

Spectra との主な違い

• AMM モデル：Pendle は時間減衰ロジット AMM を使用します（Curve StableSwap ではありません）。容量ツールと見積もりツールでは、保守的な scalarRoot=50 の推定値を使用します。
• YT 取引：Pendle の YT は AMM 上で直接取引されます（SY↔YT）。Spectra の YT は Router のフラッシュミント／リディームを介して間接的に取引されます。
• インセンティブ：Pendle は PENDLE トークンの排出と vePENDLE によるブーストを使用します（Spectra の SPECTRA／veSPECTRA システムとは別です）。
• トークンラッピング：Pendle はプール資産として SY（Standardized Yield）トークンを使用します。Spectra のような IBT（Interest-Bearing Token）は使用しません。

オンチェーンの過去のアクティビティ

Spectra REST API（/v1/{network}/pools/{pool}/activity）が保持するのは、直近のトランザクションの限られた期間分のみです。古いアクティビティがあるアドレスやプールを調査する場合、spectra_get_onchain_activity は eth_getLogs を介して、ブロックチェーンから直接、過去のイベントログを読み取ります。

対応するコントラクトタイプ：

• Curve プール（pool_address）：TokenExchange、AddLiquidity、RemoveLiquidity、RemoveLiquidityOne
• Spectra PT ボールト（pt_address）：Mint（IBT を入金 → PT+YT）、Redeem（PT をバーン → IBT）、YieldClaimed

両方を同時に指定できます。イベントは並列に取得され、統合された後、ブロック番号順に並べ替えられます。

主な機能：

• 動的な RPC URL：エージェントは任意の rpc_url パラメーターを渡せます。RPC がハードコードされていないチェーン（Katana、Monad）でも動作します。
• 分割取得：チャンクごとに再試行しながら、ベストエフォート方式で 2000 ブロックずつ取得します（RPC に問題がある場合は部分的な結果を返します）。
• 2 種類のコントラクトのデコード：Curve StableSwap-NG プールイベントと Spectra PrincipalToken ボールトイベントに対応します。
• ブロック範囲の制御：from_block／to_block を明示的に指定するか、lookback_hours を指定します（デフォルトは 24h、最大は 720h／30 日）。
• アドレスフィルタリング：特定のアドレスでイベントを絞り込みます。
• USD 値なし：オンチェーンログに価格は含まれないため、トークン数量は人が読み取れる形式で表示されます。価格の文脈を確認するには、spectra_get_pt_details と照合してください。

既存ツールとの組み合わせ：

Agent flow: spectra_get_pool_activity → empty? → spectra_get_onchain_activity(pool_address=...) → pool events
Agent flow: portfolio shows PT but no pool trades → spectra_get_onchain_activity(pt_address=...) → vault events (mint/redeem)

拡張

Open Emergence パターンに従う

新しいツールを追加する際は、次の3層アーキテクチャに従ってください。

1. 説明（レイヤー2）： ツールのデータの解釈に影響するプロトコルの仕組みを説明します。曖昧なシグナルには「可能性があります」という表現を使います。関連するツールを少なくとも1つ参照するよう促します。
2. 出力（レイヤー3）： データに、気づくためにドメイン知識を要するシグナル（例：戦略を示唆する比率、複数の意味を持ち得るイベント）が含まれる場合は、構造化されたヒントを算出して出力に含めます。目立つようにしますが、指示的な内容にはしません。観察可能なパターンに複数の妥当な解釈がある場合は、同じ重みの競合する分岐として示し、いずれかを選ばないでください。サンプル数が少ない場合は、統計的に不十分であることを明示します。
3. カバレッジ（レイヤー4）： ツールの出力がアドレスまたはプールの全体的な動作の一部しか対象としていない場合は、把握できない範囲を定量化します。価値のカバレッジ（観察可能なアクティビティとポジションサイズの比較）、時間的な欠落、使用したデータソースと利用可能なデータソースを報告します。最後に境界マーカーを付けます：「ポジションサイズの判断では、この分析を包括的なものではなく、不完全なものとして想定してください。」カバレッジ指標は、すべての解釈分岐の範囲を定めます。確信度の高い評価でも、カバレッジが低ければ誤った確信につながります。
4. リソース（レイヤー1）： 新しいツールによって、既存のリソースで扱われていない根本的なプロトコル概念が導入される場合は、index.ts の spectra-overview を更新します。
5. 解消条件： 新しい構造が役立たなくなる条件を docs/dissolution-conditions.md に記録します。すべてのレイヤー3のヒント、アーキテクチャパターン、生成的な摩擦点には解消条件が必要です。これは、状況の変化に応じた再評価を促すものです。

目標は、ツールの説明と出力のヒントだけを読むコールドスタートのエージェントが、ツールを正しく使い、他のツールと組み合わせて新しい分析ワークフローを構成できるようにすることです。

書き込み機能の追加（今後）

エージェントが実際に戦略を実行できるようにするには、Spectra の Router コントラクトを介して未署名のトランザクションを構築するツールを追加します。エージェントは、ユーザーが署名するためのトランザクションの calldata を返します。エージェントが鍵を保持することはありません。

ゲージ／賄賂データの追加

spectra-governance サブグラフにクエリを実行して、現在のエポックの投票、賄賂の額、投票者の報酬を取得します。これは、veSPECTRA の投票戦略を最適化するエージェントにとって有用です。

未接続（API エンドポイントは利用可能）

次の Spectra API エンドポイントは、統合できる状態です。src/tools/ に新しいファイルを作成して register() をエクスポートし、src/index.ts でインポートしてください。

• GET /v1/vision/{network}?tokens=... -- 特定のトークンの APR データ
• GET /v1/watch-tower/{network}/transactions -- 条件付き注文データ
• GET /v1/{network}/metavaults/bridge/transactions -- MetaVault のクロスチェーンブリッジのトランザクションデータ（ブリッジ済みの取引量、処理中の額）

ライセンス

MIT