# uniswap-tx-builder-mcp

[![CI](https://github.com/Yummybait-fin/uniswap-tx-builder-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Yummybait-fin/uniswap-tx-builder-mcp/actions/workflows/ci.yml)
[![coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FYummybait-fin%2Funiswap-tx-builder-mcp%2Fbadges%2Fcoverage.json)](https://github.com/Yummybait-fin/uniswap-tx-builder-mcp/actions/workflows/coverage-badge.yml)
[![npm version](https://img.shields.io/npm/v/%40yummybait%2Funiswap-tx-builder-mcp)](https://www.npmjs.com/package/@yummybait/uniswap-tx-builder-mcp)
[![node](https://img.shields.io/node/v/%40yummybait%2Funiswap-tx-builder-mcp)](https://www.npmjs.com/package/@yummybait/uniswap-tx-builder-mcp)
[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Yummybait-fin/uniswap-tx-builder-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/Yummybait-fin/uniswap-tx-builder-mcp)

A **keyless** [MCP](https://modelcontextprotocol.io) server that builds *unsigned* Uniswap v3
liquidity-position transactions and optionally simulates them via `eth_call`. **It never holds
keys and never signs** — you take the returned calldata and sign + broadcast it with your own
wallet (viem, a CDP wallet MCP, any signer).

Because it's keyless, the only limits that apply to a built tx are *your wallet's* — the server's
threat surface is just "it returns calldata and reads public RPCs."

## Ecosystem

Part of [Yummybait](https://www.yummybait.finance/):

- [`cdp-wallet-agent-example`](https://github.com/Yummybait-fin/cdp-wallet-agent-example) — a
  reference agent that drives this MCP with a Coinbase CDP wallet as the signer.
- [yummybait.finance](https://www.yummybait.finance/) — the product these tools power.

## Tools

Every build tool returns `tx = { to, data, value, chainId }` plus `rlp` — the **unsigned
EIP-1559 (type-2)** serialization of `tx` with nonce/fees/gas zeroed (signing services like the
CDP API populate them; serialize `tx` yourself if you manage nonces) — and a human `description`.
`value` is `"0"` except the payable Universal Router wrap/swap builds. Addresses are `0x…40`;
`positionId` and amounts are decimal **strings** (they exceed JS safe integers).

| Tool | Purpose | Needs RPC? |
|------|---------|------------|
| `build_collect` | Collect all uncollected fees from a position to `recipient`. | Only for the dry-run (on by default; `simulate: false` builds offline) |
| `build_close` | Remove all liquidity **+** collect; `burn: true` also burns the empty NFT. Returns the read position. | **Always** — reads the position first |
| `build_mint` | Mint a new position (raw ticks + wei amounts). | Only with `simulate: true` |
| `build_increase` | Add liquidity to an existing position. | Only with `simulate: true` |
| `build_approve` | Build an ERC-20 `approve(spender, amount)` tx — e.g. the NFPM before `build_mint`/`build_increase`, or Permit2 before a Permit2-paid `build_swap`. `amount: "max"` for an unlimited allowance. | Only with `sender` (enables the dry-run) |
| `build_wrap` | Wrap native ETH → WETH via the Universal Router (`WRAP_ETH`). | Only with `sender` (enables the dry-run) |
| `build_swap` | Exact-in single-hop `tokenIn` → `tokenOut` swap via the Universal Router; with `wrapWei` (tokenIn = WETH9) it wraps native ETH first and sweeps the remainder, with `unwrapOut` (tokenOut = WETH9) it unwraps the output to native ETH — in the same tx either way. Pass `sender` and the default Permit2 payment path auto-detects an insufficient allowance, returning a signed-permit request instead of a tx — no separate on-chain Permit2 approval needed. | Only with `sender` (enables the dry-run) |
| `get_swap_quote` | **Read-only.** Quote an exact-in single-hop swap via Uniswap v3 QuoterV2 — the live `amountOut` a `build_swap` with the same params would get, plus `amountOutMin` (after `slippageBps`) ready to feed straight into `build_swap`. | **Always** |
| `plan_position` | **Read-only.** Turn a human price range + human amounts into aligned ticks + wei amounts for `build_mint`. Reads token decimals over RPC. | **Always** |
| `get_pool_state` | **Read-only.** Live pool state (tick, sqrtPriceX96, human price, spacing); optional ±pct range suggestion (rounded inward) and live-ratio `amount0Desired`/`amount1Desired` from wallet balances. | **Always** |
| `get_positions` | **Read-only.** List every position NFT a wallet holds (token0/1, fee, tick range, liquidity, tokens owed) via the NFPM's ERC-721 enumeration. | **Always** |

Encoding itself is **offline**: `build_mint`, `build_increase`, `build_wrap`, `build_swap`, and
`build_collect` (with `simulate: false`) produce calldata without any network access. Only chain
*reads* need a reachable RPC endpoint — and public defaults are baked in per chain, so nothing has
to be configured either way (see [Configuration](#configuration) to override them).

`simulate` runs an opt-in `eth_call` dry-run: **on by default** for collect/close, **off** for
mint/increase (those need approvals + balances, so the dry-run usually reverts); wrap/swap/approve
simulate when you pass `sender` (the signing wallet). A reverted simulation comes back as an
error — don't sign a tx that failed to simulate. When a dry-run succeeds, the response also
includes `simulationResult` — the actual decoded return value of the call (e.g.
`{amount0, amount1}` for `build_collect`/`build_close`, `{tokenId, liquidity, amount0, amount1}`
for `build_mint`, `{approved}` for `build_approve`) rather than just the `simulated: true` flag.
`build_wrap`/`build_swap` go through the Universal Router's `execute`, which has no return value,
so they only report `simulated`. See the companion skill for the full argument reference and
position lifecycle.

## Install & run

From npm (no clone, stdio transport — what MCP clients spawn):

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

From source:

```bash
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
```

Set `MCP_HTTP_PORT` to serve the streamable-HTTP transport instead of stdio (endpoint:
`http://<host>:<port>/mcp`). HTTP runs **stateless** — every POST gets a fresh server/transport
pair, so any number of clients can connect and reconnect freely with no session bookkeeping:

```bash
MCP_HTTP_PORT=8102 npm run dev
```

Docker — build locally, or pull a released image from GHCR:

```bash
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
```

## Connect to an MCP client

**Claude Code** (stdio via npm):

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

**Generic client config** (Claude Desktop, etc.) — add to the client's `mcpServers`:

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

(For a local build, swap the command for `node /abs/path/to/uniswap-tx-builder-mcp/dist/mcp.js`.)

For HTTP, run the server with `MCP_HTTP_PORT` and point the client at `http://<host>:<port>/mcp`.

## Install the companion skill

`skills/uniswap-tx-builder/` is a generic agent **skill** (no app- or wallet-specific knowledge)
that teaches an agent how to drive these tools: the argument reference, simulate-first, the
close→mint rebalance sequence, and the "your wallet signs" handoff. It pairs with the MCP — install
both. Pick whichever install path suits you.

**A. Claude Code plugin (`/plugin`)** — the repo doubles as a plugin marketplace:

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

**B. npx** — copies the skill into a skills dir (no clone needed):

```bash
# 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. Manual copy** — straight from a checkout:

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

The agent picks it up by its `SKILL.md` frontmatter — no restart needed for project skills.

## Configuration

Per-chain RPCs default to public endpoints; override with env vars (see `src/config.ts`):

| Chain | ID | RPC env var |
|-------|----|-------------|
| Ethereum | 1 | `RPC_ETH` |
| Optimism | 10 | `RPC_OP` |
| Polygon | 137 | `RPC_POLYGON` |
| Base | 8453 | `RPC_BASE` |
| Arbitrum | 42161 | `RPC_ARB` |

Public RPCs are rate-limited and best-effort — set your own for anything beyond casual use.

## Architecture

One code path, transport kept separate so it stays testable and ready for a future v4 tool set:

```
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 / releases

GitHub Actions (`.github/workflows/`):

- **CI** — typecheck + tests + npm-tarball allowlist check on every push to `main` and on PRs.
- **Release** — pushing a `v*` tag re-runs the tests, bumps the version on `main` to match the tag
  (`package.json` + `.claude-plugin/plugin.json`), publishes the npm package
  (`@yummybait/uniswap-tx-builder-mcp`) **with provenance**, and builds + publishes the Docker
  image to GHCR (`ghcr.io/yummybait-fin/uniswap-tx-builder-mcp`), tagged with the version (and
  `latest`). The tag is the single version source for both artifacts; the bump lands on `main`
  after the tag, so the tagged commit keeps its old version.

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

### npm supply-chain posture

The npm publish job is locked down; keep these properties when touching it:

- **Trusted publishing (OIDC)** — no long-lived npm token in CI. Configured on npmjs.com under
  *package → Settings → Trusted publisher* (GitHub Actions, this repo, `release.yml`). The
  `NPM_TOKEN` secret path in the workflow exists **only to bootstrap the first release** (trusted
  publishers can't be configured before the package exists) — delete the secret afterwards and
  set the package's publishing access to *"Require two-factor authentication and disallow
  tokens"*.
- **Provenance** — `publishConfig.provenance: true` attaches a Sigstore attestation linking every
  published tarball to the exact workflow run and commit. It also makes an accidental local
  `npm publish` fail (no OIDC outside CI). Consumers verify with `npm audit signatures`.
- **Gates before publish** — `npm audit signatures` (registry attestations of the dep tree),
  `npm audit --omit=dev --audit-level=high` (no known high/critical vulns in shipped deps),
  typecheck + full test suite (`prepublishOnly`), and `scripts/verify-tarball.mjs` (the tarball
  must contain exactly the allowlisted files — no secrets, no strays).
- **Hardened job** — `npm ci --ignore-scripts` (no dependency postinstall runs where publish
  credentials live), minimal per-job permissions, actions pinned to commit SHAs, Dependabot
  keeping pins and deps fresh.

## Scope

Uniswap v3 `NonfungiblePositionManager` on the chains above. Calling an unconfigured chain returns
an "Unsupported chain" error. Roadmap: Uniswap v4 as a separate set of tools alongside these.