@moly-mcp/lido 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# @moly-mcp/lido
+
+MCP server for Lido — stake, unstake, wrap, bridge, and govern directly from any MCP-compatible AI client (Claude Desktop, Cursor, etc.).
+
+Runs on Bun. Supports Holesky testnet (simulation mode) and Ethereum mainnet (live mode).
+
+---
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `get_balance` | ETH, stETH, wstETH balances + staking APR |
+| `get_rewards` | Reward history over N days |
+| `get_conversion_rate` | Current stETH / wstETH exchange rate |
+| `stake_eth` | Stake ETH to receive stETH |
+| `request_withdrawal` | Queue stETH withdrawal back to ETH |
+| `claim_withdrawals` | Claim finalized withdrawal requests |
+| `get_withdrawal_requests` | List pending withdrawal request IDs |
+| `get_withdrawal_status` | Check finalization status of requests |
+| `wrap_steth` | Wrap stETH into wstETH |
+| `unwrap_wsteth` | Unwrap wstETH back to stETH |
+| `get_proposals` | List recent Lido DAO governance proposals |
+| `get_proposal` | Get details on a specific proposal |
+| `cast_vote` | Vote YEA / NAY on a DAO proposal |
+| `get_l2_balance` | ETH + wstETH balances on Base or Arbitrum |
+| `get_bridge_quote` | Quote for bridging from L2 to L1 via LI.FI |
+| `bridge_to_ethereum` | Execute L2 to L1 bridge via LI.FI |
+| `get_bridge_status` | Track an in-progress bridge transaction |
+
+---
+
+## Modes
+
+| Mode | Network | Default for write ops |
+|---|---|---|
+| `simulation` | Holesky testnet | `dry_run: true` (no real txs) |
+| `live` | Ethereum mainnet | `dry_run: false` (real txs) |
+
+Set `LIDO_MODE=simulation` (default) to experiment safely. Set `LIDO_MODE=live` for mainnet.
+
+---
+
+## Setup
+
+**1. Copy env file**
+
+```bash
+cp .env.example .env
+```
+
+**2. Fill in `.env`**
+
+```env
+LIDO_MODE=simulation         # or "live" for mainnet
+PRIVATE_KEY=0x...            # wallet private key
+HOLESKY_RPC_URL=...          # optional, has public fallback
+MAINNET_RPC_URL=...          # optional, has public fallback
+REFERRAL_ADDRESS=0x...       # optional
+```
+
+**3. Install dependencies**
+
+```bash
+bun install
+```
+
+**4. Run**
+
+```bash
+bun run start
+```
+
+---
+
+## Claude Desktop Config
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "lido": {
+      "command": "bunx",
+      "args": ["@moly-mcp/lido"],
+      "env": {
+        "LIDO_MODE": "simulation",
+        "PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+---
+
+## Source Structure
+
+```
+src/
+  index.ts          entry point
+  server.ts         MCP server setup
+  config.ts         env config + chain constants
+  sdk.ts            Lido SDK singleton
+  wallet.ts         viem wallet + L2 client helpers
+  tools/
+    index.ts        tool registration
+    balance.ts      get_balance, get_rewards
+    stake.ts        stake_eth
+    unstake.ts      request_withdrawal, claim_withdrawals, get_withdrawal_*
+    wrap.ts         wrap_steth, unwrap_wsteth, get_conversion_rate
+    governance.ts   get_proposals, get_proposal, cast_vote
+    bridge.ts       get_l2_balance, get_bridge_*, bridge_to_ethereum
+```
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@moly-mcp/lido",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MCP server for Lido — stake, unstake, wrap, bridge, and govern from any MCP-compatible AI client",
+  "bin": {
+    "lido-mcp": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "start": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@lidofinance/lido-ethereum-sdk": "^3.4.0",
+    "@modelcontextprotocol/sdk": "^1.10.1",
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}

package/src/config.ts

@@ -0,0 +1,48 @@
+import { holesky, mainnet, base, arbitrum } from 'viem/chains';
+import type { Chain } from 'viem';
+
+export type Mode = 'simulation' | 'live';
+export type L2Chain = 'base' | 'arbitrum';
+
+const mode = (process.env.LIDO_MODE ?? 'simulation') as Mode;
+
+if (mode !== 'simulation' && mode !== 'live') {
+  throw new Error(`LIDO_MODE must be "simulation" or "live", got: ${mode}`);
+}
+
+export const config = {
+  mode,
+  isSimulation: mode === 'simulation',
+  chain: mode === 'simulation' ? holesky : mainnet,
+  chainId: mode === 'simulation' ? 17000 : 1,
+  rpcUrl:
+    mode === 'simulation'
+      ? (process.env.HOLESKY_RPC_URL ?? 'https://ethereum-holesky-rpc.publicnode.com')
+      : (process.env.MAINNET_RPC_URL ?? 'https://eth.llamarpc.com'),
+  referralAddress: (process.env.REFERRAL_ADDRESS ?? '0x0000000000000000000000000000000000000000') as `0x${string}`,
+};
+
+export interface L2ChainConfig {
+  chainId: number;
+  name: string;
+  defaultRpc: string;
+  viemChain: Chain;
+  wstETH: `0x${string}`;
+}
+
+export const L2_CHAINS: Record<L2Chain, L2ChainConfig> = {
+  base: {
+    chainId: 8453,
+    name: 'Base',
+    defaultRpc: 'https://mainnet.base.org',
+    viemChain: base,
+    wstETH: '0xc1CBa3fCea344f92D9239c08C0568f6F2F0ee452',
+  },
+  arbitrum: {
+    chainId: 42161,
+    name: 'Arbitrum One',
+    defaultRpc: 'https://arb1.arbitrum.io/rpc',
+    viemChain: arbitrum,
+    wstETH: '0x5979D7b546E38E9Ab8049dCFAc0B5D35A8De3f6e',
+  },
+};

package/src/index.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+
+const { server, modeNote } = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`Lido MCP server started — ${modeNote}`);

package/src/sdk.ts

@@ -0,0 +1,23 @@
+import { LidoSDK } from '@lidofinance/lido-ethereum-sdk';
+import { createPublicClient, http } from 'viem';
+import { config } from './config.js';
+
+const publicClient = createPublicClient({
+  chain: config.chain,
+  transport: http(config.rpcUrl),
+});
+
+let _sdk: LidoSDK | null = null;
+
+export function getSDK(): LidoSDK {
+  if (_sdk) return _sdk;
+
+  _sdk = new LidoSDK({
+    chainId: config.chainId as 1 | 17000,
+    rpcProvider: publicClient,
+  });
+
+  return _sdk;
+}
+
+export { publicClient };

package/src/server.ts

@@ -0,0 +1,18 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { config } from './config.js';
+import { registerTools } from './tools/index.js';
+
+export function createServer() {
+  const modeNote = config.isSimulation
+    ? 'SIMULATION MODE (Holesky) — write operations are dry_run by default'
+    : 'LIVE MODE (Mainnet) — real transactions will be broadcast';
+
+  const server = new McpServer({
+    name: 'lido-mcp',
+    version: '0.1.0',
+  });
+
+  registerTools(server, modeNote);
+
+  return { server, modeNote };
+}

package/src/tools/balance.ts

@@ -0,0 +1,50 @@
+import { formatEther } from 'viem';
+import { getSDK } from '../sdk.js';
+import { getAddress } from '../wallet.js';
+import { config } from '../config.js';
+
+export async function getBalance(address?: string) {
+  const sdk = getSDK();
+  const addr = (address ?? getAddress()) as `0x${string}`;
+
+  const [eth, steth, wsteth] = await Promise.all([
+    sdk.core.balanceETH(addr),
+    sdk.steth.balance(addr),
+    sdk.wsteth.balance(addr),
+  ]);
+
+  return {
+    address: addr,
+    mode: config.mode,
+    network: config.chain.name,
+    balances: {
+      eth: formatEther(eth),
+      stETH: formatEther(steth),
+      wstETH: formatEther(wsteth),
+    },
+    // APR fetched from protocol stats
+  };
+}
+
+export async function getRewards(address?: string, days = 7) {
+  const sdk = getSDK();
+  const addr = (address ?? getAddress()) as `0x${string}`;
+
+  const rewards = await sdk.rewards.getRewardsFromChain({
+    address: addr,
+    stepBlock: 1000,
+    back: { days },
+  });
+
+  return {
+    address: addr,
+    period: `${days} days`,
+    totalRewards: formatEther(rewards.totalRewards ?? 0n),
+    totalStaked: formatEther(rewards.totalStaked ?? 0n),
+    events: rewards.events?.slice(0, 10).map((e: any) => ({
+      type: e.type,
+      change: formatEther(e.change ?? 0n),
+      balance: formatEther(e.balance ?? 0n),
+    })),
+  };
+}

package/src/tools/bridge.ts

@@ -0,0 +1,186 @@
+import { formatEther, parseEther, parseAbi, type Hex } from 'viem';
+import { config, L2_CHAINS } from '../config.js';
+import type { L2Chain } from '../config.js';
+import { getAddress, getL2Wallet, getL2PublicClient } from '../wallet.js';
+
+const LIFI_BASE = 'https://li.quest/v1';
+
+const ERC20_ABI = parseAbi([
+  'function balanceOf(address) view returns (uint256)',
+  'function allowance(address owner, address spender) view returns (uint256)',
+  'function approve(address spender, uint256 amount) returns (bool)',
+]);
+
+const NATIVE_TOKEN = '0x0000000000000000000000000000000000000000' as const;
+const L1_WSTETH = '0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0' as const;
+
+type BridgeToken = 'ETH' | 'wstETH';
+
+function tokenAddress(chain: L2Chain, token: BridgeToken): `0x${string}` {
+  if (token === 'ETH') return NATIVE_TOKEN;
+  return L2_CHAINS[chain].wstETH;
+}
+
+function toTokenAddress(toToken?: string): `0x${string}` {
+  if (!toToken || toToken === 'ETH') return NATIVE_TOKEN;
+  return L1_WSTETH;
+}
+
+function ensureMainnet() {
+  if (config.isSimulation) {
+    throw new Error('Bridge tools only work in live mode (mainnet). LI.FI does not support testnets.');
+  }
+}
+
+export async function getL2Balance(sourceChain: L2Chain, address?: string) {
+  ensureMainnet();
+  const addr = (address ?? getAddress()) as `0x${string}`;
+  const client = getL2PublicClient(sourceChain);
+  const cfg = L2_CHAINS[sourceChain];
+
+  const [eth, wsteth] = await Promise.all([
+    client.getBalance({ address: addr }),
+    client.readContract({ address: cfg.wstETH, abi: ERC20_ABI, functionName: 'balanceOf', args: [addr] }),
+  ]);
+
+  return {
+    address: addr,
+    chain: cfg.name,
+    chainId: cfg.chainId,
+    balances: { ETH: formatEther(eth), wstETH: formatEther(wsteth) },
+  };
+}
+
+export async function getBridgeQuote(
+  sourceChain: L2Chain,
+  token: BridgeToken,
+  amount: string,
+  toToken?: string,
+) {
+  ensureMainnet();
+  const addr = getAddress();
+  const cfg = L2_CHAINS[sourceChain];
+  const fromToken = tokenAddress(sourceChain, token);
+  const toAddr = toTokenAddress(toToken);
+  const fromAmount = parseEther(amount).toString();
+
+  const url = `${LIFI_BASE}/quote?fromChain=${cfg.chainId}&toChain=1&fromToken=${fromToken}&toToken=${toAddr}&fromAmount=${fromAmount}&fromAddress=${addr}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`LI.FI quote failed (${res.status}): ${body}`);
+  }
+  const data = await res.json();
+
+  return {
+    sourceChain: cfg.name,
+    token,
+    amount,
+    toToken: toToken ?? 'ETH',
+    toAmount: formatEther(BigInt(data.estimate?.toAmount ?? '0')),
+    estimatedDuration: `${Math.ceil((data.estimate?.executionDuration ?? 0) / 60)} min`,
+    gasCosts: data.estimate?.gasCosts ?? [],
+    feeCosts: data.estimate?.feeCosts ?? [],
+    tool: data.tool,
+  };
+}
+
+export async function bridgeToEthereum(
+  sourceChain: L2Chain,
+  token: BridgeToken,
+  amount: string,
+  toToken?: string,
+  dryRun?: boolean,
+) {
+  ensureMainnet();
+  const addr = getAddress();
+  const cfg = L2_CHAINS[sourceChain];
+  const fromToken = tokenAddress(sourceChain, token);
+  const toAddr = toTokenAddress(toToken);
+  const fromAmount = parseEther(amount).toString();
+  const shouldDryRun = config.isSimulation ? (dryRun !== false) : !!dryRun;
+
+  const url = `${LIFI_BASE}/quote?fromChain=${cfg.chainId}&toChain=1&fromToken=${fromToken}&toToken=${toAddr}&fromAmount=${fromAmount}&fromAddress=${addr}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`LI.FI quote failed (${res.status}): ${body}`);
+  }
+  const data = await res.json();
+  const txReq = data.transactionRequest;
+
+  const quote = {
+    sourceChain: cfg.name,
+    token,
+    amount,
+    toToken: toToken ?? 'ETH',
+    toAmount: formatEther(BigInt(data.estimate?.toAmount ?? '0')),
+    estimatedDuration: `${Math.ceil((data.estimate?.executionDuration ?? 0) / 60)} min`,
+    tool: data.tool,
+  };
+
+  if (shouldDryRun) {
+    return { simulated: true, mode: config.mode, ...quote };
+  }
+
+  const wallet = getL2Wallet(sourceChain);
+  const client = getL2PublicClient(sourceChain);
+
+  // ERC-20 approval for wstETH
+  if (token === 'wstETH' && txReq.to) {
+    const allowance = await client.readContract({
+      address: cfg.wstETH,
+      abi: ERC20_ABI,
+      functionName: 'allowance',
+      args: [addr as `0x${string}`, txReq.to as `0x${string}`],
+    });
+    if (allowance < BigInt(fromAmount)) {
+      const approveTx = await wallet.writeContract({
+        address: cfg.wstETH,
+        abi: ERC20_ABI,
+        functionName: 'approve',
+        args: [txReq.to as `0x${string}`, BigInt(fromAmount)],
+        chain: cfg.viemChain,
+      } as any);
+      await client.waitForTransactionReceipt({ hash: approveTx });
+    }
+  }
+
+  const hash = await wallet.sendTransaction({
+    to: txReq.to as `0x${string}`,
+    data: txReq.data as Hex,
+    value: txReq.value ? BigInt(txReq.value) : 0n,
+    gas: txReq.gasLimit ? BigInt(txReq.gasLimit) : undefined,
+    chain: cfg.viemChain,
+  } as any);
+
+  return {
+    simulated: false,
+    mode: config.mode,
+    ...quote,
+    txHash: hash,
+    note: 'Bridge submitted. Use get_bridge_status to track progress (may take 1-20 min).',
+  };
+}
+
+export async function getBridgeStatus(txHash: string, sourceChain: L2Chain) {
+  ensureMainnet();
+  const cfg = L2_CHAINS[sourceChain];
+
+  const url = `${LIFI_BASE}/status?txHash=${txHash}&fromChain=${cfg.chainId}&toChain=1`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`LI.FI status failed (${res.status}): ${body}`);
+  }
+  const data = await res.json();
+
+  return {
+    txHash,
+    sourceChain: cfg.name,
+    status: data.status,
+    substatus: data.substatus ?? null,
+    sending: data.sending ? { txHash: data.sending.txHash, amount: data.sending.amount } : null,
+    receiving: data.receiving ? { txHash: data.receiving.txHash, amount: data.receiving.amount } : null,
+  };
+}

package/src/tools/governance.ts

@@ -0,0 +1,131 @@
+import { createPublicClient, http, parseAbi, formatEther } from 'viem';
+import { getAddress } from '../wallet.js';
+import { getWallet } from '../wallet.js';
+import { config } from '../config.js';
+
+// Aragon Voting contract addresses
+const VOTING_ADDRESSES: Record<number, `0x${string}`> = {
+  1: '0x2e59A20f205bB85a89C53f1936454680651E618e',   // mainnet Lido DAO Aragon Voting
+  17000: '0xDA7d2573Df555002503F29aA4003e398d28cc00f', // holesky
+};
+
+const VOTING_ABI = parseAbi([
+  'function vote(uint256 _voteId, bool _supports, bool _executesIfDecided) external',
+  'function getVote(uint256 _voteId) external view returns (bool open, bool executed, uint64 startDate, uint64 snapshotBlock, uint64 supportRequired, uint64 minAcceptQuorum, uint256 yea, uint256 nay, uint256 votingPower, bytes script)',
+  'function votesLength() external view returns (uint256)',
+]);
+
+export async function getProposals(count = 5) {
+  const client = createPublicClient({
+    chain: config.chain,
+    transport: http(config.rpcUrl),
+  });
+
+  const votingAddress = VOTING_ADDRESSES[config.chainId];
+  if (!votingAddress) throw new Error(`No voting contract for chain ${config.chainId}`);
+
+  const totalVotes = await client.readContract({
+    address: votingAddress,
+    abi: VOTING_ABI,
+    functionName: 'votesLength',
+  });
+
+  const latest = Number(totalVotes);
+  const from = Math.max(0, latest - count);
+  const ids = Array.from({ length: latest - from }, (_, i) => from + i);
+
+  const votes = await Promise.all(
+    ids.map(async (id) => {
+      const v = await client.readContract({
+        address: votingAddress,
+        abi: VOTING_ABI,
+        functionName: 'getVote',
+        args: [BigInt(id)],
+      });
+      return {
+        id,
+        open: v[0],
+        executed: v[1],
+        startDate: new Date(Number(v[2]) * 1000).toISOString(),
+        yea: formatEther(v[6]),
+        nay: formatEther(v[7]),
+        votingPower: formatEther(v[8]),
+      };
+    })
+  );
+
+  return {
+    mode: config.mode,
+    network: config.chain.name,
+    votingContract: votingAddress,
+    totalProposals: latest,
+    proposals: votes.reverse(),
+  };
+}
+
+export async function getProposal(proposalId: number) {
+  const client = createPublicClient({
+    chain: config.chain,
+    transport: http(config.rpcUrl),
+  });
+
+  const votingAddress = VOTING_ADDRESSES[config.chainId];
+  const v = await client.readContract({
+    address: votingAddress,
+    abi: VOTING_ABI,
+    functionName: 'getVote',
+    args: [BigInt(proposalId)],
+  });
+
+  return {
+    mode: config.mode,
+    id: proposalId,
+    open: v[0],
+    executed: v[1],
+    startDate: new Date(Number(v[2]) * 1000).toISOString(),
+    snapshotBlock: v[3].toString(),
+    supportRequired: `${(Number(v[4]) / 1e16).toFixed(1)}%`,
+    minAcceptQuorum: `${(Number(v[5]) / 1e16).toFixed(1)}%`,
+    yea: formatEther(v[6]),
+    nay: formatEther(v[7]),
+    votingPower: formatEther(v[8]),
+  };
+}
+
+export async function castVote(proposalId: number, support: boolean, dryRun?: boolean) {
+  const votingAddress = VOTING_ADDRESSES[config.chainId];
+  if (!votingAddress) throw new Error(`No voting contract for chain ${config.chainId}`);
+  const shouldDryRun = config.isSimulation ? (dryRun !== false) : !!dryRun;
+  const account = getAddress();
+
+  if (shouldDryRun) {
+    const proposal = await getProposal(proposalId);
+    return {
+      simulated: true,
+      mode: config.mode,
+      action: 'cast_vote',
+      proposalId,
+      vote: support ? 'YEA' : 'NAY',
+      proposal,
+      note: 'You need LDO tokens to vote. Voting power is based on LDO balance at snapshot block.',
+    };
+  }
+
+  const wallet = getWallet();
+  const hash = await wallet.writeContract({
+    address: votingAddress,
+    abi: VOTING_ABI,
+    functionName: 'vote',
+    args: [BigInt(proposalId), support, false],
+    account,
+  });
+
+  return {
+    simulated: false,
+    mode: config.mode,
+    action: 'cast_vote',
+    proposalId,
+    vote: support ? 'YEA' : 'NAY',
+    txHash: hash,
+  };
+}

package/src/tools/index.ts

@@ -0,0 +1,208 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { getBalance, getRewards } from './balance.js';
+import { stakeEth } from './stake.js';
+import { requestWithdrawal, claimWithdrawals, getWithdrawalRequests, getWithdrawalStatus } from './unstake.js';
+import { wrapSteth, unwrapWsteth, getConversionRate } from './wrap.js';
+import { getProposals, getProposal, castVote } from './governance.js';
+import { getL2Balance, getBridgeQuote, bridgeToEthereum, getBridgeStatus } from './bridge.js';
+
+export function registerTools(server: McpServer, modeNote: string) {
+  // balance & info
+  server.tool(
+    'get_balance',
+    `Get ETH, stETH, and wstETH balances for an address. Also returns current staking APR. ${modeNote}`,
+    { address: z.string().optional().describe('Ethereum address (defaults to configured wallet)') },
+    async ({ address }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await getBalance(address), null, 2) }],
+    })
+  );
+
+  server.tool(
+    'get_rewards',
+    'Get staking reward history for an address over N days.',
+    {
+      address: z.string().optional().describe('Ethereum address (defaults to configured wallet)'),
+      days: z.number().int().min(1).max(365).optional().default(7).describe('Number of days to look back'),
+    },
+    async ({ address, days }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await getRewards(address, days), null, 2) }],
+    })
+  );
+
+  server.tool(
+    'get_conversion_rate',
+    'Get current stETH <=> wstETH conversion rates.',
+    {},
+    async () => ({
+      content: [{ type: 'text', text: JSON.stringify(await getConversionRate(), null, 2) }],
+    })
+  );
+
+  // staking
+  server.tool(
+    'stake_eth',
+    `Stake ETH to receive stETH. In simulation mode, dry_run defaults to true. ${modeNote}`,
+    {
+      amount_eth: z.string().describe('Amount of ETH to stake (e.g. "0.1")'),
+      dry_run: z.boolean().optional().describe('Simulate without broadcasting. Always true in simulation mode unless set to false.'),
+    },
+    async ({ amount_eth, dry_run }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await stakeEth(amount_eth, dry_run), null, 2) }],
+    })
+  );
+
+  // unstaking / withdrawals
+  server.tool(
+    'request_withdrawal',
+    `Request withdrawal of stETH back to ETH via the Lido withdrawal queue. ${modeNote}`,
+    {
+      amount_steth: z.string().describe('Amount of stETH to withdraw (min 0.1, max 1000 per request)'),
+      dry_run: z.boolean().optional().describe('Simulate without broadcasting.'),
+    },
+    async ({ amount_steth, dry_run }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await requestWithdrawal(amount_steth, dry_run), null, 2) }],
+    })
+  );
+
+  server.tool(
+    'claim_withdrawals',
+    `Claim finalized withdrawal requests and receive ETH. ${modeNote}`,
+    {
+      request_ids: z.array(z.string()).describe('Array of withdrawal request NFT IDs to claim'),
+      dry_run: z.boolean().optional().describe('Simulate without broadcasting.'),
+    },
+    async ({ request_ids, dry_run }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await claimWithdrawals(request_ids, dry_run), null, 2) }],
+    })
+  );
+
+  server.tool(
+    'get_withdrawal_requests',
+    'Get all pending withdrawal request IDs for an address.',
+    { address: z.string().optional().describe('Ethereum address (defaults to configured wallet)') },
+    async ({ address }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await getWithdrawalRequests(address), null, 2) }],
+    })
+  );
+
+  server.tool(
+    'get_withdrawal_status',
+    'Check finalization status of withdrawal request IDs.',
+    { request_ids: z.array(z.string()).describe('Withdrawal request IDs to check') },
+    async ({ request_ids }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await getWithdrawalStatus(request_ids), null, 2) }],
+    })
+  );
+
+  // wrap / unwrap
+  server.tool(
+    'wrap_steth',
+    `Wrap stETH into wstETH (non-rebasing, better for DeFi). ${modeNote}`,
+    {
+      amount_steth: z.string().describe('Amount of stETH to wrap'),
+      dry_run: z.boolean().optional().describe('Simulate without broadcasting.'),
+    },
+    async ({ amount_steth, dry_run }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await wrapSteth(amount_steth, dry_run), null, 2) }],
+    })
+  );
+
+  server.tool(
+    'unwrap_wsteth',
+    `Unwrap wstETH back to stETH. ${modeNote}`,
+    {
+      amount_wsteth: z.string().describe('Amount of wstETH to unwrap'),
+      dry_run: z.boolean().optional().describe('Simulate without broadcasting.'),
+    },
+    async ({ amount_wsteth, dry_run }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await unwrapWsteth(amount_wsteth, dry_run), null, 2) }],
+    })
+  );
+
+  // governance
+  server.tool(
+    'get_proposals',
+    'List recent Lido DAO governance proposals from the Aragon Voting contract.',
+    { count: z.number().int().min(1).max(20).optional().default(5).describe('Number of recent proposals to fetch') },
+    async ({ count }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await getProposals(count), null, 2) }],
+    })
+  );
+
+  server.tool(
+    'get_proposal',
+    'Get detailed info on a specific Lido DAO governance proposal.',
+    { proposal_id: z.number().int().describe('Proposal/vote ID') },
+    async ({ proposal_id }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await getProposal(proposal_id), null, 2) }],
+    })
+  );
+
+  server.tool(
+    'cast_vote',
+    `Vote YEA or NAY on a Lido DAO governance proposal. Requires LDO tokens. ${modeNote}`,
+    {
+      proposal_id: z.number().int().describe('Proposal/vote ID to vote on'),
+      support: z.boolean().describe('true = YEA (support), false = NAY (against)'),
+      dry_run: z.boolean().optional().describe('Simulate without broadcasting.'),
+    },
+    async ({ proposal_id, support, dry_run }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await castVote(proposal_id, support, dry_run), null, 2) }],
+    })
+  );
+
+  // L2 bridging
+  server.tool(
+    'get_l2_balance',
+    'Get ETH and wstETH balances on Base or Arbitrum. Only works in live (mainnet) mode.',
+    {
+      source_chain: z.enum(['base', 'arbitrum']).describe('L2 chain to query'),
+      address: z.string().optional().describe('Address to check (defaults to configured wallet)'),
+    },
+    async ({ source_chain, address }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await getL2Balance(source_chain, address), null, 2) }],
+    })
+  );
+
+  server.tool(
+    'get_bridge_quote',
+    'Get a quote for bridging ETH or wstETH from an L2 to Ethereum L1 via LI.FI. Mainnet only.',
+    {
+      source_chain: z.enum(['base', 'arbitrum']).describe('L2 chain to bridge from'),
+      token: z.enum(['ETH', 'wstETH']).describe('Token to bridge'),
+      amount: z.string().describe('Amount to bridge (e.g. "0.1")'),
+      to_token: z.enum(['ETH', 'wstETH']).optional().describe('Token to receive on L1 (default ETH)'),
+    },
+    async ({ source_chain, token, amount, to_token }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await getBridgeQuote(source_chain, token, amount, to_token), null, 2) }],
+    })
+  );
+
+  server.tool(
+    'bridge_to_ethereum',
+    `Bridge ETH or wstETH from Base/Arbitrum to Ethereum L1 via LI.FI. ${modeNote}`,
+    {
+      source_chain: z.enum(['base', 'arbitrum']).describe('L2 chain to bridge from'),
+      token: z.enum(['ETH', 'wstETH']).describe('Token to bridge'),
+      amount: z.string().describe('Amount to bridge'),
+      to_token: z.enum(['ETH', 'wstETH']).optional().describe('Token to receive on L1'),
+      dry_run: z.boolean().optional().describe('Simulate without broadcasting'),
+    },
+    async ({ source_chain, token, amount, to_token, dry_run }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await bridgeToEthereum(source_chain, token, amount, to_token, dry_run), null, 2) }],
+    })
+  );
+
+  server.tool(
+    'get_bridge_status',
+    'Check the status of an in-progress bridge transaction via LI.FI. Mainnet only.',
+    {
+      tx_hash: z.string().describe('Bridge transaction hash on the L2'),
+      source_chain: z.enum(['base', 'arbitrum']).describe('L2 chain the bridge was sent from'),
+    },
+    async ({ tx_hash, source_chain }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await getBridgeStatus(tx_hash, source_chain), null, 2) }],
+    })
+  );
+}

package/src/tools/stake.ts

@@ -0,0 +1,67 @@
+import { parseEther, formatEther } from 'viem';
+import { getSDK, publicClient } from '../sdk.js';
+import { getWallet, getAddress } from '../wallet.js';
+import { config } from '../config.js';
+
+// stETH (Lido) contract addresses
+const LIDO_ADDRESSES: Record<number, `0x${string}`> = {
+  1: '0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84',
+  17000: '0x3F1c547b21f65e10480dE3ad8E19fAAC46C95034',
+};
+
+const SUBMIT_ABI = [
+  {
+    name: 'submit',
+    type: 'function',
+    inputs: [{ name: '_referral', type: 'address' }],
+    outputs: [{ type: 'uint256' }],
+    stateMutability: 'payable',
+  },
+] as const;
+
+export async function stakeEth(amountEth: string, dryRun?: boolean) {
+  const sdk = getSDK();
+  const value = parseEther(amountEth);
+  const account = getAddress();
+  const lidoAddress = LIDO_ADDRESSES[config.chainId];
+
+  const shouldDryRun = config.isSimulation ? (dryRun !== false) : !!dryRun;
+
+  if (shouldDryRun) {
+    const gas = await publicClient.estimateContractGas({
+      address: lidoAddress,
+      abi: SUBMIT_ABI,
+      functionName: 'submit',
+      args: [config.referralAddress],
+      value,
+      account,
+    });
+
+    return {
+      simulated: true,
+      mode: config.mode,
+      action: 'stake',
+      amountEth,
+      estimatedGas: gas.toString(),
+      expectedStETH: amountEth,
+      note: 'stETH rebases daily — your balance grows automatically after staking.',
+    };
+  }
+
+  const wallet = getWallet();
+  const tx = await sdk.stake.stakeEth({
+    value,
+    account: { address: account } as any,
+    callback: ({ stage, payload }: any) => {},
+  });
+
+  return {
+    simulated: false,
+    mode: config.mode,
+    action: 'stake',
+    amountEth,
+    txHash: (tx as any).hash,
+    stethReceived: formatEther((tx as any).result?.stethReceived ?? 0n),
+    sharesReceived: formatEther((tx as any).result?.sharesReceived ?? 0n),
+  };
+}

package/src/tools/unstake.ts

@@ -0,0 +1,103 @@
+import { parseEther, formatEther } from 'viem';
+import { getSDK, publicClient } from '../sdk.js';
+import { getAddress } from '../wallet.js';
+import { config } from '../config.js';
+
+export async function requestWithdrawal(amountSteth: string, dryRun?: boolean) {
+  const sdk = getSDK();
+  const amount = parseEther(amountSteth);
+  const account = getAddress();
+  const shouldDryRun = config.isSimulation ? (dryRun !== false) : !!dryRun;
+
+  if (shouldDryRun) {
+    return {
+      simulated: true,
+      mode: config.mode,
+      action: 'request_withdrawal',
+      amountSteth,
+      note: 'Withdrawal requests enter a queue. Finalization can take hours to days depending on validator exits. You will receive an ERC-721 NFT representing your position in the queue.',
+      minWithdrawal: '0.1 stETH',
+      maxWithdrawal: '1000 stETH per request',
+    };
+  }
+
+  const tx = await sdk.withdrawals.requestWithdrawals({
+    amounts: [amount],
+    account: { address: account } as any,
+    callback: ({ stage, payload }: any) => {},
+  });
+
+  return {
+    simulated: false,
+    mode: config.mode,
+    action: 'request_withdrawal',
+    amountSteth,
+    txHash: (tx as any).hash,
+    requestIds: (tx as any).result?.requestIds?.map((id: bigint) => id.toString()),
+    note: 'Check withdrawal status with get_withdrawal_status. Claim when finalized.',
+  };
+}
+
+export async function claimWithdrawals(requestIds: string[], dryRun?: boolean) {
+  const sdk = getSDK();
+  const ids = requestIds.map(BigInt);
+  const account = getAddress();
+  const shouldDryRun = config.isSimulation ? (dryRun !== false) : !!dryRun;
+
+  if (shouldDryRun) {
+    return {
+      simulated: true,
+      mode: config.mode,
+      action: 'claim_withdrawals',
+      requestIds,
+      note: 'Claims can only be made after requests are finalized. Use get_withdrawal_status to check.',
+    };
+  }
+
+  const tx = await sdk.withdrawals.claimWithdrawals({
+    requestsIds: ids,
+    account: { address: account } as any,
+    callback: ({ stage, payload }: any) => {},
+  });
+
+  return {
+    simulated: false,
+    mode: config.mode,
+    action: 'claim_withdrawals',
+    requestIds,
+    txHash: (tx as any).hash,
+  };
+}
+
+export async function getWithdrawalRequests(address?: string) {
+  const sdk = getSDK();
+  const addr = (address ?? getAddress()) as `0x${string}`;
+
+  const requests = await sdk.withdrawals.getWithdrawalRequests({ account: addr });
+
+  return {
+    address: addr,
+    mode: config.mode,
+    requests: requests.map((id: bigint) => id.toString()),
+    count: requests.length,
+  };
+}
+
+export async function getWithdrawalStatus(requestIds: string[]) {
+  const sdk = getSDK();
+  const ids = requestIds.map(BigInt);
+
+  const statuses = await sdk.withdrawals.getWithdrawalStatus({ requestsIds: ids });
+
+  return {
+    mode: config.mode,
+    statuses: statuses.map((s: any, i: number) => ({
+      requestId: requestIds[i],
+      amountOfStETH: formatEther(s.amountOfStETH ?? 0n),
+      amountOfShares: formatEther(s.amountOfShares ?? 0n),
+      owner: s.owner,
+      isFinalized: s.isFinalized,
+      isClaimed: s.isClaimed,
+    })),
+  };
+}

package/src/tools/wrap.ts

@@ -0,0 +1,91 @@
+import { parseEther, formatEther } from 'viem';
+import { getSDK } from '../sdk.js';
+import { getAddress } from '../wallet.js';
+import { config } from '../config.js';
+
+export async function wrapSteth(amountSteth: string, dryRun?: boolean) {
+  const sdk = getSDK();
+  const amount = parseEther(amountSteth);
+  const account = getAddress();
+  const shouldDryRun = config.isSimulation ? (dryRun !== false) : !!dryRun;
+
+  // Get current wstETH conversion rate
+  const wstethPerSteth = await sdk.core.convertStethToWsteth(amount);
+
+  if (shouldDryRun) {
+    return {
+      simulated: true,
+      mode: config.mode,
+      action: 'wrap_steth',
+      amountSteth,
+      expectedWstETH: formatEther(wstethPerSteth),
+      note: 'wstETH is a non-rebasing wrapper. Its balance stays fixed while its value grows. Better for DeFi integrations.',
+    };
+  }
+
+  const tx = await sdk.wrap.wrapSteth({
+    value: amount,
+    account: { address: account } as any,
+    callback: ({ stage, payload }: any) => {},
+  });
+
+  return {
+    simulated: false,
+    mode: config.mode,
+    action: 'wrap_steth',
+    amountSteth,
+    txHash: (tx as any).hash,
+    wstethReceived: formatEther((tx as any).result?.wstethReceived ?? 0n),
+  };
+}
+
+export async function unwrapWsteth(amountWsteth: string, dryRun?: boolean) {
+  const sdk = getSDK();
+  const amount = parseEther(amountWsteth);
+  const account = getAddress();
+  const shouldDryRun = config.isSimulation ? (dryRun !== false) : !!dryRun;
+
+  const stethAmount = await sdk.core.convertWstethToSteth(amount);
+
+  if (shouldDryRun) {
+    return {
+      simulated: true,
+      mode: config.mode,
+      action: 'unwrap_wsteth',
+      amountWsteth,
+      expectedStETH: formatEther(stethAmount),
+      note: 'Unwrapping gives you rebasing stETH back. Your balance will update daily with rewards.',
+    };
+  }
+
+  const tx = await sdk.wrap.unwrapWsteth({
+    value: amount,
+    account: { address: account } as any,
+    callback: ({ stage, payload }: any) => {},
+  });
+
+  return {
+    simulated: false,
+    mode: config.mode,
+    action: 'unwrap_wsteth',
+    amountWsteth,
+    txHash: (tx as any).hash,
+    stethReceived: formatEther((tx as any).result?.stethReceived ?? 0n),
+  };
+}
+
+export async function getConversionRate() {
+  const sdk = getSDK();
+  const oneEther = parseEther('1');
+  const [wstethPerSteth, stethPerWsteth] = await Promise.all([
+    sdk.core.convertStethToWsteth(oneEther),
+    sdk.core.convertWstethToSteth(oneEther),
+  ]);
+
+  return {
+    mode: config.mode,
+    '1_stETH_in_wstETH': formatEther(wstethPerSteth),
+    '1_wstETH_in_stETH': formatEther(stethPerWsteth),
+    note: 'wstETH/stETH ratio increases over time as staking rewards accumulate.',
+  };
+}

package/src/wallet.ts

@@ -0,0 +1,50 @@
+import { createWalletClient, createPublicClient, http, type WalletClient, type PublicClient } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { config, L2_CHAINS } from './config.js';
+import type { L2Chain } from './config.js';
+
+let _wallet: WalletClient | null = null;
+
+export function getWallet(): WalletClient {
+  if (_wallet) return _wallet;
+
+  const pk = process.env.PRIVATE_KEY;
+  if (!pk) throw new Error('PRIVATE_KEY env var is required');
+
+  const account = privateKeyToAccount(pk as `0x${string}`);
+  _wallet = createWalletClient({
+    account,
+    chain: config.chain,
+    transport: http(config.rpcUrl),
+  });
+
+  return _wallet;
+}
+
+export function getAddress(): `0x${string}` {
+  const pk = process.env.PRIVATE_KEY;
+  if (!pk) throw new Error('PRIVATE_KEY env var is required');
+  return privateKeyToAccount(pk as `0x${string}`).address;
+}
+
+const _l2Wallets: Partial<Record<L2Chain, WalletClient>> = {};
+const _l2Clients: Partial<Record<L2Chain, PublicClient>> = {};
+
+export function getL2Wallet(chain: L2Chain): WalletClient {
+  if (_l2Wallets[chain]) return _l2Wallets[chain]!;
+  const pk = process.env.PRIVATE_KEY;
+  if (!pk) throw new Error('PRIVATE_KEY env var is required');
+  const account = privateKeyToAccount(pk as `0x${string}`);
+  const cfg = L2_CHAINS[chain];
+  const w = createWalletClient({ account, chain: cfg.viemChain, transport: http(cfg.defaultRpc) });
+  _l2Wallets[chain] = w;
+  return w;
+}
+
+export function getL2PublicClient(chain: L2Chain): PublicClient {
+  if (_l2Clients[chain]) return _l2Clients[chain]!;
+  const cfg = L2_CHAINS[chain];
+  const c = createPublicClient({ chain: cfg.viemChain, transport: http(cfg.defaultRpc) });
+  _l2Clients[chain] = c;
+  return c;
+}