Uniswap Tx Builder

uniswap-tx-builder-mcp

一个无需密钥的 MCP 服务，用于构建 Uniswap v3 流动性头寸交易，并可选择通过 eth_call 对其进行模拟。它绝不会持有密钥，也不会签名——你可以使用自己的钱包（viem、CDP 钱包 MCP 或任何签名器）对返回的 calldata 进行签名并广播。

由于无需密钥，构建的交易唯一受限于你的钱包——该服务的威胁面仅限于“返回 calldata 并读取公共 RPC”。

生态系统

它是 Yummybait 的一部分：

• cdp-wallet-agent-example — 一个参考 Agent，使用 Coinbase CDP 钱包作为签名器来驱动此 MCP。
• yummybait.finance — 这些工具所支持的产品。

工具

每个构建工具都会返回 tx = { to, data, value, chainId }，以及 rlp——tx 的未签名 EIP-1559（type-2）序列化数据，其中 nonce/费用/gas 均置零（CDP API 等签名服务会填充这些字段；如果你自行管理 nonce，则自行序列化 tx）——以及便于人类阅读的 description。除可支付的 Universal Router wrap/swap 构建外，value 均为 "0"。地址格式为 0x…40；positionId 和金额均为十进制字符串（它们超出了 JS 安全整数范围）。

工具	用途	是否需要 RPC？
build_collect	从一个头寸中收取所有尚未收取的费用，并发送给 recipient。	仅试运行需要（默认开启；simulate: false 时离线构建）
build_close	移除所有流动性 + 收取费用；burn: true 还会销毁空 NFT。返回读取到的头寸。	始终需要 — 会先读取头寸
build_mint	铸造新头寸（原始刻度值 + wei 数量）。	仅在 simulate: true 时需要
build_increase	向现有头寸添加流动性。	仅在 simulate: true 时需要
build_approve	构建 ERC-20 approve(spender, amount) 交易 — 例如，在 build_mint/build_increase 之前为 NFPM 授权，或在通过 Permit2 支付的 build_swap 之前为 Permit2 授权。对于无限额度授权，设置 amount: "max"。	仅在提供 sender 时需要（启用试运行）
build_wrap	通过 Universal Router（WRAP_ETH）将原生 ETH 包装为 WETH。	仅在提供 sender 时需要（启用试运行）
build_swap	通过 Universal Router 执行 tokenIn → tokenOut 的精确输入单跳兑换；使用 wrapWei（tokenIn = WETH9）时，会先包装原生 ETH 并将剩余金额转入指定地址；使用 unwrapOut（tokenOut = WETH9）时，会将输出解包为原生 ETH — 两种情况都在同一笔交易中完成。传入 sender 后，默认的 Permit2 支付路径会自动检测授权额度是否不足，并返回签名许可请求而不是交易 — 无需单独进行链上 Permit2 授权。	仅在提供 sender 时需要（启用试运行）
get_swap_quote	只读。 通过 Uniswap v3 QuoterV2 为精确输入单跳兑换提供报价 — 返回使用相同参数的 build_swap 可获得的实时 amountOut，以及应用 slippageBps 后的 amountOutMin，可直接传入 build_swap。	始终需要
plan_position	只读。 将人类可读的价格范围和数量转换为对齐的刻度值和 wei 数量，供 build_mint 使用。通过 RPC 读取代币精度。	始终需要
get_pool_state	只读。 实时池状态（刻度值、sqrtPriceX96、人类可读价格、间距）；可选提供 ±pct 范围建议（向内取整），并根据实时比例和钱包余额提供 amount0Desired/amount1Desired。	始终需要
get_positions	只读。 通过 NFPM 的 ERC-721 枚举功能，列出钱包持有的所有头寸 NFT（token0/1、费用、刻度范围、流动性、欠款代币）。	始终需要

编码本身是离线的：build_mint、build_increase、build_wrap、build_swap 和 build_collect（使用 simulate: false）会在不访问网络的情况下生成 calldata。只有链上 读取需要可访问的 RPC 端点 — 每条链都内置了公共默认端点，因此无论是否配置都可以使用（如需覆盖，请参阅配置）。

simulate 会运行选择启用的 eth_call 试运行：对于 collect/close，默认开启；对于 mint/increase，默认关闭（它们需要授权和余额，因此试运行通常会回滚）；对于 wrap/swap/approve， 传入 sender（签名钱包）时会进行模拟。模拟回滚时会返回错误 — 不要签署未通过模拟的交易。试运行 成功时，响应还会包含 simulationResult — 即调用实际解码后的返回值（例如， build_collect/build_close 返回 {amount0, amount1}，build_mint 返回 {tokenId, liquidity, amount0, amount1}，build_approve 返回 {approved}），而不仅仅是 simulated: true 标记。build_wrap/build_swap 通过 Universal Router 的 execute 执行，该方法没有返回值， 因此它们只会报告 simulated。完整的参数参考和头寸生命周期说明，请参阅配套技能。

安装和运行

从 npm 安装（无需克隆，使用 MCP 客户端启动时采用的 stdio 传输）：

npx -y @yummybait/uniswap-tx-builder-mcp

从源码安装：

npm install
npm run dev                 # stdio MCP from source via tsx
npm run build && npm start  # compile to dist/, then run the built server
npm test                    # vitest

设置 MCP_HTTP_PORT，即可使用可流式传输的 HTTP 传输，而不是 stdio（端点： http://<host>:<port>/mcp）。HTTP 以无状态模式运行——每个 POST 请求都会创建一对全新的服务和传输，因此任意数量的客户端都可以自由连接和重新连接，无需管理会话：

MCP_HTTP_PORT=8102 npm run dev

Docker — 在本地构建，或从 GHCR 拉取已发布的镜像：

docker build -t uniswap-tx-builder-mcp:local .                        # local build
docker pull ghcr.io/yummybait-fin/uniswap-tx-builder-mcp:latest       # released image

docker run -i --rm uniswap-tx-builder-mcp:local                       # stdio
docker run --rm -p 8102:8102 -e MCP_HTTP_PORT=8102 uniswap-tx-builder-mcp:local  # HTTP

连接到 MCP 客户端

Claude Code（通过 npm 使用 stdio）：

claude mcp add uniswap-tx-builder -- npx -y @yummybait/uniswap-tx-builder-mcp

通用客户端配置（Claude Desktop 等）——添加到客户端的 mcpServers 中：

{
  "mcpServers": {
    "uniswap-tx-builder": {
      "command": "npx",
      "args": ["-y", "@yummybait/uniswap-tx-builder-mcp"],
      "env": { "RPC_ETH": "https://your-eth-rpc" }
    }
  }
}

（若使用本地构建，请将命令替换为 node /abs/path/to/uniswap-tx-builder-mcp/dist/mcp.js。）

对于 HTTP，使用 MCP_HTTP_PORT 运行服务，并让客户端连接到 http://<host>:<port>/mcp。

安装配套技能

skills/uniswap-tx-builder/ 是一项通用 Agent 技能（不包含针对特定应用或钱包的知识），用于教会 Agent 如何使用这些工具：参数参考、先模拟、close→mint 再平衡顺序，以及“由你的钱包签名”的交接流程。它与 MCP 配套使用——请同时安装两者。选择适合你的安装方式。

A. Claude Code 插件（/plugin）——此仓库同时也是一个插件市场：

/plugin marketplace add Yummybait-fin/uniswap-tx-builder-mcp
/plugin install uniswap-tx-builder@yummybait

B. npx——将技能复制到技能目录（无需克隆）：

# personal (~/.claude/skills, every project)
npx -p @yummybait/uniswap-tx-builder-mcp uniswap-tx-builder-skill

# or project-scoped (./.claude/skills, checked in with a repo)
npx -p @yummybait/uniswap-tx-builder-mcp uniswap-tx-builder-skill --project

C. 手动复制——直接从检出目录复制：

cp -r skills/uniswap-tx-builder ~/.claude/skills/                       # personal
mkdir -p .claude/skills && cp -r skills/uniswap-tx-builder .claude/skills/  # project

Agent 会通过其 SKILL.md frontmatter 识别技能——项目技能无需重启即可生效。

配置

各链的 RPC 默认使用公共端点；可通过环境变量覆盖（参见 src/config.ts）：

链	ID	RPC 环境变量
Ethereum	1	RPC_ETH
Optimism	10	RPC_OP
Polygon	137	RPC_POLYGON
Base	8453	RPC_BASE
Arbitrum	42161	RPC_ARB

公共 RPC 有速率限制，且尽力提供服务——除非只是偶尔使用，否则请设置自己的 RPC。

架构

只使用一条代码路径，并将传输层分离，以便进行测试并为未来的 v4 工具集做好准备：

builder.ts     calldata + unsigned-RLP encoding (viem), position/pool reads
ticks.ts       pure tick / sqrt-price / liquidity math (no I/O)
operations.ts  build + optional eth_call simulate + response shaping
server.ts      the MCP tool surface (schemas, registration, logging)
mcp.ts         transport bootstrap (stdio / stateless streamable HTTP)

CI / 发布

GitHub Actions（.github/workflows/）：

• CI——每次推送到 main 以及每个 PR 时，都会执行类型检查、测试和 npm 压缩包允许列表检查。
• 发布——推送 v* 标签后，会重新运行测试，将 main 上的版本号更新为与标签一致（package.json + .claude-plugin/plugin.json），附带来源证明发布 npm 包（@yummybait/uniswap-tx-builder-mcp），并构建 Docker 镜像并发布到 GHCR（ghcr.io/yummybait-fin/uniswap-tx-builder-mcp），标签为版本号（以及 latest）。该标签是两个产物共用的唯一版本来源；版本号更新会在打标签后提交到 main，因此带标签的提交仍保留旧版本号。

git tag v0.3.0 && git push origin v0.3.0   # cut a release

npm 供应链安全态势

npm 发布任务已加固；修改时请保留以下特性：

• 可信发布（OIDC） — CI 中不使用长期有效的 npm 令牌。在 npmjs.com 的 package → Settings → Trusted publisher 下配置（GitHub Actions、本仓库、release.yml）。 工作流中的 NPM_TOKEN 密钥路径 仅用于引导首次发布（软件包尚不存在时无法配置可信发布者）——之后请删除该密钥，并将软件包的发布访问权限设置为 "Require two-factor authentication and disallow tokens"。
• 来源证明 — publishConfig.provenance: true 会附加 Sigstore 证明，将每个已发布的 tarball 与确切的工作流运行记录和提交关联起来。它也会导致意外的本地 npm publish 失败（CI 外没有 OIDC）。使用 npm audit signatures 验证。
• 发布前门禁 — npm audit signatures（注册表提供的依赖树证明）、npm audit --omit=dev --audit-level=high（已发布的依赖中没有已知的高危／严重漏洞）、类型检查和完整测试套件（prepublishOnly），以及 scripts/verify-tarball.mjs（tarball 必须只包含允许列表中的文件，不得包含密钥或多余文件）。
• 加固的任务 — npm ci --ignore-scripts（不在发布凭据所在环境中运行依赖项的 postinstall 脚本）、每个任务仅授予最低限度的权限、将 actions 固定到提交 SHA，并由 Dependabot 确保固定项和依赖项保持最新。

范围

上述链上的 Uniswap v3 NonfungiblePositionManager。调用未配置的链会返回 "Unsupported chain" 错误。路线图：将 Uniswap v4 作为单独的一组工具，与这些工具并列提供。