spectra-mcp-server

MetaVault MCP

面向 AI Agent 的多协议收益情报——通过 Model Context Protocol 支持 Spectra Finance、Pendle 和 Morpho。

55 个工具 · 3 个协议 · 10+ 条链 · 只读 · 开放式涌现架构 · 校准情报 · 链上 Curve 报价 · Pendle logit AMM 建模 · ERC-4626 健康检查 · 收益率曲线期限结构 · 历史 eth_getLogs · 完整的 Pendle 协议功能对等（15 个工具） · 跨协议头寸映射 · Spectra↔Pendle 跨协议比较 · veSPECTRA + vePENDLE 治理 · Pendle 历史时间序列 · Morpho 供应端可见性与供应方级联建模 · Morpho 用户头寸与历史利率 · Merkl 活动 APR + 到期集成 · 入场路径感知 · 明确的观测边界 · 策展方风险监控 · 提款压力测试 · 滚动规划 · 多金库投资组合聚合 · 池到期监控 · 零 web3 库依赖

功能介绍

任何支持 MCP 的 AI Agent（Claude、GPT、开源模型）都可以通过统一界面查询 Spectra、Pendle 和 Morpho，以便：

• 发现跨 10 条链的最佳固定利率收益机会
• 分析具体的 PT/YT 仓位，获取完整数据（APY、TVL、流动性、价格）
• 计算杠杆循环策略（Spectra PT + Morpho 抵押品），并自动检测借款利率
• 比较固定收益与浮动收益，助你做出明智决策
• 跟踪所有 Spectra 仓位（PT、YT、LP）的钱包投资组合，并集成 Merkl 奖励，完整计算盈亏
• 展示外部 Merkl 活动的 APR，并同时提供 Spectra 和 Pendle 的池及市场数据
• 监控池交易量、单笔交易活动，以及跨池地址扫描结果
• 查询PT 交易报价：使用链上 Curve get_dy() 获取精确输出，无法获取时则采用数学估算
• 模拟假设交易后的投资组合状态（BEFORE / TRADE / AFTER，含变化量）
• 扫描所有链上的机会，并结合资金规模分析价格影响、实际 APY 和 Morpho 循环策略
• 检测IBT APR 与 YT 隐含利率出现偏差时的 YT 套利机会
• 计算基于 Base 实时链上数据的每池实际 veSPECTRA 加成倍数，以及 Ethereum 主网的 vePENDLE 投票权重（考虑 sPENDLE 过渡）
• 通过一次调用映射你的完整跨协议仓位——Spectra + Pendle + Morpho + 治理（veSPECTRA + vePENDLE），并检测矛盾情况（未使用的加成、借贷利率与固定利率的利差、集中度、循环策略识别、跨协议到期仓位）
• 评估入场路径复杂度——自动标记特殊标的、sw-wrapper 跳转和主网 Gas 成本阻力，让 Agent 了解获取标称收益的实际成本
• 发现所有链上的实时 MetaVault——包括管理者信息、TVL、APY、仓位和周期历史
• 为管理者建模MetaVault“双重循环”策略——结合金库复利、Morpho 杠杆和管理者经济模型，并根据实时 API 数据或手动参数自动填充
• 监控MetaVault 运营状况——通过管理者仪表板查看各仓位的金库配置、存款流向、费用收入、跨链桥活动和可执行警报
• 查询Morpho 借贷市场中的 PT 抵押机会，识别借贷流动性的提供方，并发现各市场的金库配置
• 查询协议统计数据、代币经济模型和治理数据
• 并排比较Spectra 与 Pendle 的收益机会，并在重叠链上根据到期时间进行匹配
• 扫描Spectra 和 Pendle，发现最佳管理者机会，并结合资金规模进行配置，同时标记跨协议匹配情况
• 浏览Pendle 支持的所有链上的 Pendle 市场（包括 Mantle、Berachain、HyperEVM、Corn 等仅 Pendle 支持的链）
• 深入分析Pendle 市场——包括市场详情、投资组合跟踪、交易报价、交易模拟、循环策略、YT 套利、到期监控、收益率曲线、容量分析和协议级统计数据（与 Spectra 工具完全对等）
• 评估池深度和多规模容量曲线——在 Spectra 和 Pendle 上按几何递增的资金档位（$1K→$1M）查询 PT 交易报价，找到最佳规模和流动性耗尽点
• 在部署前验证IBT 健康状况——检查链上 ERC-4626 转换率、APR 可持续性（自然收益还是激励）、池余额、协议认可情况和流动性
• 可视化所有链上任意标的的收益率曲线（期限结构）——按时间顺序排列所有到期日，并分析曲线形态
• 通过 eth_getLogs 恢复已从 API 数据中移除的历史链上池活动记录，并支持通过动态 RPC URL 查询任意链
• 监控管理者的 Morpho 仓位健康状况——查看所有链上的清算距离、借款利率变化和健康因子
• 压力测试MetaVault 提取情景——模拟市场压力，分析流动性瀑布（闲置资金 → 到期资金 → 移除 LP → 卖出 PT）
• 规划即将到期的 MetaVault 仓位展期——根据入场影响、收益差距和重叠窗口，对跨协议候选方案进行排序
• 汇总管理者的多金库投资组合——查看总 AUM、综合 APY、费用收入预测，以及按标的/链划分的集中度分析
• 监控所有链上的池到期情况并评估准备状态——检测后继池、从治理 API 获取 Gauge 状态，并提供操作清单（部署池 / 提交 Gauge / 准备迁移）
• 按需了解协议机制：通过 mv_get_protocol_context 查询（PT/YT 关系、Router 批处理、存款路径、术语表、费用与成本、工作流路由、externalPositions 注册表）
• 直接在工具输出中展示协议 YT 费用（Spectra 3%、Pendle 5%）及 Merkl 活动资格（POOL 与 HOLD），让 Agent 无需外部查询即可应用这些信息 Agent 无需理解 PT/YT 的运作机制——它只需调用 spectra_scan_opportunities 或 pendle_scan_opportunities，传入资金规模，即可获得经过排名、可直接采取行动的数据。如需跨协议比较，mv_scan_curator_opportunities 会对两个协议进行统一排名。如果需要了解某种机制为何如此运作，则调用 mv_get_protocol_context。

开放式涌现架构

该服务旨在让 AI Agent 无需接受特定策略的教学，也能发现新策略。系统不会将策略识别逻辑硬编码，而是在三个层面讲解协议机制，并让 Agent 将各个构建模块组合起来进行分析。

三个层面

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 可能是一项 mint+LP 批处理操作，但不会得出“此用户正在累积 YT”的结论。
• 呈现相互竞争的解读，而非单一叙事。 活动分析会输出多个解读分支（A/B/C），分别预测不同的未来行为。Agent 必须引入外部证据才能排除其他分支。这种摩擦机制可防止过早进行模式匹配——这是钱包策略分析中最常见的失败模式。
• 标明统计数据不足。 当重复次数较少（≤5 次周期检测）时，会明确标记为不足以进行外推。Agent 不能将 N=3 视为已确认的模式。
• 每个工具都至少交叉引用另一个工具。 这样可以形成分析工作流，而不对其作出规定。看到活动模式后，Agent 会学会检查 spectra_get_portfolio，而不是因为有人告诉它要这么做。
• 在可能造成误导的地方指出隐藏机制。 Spectra Router 会以原子方式批处理多个操作。SELL_PT 事件实际上可能是通过 flash-mint 获取 YT。工具描述会讲解这一点，避免 Agent 仅凭池数据得出错误结论。
• 输出完整地址，绝不截断。 活动数据中出现地址时，会完整显示，以便 Agent 直接将其传给 spectra_get_portfolio，无需使用区块浏览器。
• 发现工具会提醒资本规模考量的不足。 spectra_get_best_fixed_yields 会明确说明：“该工具按原始 APY 排名——如需按资本规模考量，请使用 spectra_scan_opportunities。”
• 量化盲点，而不只是给出解读。 工具现在会输出观测覆盖率指标：有多少行为可见、查询了哪些数据源以及还有哪些数据源可用，以及黑暗期持续了多久。这些不是解读，而是对分析自身不完整性的结构化衡量。即使最符合数据的解读看起来十分连贯，看到数值覆盖率为 35% 的 Agent 也应据此调整置信度。

这为何重要

一个对这些协议一无所知的冷启动 Agent 可以：

1. 调用 mv_scan_curator_opportunities — 查看跨协议（Spectra + Pendle）的收益率排名，以及考虑资金规模的指标
2. 调用 spectra_get_pool_activity — 查看交易模式，并通过 ⚠ 提示了解存在歧义的事件
3. 对标记出的地址调用 spectra_get_portfolio 和 pendle_get_portfolio — 查看两个协议中的仓位形态
4. 阅读交叉引用提示 — 构建自己的分析工作流，涵盖所有三个协议
5. 识别服务从未被明确编程为检测的新颖策略

验证结果如下：一个未接受任何预先引导的子 Agent，仅通过 3 次工具调用，就正确识别出一种铸造并卖出 PT 的循环策略（通过 PT 折价积累 YT）；它只依据描述中传达的机制以及输出中的结构化提示完成了分析。

竞争分支设计的动机源于一个真实故障：一个分析多链钱包的 Agent，将所有活动都归结为“YT 累积”，尽管不同池展现出不同模式（价差捕获、做市、LP 循环）。单一叙事的故障模式——Agent 选定一种解释并为之辩护——最危险，因为从内部看来，这像是出色的分析。

观察覆盖层解决了一个更深层的问题：即使对已观察到的数据做出完美解读，当数据仅覆盖少数行为时，仍会产生误导。竞争分支解决的是叙事问题（哪种说法最符合情况？）。覆盖率指标解决的是暴露范围问题（我看到的图景有多完整？）。如果 Agent 选中了最佳解释分支，却忽略了 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 仓位。显示抵押品、借款、供应及其美元价值、金库存款、健康因子、循环策略检测和仓位信号。
morpho_get_history	获取特定 Morpho 市场的历史利率和增长数据。显示借款/供应 APY、利用率和 TVL 趋势，以及最小值/平均值/最大值/当前值统计。包含利率稳定性信号、峰值检测和供应/需求挤压警报。
spectra_get_protocol_stats	SPECTRA 代币经济学、排放计划、费用分配和治理信息。
spectra_list_chains	列出可用网络（10 条链）。
spectra_get_portfolio	获取钱包在 PT、YT 和 LP 中的仓位及其美元价值、可领取收益和 Merkl 奖励（SPECTRA gauge 排放 + 激励计划）。通过解析 reason key，将奖励与特定池匹配。
spectra_get_pool_volume	获取特定池的历史买入/卖出交易量。接受 PT 地址或池地址。
spectra_get_pool_activity	获取近期单笔交易（买入、卖出、流动性事件），并支持筛选。地址隔离模式会展示相互竞争的解读分支（A/B/C）、交易周期的统计置信边界、带有竞争性假设的资金流核算、合约/EOA 检测和 Gas 估算。接受 PT 地址或池地址。
spectra_get_address_activity	跨池地址扫描器——一次调用即可查找某个地址在某条链（或所有链）上交互过的所有池。通过投资组合查询包含已过期/已到期的池。提供逐池细分和跨池汇总。
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 数据（通过链上读取获取总供应量），以及按池乘数计算的 boost。
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 激励 + boost）、底层浮动 APY、池储备金、费率和 Merkl 活动。
pendle_get_best_fixed_yields	扫描所有 Pendle 链，寻找最佳固定利率机会。按隐含 APY 排序，并可按 TVL/流动性筛选。相当于 Pendle 版的 spectra_get_best_fixed_yields。
pendle_get_portfolio	获取钱包在所有 Pendle 链上的仓位——PT、YT、LP 余额及其美元价值和每个仓位的隐含 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 循环计算器——包括借款利率敏感性、盈亏平衡分析、30 天历史风险评估及低于盈亏平衡的概率 P(underwater)。自动检测 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 的收益率。按到期时间匹配，并可配置容差（精确 ≤7d、接近 ≤30d、宽松 ≤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）、对剩余存款人的成本，以及最大安全赎回规模。提供市场压力模式（2x 影响）。
mv_plan_rollover	为即将到期的 MetaVault 仓位规划展期——扫描 Spectra + Pendle 以寻找替代选项，计算入场影响、收益率差距、重叠窗口和净有效 APY。
mv_get_curator_portfolio	汇总多个金库的投资组合——总 AUM、加权 APY、费用收入预测、按底层资产/链划分的集中度，以及跨金库待办事项。支持发现模式（按管理人地址查询）或显式模式。
mv_get_calibration	校准预言机——“正常”是什么样的？根据任意 Morpho 市场、Pendle 市场或 Spectra 池的历史数据计算统计基线（百分位数、异常阈值）。包含同类对比和可直接用于断言的阈值表述。连接感知（监控）与规范（安全断言）的桥梁。
mv_get_position_map	跨协议仓位图——通过一次并行调用查看用户在 Spectra + Pendle + Morpho + 治理（veSPECTRA + vePENDLE）中的完整钱包情况。检测矛盾：未使用的治理 boost、固定利率更高时仍在借贷、集中度风险、循环策略检测、跨协议即将到期的仓位。诚实报告失败（先显示 INCOMPLETE，再显示数字）。首个关注用户本身而不仅是协议的工具。
spectra_get_gauge_votes	完整的 veSPECTRA 治理仪表板——gauge 投票分布、投票 APR、贿赂激励和各池的 SPECTRA 排放。显示 veSPECTRA 持有者将票投向何处、获得哪些奖励、排放集中度和贿赂效率（每票的美元价值）。
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 获取 gauge 状态。提供逐池就绪度评估（OK/CAUTION/WARNING）。运营检查清单：部署后继池、提交 gauge 提案、准备迁移。
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（主网）、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 市场：Ethereum、Base、Arbitrum、Katana

链列表维护（手动）

这三个列表都硬编码在 src/config.ts 中，协议部署到新链时必须手动更新：

• Spectra — 编辑 SUPPORTED_CHAINS_INTERNAL（以及各链对应的 CHAIN_RPC_URLS、CHAIN_RPC_FALLBACKS、CHAIN_BLOCK_TIMES、CHAIN_GAS_ESTIMATES 表）。所有原生 Spectra 工具（metavault 列表、池列表、即将到期的池、协议脉搏、策展人仪表板等）都会读取此列表，因此只需修改一处即可影响所有工具。
• 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 市场——它与我们新添加的 hyperevm 是同一条链。如果 Morpho 在 HyperEVM 上推出 PT 市场，且我们希望扫描这些市场，请将 hyperevm: 999 添加到 Morpho 映射中。

veSPECTRA Boost

服务会通过原始 eth_call（不依赖 ethers/viem）直接从 Base 链读取实时 veSPECTRA 总供应量，并使用 Spectra 的实际公式计算各池的 Boost 倍数：

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.5x Boost。

接受 ve_spectra_balance 的工具（spectra_scan_opportunities、spectra_scan_yt_arbitrage、spectra_compare_yield、spectra_get_ve_info）会自动计算各池的 Boost。veSPECTRA 合约是 Base 上基于 NFT 的投票托管（veNFT），地址为 0x6a89228055c7c28430692e342f149f37462b478b，来源于 spectra-core。

MetaVault 发现与策略建模

MetaVault 是 ERC-7540 策展型金库，可自动执行 LP 滚仓，并将 YT 收益复投到 LP 仓位。两个工具协同工作：

spectra_list_metavaults — 发现工具。从 API（/v1/{network}/metavaults）获取实时 MetaVault 数据，可并行扫描单条链或所有链。返回策展人信息、TVL、实时 APY、份额价格、包含 PT/池详情的活跃仓位，以及 Epoch 利率历史记录。

spectra_model_metavault — 策略建模工具，支持两种模式：

• 实时模式：提供 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，而杠杆会进一步放大这个更高的基础收益。这会形成相对于纯 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

深度分析提示词

预先提供的上下文越多，Agent 就能分析得越深入。每项输入都会解锁不同的工具链：

输入	解锁的功能
资金规模（$200K）	该资金规模下的价格影响、池容量限制、实际 APY
钱包地址（0x...）	投资组合模拟、现有持仓背景、Merkl 奖励
veSPECTRA 余额	每个池的实际加成（而非最小值/最大值范围）
资产偏好	筛选后的收益率曲线、定向扫描
策略类型	LP 与 PT、循环策略或 MetaVault——决定串联哪些工具
到期窗口	期限结构分析、展期时机

理想的提示词会结合以上所有信息。 以下示例会触发 8-10 个工具链：

• 收益猎手：“我有 $50K USDC 和 10,000 veSPECTRA。帮我找到风险调整后最优的 60-180 天固定收益机会。检查 IBT 健康状况，按我的实际入场规模报价，并告诉我池中还有谁。”
• 策划者：“我正在 Base 上搭建一个 USDC MetaVault，计划投入 $500K 自有资金，并预计吸引 $2M 外部资金。请模拟双重循环策略的经济效益，并比较 Spectra 与 Pendle 的 LP 配置。”
• 调查者：“钱包 0xABC... 在 Spectra 主网很活跃。全面展示相关信息——投资组合、所有池中的活动、序列分析，以及他们采用的策略。”
• 期限结构：“展示所有链上的 ETH 收益率曲线。期限溢价异常在哪里？针对定价偏差最大的 3 个池，按 $200K 资金规模报价其容量。”

工具之间的交叉引用能带来真正深入的分析——没有任何单个工具能呈现完整情况。Agent 会在运行时调用 mv_get_protocol_context(topic="workflow_routing") 来了解这些组合方式。

示例查询

连接后，你可以向 Claude 提出以下问题：

• “目前 USDC 的最佳固定收益率是多少？”
• “列出 Base 上 TVL 超过 50k 美元的所有 Spectra 池”
• “使用 Morpho，计算 Base 上 PT-USDC 的 3 倍循环策略”
• “stETH 的固定利率是否优于浮动利率？”
• “哪些 Morpho 市场接受 Spectra PT 作为抵押品？”
• “该 Morpho PT-USDC 市场的借款利率是多少？”
• “目前的 SPECTRA 排放量和锁定率是多少？”
• “显示 0xABC...DEF 在所有链上的投资组合——包括所有未领取的 Merkl 奖励”
• “这个池最近的交易活动是什么？”
• “扫描主网上所有池，查找地址 0xABC...DEF 的活动”
• “检查地址 0xABC...DEF 是合约还是 EOA，并显示其交易模式”
• “报价：购买价值 10,000 USDC 的该池 PT”
• “如果我购买 50k 美元的该 PT，我的投资组合会是什么样？”
• “我有 100K 美元要投入——扫描所有链，寻找风险调整后收益最高的机会”
• “寻找适合投入 500K 美元的 USDC 机会，最大入场价格影响为 2%”
• “寻找 YT 套利机会，即市场对收益率定价有误的机会”
• “我有 100K veSPECTRA——在这个池存入 10K 美元能获得多少加成？”
• “显示 veSPECTRA 总供应量，以及达到最高加成所需的数量”
• “目前有哪些 MetaVaults 正在运行？列出所有链上的全部 MetaVault”
• “显示 Base 上的 MetaVaults——APY 是多少，管理者是谁？”
• “为这个 Base 上的 MetaVault 建模一个策略”（自动获取实时 APY）
• “为一个基础 APY 为 12%、YT 复利为 3%、管理者费用为 10% 的 MetaVault 建模——循环策略会是什么样？”
• “比较 MetaVault 循环和原始 PT 循环，基础 APY 为 12%”
• “我正在管理一个金库，自有资金为 100K 美元，外部存款为 1M 美元——我的实际 ROI 是多少？”
• “比较 Base 上 Spectra 和 Pendle 的收益率——哪个协议提供的 USDC 利率更高？”
• “我正在管理一个有 500K 美元的 MetaVault——扫描 Spectra 和 Pendle，寻找最佳机会”
• “按 TVL 排序，列出 Arbitrum 上所有活跃的 Pendle 市场”
• “在价格影响侵蚀收益前，我最多可以向这个池投入多少资金？”
• “这个 PT 背后的 IBT 是否健康？检查转换率和 APR 构成”
• “显示 USDC 收益率曲线——各个到期时间有哪些利率？”
• “比较所有链上 ETH 的 30 天、90 天和 180 天利率”
• “这个地址几周前在 Katana 上有过交易，但 spectra_get_pool_activity 没有显示任何内容——提取过去 7 天的链上日志”
• “使用我的 RPC URL 获取这个池的历史活动：https://rpc.katana.network”
• “监控我的 Morpho 仓位是否有清算风险——显示每个仓位距离清算还有多远”
• “对我在 Base 上的 MetaVault 进行压力测试——如果一个 epoch 内有 30% 的存款人赎回，会发生什么？”
• “我在 MetaVault 上有一个 14 天后到期的仓位——规划展期并列出最佳候选项”
• “汇总我在所有链上的管理者投资组合——显示总 AUM、综合 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、链 RPC 以获取链上 Curve get_dy() 报价和合约检测，以及 Base RPC 以获取 veSPECTRA 数据。无需钱包、无需交易、无需密钥，也无需 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 个十六进制字符）。所有 API 调用的超时时间均为 15 秒，并会在遇到临时故障（5xx、ETIMEDOUT、ENETUNREACH、ENOTFOUND）时自动重试。跨链扫描使用 Promise.allSettled，因此某条链故障不会阻止其他链返回结果。GraphQL 输入经过清理，以防止注入。所有错误返回均使用 MCP 的 isError: true 标志，以便向 Agent 正确传递错误信号。

类型安全

• 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 错误
• 池数据缓存：每条链的 TTL 为 30 秒，并对进行中的请求去重——30 秒内的重复扫描会使用缓存数据
• API 验证：validatePtEntries() 会在系统边界过滤格式错误的 API 响应（验证地址、到期时间和名称字段）
• veSPECTRA 缓存：基于 Promise 的去重机制可在多个工具并发运行时避免重复调用 RPC（TTL 为 5 分钟）
• Morpho 批次上限：first 参数上限设为 min(addresses * 3, 500)，以避免超出 GraphQL 响应限制
• 链上报价：在 8 条链上通过原始 eth_call 调用 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（缓存 TTL 为 60 秒，并对进行中的请求去重）。失败时返回空映射——工具输出不变。通过跳过奖励代币已由原生 API 数据展示的活动来避免重复计算
• MCP 错误信号：所有错误捕获块都会返回 isError: true，以便 Agent 区分错误和空结果
• PT 地址解析：池工具（spectra_get_pool_volume、spectra_get_pool_activity）接受池地址或 PT 地址，并自动解析
• 错误日志记录：Morpho 查询中的捕获块会将错误记录到 stderr，而不是静默吞掉错误
• 优雅关闭：收到 SIGTERM/SIGINT 时，会先调用 server.close()，再调用 process.exit()

测试

从源码检出目录运行：

# 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 奖励解析（从原因键中提取池地址、将 wei 转换为可读数值、匹配/未匹配分类）、Merkl 奖励格式化、余额格式化、跨协议到期时间匹配（normalizeUnderlyingSymbol、matchByAssetAndMaturity）、Pendle logit AMM 价格影响模型（estimatePendlePriceImpact）、Pendle 日期/到期时间辅助函数（pendleDaysToMaturity）、Pendle 市场格式化工具（简洁版 + 摘要版）以及配置验证。无需网络。

集成测试（test.cjs）

共 405 项测试，涵盖工具注册、架构验证、API 响应、链上 Curve get_dy() 报价、跨池地址扫描、地址隔离模式、跨协议管理人扫描以及格式错误地址的负向测试。测试会从实时 API 动态发现池地址和 PT 地址，因此池到期时测试不会过时。

Agent 推理测试（test-agent.cjs）

82 项断言，通过多工具工作流测试来验证“推理表面”——使用这些工具的 Agent 能否发现异常、交叉引用数据，并避开协议机制陷阱？测试包括：

• 协议上下文完整性——包含所有主题，解释 Router 批处理的歧义，并提供交叉引用指南
• 异常检测——原始 APY 与考虑资本因素的排名会得出不同结果（有意产生的差异）
• 跨工具数据一致性——APY 在 spectra_list_pools → spectra_get_pt_details → spectra_compare_yield 之间保持一致
• Router 机制——通过池活动 → 投资组合交叉引用检测铸造并卖出的循环
• Router 限制——API 能解析 eth_getLogs 地址过滤遗漏的 Router 交易
• 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、多重加成（积分计划）、标签、含比例的池储备、IBT APR 构成、包装代币的 baseIbt
• 投资组合中的 Merkl 奖励——SPECTRA gauge 排放量会显示在投资组合输出中，空钱包也能妥善处理

主观测试套件（AGENT-TESTS.md）

包含 38 个可复制粘贴的问题，分为 11 个层级（基本工具使用 → 开放式涌现 → 新手理解），并附有评分标准，用于评估 LLM Agent 使用 MCP 工具时的表现。第 8 层测试“开放式涌现”——在不将多种相互竞争的解读简化成单一叙事的情况下，兼容这些解读的能力。第 11 层测试新手理解能力——Agent 能否解释存入路径、识别保守的影响估算，并调用正确的扫描工具？这些测试旨在通过启动子 Agent 来执行，并由人工或通过 LLM-as-judge 手动评分。

API 参考

此服务封装了以下端点：

端点	使用方
GET /v1/{chain}/pools	spectra_list_pools、spectra_get_best_fixed_yields、spectra_scan_opportunities、spectra_scan_yt_arbitrage、spectra_get_yield_curve（30s TTL 缓存）
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→pool 解析）
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 gauge 排放 + 激励计划）
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 — 60s TTL 缓存）
GET api.spectra.finance/v1/governance/voting-incentives	spectra_list_expiring_pools（gauge 状态 — 存在池地址表示 gauge 存在）
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} 使用 mainnet 作为 Ethereum 的 slug（服务端接受别名 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 使用时间衰减 logit 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：Agent 可传入任意 rpc_url 参数，适用于没有硬编码 RPC 的链（Katana、Monad）
• 分块获取：每块 2000 个区块，每块单独重试；尽力获取（RPC 出现问题时返回部分结果）
• 双合约解码：Curve StableSwap-NG 池事件以及 Spectra PrincipalToken 金库事件
• 区块范围控制：显式指定 from_block/to_block 或 lookback_hours（默认 24 小时，最长 720 小时/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 模式

添加新工具时，请遵循三层架构：

1. 描述（第 2 层）： 说明会影响工具数据解读的协议机制。对于含义不明确的信号，使用“可能是”这样的措辞。至少添加一条指向相关工具的交叉引用提示。
2. 输出（第 3 层）： 如果数据包含需要领域知识才能识别的信号（例如，暗示某种策略的比率，或可能有不同含义的事件），请计算结构化提示并将其纳入输出。让提示醒目，但不要带有指示性。当一种可观察模式存在多种合理解释时，应将它们作为权重相同的不同分支呈现，不要自行选择其中一种。若样本量较小，应标明其在统计上不足。
3. 覆盖范围（第 4 层）： 如果工具输出仅涵盖地址或资金池完整行为的一部分，请量化盲区。报告数值覆盖率（可观察活动与持仓规模的对比）、时间缺口，以及使用了哪些数据源、还有哪些数据源可用。最后添加边界标记：“仓位规模应基于这项分析并不完整，而非全面这一前提来确定。”覆盖率指标会限制所有解读分支的适用范围——高置信度评估 + 低覆盖率 = 虚假的信心。
4. 资源（第 1 层）： 如果新工具引入了现有资源未涵盖的基础协议概念，请更新 index.ts 中的 spectra-overview。
5. 消解条件： 在 docs/dissolution-conditions.md 中记录新结构何时不再适用。每条第 3 层提示、架构模式和生成性摩擦点都应附带消解条件——即在情况变化时重新评估的提示。

目标是：从未接触过该项目的 Agent 仅阅读工具描述和输出提示，就能正确使用工具，并将其与其他工具组合成新的分析工作流。

添加写入能力（未来）

若要让 Agent 真正执行策略，可以添加通过 Spectra 的 Router 合约构造未签名交易的工具。Agent 会返回供用户签名的交易 calldata——绝不持有密钥。

添加 gauge/bribe 数据

查询 spectra-governance 子图，获取当前 epoch 投票、贿赂金额和投票者奖励。这对优化 veSPECTRA 投票策略的 Agent 很有价值。

尚未接入（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