Bvcc Agent Wallet

@bvcc/agent-mcp

用于 BVCC Agent 钱包的 Model Context Protocol 服务。 它让支持 MCP 的 AI 运行时——Claude Code、Cursor、Claude 桌面应用——能够在链上操作 BVCC Agent 钱包：查询余额和限额、规划并模拟兑换、发送代币、在 Uniswap v3/v4 上兑换（包括兑换为原生 ETH 或从原生 ETH 兑换），在 Uniswap v3/v4 上提供流动性（包括原生 ETH 池），以及在 Aave v3 上借贷和解除头寸——包括自行通过安全步骤平仓或降低头寸杠杆。它还内置了操作指南（listGuides / getGuide，也以提示词形式提供），让 Agent 可以按需学习如何使用各个功能领域。

每个工具都由 @bvcc/agent-sdk 的能力目录生成。这里没有逐个工具编写的代码：只需将能力添加到 SDK 目录中，它就会自动显示在这里。

刚接触此项目？请从 QUICKSTART.md 开始 — 完整的端到端设置指南（创建钱包 → 在链上授权 Agent → 为其注入 Gas → 配置 → 验证）。指南涵盖了大家容易遗漏的两个步骤；若缺少这些步骤，Agent 将无法执行任何操作。

安全性

此服务不会赋予额外权限。所有限额——支出上限（原生代币 + 单个代币、每日 + 总额）、允许使用的代币、允许使用的协议、收款人白名单以及全局暂停——均由 Agent 钱包合约在链上强制执行。任何工具可能造成的最坏影响，都不会超出你在 BVCC 控制面板中授予 Agent 的权限范围。

• Agent 的私钥从环境中读取，在本地用于签名，且绝不会传输。BVCC 不会接收、存储或托管该私钥。
• 工具通过 SDK 目录显式公开，不会自动发现工具。
• 设置 BVCC_MCP_READONLY=true，即可仅公开读取和模拟工具（不执行写入操作）。

工具

根据目录生成并按类别标记：

核心（钱包、转账、兑换）：

类别	工具
🟢 读取	getAgentStatus、getCapabilities、getNativeBalance、getTokenBalances、getRemaining、needsApproval
🟡 模拟	buildSwapPlan、dryRunSendNative、dryRunSendToken、dryRunSwapV3、dryRunSwapV4
🔴 写入	sendNative、sendToken、approve、swapV3、swapV4、swapToNative、swapFromNative

Agent 执行操作时会自动在链上收取 0.15% 的 BVCC Agent 费用，该费用与 Gas 费用和你的支出预算分开计算。

Aave v3 借贷（aave 模块 — Arbitrum、Ethereum、BNB、Base、Polygon）：

类别	工具
🟢 读取	getAavePositions、getAaveMarket
🟡 模拟	dryRunAaveSupply、dryRunAaveBorrow、aavePlanClosePosition、aavePlanDeleverage、aavePlanCollateralSwap、aavePlanDebtSwap
🔴 写入	aaveSupply、aaveWithdraw、aaveBorrow、aaveRepay、aaveRepayWithATokens、aaveSetCollateral、aaveSetEMode、aaveClosePosition、aaveDeleverage、aaveCollateralSwap、aaveDebtSwap

存款和借款始终针对钱包本身——不存在 to 或 onBehalfOf 参数，因为钱包的链上调用策略会锁定受益人。

⚠️ 四个 aave* 平仓工具可能在一次调用中发送多笔交易。 aaveClosePosition、aaveDeleverage、aaveCollateralSwap 和 aaveDebtSwap 会运行分块循环，根据实时状态重新推导并模拟每一步。请先调用对应的 aavePlan* 工具，查看其计划执行的操作。如果健康因子低于 hfFloor（默认值为 1.05）、兑换价格与 Aave 预言机价格偏差过大、循环无法继续取得进展，或 Agent 预算即将耗尽，这些工具会停止，而不会继续执行。

Uniswap 流动性（lp 模块 — 在 v3 和 v4 上开仓、收取费用、平仓）：

类别	工具
🟢 读取	getV3Position、getV4Position
🟡 模拟	dryRunAddLiquidityV3、dryRunRemoveLiquidityV3、dryRunAddLiquidityV4、dryRunRemoveLiquidityV4
🔴 写入	addLiquidityV3、removeLiquidityV3、collectFeesV3、burnV3、addLiquidityV4、removeLiquidityV4、collectFeesV4、burnV4

头寸 NFT 会铸造给钱包，每笔资金也都会返回钱包——这由链上规则锁定。addLiquidityV3 会根据池子的当前价格调整两侧的数量（默认覆盖完整价格范围，也可以传入 ticks）。v4 支持原生 ETH 池；其工具要求链上已为 Agent 激活 v4 PositionManager 的 DEEP 验证器，否则操作会安全失败。请注意，v3 没有 increaseLiquidity（NFPM 不限制所有者，因此需通过铸造新头寸来添加流动性）。

指南（meta 模块 — 始终公开，提供帮助）：

类别	工具
🟢 读取	listGuides、getGuide

listGuides 会列出操作指南；getGuide({ area }) 会返回某个领域的操作手册，其中包含推荐的工作流和注意事项，并指出具体工具，涵盖 getting-started、swaps、lending 和 liquidity。即使启用了模块筛选，这些指南仍然可用，因此受限于单项功能的 Agent 仍能了解如何使用该功能。同一指南也会以提示词（guide-<area>）的形式提供，方便用户通过斜杠命令调用。

写入操作带有 MCP destructiveHint 注解，因此客户端可以要求确认。推荐的操作工作流请参阅 GUIDE.md。

配置

建议： 将这些值（尤其是 AGENT_PRIVATE_KEY）保存在专用的 env 文件中，并通过 BVCC_ENV_FILE 指定该文件，而不要将密钥直接写入 MCP 宿主的配置（配置可能会被共享、同步和截图）。 对该文件运行 chmod 600，并将其放在任何云同步文件夹之外。如果愿意， 也可以将变量直接写入宿主的 env 块；宿主环境变量的优先级高于文件中的值。请参阅 .env.example。

示例 agent.env（通过 BVCC_ENV_FILE 传入路径）：

AGENT_PRIVATE_KEY=0xYOUR_AGENT_KEY
WALLET_ADDRESS=0xYOUR_WALLET
CHAIN_ID=42161

变量	必需	描述
AGENT_PRIVATE_KEY	是	Agent EOA 私钥（0x + 64 位十六进制字符）。仅在本地使用。
WALLET_ADDRESS	是	此 Agent 操作的 BVCC Agent Wallet。
CHAIN_ID	是	默认链：42161 Arbitrum One · 56 BNB · 1 Ethereum · 8453 Base · 137 Polygon · 421614 Arbitrum Sepolia。
RPC_URL	否	默认链的自定义 RPC（否则使用公共默认值）。
RPC_URL_<chainId>	否	按链覆盖 RPC，例如 RPC_URL_56。
BVCC_ENV_FILE	否	要加载的专用 env 文件路径（避免将密钥放入宿主配置）。宿主环境变量的优先级高于该文件中的值。
BVCC_MCP_READONLY	否	true 仅开放读取/模拟工具。
BVCC_MCP_MODULES	否	要开放的逗号分隔功能组：core、aave、lp。未设置 = 全部。

限制 Agent 可访问的内容。 BVCC_MCP_READONLY 和 BVCC_MCP_MODULES 相互独立，可以组合使用。如果 Agent 永远不会使用借贷功能，不开放这些 工具就能少一个出错的机会：

BVCC_MCP_MODULES=core              # wallet + swaps    (18 + 2 guides = 20)
BVCC_MCP_MODULES=aave              # Aave lending      (19 + 2 = 21)
BVCC_MCP_MODULES=lp                # Uniswap liquidity (14 + 2 = 16)
BVCC_MCP_MODULES=core,aave,lp      # everything (= unset)  (51 + 2 = 53)
BVCC_MCP_MODULES=core
BVCC_MCP_READONLY=true             # read-only wallet  (11 + 2 = 13)

两个指南工具（listGuides、getGuide，以及模块 meta）始终会在 这些工具之外开放——这就是 + 2 的含义——因此，即使 Agent 仅能访问一个 功能，也仍然可以查看该功能的使用方法。

无法识别的模块名称会被忽略，因此拼写错误只会让可用范围变小，不会 变大。这两个开关都不是安全边界——合约才是——但可用范围越小，困惑的 Agent 采取错误操作的途径就越少。

多网络： 一个服务即可让 Agent 在任何受支持的链上运行。每个 工具都接受可选的 network（链 ID 或名称：ethereum、bsc、arbitrum、 base、polygon、arbitrum-sepolia），默认使用 CHAIN_ID——因此无需重启， 就可以说“在 bsc 上兑换”。所有链上的钱包地址都相同（CREATE2）； Agent 必须在你使用的每条链上获得授权。

安装与构建

npm install
npm run build
npm test          # builds + stdio smoke test (no chain calls)

连接到客户端

Claude Code

claude mcp add bvcc-agent-wallet \
  --env BVCC_ENV_FILE=/secure/agent.env \
  -- npx -y @bvcc/agent-mcp

Cursor / Claude 应用（mcp.json）

{
  "mcpServers": {
    "bvcc-agent-wallet": {
      "command": "npx",
      "args": ["-y", "@bvcc/agent-mcp"],
      "env": { "BVCC_ENV_FILE": "/secure/agent.env" }
    }
  }
}

密钥保存在 agent.env 中，而非上方的配置里。如果你更愿意直接写入， 请将 env 块替换为直接填写 AGENT_PRIVATE_KEY / WALLET_ADDRESS / CHAIN_ID （安全性较低——密钥会留在宿主配置中）。为确保可复现，请固定版本， 例如 @bvcc/[email protected]（请参阅升级）。

升级

SDK 已打包在此软件包中，因此只需更新 MCP 即可获得新功能（Aave 借贷功能就是以这种方式在 0.2.0 中推出的）——你无需单独安装或更新 @bvcc/agent-sdk。

1. 在配置中固定版本，确保可复现：

   "args": ["-y", "@bvcc/[email protected]"]
   

   npx 会缓存，因此未固定版本的 @bvcc/agent-mcp 可能会继续运行旧版本。 如需升级，请提高版本号（例如 @0.2.1）——也可以按需使用 @latest。 全局安装：npm i -g @bvcc/agent-mcp@latest。
2. 重启 MCP 客户端。 目录中的新工具会自动显示；配置中的其他内容无需更改。启动横幅会显示正在运行的版本（[bvcc-agent-mcp vX.Y.Z]）。
3. ⚠️ 在链上授权任何新协议。 新增协议（例如 Aave）的版本会立即提供相关工具，但 Agent 必须在其 allowedProtocols 中包含该协议的合约，否则操作会因 ProtocolNotAllowed 而回退。从仪表板授权即可，方式与路由器相同。

请参阅 CHANGELOG.md，了解各版本的变更内容。版本遵循 SemVer：patch 表示修复，minor 表示新增兼容功能，0.x 表示 API 仍可能变更。

工作原理

@bvcc/agent-sdk  ──catalog──►  @bvcc/agent-mcp  ──MCP──►  Claude Code / Cursor / Claude
   (on-chain limits live in the Agent Wallet contract, not here)

服务会加载目录，为每项功能注册一个 MCP 工具（Zod schema → 工具输入 schema，kind → 工具注释），并将每次调用路由至 SDK，由 SDK 使用 Agent 密钥签名并提交 executeAsAgent。

许可证

MIT © BlockVenture Chain Capital (BVCC)