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