Spectra MCP Server

🚀 MetaVault MCP

為AI智能體提供多協議收益智能服務，通過模型上下文協議覆蓋Spectra Finance、Pendle和Morpho。

🚀 快速開始

任何支持MCP的AI智能體（Claude、GPT、開源模型），都能通過統一接口查詢Spectra、Pendle和Morpho，實現以下功能：

• 發現：同時在10條鏈上探尋最優固定利率收益機會。
• 分析：藉助完整數據（APY、TVL、流動性、價格）剖析特定PT/YT頭寸。
• 計算：利用自動檢測的借款利率，算出槓桿循環策略（Spectra PT + Morpho抵押品）。
• 比較：對比固定收益和可變收益，以便做出明智決策。
• 跟蹤：通過整合Merkl獎勵，全面跟蹤錢包在所有Spectra頭寸（PT、YT、LP）的投資組合，計算完整的盈虧情況。
• 展示：在Spectra和Pendle的池和市場數據中，呈現外部Merkl活動的APR。
• 監控：監控池的交易量、個人交易活動以及跨池地址掃描情況。
• 報價：使用鏈上Curve的get_dy()函數為PT交易提供精確輸出報價，若失敗則採用數學估算。
• 模擬：模擬假設交易後投資組合的狀態（交易前/交易中/交易後及差異）。
• 掃描：在所有鏈上掃描考慮資金影響的機會，包括價格影響、有效APY和Morpho循環分析。
• 檢測：檢測YT套利機會，即IBT APR與YT隱含利率出現偏差的情況。
• 計算：利用Base鏈上的即時數據，計算每個池的實際veSPECTRA增強乘數。
• 發現：查找所有鏈上的即時MetaVaults，包括策展人信息、TVL、APY、頭寸和紀元歷史。
• 建模：為策展人構建MetaVault“雙循環”策略模型，包括金庫複利和Morpho槓桿，並結合策展人經濟模型，可從即時API數據或手動參數自動填充。
• 監控：監控MetaVault的運營健康狀況，包括策展人儀表盤，顯示每個頭寸的金庫分配、存款人資金流向、費用收入、跨鏈橋活動和可操作警報。
• 查詢：查詢Morpho借貸市場中PT抵押品的機會，確定提供借貸流動性的主體，並發現跨市場的金庫分配情況。
• 查詢：查詢協議統計數據、通證經濟學和治理數據。
• 比較：在重疊的鏈上，並排比較Spectra和Pendle的收益機會，並進行考慮到期日的匹配。
• 掃描：在Spectra和Pendle中尋找最佳策展人機會，考慮資金規模並進行跨協議匹配標記。
• 瀏覽：瀏覽所有Pendle支持的鏈上的Pendle市場（包括僅支持Pendle的鏈，如Mantle、Berachain、HyperEVM、Corn）。
• 分析：深入分析Pendle市場，包括市場詳情、投資組合跟蹤、交易報價、交易模擬、循環策略、YT套利、到期監控、收益曲線、容量分析和協議級統計數據（與Spectra工具功能完全對等）。
• 評估：通過多規模容量曲線評估池的深度，在幾何資金層級（$1K→$1M）上為PT交易報價，以找到Spectra和Pendle上的最佳點和耗盡點。
• 驗證：在部署前驗證IBT的健康狀況，包括鏈上ERC - 4626轉換率、APR可持續性（自然收益與激勵收益）、池餘額、協議認可度和流動性。
• 可視化：可視化任何基礎資產在所有鏈上的收益曲線（期限結構），按到期日順序排列並進行曲線形狀分析。
• 恢復：當API數據過期時，通過eth_getLogs恢復歷史鏈上池活動，支持任何鏈的動態RPC URL。
• 監控：監控策展人Morpho頭寸的健康狀況，包括清算距離、借款利率漂移和所有鏈上的健康因素。
• 壓力測試：對MetaVault的提款場景進行壓力測試，包括流動性瀑布分析（閒置資金→到期資金→LP移除→PT出售）和市場壓力模擬。
• 規劃：為即將到期的MetaVault頭寸規劃展期，通過跨協議候選排名，考慮入場影響、收益差距和重疊窗口。
• 聚合：聚合多金庫策展人投資組合，包括總資產管理規模（AUM）、綜合APY、費用收入預測和按基礎資產/鏈的集中度分析。
• 監控：監控所有鏈上池的到期情況，並進行準備情況評估，包括檢測繼任池、從治理API獲取指標狀態和操作員清單（部署池/提交指標/準備遷移）。
• 學習：通過mv_get_protocol_context按需學習協議機制（PT/YT身份、路由器批處理、存款路徑、術語表、工作流路由）。

智能體無需瞭解PT/YT機制，只需調用spectra_scan_opportunities或pendle_scan_opportunities並提供資金規模，就能獲得排名和可操作的數據。進行跨協議比較時，mv_scan_curator_opportunities會對兩個協議一起進行排名。若需要了解某些現象的原因，可調用mv_get_protocol_context。

✨ 主要特性

開放湧現架構

服務器的設計使得AI智能體能夠在未被教導特定策略的情況下發現新穎策略。系統沒有硬編碼策略識別邏輯，而是在三個層面教授協議機制，讓智能體將這些構建塊組合成自己的分析。

三個層面

層面1：協議上下文（mv_get_protocol_context工具 + 資源）
  → 教授協議的“物理原理”：PT/YT身份、路由器批處理、鑄造
  → 可作為可調用工具（按需）和MCP資源使用
  → 靜態知識 —— 可能發生的事情，而非正在發生的事情

層面2：工具描述（每個工具的描述字符串）
  → 教授與該工具數據相關的特定領域機制
  → 交叉引用提示：“使用spectra_get_portfolio檢查實際持倉”
  → 使用“可能是”的表述，而非“是” —— 保留存在的模糊性
  → 指出可能誤導的隱藏機制（例如，AMM_ADD_LIQUIDITY可能鑄造YT）

層面3：結構化輸出提示（在工具輸出中即時計算）
  → 投資組合中的頭寸形狀分析：餘額比率（例如，“YT/PT 4:1”）
  → 投資組合信號：集中度、到期警報、跨頭寸的策略形狀
  → 交易量信號：交易量/流動性比率、買賣偏差、趨勢檢測
  → Morpho市場提示：容量警告、利用率警報、利差分析、獎勵激勵
  → Morpho供應方分析：供應商識別（金庫/外部賬戶/循環者）、集中度指標、
    供應缺口警告 —— 揭示借貸流動性的來源以及是否充足
  → 每個地址活動分析中的競爭解釋分支（A/B/C）：
    對同一可觀察模式的多種解釋，同等權重呈現。
    智能體必須提供外部證據來消除分支 —— 這種張力就是信息。
  → 統計置信邊界：小樣本循環重複（≤5次）標記為不足以進行外推，防止錯誤的模式匹配
  → 具有競爭假設的流量核算：僅YT、僅PT、完全退出的頭寸
    每個都有多種預測不同未來行為的解釋
  → 地址隔離模式：循環檢測、流量核算、合約/外部賬戶檢測、
    池影響警告、燃氣估算、池上下文
  → 考慮資金的警告：短期到期、低流動性、負有效APY
  → 掃描輸出中的收益維度：固定、可變、LP、循環並排顯示
  → 策略張力：同一池上競爭的PT循環與YT積累
  → 鏈上報價來源指示符：“(鏈上Curve get_dy)” 與 “(估計)”
  → 收益組成：掃描和報價中IBT APR分解（自然基礎收益與外部激勵）
  → 激勵可持續性：當IBT APR或LP APY超過50%來自激勵時標記，
    顯示“僅自然”APY，以便智能體在不考慮激勵假設的情況下評估收益的持久性
  → 池儲備：IBT/PT數量及比率，用於AMM不平衡分析
  → Merkl活動APR：每個池/市場顯示外部激勵計劃（例如，KAT獎勵）
    避免重複計算（跳過獎勵通證已顯示的活動）
  → 積分乘數：外部計劃（Drops、InfiniFi、Firelight）及金額
  → “可能是” / “按當前利率” 表述：保留排名輸出中的模糊性
  → 突出關鍵信號，不規定解釋

層面4：觀察覆蓋範圍（量化工具輸出中的盲點）
  → 價值覆蓋：可觀察活動解釋的地址頭寸百分比。
    低覆蓋意味著大多數行為不可見（直接鑄造、轉賬、跨鏈）。
  → 時間覆蓋：活躍天數與無可見事件的黑暗期。
    顯示最長間隔時間，以便智能體推斷不可見活動。
  → 數據源覆蓋：諮詢的5個可用數據源與未使用的數據源。
    明確列出當前分析不可見的內容。
  → 活動多樣性：單一類型的活動標記為最高模糊模式。
  → 邊界標記：“頭寸規模應假設此分析不完整，而非全面。” —— 對有效性範圍限制的結構性承認。
  → 覆蓋指標限制了以上所有解釋。高置信度策略評估 + 低觀察覆蓋 = 錯誤置信。覆蓋部分迫使智能體根據實際觀察來調整其信心。

設計原則

• 教授機制，而非結論：服務器解釋AMM_ADD_LIQUIDITY 可能是 鑄造 + LP批量操作，而不是得出“此用戶正在積累YT”的結論。
• 呈現競爭解釋，而非單一敘述：活動分析輸出多個預測不同未來行為的解釋分支（A/B/C）。智能體必須提供外部證據來消除它們。這種摩擦表面防止過早的模式匹配 —— 錢包策略分析中最常見的失敗模式。
• 標記統計不足：小重複次數（≤5次循環檢測）明確標記為不足以進行外推。智能體不能將N = 3視為已確認的模式。
• 每個工具至少交叉引用一個其他工具：這創建了分析工作流，但不規定它們。智能體在看到活動模式後學會檢查spectra_get_portfolio，而不是因為被告知這樣做。
• 指出可能誤導的隱藏機制：Spectra路由器原子性地批量處理多個操作。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. 閱讀交叉引用提示 —— 組合自己跨越所有三個協議的分析工作流。
5. 識別服務器從未明確編程檢測的新穎策略。

這已得到驗證：一個零初始化的子智能體在3次工具調用中，僅使用描述中教授的機制和輸出中的結構化提示，正確識別了一個鑄造並出售PT的循環策略（通過PT折扣積累YT）。

競爭分支設計源於一個實際失敗案例：一個分析多鏈錢包的智能體將所有活動歸結為“YT積累者”，儘管不同池顯示不同模式（利差捕獲、做市、LP循環）。單一敘述的失敗模式 —— 智能體選擇一種解釋並堅持它 —— 是最危險的，因為從內部看它像是良好的分析。

觀察覆蓋層面解決了一個更深層次的問題：即使對觀察數據的完美解釋，當數據僅覆蓋少數行為時也會產生誤導。競爭分支解決了敘述問題（哪個故事合適？）。覆蓋指標解決了暴露問題（我看到了多少畫面？）。一個選擇了最佳解釋分支但忽略了65%不可見活動的智能體，是根據連貫性而非證據來調整信心。

工具

支持的鏈

Spectra：以太坊（主網）、Base、Arbitrum、Optimism、Avalanche、Katana、Sonic、Flare、BSC、Monad

Pendle：以太坊、Optimism、BSC、Sonic、Base、Arbitrum、Mantle、Berachain、HyperEVM、Corn

veSPECTRA增強

服務器通過原始eth_call（無需ethers/viem依賴）直接從Base鏈讀取即時veSPECTRA總供應量，並使用實際的Spectra公式計算每個池的增強乘數：

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

v = 您的veSPECTRA餘額
V = 總veSPECTRA供應量（從Base即時讀取）
D = 池TVL
d = 您的存款規模

當您在總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發現與策略建模

MetaVaults是符合ERC - 7540標準的策展金庫，可自動進行LP展期並將YT收益複利回LP頭寸。有兩個工具協同工作：

• spectra_list_metavaults —— 發現工具。從API（/v1/{network}/metavaults）獲取即時MetaVault數據，可並行掃描單條鏈或所有鏈。返回策展人信息、TVL、即時APY、份額價格、帶有PT/池詳情的活躍頭寸和紀元利率歷史。
• spectra_model_metavault —— 策略建模工具，有兩種模式：
  • 即時模式：提供chain + metavault_address，自動獲取金庫的即時APY作為base_apy。其他參數（借款利率、LTV、策展人費用）仍可覆蓋。
  • 手動模式：直接提供base_apy，用於假設或預發佈建模。

“雙循環”經濟模型：

層面1（金庫內部）： 存款 → PT/LP分配 → YT收益 → 更多LP（複利）
層面2（上層）：        MV份額 → Morpho抵押品 → 借款 → 再存款（槓桿）

關鍵見解：YT複利提高了金庫的基礎APY，而槓桿則放大了這個更高的基礎收益。這創造了一個相對於原始PT循環的“雙循環溢價”，並隨著槓桿的增加而擴大。

策展人經濟模型已內置其中，該工具可模擬外部存款的費用收入、循環創造的額外TVL以及策展人自有資金的有效投資回報率。

📦 安裝指南

從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，您將看到所有50個工具（Spectra、Pendle、Morpho、跨協議）可用。

連接到Claude Code

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

💻 使用示例

深度分析提示

您提供的上下文越多，智能體就能進行更深入的分析。每個輸入都能解鎖不同的工具鏈：

理想的提示應結合所有這些因素。以下是觸發8 - 10個工具鏈的示例：

• 收益獵手：“我有5萬美元USDC和1萬個veSPECTRA。為我找到60 - 180天內風險調整後最佳的固定收益機會。檢查IBT健康狀況，為我的入場提供精確報價，並顯示池中還有哪些其他參與者。”
• 策展人：“我正在Base上用50萬美元自有資金建立一個USDC MetaVault，預計有200萬美元外部資金。模擬雙循環經濟模型，並比較Spectra和Pendle的LP分配。”
• 調查員：“錢包0xABC...在Spectra主網上很活躍。向我展示所有信息 —— 投資組合、所有池的活動、序列分析以及他們正在執行的策略。”
• 期限結構：“向我展示所有鏈上的ETH收益曲線。哪些地方存在期限溢價異常？為前3個定價錯誤的池提供20萬美元的池容量報價。”

工具之間的交叉引用才是真正深入分析的關鍵 —— 沒有單個工具能講述完整的故事。智能體可以調用mv_get_protocol_context(topic="workflow_routing")在運行時學習這些組合。

示例查詢

連接後，您可以向Claude詢問以下問題：

• “目前USDC的最佳固定收益是多少？”
• “向我展示Base上所有TVL超過5萬美元的Spectra池。”
• “使用Morpho為Base上的PT - USDC計算3倍循環策略。”
• “stETH的固定利率是否優於可變利率？”
• “哪些Morpho市場接受Spectra PT作為抵押品？”
• “那個Morpho PT - USDC市場的借款利率是多少？”
• “當前SPECTRA的排放量和鎖定率是多少？”
• “向我展示0xABC...DEF在所有鏈上的投資組合，包括任何未領取的Merkl獎勵。”
• “這個池最近的交易活動如何？”
• “掃描主網上所有池，查找地址0xABC...DEF的活動記錄。”
• “檢查地址0xABC...DEF是合約還是外部賬戶，並展示他們的交易模式。”
• “為在這個池購買價值1萬美元的PT提供報價。”
• “如果我購買5萬個這個PT，我的投資組合會是什麼樣子？”
• “我有10萬美元可用於部署，掃描所有鏈，尋找風險調整後最佳的收益機會。”
• “掃描適合50萬美元規模的USDC機會，入場影響最大為2%。”
• “尋找市場對收益定價錯誤的YT套利機會。”
• “我有10萬個veSPECTRA，在這個池存入1萬美元能獲得多少增強？”
• “展示veSPECTRA的總供應量以及我需要多少才能獲得最大增強。”
• “目前有哪些MetaVaults處於活躍狀態？向我展示所有鏈上的MetaVaults。”
• “向我展示Base上的MetaVaults，它們的APY是多少，策展人是誰？”
• “為Base上的這個MetaVault建模一個策略（自動獲取即時APY）。”
• “為一個基礎APY為12%、YT複利為3%、策展人費用為10%的MetaVault建模，循環策略會是什麼樣子？”
• “在基礎APY為12%的情況下，比較MetaVault循環和原始PT循環。”
• “我作為策展人管理一個擁有10萬美元自有資金和100萬美元外部存款的金庫，我的有效投資回報率是多少？”
• “比較Base上Spectra和Pendle的收益，哪個協議為USDC提供更好的利率？”
• “我作為策展人管理一個擁有50萬美元的MetaVault，掃描Spectra和Pendle，尋找最佳機會。”
• “向我展示Arbitrum上按TVL排序的所有活躍Pendle市場。”
• “在價格影響使我的收益歸零之前，我可以向這個池投入多少資金？”
• “這個PT背後的IBT健康狀況如何？檢查轉換率和APR組成。”
• “向我展示USDC的收益曲線，每個到期日的利率是多少？”
• “比較所有鏈上ETH的30天、90天和180天利率。”
• “這個地址幾周前在Katana上進行了交易，但spectra_get_pool_activity沒有顯示任何信息，拉取過去7天的鏈上日誌。”
• “使用我的RPC URL（https://rpc.katana.network）獲取這個池的歷史活動。”
• “監控我的Morpho頭寸的清算風險，向我展示每個頭寸的清算距離。”
• “對我在Base上的MetaVault進行壓力測試，如果30%的存款人在一個紀元內贖回，會發生什麼？”
• “我在MetaVault上有一個14天后到期的頭寸，規劃展期並向我展示最佳候選池。”
• “聚合我在所有鏈上的策展人投資組合，向我展示總AUM、綜合APY和集中度。”

📚 詳細文檔

架構

智能體 (Claude/GPT等)
  | MCP協議 (標準輸入輸出)
MetaVault MCP (本項目)
  | HTTP (15秒超時，5xx/網絡錯誤時重試1次)
  |
  +-- 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 (每個錢包的未領取Merkl獎勵)
  +-- api.merkl.xyz/v4/opportunities (每個鏈的Merkl活動APR)
  +-- api.morpho.org/graphql (PT抵押市場、借款利率)
  +-- api-v2.pendle.finance/core/* (用於跨協議比較的Pendle市場數據)
  +-- mainnet.base.org (通過原始eth_call讀取veSPECTRA鏈上數據)
  +-- 鏈RPCs: eth_call用於Curve get_dy()報價，eth_getCode用於合約檢測
  |   (主網、Base、Arbitrum、Optimism、Avalanche、Sonic、BSC、Flare)
  +-- 鏈RPCs: eth_getLogs用於獲取歷史池活動 (任何鏈通過動態rpc_url)

這是一個模塊化的TypeScript服務器，為只讀模式。它查詢Spectra現有的API、Morpho的GraphQL API、鏈RPC以獲取鏈上Curve的get_dy()報價和合約檢測信息，以及Base RPC以獲取veSPECTRA數據。無需錢包、交易、密鑰和web3庫。

src/
  index.ts          入口點，工具註冊，層面1資源 (spectra概述、策展人策略指南)，main()，優雅關閉
  config.ts         常量、鏈配置、Zod模式、協議參數、veSPECTRA常量、
                      每個鏈的區塊時間常量、RPC URL解析 (硬編碼 + 動態覆蓋)
  types.ts          TypeScript接口 (SpectraPt、MorphoMarket、ScanOpportunity、MerklTokenReward、MerklChainRewards、MerklCampaign等)
  api.ts            帶有重試的獲取助手，GraphQL清理，Morpho批量查找，
                      基於Promise的veSPECTRA RPC去重緩存，30秒TTL池數據緩存，
                      鏈上Curve get_dy()報價，ERC - 4626 convertToAssets()健康檢查，
                      eth_getCode合約檢測，
                      MetaVault多鏈掃描，系統邊界處的API響應驗證，
                      帶有重試的分塊eth_getLogs用於獲取歷史事件日誌，
                      Merkl獎勵獲取和解析 (從原因鍵中提取池地址，
                      BigInt wei→人類可讀轉換，匹配/未匹配獎勵分類)，
                      Merkl v4活動APR獲取 (60秒TTL緩存，進行中的請求去重，基於地址的查找)
  formatters.ts     格式化，BigInt LLTV解析，封閉形式的槓桿數學，
                      價格影響，小數天到期，增強計算，
                      精簡信封助手，通證數量格式化 (BigInt → 人類可讀)，
                      跨協議到期匹配 (normalizeUnderlyingSymbol，matchByAssetAndMaturity)，
                      層面3輸出提示 (頭寸形狀、LP APY分解、
                      交易量信號、Morpho市場提示、投資組合信號、
                      競爭解釋分支、統計置信邊界、
                      帶有競爭假設的流量核算)，
                      層面4觀察覆蓋 (價值覆蓋、時間差距、
                      數據源覆蓋、活動多樣性、邊界標記)，
                      Merkl獎勵顯示 (每個頭寸的匹配獎勵、未匹配/已退出獎勵)，
                      Merkl活動APR顯示 (formatMerklCampaignLines，避免重複計算)
  tools/            層面2: 每個工具描述教授特定領域的機制
    context.ts      mv_get_protocol_context (層面1協議機制、存款路徑、術語表，按需調用)
    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 (餘額比率策略信號、投資組合級提示、交叉引用提示、
                      Merkl獎勵集成 —— 並行獲取、每個頭寸匹配、未匹配獎勵)
    pool.ts         spectra_get_pool_volume (帶有交易量/流動性提示)，spectra_get_pool_activity (PT地址解析、路由器批處理、
                      地址隔離與循環檢測、流量核算、合約檢測、
                      燃氣估算、池影響警告、觀察覆蓋指標)，
                      spectra_get_address_activity (帶有覆蓋邊界標記的跨池掃描器)
    morpho.ts       morpho_list_markets (帶有容量/利用率提示)，morpho_get_rate (帶有PT利差分析)
    protocol.ts     spectra_get_protocol_stats，spectra_list_chains
    quote.ts        spectra_quote_trade (鏈上Curve get_dy()，數學備用)
    simulate.ts     spectra_simulate_trade (也使用鏈上報價)
    strategy.ts     spectra_scan_opportunities (考慮資金規模，批量Morpho，過濾負APY機會，策略張力)
    yt_arb.ts       spectra_scan_yt_arbitrage (YT執行機制，閃電鑄造/閃電贖回)
    ve.ts           spectra_get_ve_info
    metavault.ts    spectra_list_metavaults，spectra_model_metavault (即時API + 計算建模)，
                      spectra_get_curator_dashboard (金庫分配消除歧義，跨鏈頭寸意識)
    pendle.ts       pendle_list_markets，mv_compare_yield (考慮到期日的跨協議收益比較)
    curator_scan.ts mv_scan_curator_opportunities (為MetaVault策展人提供跨協議考慮資金規模的掃描器)
    onchain.ts      spectra_get_onchain_activity (歷史eth_getLogs，Curve池 + PT金庫事件解碼，動態RPC)
    capacity.ts     spectra_get_pool_capacity (多規模報價階梯，最佳點/耗盡點檢測)
    ibt_health.ts   mv_check_ibt_health (ERC - 4626轉換率、APR組成、池餘額、評估結果)
    yield_curve.ts  spectra_get_yield_curve (給定基礎資產在所有鏈上的期限結構)
    risk_monitor.ts morpho_monitor_risk (清算距離、健康因素、借款利率漂移、警報級別)
    stress_test.ts  spectra_stress_test_vault (提款流動性瀑布，市場壓力模擬)
    rollover.ts     mv_plan_rollover (即將到期頭寸展期規劃，帶有跨協議候選池)
    curator_portfolio.ts mv_get_curator_portfolio (多金庫聚合，AUM，綜合APY，集中度)
    expiry_monitor.ts spectra_list_expiring_pools (池到期監控，緊急程度分組，繼任池交叉引用，指標狀態，準備情況評估)
test.cjs              集成測試套件 (405個測試，McpTestClient通過標準輸入輸出)
test-agent.cjs        智能體推理測試套件 (82個斷言，McpTestClient通過標準輸入輸出)
AGENT - TESTS.md        38個問題的主觀測試套件，帶有評分標準 (包括開放湧現、覆蓋範圍、新手理解層級)
EMERGENCE - AUDIT.md    開放湧現審計 —— 競爭分支、觀察覆蓋、異常檢測差距
CODE - REVIEW.md        完整代碼庫審查 (漏洞、安全性、代碼質量、測試覆蓋率)
SECURITY - REVIEW.md    以安全為重點的審查 (SSRF、GraphQL注入、依賴漏洞)
docs/
  recursive - meta - process.md    開放湧現元框架規範
  dissolution - conditions.md    每個結構決策的解散條件
  architecture - review - agentic - accessibility.md    智能體可訪問性審查，帶有功能提案

每個工具文件都導出一個register(server)函數。要添加新工具，可創建src/tools/newtool.ts，導出register()，並在index.ts中導入和調用它。

所有地址參數都會進行驗證（0x + 40個十六進制字符）。所有API調用都有15秒的超時時間，並會在臨時故障（5xx、ETIMEDOUT、ENETUNREACH、ENOTFOUND）時自動重試。跨鏈掃描使用Promise.allSettled，因此一條鏈失敗不會阻止其他鏈的結果。GraphQL輸入會進行清理，以防止注入攻擊。所有錯誤返回都使用MCP的isError: true標誌，以便向智能體正確發出錯誤信號。

類型安全

• API返回類型：fetchSpectra()和fetchMorpho()返回Promise<unknown>（而非Promise<any>），強制在每個調用點進行顯式類型斷言。
• 空值合併：所有小數/餘額回退都使用??（而非||），以正確處理0小數通證。
• Morpho狀態字段：類型為number | null，以匹配實際API行為，防止靜默的NaN傳播。
• JSON解析：先將響應體作為文本讀取，然後使用JSON.parse()，避免流的雙重消費，從而掩蓋錯誤診斷信息。
• BigInt精度：veSPECTRA總供應量使用10n ** BigInt(18)進行解析，以避免浮點數中間溢出。交易報價使用amountToBigInt()（字符串算術），以避免當amount * 10^decimals超過MAX_SAFE_INTEGER時的精度損失。
• 輸入驗證：Zod模式對所有數字輸入強制執行.min() / .max()邊界，以防止無效的GraphQL查詢。

🔧 技術細節

精度與正確性

• Morpho LLTV：使用BigInt算術進行解析，避免在18位小數的原始值上出現浮點精度損失（例如，860000000000000000精確轉換為0.86）。
• 槓桿數學：使用封閉形式的幾何級數(1 - ltv^(n+1)) / (1 - ltv)代替迭代循環累加，數值精確且複雜度為O(1)。
• YT套利：在計算隱含利率時使用小數天到期，避免在到期附近出現年化誤差。
• 價格影響：零流動性池返回100%的影響（而非0%），防止機會掃描器中出現誤報。影響上限設為99%，防止交易報價中出現負輸出。
• 負APY過濾：在排名之前過濾掉入場成本超過收益的機會，而不是將其排在底部。

彈性設計

• 重試邏輯：涵蓋ECONNRESET、ETIMEDOUT、ENETUNREACH、ENOTFOUND、EPIPE、EHOSTUNREACH、EAI_AGAIN和UND_ERR_SOCKET錯誤。
• 池數據緩存：每個鏈有30秒的TTL緩存，並對進行中的請求進行去重，30秒內的重複掃描將使用緩存數據。
• API驗證：validatePtEntries()在系統邊界過濾格式錯誤的API響應（驗證地址、到期日、名稱字段）。
• veSPECTRA緩存：基於Promise的去重機制防止多個工具併發運行時出現重複的RPC調用（5分鐘TTL）。
• Morpho批量限制：first參數上限為min(addresses * 3, 500)，以避免GraphQL響應限制。
• 鏈上報價：通過原始eth_call在8條鏈上進行Curve get_dy()報價，在RPC失敗時自動回退到數學估算。
• IBT健康檢查：通過原始eth_call進行ERC - 4626 convertToAssets()檢查，在RPC不可用時優雅降級（其他健康檢查仍會運行）。
• 歷史事件日誌：分塊eth_getLogs（每塊2000個區塊），並對每塊進行重試，失敗的塊會被跳過，仍會返回部分結果。動態rpc_url參數支持任何鏈，無需硬編碼RPC。
• 合約檢測緩存：使用永久Map緩存eth_getCode結果（合約代碼不會改變）。
• Merkl獎勵：盡力從Merkl API並行獲取獎勵，失敗不會阻止投資組合顯示。通過正則表達式從原因鍵中提取池地址進行匹配。使用BigInt parseWei()進行安全的18位小數算術轉換。
• Merkl活動：盡力為每個鏈獲取v4活動APR（60秒TTL緩存，進行中的請求去重）。失敗時返回空映射，工具輸出不變。避免重複計算，跳過獎勵通證已通過原生API數據顯示的活動。
• MCP錯誤信號：所有錯誤捕獲塊都返回isError: true，以便智能體區分錯誤和空結果。
• PT地址解析：池工具（spectra_get_pool_volume、spectra_get_pool_activity）可接受池地址或PT地址，並自動解析。
• 錯誤日誌記錄：Morpho查找中的捕獲塊將錯誤記錄到stderr，而不是靜默吞失敗。
• 優雅關閉：在SIGTERM/SIGINT信號下，在process.exit()之前調用server.close()。

測試

從源代碼檢出後，可運行以下命令進行測試：

# 完整集成測試套件 (405個測試，需要網絡)
npm test

# 僅模式/註冊測試 (98個測試，無需網絡)
npm run test:offline

# 單元測試 (242個測試，無需網絡)
npm run test:unit

# 智能體推理測試 (82個斷言，需要網絡)
npm run test:agent

單元測試 (api.test.ts, formatters.test.ts, config.test.ts)

242個測試覆蓋純函數邏輯，包括GraphQL清理、Morpho字段常量、Merkl獎勵解析（從原因鍵中提取池地址、wei到人類可讀的轉換、匹配/未匹配分類）、Merkl獎勵格式化、餘額格式化、跨協議到期匹配（normalizeUnderlyingSymbol，matchByAssetAndMaturity）、Pendle對數AMM價格影響模型（estimatePendlePriceImpact）、Pendle日期/到期助手（pendleDaysToMaturity）、Pendle市場格式化器（緊湊 + 摘要）和配置驗證。無需網絡。

集成測試 (test.cjs)

405個測試覆蓋工具註冊、模式驗證、API響應、鏈上Curve get_dy()報價、跨池地址掃描、地址隔離模式、跨協議策展人掃描和格式錯誤地址的負測試。從即時API動態發現池和PT地址，因此當池到期時測試不會過時。

智能體推理測試 (test-agent.cjs)

82個斷言分佈在多工具工作流測試中，驗證“推理表面” —— 使用這些工具的智能體能否檢測異常、交叉引用數據並避免協議機制陷阱？測試包括：

• 協議上下文完整性 —— 所有主題都存在，解釋路由器批處理的歧義，包括交叉引用指導。
• 異常檢測 —— 原始APY與考慮資金規模的排名產生不同結果（有意的差異）。
• 跨工具數據一致性 —— spectra_list_pools → spectra_get_pt_details → spectra_compare_yield之間的APY匹配。
• 路由器機制 —— 通過池活動 → 投資組合交叉引用檢測鑄造並出售循環。
• 路由器限制 —— API解決eth_getLogs地址過濾遺漏的路由器交易。
• MetaVault數據完整性 —— 策展人信息、TVL、APY、金庫資金流向、到期頭寸標記。
• 到期池發現 —— spectra_list_pools僅返回活躍池；MetaVaults顯示到期頭寸。
• veSPECTRA增強數學 —— 最大增強（100萬個veSPECTRA + 1000美元）與最小增強（100個veSPECTRA + 100萬美元）。
• Morpho循環回退 —— 當PT沒有Morpho市場時的優雅處理。
• Morpho市場分類 —— Spectra與Pendle/其他標籤，不支持的鏈處理。
• MetaVault掃描包含 —— include_metavaults標誌正確顯示/隱藏MetaVault部分。
• Pendle比較 —— 一對一匹配對，帶有差異、僅Pendle市場、彙總。
• 顯示的API字段 —— 到期價值、乘數（積分計劃）、標籤、池儲備及比率、IBT APR組成、包裝通證的基礎IBT。
• 投資組合中的Merkl獎勵 —— SPECTRA指標排放出現在投資組合輸出中，對空錢包的優雅處理。

主觀測試套件 (AGENT-TESTS.md)

38個可複製粘貼的問題分佈在11個層級（基本工具使用 → 開放湧現 → 新手理解），帶有評分標準，用於評估使用MCP工具的LLM智能體質量。第8層測試“開放湧現” —— 能夠持有競爭解釋而不陷入單一敘述的能力。第11層測試新手理解 —— 智能體能否解釋存款路徑、識別保守的影響估計並路由到正確的掃描器？這些測試旨在通過生成子智能體並手動評分或使用LLM作為評委來運行。

API參考

本服務器封裝了以下端點：

注意：{chain}對以太坊使用mainnet別名（服務器接受ethereum別名並自動映射）。

Pendle協議集成

13個Pendle工具提供與Spectra工具集的完整功能對等性，另外還有2個跨協議工具用於統一分析：

Pendle原生工具 (13個)

跨協議工具 (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重疊的鏈：以太坊、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通過路由器閃電鑄造/贖回間接交易。
• 激勵機制：Pendle使用PENDLE通證排放 + vePENDLE增強（與Spectra的SPECTRA/veSPECTRA系統不同）。
• 通證包裝：Pendle使用SY（標準化收益）通證作為池資產，而非Spectra的IBT（生息通證）。

鏈上歷史活動

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問題時提供部分結果）。
• 雙合約解碼：Curve StableSwap - NG池事件和Spectra PrincipalToken金庫事件。
• 塊範圍控制：顯式from_block/to_block或lookback_hours（默認24小時，最大720小時/30天）。
• 地址過濾：按特定地址過濾事件。
• 無美元價值：鏈上日誌不包含價格信息，通證數量以人類可讀形式顯示。可與spectra_get_pt_details交叉引用以獲取價格上下文。

與現有工具的可組合性：

智能體流程：spectra_get_pool_activity → 無結果? → spectra_get_onchain_activity(pool_address=...) → 池事件
智能體流程：投資組合顯示PT但無池交易 → spectra_get_onchain_activity(pt_address=...) → 金庫事件（鑄造/贖回）

擴展

遵循開放湧現模式

添加新工具時，請遵循三層架構：

1. 描述（層面2）：教授任何影響工具數據解釋的協議機制。對於模糊信號，使用“可能是”的表述。至少添加一個與相關工具的交叉引用提示。
2. 輸出（層面3）：如果數據包含需要領域知識才能注意到的信號（例如，暗示策略的比率、可能有不同含義的事件），計算結構化提示幷包含在輸出中。突出顯示但不規定解釋。當可觀察模式有多個有效解釋時，將它們作為競爭分支同等權重呈現，不要選擇一個。標記小樣本量為統計上不充分。
3. 覆蓋範圍（層面4）：如果工具的輸出僅覆蓋地址或池的部分完整行為，量化盲點。報告價值覆蓋（可觀察活動與頭寸規模）、時間差距以及使用的數據源與可用數據源。最後加上邊界標記：“頭寸規模應假設此分析不完整，而非全面。”覆蓋指標限制所有解釋分支 —— 高置信度評估 + 低覆蓋 = 錯誤置信。
4. 資源（層面1）：如果新工具引入了現有資源未涵蓋的基本協議概念，請更新index.ts中的spectra-overview。
5. 解散條件：在docs/dissolution-conditions.md中記錄新結構不再適用的情況。每個層面3提示、架構模式和生成摩擦點都有解散條件 —— 當情況變化時進行重新評估的提示。

目標是：一個僅閱讀工具描述和輸出提示的冷啟動智能體應該能夠正確使用該工具，並將其與其他工具組合成新穎的分析工作流。

添加寫入功能（未來）

要使智能體能夠實際執行策略，您可以添加通過Spectra的路由器合約構建未簽名交易的工具。智能體將返回交易調用數據供用戶簽名，絕不持有密鑰。

添加指標/賄賂數據

查詢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許可證。