@drparadox05/lido-mcp-server 0.1.0

package/.env.example

@@ -0,0 +1,7 @@
+LIDO_PRIVATE_KEY=0x_your_private_key_here
+ETHEREUM_RPC_URL=https://eth-mainnet.your-rpc.example
+BASE_RPC_URL=https://mainnet.base.org
+OPTIMISM_RPC_URL=https://mainnet.optimism.io
+ARBITRUM_RPC_URL=https://arb1.arbitrum.io/rpc
+UNISWAP_API_KEY=your_uniswap_api_key_here
+UNISWAP_UNIVERSAL_ROUTER_VERSION=2.0

package/DEMO.md

@@ -0,0 +1,145 @@
+# Demo Guide
+
+## Goal
+
+This guide gives a judge or developer a fast path to evaluate the Lido MCP server in Cursor or Claude Desktop.
+
+The strongest story is:
+
+- inspect setup
+- inspect the full Lido portfolio
+- preflight a write safely
+- dry-run the write
+- preflight a Uniswap bridge or swap route safely
+- dry-run the Uniswap route with approvals surfaced explicitly
+- inspect governance context
+
+## Recommended flow
+
+### 1. Check setup
+
+Prompt:
+
+```text
+Show my Lido MCP setup status.
+```
+
+Expected outcome:
+
+- confirms wallet configuration
+- confirms RPC availability
+- shows readable and writable networks
+
+### 2. Inspect the full portfolio
+
+Prompt:
+
+```text
+Show my aggregated Lido portfolio summary.
+```
+
+Expected outcome:
+
+- balances across Ethereum, Base, Optimism, and Arbitrum
+- total stETH-equivalent exposure
+- withdrawal queue status and claimable ETH
+- recent governance context
+- action recommendations
+
+### 3. Preflight a write before execution
+
+Prompt:
+
+```text
+Preflight wrapping 0.1 stETH into wstETH on Ethereum.
+```
+
+Expected outcome:
+
+- checks wallet presence
+- validates balance
+- checks allowance
+- states whether approval is required
+- recommends the next safe command
+
+### 4. Dry-run the actual write
+
+Prompt:
+
+```text
+Dry run wrapping 0.1 stETH into wstETH on Ethereum.
+```
+
+Expected outcome:
+
+- returns the simulated request
+- shows whether approval is part of the path
+- does not broadcast a transaction
+
+### 5. Inspect governance
+
+Prompt:
+
+```text
+Show the 5 most recent Lido governance proposals and whether my wallet can vote.
+```
+
+Expected outcome:
+
+- recent proposals
+- execution state
+- wallet voting eligibility if a wallet is configured
+
+### 6. Preflight a Uniswap bridge or swap route
+
+Prompt:
+
+```text
+Preflight a Uniswap route from ETH on Ethereum into wstETH on Base.
+```
+
+Expected outcome:
+
+- confirms Uniswap API readiness
+- resolves token aliases and source/destination chains
+- shows whether approval is required on the source chain
+- reports the selected routing type and whether the server can execute it live
+- recommends the next safe command
+
+### 7. Dry-run the Uniswap route
+
+Prompt:
+
+```text
+Dry run a Uniswap route from wstETH on Base into native ETH on Base.
+```
+
+Expected outcome:
+
+- returns approval transaction details if needed
+- returns the generated swap transaction calldata
+- does not broadcast any transaction
+- makes the route shape and gas expectations explicit before execution
+
+## Copy-paste prompt set
+
+```text
+Show my Lido MCP setup status.
+Show my aggregated Lido portfolio summary.
+Show bridgable destinations for wstETH on Ethereum.
+Preflight a Uniswap route from ETH on Ethereum into wstETH on Base.
+Dry run a Uniswap route from wstETH on Base into native ETH on Base.
+Preflight staking 0.01 ETH on Ethereum.
+Preflight wrapping 0.1 stETH into wstETH on Ethereum.
+Dry run wrapping 0.1 stETH into wstETH on Ethereum.
+Show my withdrawal requests and claimable ETH on Ethereum.
+Show the 5 most recent Lido governance proposals.
+```
+
+## What judges should notice
+
+- all write actions are safe by default because `dry_run=true`
+- the preflight tool turns raw contract actions into agent-friendly safety checks
+- the Uniswap route preflight exposes approval requirements and route compatibility before any source-chain transaction is sent
+- the portfolio summary tool gives a single high-signal view instead of forcing many separate calls
+- Ethereum is the canonical execution layer for Lido core actions while L2s provide read visibility for bridged assets

package/README.md

@@ -0,0 +1,252 @@
+ # Lido MCP Server
+
+ A reference MCP server for Lido that exposes real on-chain tools for:
+
+- staking ETH into `stETH`
+- wrapping and unwrapping `stETH` and `wstETH`
+- requesting and claiming withdrawals through the Lido withdrawal queue
+- balance and reward-aware position queries
+- Lido DAO governance proposal queries and voting
+- Uniswap-powered swaps and cross-chain bridge routing with approval-aware preflight and dry-run execution
+- agent-friendly discovery and mental-model guidance for safe tool selection
+
+The server uses direct contract calls through `viem`.
+It is not a REST wrapper.
+All write tools support `dry_run` and default to `true`.
+
+## Installation & usage
+
+**For users:** See [USER_GUIDE.md](USER_GUIDE.md) for complete setup instructions.
+
+**Quick start:**
+
+You don't need to manually install anything. Just add this to your MCP client config (Cursor, Claude Desktop, etc.):
+
+```json
+{
+  "mcpServers": {
+    "lido": {
+      "command": "npx",
+      "args": ["-y", "lido-mcp-server"],
+      "env": {
+        "LIDO_PRIVATE_KEY": "0x...",
+        "ETHEREUM_RPC_URL": "https://eth-mainnet.g.alchemy.com/v2/...",
+        "UNISWAP_API_KEY": "..."
+      }
+    }
+  }
+}
+```
+
+> [!TIP]
+> **Important:** To get the best out of this server, feed the `lido.skill.md` file to your AI agent (in custom instructions or workspace rules). This ensures the agent understands Lido's rebasing mechanics and safety patterns.
+
+**Configuration templates:**
+- [Example Config](mcp.config.example.json) - Standard configuration example
+
+## Project structure
+
+```text
+src/
+  config/
+    env.ts
+  lido/
+    abis.ts
+    advisor.ts
+    account.ts
+    clients.ts
+    governance.ts
+    index.ts
+    networks.ts
+    rewards.ts
+    setup.ts
+    staking.ts
+    types.ts
+    utils.ts
+    withdrawals.ts
+  server/
+    createServer.ts
+    index.ts
+  shared/
+    mcp.ts
+  uniswap/
+    api.ts
+    index.ts
+    tokens.ts
+    types.ts
+  index.ts
+```
+
+The repo is structured so contract metadata, runtime configuration, chain clients, business logic, and MCP transport wiring are separated.
+Sensitive environment access is centralized in `src/config/env.ts` instead of being scattered across the codebase.
+
+ ## Supported networks
+
+ - `ethereum`
+ - `base`
+ - `optimism`
+ - `arbitrum`
+
+ Core staking, withdrawal queue actions, wrapping, and governance execute on `ethereum`.
+ L2 networks are supported for balance-aware reads of bridged Lido assets.
+
+ ## Implemented MCP tools
+
+ - `lido_get_setup`
+ - `lido_get_agent_guide`
+ - `lido_get_account_overview`
+ - `lido_get_portfolio_summary`
+ - `lido_preflight_write_action`
+ - `lido_get_rewards`
+ - `lido_stake_eth`
+ - `lido_wrap_steth`
+ - `lido_unwrap_wsteth`
+ - `lido_request_unstake`
+ - `lido_get_withdrawal_requests`
+ - `lido_claim_withdrawals`
+ - `lido_get_governance_proposals`
+ - `lido_vote_on_proposal`
+ - `lido_execute_proposal`
+ - `lido_preflight_uniswap_route`
+ - `lido_execute_uniswap_route`
+ - `lido_get_uniswap_route_status`
+ - `lido_get_uniswap_bridgable_tokens`
+
+ ## Quick start
+
+ ### 1. Install dependencies
+
+ ```bash
+ npm install
+ ```
+
+### 2. Configure environment
+
+Copy `.env.example` to `.env` or export variables in your shell.
+
+Required for writes:
+
+- `LIDO_PRIVATE_KEY`
+- `ETHEREUM_RPC_URL`
+
+Useful variables:
+
+- `ETHEREUM_RPC_URL`
+- `BASE_RPC_URL`
+- `OPTIMISM_RPC_URL`
+- `ARBITRUM_RPC_URL`
+
+Required for Uniswap-powered route discovery and execution:
+
+- `UNISWAP_API_KEY`
+
+Optional for Uniswap route generation:
+
+- `UNISWAP_UNIVERSAL_ROUTER_VERSION`
+
+### 3. Build
+
+```bash
+npm run build
+```
+
+### 4. Run over stdio
+
+```bash
+npm start
+```
+
+For local development:
+
+```bash
+npm run dev
+```
+
+## Judge and developer quick prompts
+
+Use these prompts directly in Cursor or Claude after connecting the MCP server:
+
+```text
+Show my Lido MCP setup status.
+Show the Lido agent guide for staking.
+Show my aggregated Lido portfolio summary.
+Show bridgable destinations for wstETH on Ethereum.
+Preflight a Uniswap route from ETH on Ethereum into wstETH on Base.
+Dry run a Uniswap route from wstETH on Base into native ETH on Base.
+Preflight staking 0.01 ETH on Ethereum.
+Preflight wrapping 0.1 stETH into wstETH on Ethereum.
+Dry run wrapping 0.1 stETH into wstETH on Ethereum.
+Show my withdrawal requests and claimable ETH on Ethereum.
+Show the 5 most recent Lido governance proposals.
+```
+
+A fuller walkthrough lives in `DEMO.md`.
+
+## Cursor or Claude MCP configuration
+
+Use a stdio MCP entry that launches the server from this repo.
+
+Example:
+
+```json
+{
+  "mcpServers": {
+    "lido": {
+      "command": "node",
+      "args": ["/home/drparadox/synthesis_hack/dist/index.js"],
+      "env": {
+        "LIDO_PRIVATE_KEY": "0x...",
+        "ETHEREUM_RPC_URL": "https://eth-mainnet.your-rpc.example",
+        "BASE_RPC_URL": "https://mainnet.base.org",
+        "OPTIMISM_RPC_URL": "https://mainnet.optimism.io",
+        "ARBITRUM_RPC_URL": "https://arb1.arbitrum.io/rpc",
+        "UNISWAP_API_KEY": "your-uniswap-api-key"
+      }
+    }
+  }
+}
+```
+
+If you prefer running TypeScript directly during development, point the MCP client at `tsx` and `/home/drparadox/synthesis_hack/src/index.ts` instead.
+
+## Safety model
+
+- All write tools default to `dry_run=true`
+- `lido_get_setup` returns recommended first tools, safety defaults, quickstart prompts, and Uniswap API readiness metadata
+- `lido_get_agent_guide` returns the Lido mental model, network boundaries, workflow guidance, and topic-specific tool recommendations
+- `lido_preflight_write_action` can validate the path before a Lido-core write is even dry-run
+- `lido_preflight_uniswap_route` checks approval requirements, route type, and execution compatibility before a Uniswap swap or bridge is attempted
+- `lido_execute_uniswap_route` defaults to `dry_run=true` and uses a direct approval-then-swap flow with `x-permit2-disabled=true`
+- `lido_get_uniswap_route_status` can track the source-chain transaction status for swap and bridge routes after submission
+- Approval-dependent flows report when an approval is required before the main action can execute
+- Withdrawal requests are treated as queue entries, not instant ETH exits
+- Governance writes require the configured wallet to be eligible to act
+
+## Notes on rewards
+
+Lido rewards are not a simple claimable bucket.
+
+- `stETH` rewards appear through rebasing balances
+- `wstETH` rewards appear through an increasing conversion rate to `stETH`
+
+The `lido_get_rewards` tool can return current reward context or a net on-chain balance delta since a historical block.
+That historical delta should only be interpreted as pure staking rewards when the address had no transfers in or out during the interval.
+
+## Notes on unstaking
+
+Unstaking on Lido is a two-phase path:
+
+- request withdrawal from `stETH` or `wstETH`
+- wait for queue finalization and then claim ETH
+
+The server exposes both phases separately.
+
+## Skill file
+
+The repo includes `lido.skill.md`, which gives an agent the correct mental model for:
+
+- rebasing `stETH`
+- non-rebasing `wstETH`
+- L2 vs Ethereum responsibilities
+- safe approval and queue usage
+- governance caution

package/dist/config/env.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const PRIVATE_KEY_ENV_KEYS = ['LIDO_PRIVATE_KEY', 'WALLET_PRIVATE_KEY', 'PRIVATE_KEY'];
+function stripWrappingQuotes(value) {
+    if ((value.startsWith('"') && value.endsWith('"'))
+        || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function loadDotEnvFile() {
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    const envPath = resolve(currentDir, '../../.env');
+    if (!existsSync(envPath)) {
+        return;
+    }
+    const content = readFileSync(envPath, 'utf8');
+    for (const rawLine of content.split(/\r?\n/u)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#')) {
+            continue;
+        }
+        const separatorIndex = line.indexOf('=');
+        if (separatorIndex <= 0) {
+            continue;
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        const value = stripWrappingQuotes(line.slice(separatorIndex + 1).trim());
+        if (!key || process.env[key] !== undefined) {
+            continue;
+        }
+        process.env[key] = value;
+    }
+}
+loadDotEnvFile();
+export function getOptionalEnv(name) {
+    const value = process.env[name]?.trim();
+    return value && value.length > 0 ? value : undefined;
+}
+export function hasPrivateKeyConfigured() {
+    return PRIVATE_KEY_ENV_KEYS.some((name) => Boolean(getOptionalEnv(name)));
+}
+export function getPrivateKey() {
+    const value = PRIVATE_KEY_ENV_KEYS.map((name) => getOptionalEnv(name)).find((candidate) => Boolean(candidate));
+    if (!value) {
+        throw new Error(`No private key configured. Set ${PRIVATE_KEY_ENV_KEYS.join(', ')}.`);
+    }
+    if (!/^0x[0-9a-fA-F]{64}$/.test(value)) {
+        throw new Error('Configured private key is not a valid 32-byte hex string.');
+    }
+    return value;
+}

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server/createServer.js';
+async function main() {
+    process.stdin.resume();
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});