Uniswap Tx Builder

uniswap-tx-builder-mcp

キー不要のMCPサーバーで、Uniswap v3の流動性ポジション取引を未署名の状態で構築し、必要に応じてeth_callでシミュレーションします。キーを保持せず、署名もしません。返されたcalldataを受け取り、ご自身のウォレット（viem、CDPウォレットMCP、その他の署名ツール）で署名してブロードキャストしてください。

キー不要のため、構築した取引に適用される制限はご自身のウォレットの制限のみです。サーバーの脅威対象は「calldataを返し、公開RPCを読み取ること」だけです。

エコシステム

Yummybaitの一部です。

• cdp-wallet-agent-example — Coinbase CDPウォレットを署名ツールとして、このMCPを操作するリファレンスエージェントです。
• yummybait.finance — これらのツールが支える製品です。

ツール

すべての構築ツールは、tx = { to, data, value, chainId }に加えて、txの未署名EIP-1559（type-2）シリアライズであるrlpを返します。nonce、手数料、gasはゼロに設定されています（CDP APIなどの署名サービスがこれらを設定します。nonceを管理する場合は、txを自分でシリアライズしてください）。また、人が読めるdescriptionも返します。valueは、payableなUniversal Routerのwrap/swap構築を除いて"0"です。アドレスは0x…40形式で、positionIdと金額は10進数の文字列です（JavaScriptの安全な整数の上限を超えるため）。

ツール	用途	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 支払い経路で使用許可の不足が自動検出され、トランザクションの代わりに署名済み Permit のリクエストが返されるため、オンチェーンで別途 Permit2 の使用許可を行う必要はありません。	sender を指定した場合のみ（ドライランが有効になります）
get_swap_quote	読み取り専用。 Uniswap v3 QuoterV2 を使って、完全入力型のシングルホップスワップを見積もります。同じパラメーターで build_swap を実行した場合の現在の amountOut と、build_swap にそのまま渡せる amountOutMin（slippageBps 適用後）を返します。	常に必要
plan_position	読み取り専用。 人間向けの価格範囲と金額を、build_mint 用の調整済みティック値と wei 額に変換します。RPC 経由でトークンの小数桁数を読み取ります。	常に必要
get_pool_state	読み取り専用。 プールの現在の状態（ティック、sqrtPriceX96、人間向けの価格、間隔）を返します。オプションで、±％の範囲候補（内側に丸めた値）と、ウォレット残高から算出した現在の比率に基づく 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 を渡すとシミュレーションを実行します。シミュレーションがリバートした場合はエラーが返されます。シミュレーションに失敗したトランザクションには署名しないでください。ドライランが成功すると、レスポンスには simulated: true フラグだけでなく、呼び出しの実際のデコード済み戻り値である simulationResult も含まれます（例：build_collect／build_close では {amount0, amount1}、build_mint では {tokenId, liquidity, amount0, amount1}、build_approve では {approved}）。build_wrap／build_swap は Universal Router の execute を経由しますが、これは戻り値がないため、simulated のみを返します。引数の全リファレンスとポジションのライフサイクルについては、関連スキルを参照してください。

インストールと実行

npm から（クローン不要、stdio トランスポート — MCP クライアントが起動します）：

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 を設定すると、stdio の代わりにストリーマブル HTTP トランスポートを提供します（エンドポイント： 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/ は汎用エージェントスキルです（アプリやウォレット固有の知識は不要）。このツールの使い方（引数のリファレンス、まずシミュレーションすること、クローズ→ミントのリバランス手順、「ウォレットで署名する」引き継ぎ）をエージェントに教えます。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

エージェントは SKILL.md のフロントマターをもとにスキルを認識するため、プロジェクトスキルの場合、再起動は不要です。

設定

チェーンごとの 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 を設定してください。

アーキテクチャ

コードパスは 1 つで、トランスポートは分離されているため、テスト可能な状態を維持し、将来の 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 tarball の許可リストチェックを実行します。
• リリース — 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 により、公開される各 tarball を正確なワークフロー実行およびコミットに結び付ける Sigstore アテステーションが付与されます。また、誤ってローカルで 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 を実行しない）、ジョブごとの最小権限、コミット SHA に固定されたアクション、Dependabot による固定バージョンと依存関係の最新状態の維持。

対象範囲

上記のチェーンにおける Uniswap v3 NonfungiblePositionManager が対象です。未設定のチェーンを呼び出すと、"Unsupported chain" エラーが返されます。ロードマップでは、Uniswap v4 をこれらと並行する独立したツールセットとして追加する予定です。