Factor MCP

🚀 Factor MCP 服务器

Factor MCP 服务器是一个 MCP（模型上下文协议）服务器，它使得 AI 工具能够与 EVM 链上的 Factor 协议金库进行交互。

🚀 快速开始

一键安装

curl -sSL https://raw.githubusercontent.com/FactorDAO/factor-mcp/main/install.sh | bash

此命令将执行以下操作：

• 安装 Rust（如果尚未安装）
• 安装 Foundry（cast、anvil、forge）
• 克隆并构建 Factor MCP
• 创建 factor-mcp 命令

手动安装

git clone https://github.com/FactorDAO/factor-mcp.git
cd factor-mcp
npm install
npm run build

配置

服务器使用存储在 ~/.factor-mcp/config.json 的 JSON 配置文件：

{
  "alchemyApiKey": "your_api_key",
  "defaultChain": "ARBITRUM_ONE",
  "simulationMode": false,
  "logLevel": "info",
  "activeWallet": "default"
}

环境变量可以覆盖 JSON 配置：

• ALCHEMY_API_KEY - 用于 RPC 访问的 Alchemy API 密钥
• DEFAULT_CHAIN - 默认链（ARBITRUM_ONE、OPTIMISM、BASE、SONIC、MAINNET）
• SIMULATION_MODE - 设置为 "true" 以启用干运行模式
• LOG_LEVEL - 日志级别（debug、info、warn、error）
• FACTOR_ARTIFACTS_DIR - 将生成的 forge 脚本持久化到该目录（在 Docker/临时环境中很有用）

运行

# 直接执行
npm start

# 或者使用环境变量
ALCHEMY_API_KEY=xxx npm start

Claude 代码集成

添加到你的 Claude 代码配置文件（~/.config/claude-code/config.json 或 MCP 设置）：

{
  "mcpServers": {
    "factor": {
      "command": "node",
      "args": ["/path/to/factor-mcp/dist/index.js"],
      "env": {
        "ALCHEMY_API_KEY": "your_api_key"
      }
    }
  }
}

✨ 主要特性

• 68 个 MCP 工具：用于全面的金库管理
• 多链支持：Arbitrum One、Base、以太坊主网
• 安全的钱包管理：Foundry 密钥库（Web3 V3）+ AES - 256 - GCM 加密
• 模拟模式：在执行交易前预览交易
• 策略构建：使用构建块组合 DeFi 策略
• Foundry 集成：分叉模拟、错误解码、forge 脚本

📦 安装指南

一键安装

curl -sSL https://raw.githubusercontent.com/FactorDAO/factor-mcp/main/install.sh | bash

手动安装

git clone https://github.com/FactorDAO/factor-mcp.git
cd factor-mcp
npm install
npm run build

💻 使用示例

基础用法

# 一键安装
curl -sSL https://raw.githubusercontent.com/FactorDAO/factor-mcp/main/install.sh | bash

# 手动安装
git clone https://github.com/FactorDAO/factor-mcp.git
cd factor-mcp
npm install
npm run build

# 运行
npm start

高级用法

# 使用环境变量运行
ALCHEMY_API_KEY=xxx npm start

# Claude 代码集成配置
{
  "mcpServers": {
    "factor": {
      "command": "node",
      "args": ["/path/to/factor-mcp/dist/index.js"],
      "env": {
        "ALCHEMY_API_KEY": "your_api_key"
      }
    }
  }
}

📚 详细文档

工具参考

配置（5 个工具）

金库操作（14 个工具）

金库管理（12 个工具）

借贷操作（4 个工具）

交换操作（4 个工具）

LP 操作（4 个工具）

收益操作（1 个工具）

闪电贷（1 个工具）

代币与注册表（3 个工具）

策略构建（1 个工具）

交易工具（2 个工具）

配置文件与策略（6 个工具）

Foundry 工具（5 个工具）

SDK 覆盖路线图

此路线图跟踪 MCP 服务器对 @factordao/sdk-studio 包的覆盖情况。标记为 [x] 的项目已在 MCP 中实现，标记为 [ ] 的项目是尚未暴露的 SDK 功能。

配置与钱包

• [x] 设置活动链（ARBITRUM_ONE、BASE、MAINNET）
• [x] 设置自定义 RPC 端点
• [x] 获取当前配置（链、RPC、钱包、模拟模式）
• [x] 从私钥导入钱包
• [x] 生成钱包（新的随机钱包）
• [x] Foundry 密钥库存储（Web3 V3 格式）
• [x] Factor - MCP 加密存储（AES - 256 - GCM）
• [x] 使用现有的 Foundry 密钥库
• [x] 获取 SDK 地址簿（Pro 适配器地址）

金库创建与模板

• [x] 部署新的 Factor Pro 金库 (factor_create_vault)
• [x] 带有现成参数的金库模板 (factor_vault_templates)
• [x] 支持借贷的金库模板（Aave 预设）
• [x] 支持借贷的金库模板（Compound V3 预设）
• [x] 支持借贷的金库模板（Morpho 预设）
• [x] 从工厂自动检测记账适配器
• [x] 在部署前验证金库配置 (factor_validate_vault_config)
• [x] 获取白名单工厂地址 (factor_get_factory_addresses)
• [x] 不可变金库选项
• [x] 可配置的手续费、上限、债务比率、冷却时间、可升级性

金库查询

• [x] 获取拥有的金库 (factor_get_owned_vaults)
• [x] 获取金库信息 — 资产、手续费、管理员、适配器 (factor_get_vault_info)
• [x] 获取用户份额、总供应量、每份价格 (factor_get_shares)
• [x] 获取执行历史（解码调用） (factor_get_executions)
• [x] 预览存款 — 预期份额 (factor_preview_deposit)
• [x] 预览取款 — 预期资产 (factor_preview_withdraw)
• [ ] 检查资产是否为有效的存款资产 (isDepositAsset)
• [ ] 检查资产是否为有效的取款资产 (isWithdrawAsset)
• [ ] 获取资产记账适配器 (getAssetAccounting)
• [ ] 获取债务记账适配器 (getDebtAccounting)
• [ ] 估算原始取款预期金额 (estimateRawWithdrawExpectedAmount)
• [ ] 通过 Alchemy 获取 USD 余额明细 (balanceUsd)

金库存款与取款

• [x] 存入 ERC20 代币 (factor_deposit)
• [x] 提取/赎回份额 (factor_withdraw)
• [ ] 存入原生代币 — ETH (depositNative)
• [ ] 在一笔交易中存入并执行策略 (depositAssetAndExecute)
• [ ] 带有执行块的原始取款 (rawWithdraw)

金库手续费管理

• [x] 设置存款手续费 (factor_set_deposit_fee)
• [x] 设置取款手续费 (factor_set_withdraw_fee)
• [x] 设置业绩手续费 (factor_set_performance_fee)
• [x] 设置管理费 (factor_set_management_fee)
• [x] 收取累计的业绩手续费 (factor_charge_performance_fee)
• [x] 设置手续费接收地址 (factor_set_fee_receiver)

金库风险与访问管理

• [x] 设置最大存款上限 (factor_set_max_cap)
• [x] 设置最大债务比率 (factor_set_max_debt_ratio)
• [x] 设置价格偏差容忍度 (factor_set_price_deviation_allowance)
• [x] 添加金库管理员 (factor_add_vault_manager)
• [x] 移除金库管理员 (factor_remove_vault_manager)
• [x] 设置风险管理员 (factor_set_risk_manager)

金库策略配置

• [ ] 设置公共策略 (setPublicStrategy)
• [ ] 移除公共策略 (removePublicStrategy)
• [ ] 执行公共策略 (executePublicStrategy)
• [ ] 设置存款策略 (setDepositStrategy)
• [ ] 移除存款策略 (removeDepositStrategy)

金库模拟

• [ ] 模拟存款 (simulateDeposit)
• [ ] 模拟收取业绩手续费 (simulateChargePerformanceFee)

代币与批准

• [x] ERC20 代币批准 (factor_give_approval)
• [x] 获取借贷代币 — aTokens、债务代币、底层资产 (factor_get_lending_tokens)
• [x] 将资产/债务代币添加到金库 (factor_add_vault_token)
• [ ] ERC2612 许可/无 gas 批准 (permit 适配器)

借贷 — Aave V3

• [x] 供应 / 全部供应 / 按百分比供应
• [x] 提取 / 全部提取
• [x] 借款
• [x] 偿还 / 全部偿还

借贷 — Compound V3

• [x] 供应 / 全部供应
• [x] 提取 / 全部提取
• [x] 借款
• [x] 偿还 / 全部偿还
• [ ] 领取奖励 (claimRewards)

借贷 — Morpho

• [x] 供应（借贷）
• [x] 作为抵押品供应
• [x] 提取（借贷 + 抵押品）
• [x] 借款
• [x] 偿还 / 全部偿还

借贷 — Silo V2

• [x] 供应
• [x] 提取
• [x] 借款
• [x] 偿还

DEX — Uniswap V3

• [x] 精确输入单次交换 (factor_swap)
• [x] 交换全部余额
• [x] 按百分比交换
• [x] 可配置的手续费层级（100、500、3000、10000）
• [x] 可配置的滑点
• [x] 精确输出单次交换 (factor_swap_exact_output)
• [x] 精确输出单次交换（使用全部余额） (factor_swap_exact_output 并将 amountInMax 设置为 "all"）

DEX — OpenOcean

• [x] 聚合交换 (factor_swap_openocean)

DEX — Pendle PT/YT

• [x] 代币兑换 PT
• [x] 代币兑换 YT
• [x] PT 兑换代币
• [x] YT 兑换代币

DEX — Aqua

• [ ] Aqua DEX 交换（Base）

LP — Uniswap V3

• [x] 创建集中流动性头寸
• [x] 向现有头寸添加流动性
• [x] 移除流动性（指定金额或 "all"）
• [x] 收集累积的手续费
• [ ] 按百分比移除流动性 (removeByPercentage)

LP — Camelot V3

• [x] 创建集中流动性头寸
• [x] 添加流动性
• [x] 移除流动性
• [x] 收集手续费
• [ ] 按百分比移除流动性 (removeByPercentage)

LP — Aerodrome

• [x] 创建集中流动性头寸
• [x] 添加流动性
• [x] 移除流动性
• [x] 收集手续费

收益 — Pendle LP

• [x] 向 Pendle 市场添加流动性
• [x] 移除流动性
• [x] 收集手续费/奖励

闪电贷

• [x] 带有内部策略步骤的 Aave 闪电贷
• [x] 带有内部策略步骤的 Morpho 闪电贷
• [ ] Balancer 闪电贷 (balancerFL)

策略构建器

• [x] 通过 executeByManager 执行策略
• [x] 列出可用的适配器 (factor_list_adapters)
• [x] 将策略保存到 Stats API (factor_save_strategy)
• [x] 从 Stats API 删除策略 (factor_delete_strategy)
• [x] 通过哈希获取策略 (factor_get_strategy)
• [x] 通过所有者获取策略 (factor_get_strategies)
• [x] 将配置文件保存到 Stats API (factor_save_profile)
• [x] 从 Stats API 获取配置文件 (factor_get_profile)
• [ ] 将策略导出为调用数据 (export)
• [ ] 将策略导出为 JSON (exportToJson)
• [ ] 克隆策略 (clone)
• [ ] 逐步调试策略 (debugFromBlocks)
• [ ] 估算用户影响 (estimate / estimateFromBlocks)
• [ ] 策略摘要 (summary)
• [ ] 猜测代币状态变化 (guessTokenState)

实用适配器

• [ ] 在地址之间转移代币 (transfer 适配器)
• [ ] 退还零头金额 (refund 适配器)
• [ ] 原生代币包装/解包装 (native 适配器)
• [ ] ERC721 / NFT 操作 (erc721 适配器)
• [ ] 杠杆金库操作 (leverageVault 适配器)
• [ ] 杠杆策略构建 (leverageStrategy 适配器)
• [ ] 存款策略管理 (depositPolicy 适配器)
• [ ] Gelato 自动化设置 (gelato 适配器)
• [ ] Chainlink 直接价格馈送查询 (chainlink 适配器)

适配器发现与元数据

• [x] 按链列出适配器 (factor_list_adapters)
• [ ] 获取跨适配器的用户投资组合信息 (getUserInfo)
• [ ] 获取构建块/协议的市场信息 (getMarkets)
• [ ] 通过输入代币获取市场信息 (getMarketByInToken)
• [ ] 通过输入代币获取协议信息 (getProtocolsByInToken)
• [ ] 获取支持的输入代币 (getInTokens)
• [ ] 获取适配器元数据 (getMetadata / getMetadataByBuildingBlock)
• [ ] 获取所有构建块类型 (getBuildingBlocks)

激励系统

• [ ] 将代币添加到激励白名单 (addBoostTokenWhitelist)
• [ ] 从激励白名单中移除代币 (removeBoostTokenWhitelist)
• [ ] 存入金库奖励 (depositRewardForVaultBN)
• [ ] 赎回激励奖励 (redeemBoostRewards)
• [ ] 赎回所有激励奖励 (redeemBoostRewardAll)
• [ ] 获取激励奖励代币 (getBoostRewardTokens)
• [ ] 获取用户赚取的激励代币 (boostEarnedTokensByUser)
• [ ] 获取奖励数据 (rewardData)
• [ ] 获取指定时间段的奖励 (getRewardForDuration)

扩展系统

• [ ] 获取扩展金库 (getVaults)
• [ ] 获取扩展金库详情 (getVaultDetail)
• [ ] 获取用户的扩展头寸 (getUserVaults)
• [ ] 获取用户的活跃余额 (activeBalance)
• [ ] 获取总活跃供应量 (totalActiveSupply)
• [ ] 获取扩展奖励代币 (getScaleRewardTokens)
• [ ] 赎回扩展奖励 (redeemScaleRewards)
• [ ] 赎回激励 + 扩展奖励 (redeemBoostAndScaleRewards)
• [ ] 对计量器进行投票 (vote)
• [ ] 取消投票 (unvote)
• [ ] 获取用户/金库的投票信息
• [ ] 领取扩展奖励 (claimRewards)
• [ ] 获取扩展市场数据 (getMarketData)
• [ ] 获取历史数据 (getHistoricalData)

贿赂系统

• [ ] 创建贿赂 (addBribe)
• [ ] 领取贿赂 (claimBribe)
• [ ] 获取贿赂信息 (getBribe)
• [ ] 获取所有贿赂信息 (getAllBribes)

交易与调试

• [x] 预览交易并估算 gas (factor_preview_transaction)
• [x] 检查交易状态 (factor_get_transaction_status)
• [x] 检查 Foundry 安装情况 (factor_check_foundry)
• [x] 通过 cast 执行只读合约调用 (factor_cast_call)
• [x] 通过 anvil 在分叉网络上进行模拟 (factor_simulate_transaction)
• [x] 解码合约错误 (factor_decode_error)
• [x] 运行 Solidity forge 脚本 (factor_run_forge_script)
• [x] 模拟时的余额覆盖
• [x] 带有自动生成的 Forge 脚本的模拟提示

Pro 适配器可用性

MCP 服务器仅使用 _pro 适配器。未部署的适配器不包含在路线图中。

借贷

DEX

LP

收益

闪电贷

记账

基础设施

注意：以太坊主网没有部署 Pro 适配器（仅在测试环境中有工厂 + Chainlink 记账）。

覆盖情况总结

🔧 技术细节

钱包存储

钱包支持两种后端：

• Factor - MCP（默认）：~/.factor-mcp/wallets/ — AES - 256 - GCM 加密，PBKDF2 密钥推导（100k 次迭代）
• Foundry 密钥库：~/.foundry/keystores/ — Web3 秘密存储 V3 格式，与 cast/geth 兼容

最佳实践

1. 生产钱包始终使用加密
2. 使用模拟模式进行测试 (simulationMode: true)
3. 切勿提交钱包文件或 API 密钥

🐳 Docker 部署

# 构建镜像
docker build -t factor-mcp .

# 使用 docker-compose 运行
docker-compose up -d

💻 开发

# 安装依赖
npm install

# 类型检查
npm run typecheck

# 构建
npm run build

# 以开发模式运行
npm run dev

# 运行测试
npm test

📄 许可证

本项目采用 MIT 许可证。