Skip to main content
Glama
Yummybait-fin

uniswap-tx-builder

by Yummybait-fin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

uniswap-tx-builder-mcp

CI coverage npm version node license OpenSSF Scorecard

A keyless MCP 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:

Related MCP server: MCP Wallet Signer

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 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):

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

From source:

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:

MCP_HTTP_PORT=8102 npm run dev

Docker — build locally, or pull a released image from 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

Connect to an MCP client

Claude Code (stdio via npm):

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:

{
  "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:

/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):

# 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:

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.

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.

Available Tools

8 tools
build_closeBuild a close-position transactionA

Build an UNSIGNED tx that removes all liquidity and collects everything from a Uniswap v3 position (multicalls when needed). Returns the tx (+ unsigned rlp) plus the read position. Set burn=true to also burn the now-empty NFT in the same multicall. Set simulate=false to skip the eth_call dry-run (on by default).

ParametersJSON Schema
NameRequiredDescriptionDefault
burnNo
chainIdYes
simulateNo
recipientYes
positionIdYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description covers key behavioral aspects: it builds an unsigned transaction (non-executing), removes liquidity, multicalls when needed, returns tx+unsigned rlp+read position, and explains burn and simulate options. It could mention that it does not execute the transaction, but 'unsigned' implies that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at two sentences plus a third for details. Main purpose is front-loaded, and every sentence adds value. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description mentions return values (tx+rlp+read position). It covers the tool's core functionality, multicall behavior, and optional parameters. However, it omits descriptions for three parameters (chainId, recipient, positionId), leaving gaps for a complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning for 2 of 5 parameters (burn, simulate) but does not describe chainId, recipient, or positionId beyond their existence. Since schema description coverage is 0%, the description should compensate more for the undocumented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it builds an unsigned transaction to remove all liquidity and collect everything from a Uniswap v3 position. This distinguishes it from sibling tools like build_collect (collect fees), build_increase (add liquidity), build_mint (create position), etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for closing a position but does not explicitly state when to use or not use this tool versus alternatives. It mentions optional parameters (burn, simulate) but no context for choosing this over sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

build_collectBuild a collect-fees transactionA

Build an UNSIGNED tx that collects all uncollected fees from a Uniswap v3 position to recipient. Returns tx={to,data,value,chainId} plus rlp (the unsigned EIP-1559 serialization for signing services). Set simulate=false to skip the eth_call dry-run (on by default).

ParametersJSON Schema
NameRequiredDescriptionDefault
chainIdYes
simulateNo
recipientYes
positionIdYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description effectively discloses that the transaction is unsigned, returns specific fields, and includes a simulate parameter to skip dry-run. It does not cover authorization or side effects, but the core behavior is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with the main purpose front-loaded. Every word adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains the return format (to, data, value, chainId, rlp) and the simulate parameter. It covers key aspects, though it could mention permission requirements or state changes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It explains recipient and simulate, but chainId and positionId are not described beyond their names, which are self-explanatory but lack constraints or format details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool builds an unsigned transaction to collect uncollected fees from a Uniswap v3 position, clearly distinguishing it from sibling tools like build_mint or build_swap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for fee collection but lacks explicit guidance on when to use this tool versus alternatives or any prerequisites. No exclusion criteria are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

build_increaseBuild an increase-liquidity transactionA

Build an UNSIGNED tx that adds liquidity to an EXISTING Uniswap v3 position. Amounts are decimal strings (wei); mins are derived from slippageBps (default 0.5%). Returns the tx plus unsigned rlp. Simulation is OFF by default (needs token approvals + balances); pass simulate=true to attempt it.

ParametersJSON Schema
NameRequiredDescriptionDefault
chainIdYes
simulateNo
recipientYes
positionIdYes
slippageBpsNo
amount0DesiredYes
amount1DesiredYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses that the transaction is unsigned, simulation is off by default, and prerequisites (approvals + balances) for simulation. Does not mention error handling or gas estimation, but key behavioral traits are covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, tightly packed with essential information: purpose, parameter format, default behavior, simulation option. No redundant or superfluous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters and no output schema, the description covers purpose, parameter format, default slippage, simulation behavior, and return type (tx plus rlp). Could be more thorough on parameter constraints (e.g., positionId must exist, chainId must be valid), but overall sufficient for basic usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It explains that amount0Desired and amount1Desired are decimal strings in wei, and that slippageBps determines mins with a default. However, other parameters like chainId, positionId, and recipient are not described beyond the schema, leaving gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it builds an unsigned transaction to add liquidity to an existing Uniswap v3 position. The verb 'build' and resource 'increase-liquidity' are specific and distinct from sibling tools like 'build_mint' or 'build_close'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: adds liquidity to an existing position, amounts in wei, mins derived from slippageBps with default 0.5%, simulation off by default. Lacks explicit comparison to siblings or when-not-to-use, but the purpose is sufficiently differentiated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

build_mintBuild a mint-position transactionA

Build an UNSIGNED tx that mints a new Uniswap v3 position. Amounts are decimal strings (wei) — compute them with get_pool_state (live ratio) right before minting, or stale prices revert the mint. Returns the tx plus unsigned rlp. Simulation is OFF by default here (minting needs token approvals and balances, so eth_call usually reverts); pass simulate=true to attempt it.

ParametersJSON Schema
NameRequiredDescriptionDefault
feeYes
token0Yes
token1Yes
chainIdYes
simulateNo
recipientYes
tickLowerYes
tickUpperYes
slippageBpsNo
amount0DesiredYes
amount1DesiredYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the tx is unsigned, amounts are decimal strings (wei), simulation is off by default because minting needs approvals and balances, and that passing simulate=true attempts simulation. It also mentions the return includes the tx and unsigned rlp. This provides significant behavioral context, though it could further describe potential reverts or authorization needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with only two sentences. The first sentence states the primary purpose, and the second adds critical details about amounts, simulation, and return value. Every sentence earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 11 parameters, no output schema, and no annotations, the description covers key behaviors (stale prices, simulation) and references get_pool_state. However, it omits details on tick lower/upper format, fee tier interpretation, token ordering, slippageBps meaning, and return structure beyond 'tx plus unsigned rlp'. This leaves the agent needing additional context for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains amount0Desired and amount1Desired are decimal strings (wei) and simulate is a boolean. However, it does not describe token0, token1, fee, tickLower, tickUpper, recipient, chainId, or slippageBps. Many parameters remain undocumented, leaving gaps for correct usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Build an UNSIGNED tx that mints a new Uniswap v3 position.' It specifies the verb (build), resource (unsigned tx), and domain (Uniswap v3 mint). The title reinforces the purpose, and it differentiates from sibling tools like build_close, build_collect, and get_pool_state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use the tool: amounts must be wei strings computed with get_pool_state right before minting to avoid stale prices. It also explains that simulation is off by default and when to pass simulate=true. However, it does not explicitly state when not to use this tool or compare it directly to alternatives like plan_position.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

build_swapBuild a WETH→token swap transaction (Universal Router)A

Build an UNSIGNED tx that swaps amountInWei WETH for tokenOut (exact-in, single hop through the fee pool) via the Universal Router. With wrapWei (≥ amountInWei) the tx is payable and wraps that much native ETH first, swaps amountInWei of it, and sweeps the WETH remainder — use this when the wallet holds native ETH. Without wrapWei the wallet's WETH pays via Permit2 (needs a Permit2 approval). recipient defaults to the tx sender. Returns the tx plus unsigned rlp. Pass sender to eth_call-simulate before signing.

ParametersJSON Schema
NameRequiredDescriptionDefault
feeYes
senderNo
chainIdYes
wrapWeiNo
deadlineNo
simulateNo
tokenOutYes
recipientNo
amountInWeiYes
amountOutMinYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses that the tx is unsigned, explains the swap mechanics (exact-in, single hop), wrap behavior, and simulation hint. Lacks details on gas implications or failure modes but is sufficiently transparent for common use.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is a single dense paragraph that front-loads the main purpose. Every sentence adds value, but could benefit from structuring (e.g., separate sections for parameters, return value). Efficient for its information density.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 10 parameters, no annotations, no output schema, the description provides a good overview of functionality and key parameters. It explains the core flow but lacks details on return format and some parameters. Still adequate for an experienced agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It explains key parameters (amountInWei, tokenOut, fee, wrapWei, recipient, sender) and their roles. Missing explicit details for chainId, deadline, simulate, and amountOutMin, but the given context adds significant value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the tool builds an unsigned transaction for a WETH→token exact-in single-hop swap via Universal Router. It identifies the key resources (WETH, tokenOut, fee pool) and distinguishes from sibling tools by focusing on this specific swap operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear guidance on when to use wrapWei vs not (native ETH vs WETH via Permit2) and mentions recipient defaults to sender. However, it does not explicitly compare against sibling tools or state when to choose this tool over alternatives like build_close or build_mint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

build_wrapBuild a wrap-native-ETH transaction (Universal Router)B

Build an UNSIGNED payable tx that wraps amountWei native ETH into WETH via the Universal Router WRAP_ETH command (works under UR-allowlisting wallet policies where a direct WETH.deposit() doesn't). recipient defaults to the tx sender — omit it unless the WETH should go elsewhere. Returns the tx plus unsigned rlp. Pass sender (the signing wallet) to eth_call-simulate before signing.

ParametersJSON Schema
NameRequiredDescriptionDefault
senderNo
chainIdYes
deadlineNo
simulateNo
amountWeiYes
recipientNo

TDQS

B3.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that the transaction is unsigned and payable, returns the tx and unsigned rlp, and recommends simulation with sender. It does not mention side effects (none expected for building an unsigned tx), which is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with three sentences, front-loading the primary purpose. It avoids fluff but could be slightly more structured by listing key parameters. Overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (6 params, no output schema, no annotations), the description covers the main function and key behaviors but leaves several parameters unexplained. It is adequate but not fully complete; an agent would need additional context for chainId, deadline, and simulate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, so the description must compensate. It explains amountWei, recipient (default to sender), and sender (for simulation), but omits chainId, deadline, and simulate. Critical parameters remain undocumented, leaving significant gaps for the agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool builds an unsigned transaction that wraps ETH into WETH via the Universal Router, specifying the verb 'build' and the resource. It distinguishes itself by mentioning the Universal Router allowlisting context, but does not explicitly contrast with sibling tools like build_swap or build_mint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides usage context: it works under UR-allowlisting policies and suggests passing sender for simulation. However, it lacks explicit guidance on when not to use this tool or clear differentiation from alternatives, leaving some ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pool_stateRead live pool state; plan a range and mint amounts from itA

READ-ONLY (builds no tx). Returns the pool's LIVE state: pool address, tick, sqrtPriceX96, price (token1 per token0, human units), tickSpacing. With rangePct: suggested tickLower/tickUpper within ±pct of spot, rounded INWARD to tick spacing. With balance0+balance1 (raw wei) + tickLower/tickUpper: amount0Desired/amount1Desired for build_mint computed from the live sqrtPrice ratio, plus which side limits. Errors if spot is outside the range. ALWAYS recompute amounts with this right before build_mint — stale ratios revert with 'Price slippage check'.

ParametersJSON Schema
NameRequiredDescriptionDefault
feeYes
token0Yes
token1Yes
chainIdYes
balance0No
balance1No
rangePctNo
tickLowerNo
tickUpperNo

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Explicitly declares read-only ('builds no tx') and mentions error conditions. With no annotations, this carries the full burden acceptably.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with read-only indicator, each sentence adds value. Could be slightly more structured but efficient overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers return fields, derived computations, and error condition. No output schema, but description hints sufficiently at what is returned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Explains rangePct, balance0, balance1, tickLower, tickUpper and how they interact to compute amounts. Schema has 0% coverage, so description compensates well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns live pool state and lists specific fields (pool address, tick, etc.). It is distinct from sibling build tools which are transactional.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to recompute before build_mint, giving a clear use case. Does not specify when not to use, but the read-only nature is obvious.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

plan_positionPlan a position from a human price rangeA

READ-ONLY helper (builds no tx). Given a human price range (token1 per token0) and optional human token amounts, reads each token's decimals over RPC and returns the aligned tickLower/tickUpper (for the fee's tick spacing) plus wei amount0Desired/amount1Desired — ready to feed into build_mint. token0 must be < token1 by address. Does NOT compute the optimal amount ratio for the range.

ParametersJSON Schema
NameRequiredDescriptionDefault
feeYes
token0Yes
token1Yes
amount0No
amount1No
chainIdYes
priceLowerYes
priceUpperYes

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fully discloses behavioral traits: read-only, reads decimals over RPC, returns aligned ticks and amounts, requires token0 < token1 by address, and does not compute optimal ratio. This provides comprehensive behavioral information.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, starting with a clear label 'READ-ONLY helper' and providing all essential information in a few sentences without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (8 parameters, no output schema, no annotations), the description covers the main purpose, inputs, outputs, and constraints. It could be slightly more complete by explaining what happens when amounts are omitted or mentioning the RPC requirement, but it is largely sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description bears the burden. It explains the meaning of priceLower, priceUpper as human price range, token0/token1 address constraint, and optional amount0/amount1. However, it does not describe fee or chainId explicitly beyond mentioning 'fee's tick spacing'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: a read-only helper that computes tick and amount parameters for a Uniswap V3 position from a human price range. It distinguishes itself from siblings like build_mint by noting it builds no transaction itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly notes it is a 'READ-ONLY helper (builds no tx)' and 'ready to feed into build_mint', providing clear context for when to use it. However, it does not explicitly state when not to use it or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv0.3.2
    • First observedbuild_close
    • First observedbuild_collect
    • First observedbuild_increase
    • First observedbuild_mint
    • First observedbuild_swap
    • First observedbuild_wrap
    • First observedget_pool_state
    • First observedplan_position
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 8 tools

Disambiguation5/5

Each tool targets a distinct Uniswap v3 action or query: mint, increase, collect, close, swap, wrap, plus state helpers. No functional overlap.

Naming Consistency5/5

All transaction builders follow 'build_' prefix, read-only helpers use 'get_' and 'plan_'. Consistent verb-noun pattern.

Tool Count5/5

8 tools is well-scoped for a Uniswap tx builder covering essential operations and state queries without bloat.

Completeness5/5

Covers full lifecycle: position creation (mint), modification (increase/collect), removal (close with optional burn), swapping, wrapping, and state queries. No obvious gaps.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers