@drparadox05/lido-mcp-server 0.1.0

package/dist/uniswap/api.js

@@ -0,0 +1,104 @@
+import { getOptionalEnv } from '../config/env.js';
+const UNISWAP_API_BASE_URL = 'https://trade-api.gateway.uniswap.org/v1';
+function getUniswapApiKey() {
+    const value = getOptionalEnv('UNISWAP_API_KEY');
+    if (!value) {
+        throw new Error('No Uniswap API key configured. Set UNISWAP_API_KEY.');
+    }
+    return value;
+}
+export function hasUniswapApiKeyConfigured() {
+    return Boolean(getOptionalEnv('UNISWAP_API_KEY'));
+}
+export function getUniswapUniversalRouterVersion() {
+    return getOptionalEnv('UNISWAP_UNIVERSAL_ROUTER_VERSION') === '1.2' ? '1.2' : '2.0';
+}
+async function parseResponse(response) {
+    const text = await response.text();
+    if (!text) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function buildHeaders(includeRouterHeader, includePermitHeader) {
+    const headers = {
+        accept: 'application/json',
+        'content-type': 'application/json',
+        'x-api-key': getUniswapApiKey(),
+    };
+    if (includeRouterHeader) {
+        headers['x-universal-router-version'] = getUniswapUniversalRouterVersion();
+    }
+    if (includePermitHeader) {
+        headers['x-permit2-disabled'] = 'true';
+    }
+    return headers;
+}
+async function requestJson(path, init, includeRouterHeader, includePermitHeader) {
+    const response = await fetch(`${UNISWAP_API_BASE_URL}${path}`, {
+        ...init,
+        headers: {
+            ...buildHeaders(includeRouterHeader, includePermitHeader),
+            ...(init.headers ?? {}),
+        },
+    });
+    const payload = await parseResponse(response);
+    if (!response.ok) {
+        const detail = typeof payload === 'string'
+            ? payload
+            : payload && typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : response.statusText;
+        throw new Error(`Uniswap API ${response.status} ${response.statusText}: ${detail}`);
+    }
+    return payload;
+}
+export async function postUniswapApi(path, body, options) {
+    return requestJson(path, {
+        method: 'POST',
+        body: JSON.stringify(body),
+    }, options?.includeRouterHeader ?? false, options?.includePermitHeader ?? true);
+}
+export async function getUniswapApi(path, params, options) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        query.set(key, value);
+    }
+    return requestJson(`${path}?${query.toString()}`, {
+        method: 'GET',
+    }, options?.includeRouterHeader ?? false, options?.includePermitHeader ?? false);
+}
+export async function checkUniswapApproval(body) {
+    return postUniswapApi('/check_approval', body, {
+        includePermitHeader: true,
+    });
+}
+export async function getUniswapQuote(body) {
+    return postUniswapApi('/quote', body, {
+        includeRouterHeader: true,
+        includePermitHeader: true,
+    });
+}
+export async function createUniswapSwap(body) {
+    return postUniswapApi('/swap', body, {
+        includeRouterHeader: true,
+        includePermitHeader: true,
+    });
+}
+export async function getUniswapSwapStatus(chainId, txHashes) {
+    return getUniswapApi('/swaps', {
+        chainId: String(chainId),
+        txHashes: txHashes.join(','),
+    });
+}
+export async function getUniswapBridgableTokens(tokenInChainId, tokenIn) {
+    return getUniswapApi('/swappable_tokens', {
+        tokenInChainId: String(tokenInChainId),
+        tokenIn,
+    });
+}

package/dist/uniswap/index.js

@@ -0,0 +1,318 @@
+import { erc20Abi, formatUnits, getAddress, parseUnits } from 'viem';
+import { hasPrivateKeyConfigured } from '../config/env.js';
+import { getAccount, getPublicClient, getWalletContext } from '../lido/clients.js';
+import { getNetworkConfig } from '../lido/networks.js';
+import { checkUniswapApproval, createUniswapSwap, getUniswapBridgableTokens as fetchUniswapBridgableTokens, getUniswapQuote, getUniswapSwapStatus as fetchUniswapSwapStatus, getUniswapUniversalRouterVersion, hasUniswapApiKeyConfigured } from './api.js';
+import { NATIVE_TOKEN_ADDRESS, describeTokenReference, resolveTokenReference } from './tokens.js';
+import { EXECUTABLE_UNISWAP_ROUTINGS } from './types.js';
+function isNativeToken(address) {
+    return address.toLowerCase() === NATIVE_TOKEN_ADDRESS.toLowerCase();
+}
+function getExecutionContext(swapper) {
+    let configuredAddress = null;
+    let walletError = null;
+    if (hasPrivateKeyConfigured()) {
+        try {
+            configuredAddress = getAccount().address;
+        }
+        catch (error) {
+            walletError = error instanceof Error ? error.message : String(error);
+        }
+    }
+    const swapperAddress = swapper ? getAddress(swapper) : configuredAddress;
+    return {
+        wallet_configured: hasPrivateKeyConfigured(),
+        configured_address: configuredAddress,
+        wallet_error: walletError,
+        swapper: swapperAddress,
+        local_execution_available: Boolean(configuredAddress && swapperAddress && configuredAddress.toLowerCase() === swapperAddress.toLowerCase()),
+    };
+}
+async function getTokenDecimals(network, token) {
+    if (isNativeToken(token)) {
+        return 18;
+    }
+    const publicClient = getPublicClient(network);
+    return Number(await publicClient.readContract({
+        address: token,
+        abi: erc20Abi,
+        functionName: 'decimals',
+    }));
+}
+async function resolveTradeAmount(type, tokenInChain, tokenIn, tokenOutChain, tokenOut, amount) {
+    const amountTokenNetwork = type === 'EXACT_INPUT' ? tokenInChain : tokenOutChain;
+    const amountTokenAddress = type === 'EXACT_INPUT' ? tokenIn : tokenOut;
+    const decimals = await getTokenDecimals(amountTokenNetwork, amountTokenAddress);
+    const raw = parseUnits(amount, decimals);
+    return {
+        specified_token: type === 'EXACT_INPUT' ? 'token_in' : 'token_out',
+        decimals,
+        raw,
+        formatted: formatUnits(raw, decimals),
+    };
+}
+function getDefaultProtocols(tokenInChain, tokenOutChain, protocols) {
+    if (protocols && protocols.length > 0) {
+        return protocols;
+    }
+    if (tokenInChain !== tokenOutChain) {
+        return undefined;
+    }
+    return ['V4', 'V3', 'V2'];
+}
+async function prepareUniswapRoute(params) {
+    if (!hasUniswapApiKeyConfigured()) {
+        throw new Error('No Uniswap API key configured. Set UNISWAP_API_KEY.');
+    }
+    const execution = getExecutionContext(params.swapper);
+    if (!execution.swapper) {
+        throw new Error('Provide swapper explicitly or configure a wallet private key before requesting a Uniswap route.');
+    }
+    const inputToken = describeTokenReference(params.tokenInChain, params.tokenIn);
+    const outputToken = describeTokenReference(params.tokenOutChain, params.tokenOut);
+    const amount = await resolveTradeAmount(params.type, params.tokenInChain, inputToken.resolved, params.tokenOutChain, outputToken.resolved, params.amount);
+    const protocols = getDefaultProtocols(params.tokenInChain, params.tokenOutChain, params.protocols);
+    const quoteRequest = {
+        type: params.type,
+        amount: amount.raw.toString(),
+        tokenInChainId: getNetworkConfig(params.tokenInChain).chain.id,
+        tokenOutChainId: getNetworkConfig(params.tokenOutChain).chain.id,
+        tokenIn: inputToken.resolved,
+        tokenOut: outputToken.resolved,
+        swapper: execution.swapper,
+        routingPreference: params.routingPreference,
+        urgency: params.urgency,
+        ...(params.slippageTolerance !== undefined ? { slippageTolerance: params.slippageTolerance } : { autoSlippage: 'DEFAULT' }),
+        ...(protocols ? { protocols } : {}),
+    };
+    const quote = await getUniswapQuote(quoteRequest);
+    const routing = quote.routing;
+    const quotedInputAmount = quote.quote?.input?.amount ?? amount.raw.toString();
+    const approvalRequest = !isNativeToken(inputToken.resolved)
+        ? {
+            walletAddress: execution.swapper,
+            token: inputToken.resolved,
+            amount: quotedInputAmount,
+            chainId: getNetworkConfig(params.tokenInChain).chain.id,
+            urgency: params.urgency,
+            includeGasInfo: true,
+            tokenOut: outputToken.resolved,
+            tokenOutChainId: getNetworkConfig(params.tokenOutChain).chain.id,
+        }
+        : null;
+    const approval = approvalRequest ? await checkUniswapApproval(approvalRequest) : null;
+    return {
+        execution,
+        inputToken,
+        outputToken,
+        amount,
+        approvalRequest,
+        approval,
+        quoteRequest,
+        quote,
+        routing,
+        executable_routing: EXECUTABLE_UNISWAP_ROUTINGS.includes(routing),
+    };
+}
+function getQuoteSummary(prepared) {
+    const quote = prepared.quote.quote;
+    return {
+        request_id: prepared.quote.requestId,
+        routing: prepared.routing,
+        executable_via_swap_endpoint: prepared.executable_routing,
+        quote_id: quote.quoteId ?? null,
+        route_string: quote.routeString ?? null,
+        tx_failure_reasons: quote.txFailureReasons ?? [],
+        price_impact_pct: quote.priceImpact ?? null,
+        input: {
+            token: prepared.inputToken.resolved,
+            amount_raw: quote.input?.amount ?? (prepared.amount.specified_token === 'token_in' ? prepared.amount.raw.toString() : null),
+            amount_formatted: prepared.amount.specified_token === 'token_in' ? prepared.amount.formatted : null,
+        },
+        output: {
+            token: prepared.outputToken.resolved,
+            amount_raw: quote.output?.amount ?? null,
+            recipient: quote.output?.recipient ?? prepared.execution.swapper,
+        },
+        gas: {
+            gas_fee: quote.gasFee ?? null,
+            gas_fee_quote: quote.gasFeeQuote ?? null,
+            gas_fee_usd: quote.gasFeeUSD ?? null,
+            gas_use_estimate: quote.gasUseEstimate ?? null,
+            gas_price: quote.gasPrice ?? null,
+            max_fee_per_gas: quote.maxFeePerGas ?? null,
+            max_priority_fee_per_gas: quote.maxPriorityFeePerGas ?? null,
+        },
+    };
+}
+function createSwapRequest(prepared, deadline) {
+    const request = {
+        quote: prepared.quote.quote,
+        refreshGasPrice: true,
+        simulateTransaction: true,
+        safetyMode: 'SAFE',
+        urgency: prepared.quoteRequest.urgency,
+        deadline: deadline ?? Math.floor(Date.now() / 1000) + 1800,
+    };
+    if (prepared.quote.permitData) {
+        request.permitData = prepared.quote.permitData;
+    }
+    return request;
+}
+async function submitUniswapTransaction(network, transaction) {
+    const { account, publicClient, walletClient } = getWalletContext(network);
+    const hash = await walletClient.sendTransaction({
+        account,
+        to: getAddress(transaction.to),
+        data: transaction.data,
+        value: BigInt(transaction.value ?? '0'),
+        ...(transaction.gasLimit ? { gas: BigInt(transaction.gasLimit) } : {}),
+        ...(transaction.gasPrice ? { gasPrice: BigInt(transaction.gasPrice) } : {}),
+        ...(transaction.maxFeePerGas ? { maxFeePerGas: BigInt(transaction.maxFeePerGas) } : {}),
+        ...(transaction.maxPriorityFeePerGas ? { maxPriorityFeePerGas: BigInt(transaction.maxPriorityFeePerGas) } : {}),
+    });
+    const receipt = await publicClient.waitForTransactionReceipt({ hash });
+    return {
+        transaction_hash: hash,
+        block_number: receipt.blockNumber,
+        status: receipt.status,
+    };
+}
+export function getUniswapSetupSummary() {
+    return {
+        api_key_configured: hasUniswapApiKeyConfigured(),
+        universal_router_version: getUniswapUniversalRouterVersion(),
+        supported_networks: ['ethereum', 'base', 'optimism', 'arbitrum'],
+        supported_routing_execution_modes: [...EXECUTABLE_UNISWAP_ROUTINGS],
+        notes: [
+            'This server uses x-permit2-disabled=true and follows a direct approval-then-swap flow.',
+            'Uniswap API execution requires UNISWAP_API_KEY.',
+            'Live execution is currently limited to routes returned as CLASSIC, BRIDGE, WRAP, or UNWRAP.',
+        ],
+    };
+}
+export async function preflightUniswapRoute(params) {
+    try {
+        const prepared = await prepareUniswapRoute(params);
+        const blockers = [];
+        const warnings = [];
+        const nextSteps = [];
+        if (prepared.approval?.cancel) {
+            warnings.push('Token approval likely needs a reset transaction before the new approval can be sent.');
+        }
+        if (prepared.approval?.approval && !params.approveIfNeeded) {
+            blockers.push('Approval is required but approve_if_needed=false.');
+        }
+        if (!prepared.executable_routing) {
+            blockers.push(`Returned routing ${prepared.routing} is not currently executable through this server's gasful /swap flow.`);
+            warnings.push('This usually means the route prefers UniswapX or a chained plan instead of a direct protocol swap or bridge transaction.');
+        }
+        if (!prepared.execution.local_execution_available) {
+            warnings.push('The server can preflight this route, but live execution requires the configured wallet to match the swapper address.');
+        }
+        if (prepared.quote.quote.txFailureReasons?.length) {
+            warnings.push('The quote contains transaction failure reasons from Uniswap simulation output. Review them before execution.');
+        }
+        nextSteps.push('Run lido_execute_uniswap_route with dry_run=true to inspect the approval and swap transactions.');
+        if (!blockers.length) {
+            nextSteps.push('If the dry run matches intent, rerun lido_execute_uniswap_route with dry_run=false to broadcast the transaction(s).');
+        }
+        return {
+            ready: blockers.length === 0,
+            wallet: prepared.execution,
+            amount: {
+                specified_token: prepared.amount.specified_token,
+                raw: prepared.amount.raw,
+                formatted: prepared.amount.formatted,
+                decimals: prepared.amount.decimals,
+            },
+            token_in: prepared.inputToken,
+            token_out: prepared.outputToken,
+            approval: prepared.approval,
+            quote_request: prepared.quoteRequest,
+            quote_summary: getQuoteSummary(prepared),
+            blockers,
+            warnings,
+            next_steps: nextSteps,
+        };
+    }
+    catch (error) {
+        return {
+            ready: false,
+            blockers: [error instanceof Error ? error.message : String(error)],
+            warnings: [],
+            next_steps: ['Fix the reported configuration or routing issue and rerun the preflight.'],
+        };
+    }
+}
+export async function executeUniswapRoute(params) {
+    const prepared = await prepareUniswapRoute(params);
+    if (!prepared.executable_routing) {
+        throw new Error(`Returned routing ${prepared.routing} is not currently executable by this server. Supported live routings: ${EXECUTABLE_UNISWAP_ROUTINGS.join(', ')}.`);
+    }
+    if (params.dryRun) {
+        const swapRequest = createSwapRequest(prepared, params.deadline);
+        const swap = await createUniswapSwap(swapRequest);
+        return {
+            mode: 'dry_run',
+            wallet: prepared.execution,
+            token_in: prepared.inputToken,
+            token_out: prepared.outputToken,
+            approval: prepared.approval,
+            quote_summary: getQuoteSummary(prepared),
+            swap_request: swap,
+            notes: prepared.approval?.approval
+                ? 'Approval is required before the swap or bridge transaction can succeed onchain.'
+                : 'Swap or bridge transaction is ready for execution.',
+        };
+    }
+    if (!prepared.execution.local_execution_available || !prepared.execution.configured_address) {
+        throw new Error('Live execution requires a configured wallet whose address matches the swapper parameter.');
+    }
+    if (prepared.approval?.approval && !params.approveIfNeeded) {
+        throw new Error('Approval is required but approve_if_needed=false.');
+    }
+    const sourceNetwork = params.tokenInChain;
+    const executedApprovals = [];
+    if (prepared.approval?.cancel) {
+        executedApprovals.push({
+            step: 'cancel_approval',
+            ...(await submitUniswapTransaction(sourceNetwork, prepared.approval.cancel)),
+        });
+    }
+    if (prepared.approval?.approval) {
+        executedApprovals.push({
+            step: 'approve',
+            ...(await submitUniswapTransaction(sourceNetwork, prepared.approval.approval)),
+        });
+    }
+    const refreshed = await prepareUniswapRoute(params);
+    if (!refreshed.executable_routing) {
+        throw new Error(`Refreshed routing ${refreshed.routing} is not currently executable by this server. Re-run preflight and review the new route.`);
+    }
+    const refreshedSwapRequest = createSwapRequest(refreshed, params.deadline);
+    const refreshedSwap = await createUniswapSwap(refreshedSwapRequest);
+    const swapExecution = await submitUniswapTransaction(sourceNetwork, refreshedSwap.swap);
+    return {
+        mode: 'executed',
+        routing: refreshed.routing,
+        source_network: sourceNetwork,
+        destination_network: params.tokenOutChain,
+        approvals: executedApprovals,
+        swap_request_id: refreshedSwap.requestId,
+        gas_fee: refreshedSwap.gasFee ?? null,
+        swap: swapExecution,
+        next_steps: refreshed.routing === 'BRIDGE'
+            ? ['Use lido_get_uniswap_route_status with the source chain and returned transaction hash to monitor bridge progress.']
+            : ['The route transaction has been broadcast and mined on the source chain.'],
+    };
+}
+export async function getUniswapRouteStatus(params) {
+    const chainId = getNetworkConfig(params.chain).chain.id;
+    return fetchUniswapSwapStatus(chainId, params.txHashes);
+}
+export async function getUniswapBridgableTokens(params) {
+    const token = resolveTokenReference(params.tokenInChain, params.tokenIn);
+    const chainId = getNetworkConfig(params.tokenInChain).chain.id;
+    return fetchUniswapBridgableTokens(chainId, token);
+}

package/dist/uniswap/tokens.js

@@ -0,0 +1,44 @@
+import { getAddress, zeroAddress } from 'viem';
+import { getNetworkConfig } from '../lido/networks.js';
+export const NATIVE_TOKEN_ADDRESS = zeroAddress;
+const TOKEN_ALIASES = ['native', 'eth', 'steth', 'wsteth', 'ldo'];
+export function isAddressLike(value) {
+    return /^(0x)?[0-9a-fA-F]{40}$/.test(value);
+}
+export function resolveTokenReference(network, value) {
+    if (isAddressLike(value)) {
+        return getAddress(value);
+    }
+    const normalized = value.trim().toLowerCase();
+    const config = getNetworkConfig(network);
+    if (normalized === 'native' || normalized === 'eth') {
+        return NATIVE_TOKEN_ADDRESS;
+    }
+    if (normalized === 'steth') {
+        if (!config.steth) {
+            throw new Error(`Token alias steth is not available on ${network}. Use a token address instead.`);
+        }
+        return getAddress(config.steth);
+    }
+    if (normalized === 'wsteth') {
+        if (!config.wsteth) {
+            throw new Error(`Token alias wsteth is not available on ${network}. Use a token address instead.`);
+        }
+        return getAddress(config.wsteth);
+    }
+    if (normalized === 'ldo') {
+        if (!config.ldo) {
+            throw new Error(`Token alias ldo is not available on ${network}. Use a token address instead.`);
+        }
+        return getAddress(config.ldo);
+    }
+    throw new Error(`Unsupported token reference ${value}. Use one of ${TOKEN_ALIASES.join(', ')} or provide an explicit token address.`);
+}
+export function describeTokenReference(network, value) {
+    const resolved = resolveTokenReference(network, value);
+    return {
+        input: value,
+        resolved,
+        kind: resolved.toLowerCase() === NATIVE_TOKEN_ADDRESS.toLowerCase() ? 'native' : 'erc20',
+    };
+}

package/dist/uniswap/types.js

@@ -0,0 +1,6 @@
+export const UNISWAP_PROTOCOLS = ['V2', 'V3', 'V4', 'UNISWAPX', 'UNISWAPX_V2', 'UNISWAPX_V3'];
+export const UNISWAP_ROUTING_PREFERENCES = ['BEST_PRICE', 'FASTEST'];
+export const UNISWAP_ROUTINGS = ['CLASSIC', 'DUTCH_LIMIT', 'DUTCH_V2', 'DUTCH_V3', 'BRIDGE', 'LIMIT_ORDER', 'PRIORITY', 'WRAP', 'UNWRAP', 'CHAINED'];
+export const EXECUTABLE_UNISWAP_ROUTINGS = ['CLASSIC', 'BRIDGE', 'WRAP', 'UNWRAP'];
+export const UNISWAP_URGENCIES = ['normal', 'fast', 'urgent'];
+export const UNISWAP_TRADE_TYPES = ['EXACT_INPUT', 'EXACT_OUTPUT'];

package/lido.skill.md

@@ -0,0 +1,131 @@
+# Lido Skill
+
+## Mental model
+
+Lido staking on Ethereum turns ETH into `stETH`.
+
+`stETH` is a rebasing token.
+Its balance changes as Lido oracle reports rewards and penalties.
+The underlying accounting unit is shares, not displayed balance.
+If you are reasoning about long-term position behavior, shares are the stable anchor and displayed `stETH` balance is the rebased surface.
+
+`wstETH` is the wrapped, non-rebasing form of `stETH`.
+Its token balance stays fixed, while each unit of `wstETH` becomes redeemable for more `stETH` over time.
+That is why `wstETH` is the safer default for bridges, vaults, and DeFi integrations that do not handle rebasing tokens correctly.
+
+## When to use stETH vs wstETH
+
+Use `stETH` when:
+- you are staking directly on Ethereum and want the simplest canonical receipt token
+- you want rebases reflected directly in wallet balance
+- you may enter the withdrawal queue using `stETH`
+
+Use `wstETH` when:
+- you want a non-rebasing position representation
+- you are moving exposure into DeFi or across L2s like Base, Optimism, or Arbitrum
+- you need predictable token balances for automation logic
+
+## Safe operating patterns
+
+Always start with `dry_run=true`.
+Only switch to `dry_run=false` after the tool result clearly matches intent.
+
+A safe agent workflow is:
+- inspect setup
+- inspect the aggregated portfolio summary
+- run write preflight checks for the intended action
+- dry-run the write
+- execute with a small amount
+
+For wrap and unstake requests, approvals matter.
+If allowance is insufficient and `approve_if_needed=true`, the server may need to send an approval transaction before the main action.
+Treat approval plus action as a two-step write path.
+
+Use `lido_get_portfolio_summary` when you want a single view of balances, claimable withdrawals, and recent governance context.
+Use `lido_preflight_write_action` before any write when you want the agent to explain blockers, approvals, and the next safest step.
+
+## Staking and unstaking specifics
+
+Staking is immediate minting of `stETH` against ETH deposit.
+Unstaking is not immediate ETH redemption.
+On Lido, unstaking means creating withdrawal queue requests.
+Those requests mint `unstETH` NFTs in the queue.
+ETH is only claimable after finalization.
+A safe agent should never promise instant exit liquidity from the queue.
+
+## Rewards reasoning
+
+For `stETH`, balance growth comes from rebasing.
+For `wstETH`, token count stays constant and value accrues through the `stETH per wstETH` exchange rate.
+If calculating rewards over time, remember that pure on-chain balance deltas are only equal to rewards when there were no transfers in or out during the interval.
+Otherwise the result is net position change, not pure staking income.
+
+## Governance reasoning
+
+Lido DAO governance uses Aragon voting on Ethereum.
+Before voting, verify:
+- the target proposal id
+- whether the wallet can vote at the proposal snapshot
+- whether the intended action is yes or no
+- whether auto-execution on decision is appropriate
+
+Do not cast or execute governance actions without an explicit human instruction.
+
+## Swap and bridge reasoning
+
+The server exposes Uniswap-powered routing for same-chain swaps and cross-chain bridges.
+
+### Safety model for Uniswap routes
+
+The server uses a direct approval-then-swap flow with `x-permit2-disabled=true`.
+It does not require or accept Permit2 signatures.
+
+Always preflight first using `lido_preflight_uniswap_route`:
+- confirms API key availability
+- resolves token aliases (eth, steth, wsteth, or explicit addresses)
+- checks approval requirements on the source chain
+- reports the selected routing type and executability
+- identifies blockers before any transaction is attempted
+
+Execution defaults to `dry_run=true`:
+- dry run returns approval calldata if needed
+- dry run returns the swap/bridge transaction calldata for inspection
+- only execute live after explicit human confirmation
+
+### Routing types and executability
+
+Preflight surfaces the route type (CLASSIC, BRIDGE, WRAP, UNWRAP, UNISWAPX variants, etc.).
+The server can execute these routing types live:
+- CLASSIC (direct protocol pool swaps)
+- BRIDGE (cross-chain via bridge partners)
+- WRAP (wrapping native assets)
+- UNWRAP (unwrapping wrapped assets)
+
+UniswapX routes (DUTCH_LIMIT, DUTCH_V2, DUTCH_V3, PRIORITY) may appear in preflight results but are surfaced, not executed, by this server.
+
+### Approval handling
+
+If the source token is not native ETH and allowance is insufficient:
+- preflight reports `needs_approval: true`
+- with `approve_if_needed=true`, live execution sends approval before the swap
+- some tokens require a cancel-and-replace approval pattern; preflight surfaces this in the `cancel` field
+
+### Cross-chain bridge specifics
+
+Bridging is initiated by a source-chain transaction.
+After the source transaction mines, assets arrive on the destination chain asynchronously.
+
+Use `lido_get_uniswap_route_status` with the source chain and transaction hash to monitor progress.
+Do not assume instant destination-chain availability.
+
+### Key differences from Lido core actions
+
+- Uniswap routes execute on the source chain provided; Lido core writes execute on Ethereum
+- Uniswap routes use an external API for quote generation; Lido core actions use direct contract calls
+- Bridge routes require monitoring; Lido staking/wrapping are single-transaction outcomes
+
+## Network boundaries
+
+Ethereum mainnet is where core staking, wrapping, withdrawal queue actions, and governance live.
+L2s such as Base, Optimism, and Arbitrum primarily expose bridged `wstETH` for balance monitoring and position awareness.
+Do not assume L2 `wstETH` implies native staking or native Lido governance on that L2.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@drparadox05/lido-mcp-server",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "MCP server for Lido staking, wrapping, governance, and Uniswap-powered swaps/bridges with safety-first design.",
+  "main": "dist/index.js",
+  "bin": {
+    "lido-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*",
+    "lido.skill.md",
+    "README.md",
+    "DEMO.md",
+    ".env.example"
+  ],
+  "keywords": [
+    "mcp",
+    "lido",
+    "ethereum",
+    "staking",
+    "defi",
+    "uniswap",
+    "bridge",
+    "cursor",
+    "claude"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drparadox05/Lido-MCP-Server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/drparadox05/Lido-MCP-Server/issues"
+  },
+  "homepage": "https://github.com/drparadox05/Lido-MCP-Server#readme",
+  "engines": {
+    "node": ">=21"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "viem": "2.47.6",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "22.12.0",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3"
+  }
+}