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许可证。