recon-crypto-mcp 0.1.0

package/dist/signing/walletconnect.js

@@ -0,0 +1,226 @@
+import { SignClient } from "@walletconnect/sign-client";
+import { getSdkError } from "@walletconnect/utils";
+import { join } from "node:path";
+import { CHAIN_IDS } from "../types/index.js";
+import { readUserConfig, patchUserConfig, resolveWalletConnectProjectId, getConfigDir, } from "../config/user-config.js";
+/**
+ * Default WalletConnect Cloud project ID. Users should provide their own via
+ * WALLETCONNECT_PROJECT_ID or `recon-crypto-mcp-setup` — the default is a placeholder
+ * that will 401 against production relay. We keep a constant here so the code
+ * compiles; `getProjectId()` will throw if a real ID is not set.
+ */
+const DEFAULT_PROJECT_ID = "";
+/**
+ * EVM namespace requested when proposing a session. We deliberately omit
+ * `personal_sign` and `eth_signTypedData_v4` — no tool in this server produces
+ * either, so requesting them would be an over-broad capability grant. Blind
+ * typed-data signing is the canonical Permit2 / off-chain-order phishing
+ * surface; scoping the session away from it means a compromised process can't
+ * issue those requests against a live pairing without reconnecting (which the
+ * user would see prompted on their device).
+ */
+export const REQUIRED_NAMESPACES = {
+    eip155: {
+        methods: [
+            "eth_sendTransaction",
+            "eth_signTransaction",
+            "eth_chainId",
+        ],
+        chains: Object.values(CHAIN_IDS).map((id) => `eip155:${id}`),
+        events: ["accountsChanged", "chainChanged"],
+    },
+};
+let client = null;
+let currentSession = null;
+/**
+ * Set when the last liveness check timed out (peer didn't respond within the
+ * window) rather than returning an explicit "session not found". We keep the
+ * local session record in that case — the peer may just be offline — but
+ * surface the ambiguity via `getSessionStatus()` so callers don't treat the
+ * session as confirmed-alive.
+ */
+let peerUnreachable = false;
+export function isPeerUnreachable() {
+    return peerUnreachable;
+}
+function getProjectId() {
+    const id = resolveWalletConnectProjectId(readUserConfig()) || DEFAULT_PROJECT_ID;
+    if (!id) {
+        throw new Error("No WalletConnect project ID configured. Set WALLETCONNECT_PROJECT_ID in your env or re-run `recon-crypto-mcp-setup`. " +
+            "Create a free project at https://cloud.walletconnect.com.");
+    }
+    return id;
+}
+export async function getSignClient() {
+    if (client)
+        return client;
+    // Persist WC symkey/pairing/session state under ~/.recon-crypto-mcp so it survives process exit.
+    // Without this, the SignClient defaults to an unstorage path in cwd — which Claude Code
+    // kills on exit, leaving the saved session topic useless (no keys to decrypt the relay).
+    const storageDbPath = join(getConfigDir(), "walletconnect.db");
+    client = await SignClient.init({
+        projectId: getProjectId(),
+        metadata: {
+            name: "Recon Crypto MCP",
+            description: "MCP server that prepares DeFi transactions for Ledger Live signing.",
+            url: "https://github.com/szhygulin/recon-crypto-mcp",
+            icons: [],
+        },
+        storageOptions: { database: storageDbPath },
+    });
+    // Attempt to restore the most recent session. Prefer the explicit topic from user config,
+    // but fall back to the most recent active session if the topic is missing or stale (can
+    // happen if the user manually edited config or the session expired and was renewed).
+    const cfg = readUserConfig();
+    const topic = cfg?.walletConnect?.sessionTopic;
+    const all = client.session.getAll();
+    if (topic) {
+        const match = all.find((s) => s.topic === topic);
+        if (match)
+            currentSession = match;
+    }
+    if (!currentSession && all.length > 0) {
+        currentSession = all[all.length - 1];
+        patchUserConfig({
+            walletConnect: {
+                sessionTopic: currentSession.topic,
+                pairingTopic: currentSession.pairingTopic,
+            },
+        });
+    }
+    // Verify the restored session is still live on the relay. Three outcomes:
+    //   - alive: peer ack'd, keep using it.
+    //   - dead:  peer rejected (session was ended on their side), drop it locally.
+    //   - unknown: ping timed out — peer is offline or the relay is slow. Keep
+    //              the record so a future launch (when peer is back online) can
+    //              resume without re-pairing, but flag `peerUnreachable` so
+    //              callers don't assume the session is usable.
+    if (currentSession) {
+        const liveness = await verifySessionAlive(client, currentSession.topic);
+        if (liveness === "dead") {
+            try {
+                await client.session.delete(currentSession.topic, getSdkError("USER_DISCONNECTED"));
+            }
+            catch {
+                // Session record may already be gone; ignore.
+            }
+            currentSession = null;
+            peerUnreachable = false;
+            patchUserConfig({
+                walletConnect: { sessionTopic: undefined, pairingTopic: undefined },
+            });
+        }
+        else {
+            peerUnreachable = liveness === "unknown";
+        }
+    }
+    return client;
+}
+/**
+ * Ping the peer over the relay with a short timeout. WC's ping resolves when
+ * the peer acknowledges; it rejects promptly if the peer has no matching
+ * session (explicit "dead"); and it hangs if the peer is offline (we surface
+ * that as "unknown" via the timeout branch, so callers can distinguish it
+ * from a confirmed rejection).
+ */
+async function verifySessionAlive(c, topic) {
+    const PING_TIMEOUT_MS = 5_000;
+    let timedOut = false;
+    try {
+        await Promise.race([
+            c.ping({ topic }),
+            new Promise((_, reject) => setTimeout(() => {
+                timedOut = true;
+                reject(new Error("ping timeout"));
+            }, PING_TIMEOUT_MS)),
+        ]);
+        return "alive";
+    }
+    catch {
+        return timedOut ? "unknown" : "dead";
+    }
+}
+/** Create a new pairing + session proposal. The returned URI is what the user scans in Ledger Live. */
+export async function initiatePairing() {
+    const c = await getSignClient();
+    const { uri, approval } = await c.connect({ requiredNamespaces: REQUIRED_NAMESPACES });
+    if (!uri)
+        throw new Error("WalletConnect did not return a pairing URI.");
+    return {
+        uri,
+        approval: (async () => {
+            const session = await approval();
+            currentSession = session;
+            patchUserConfig({
+                walletConnect: {
+                    sessionTopic: session.topic,
+                    pairingTopic: session.pairingTopic,
+                },
+            });
+            return session;
+        })(),
+    };
+}
+export function getCurrentSession() {
+    return currentSession;
+}
+/** Return the list of EVM accounts exposed by the connected wallet (across all namespaces). */
+export async function getConnectedAccounts() {
+    if (!currentSession)
+        await getSignClient(); // ensure restoration attempted
+    if (!currentSession)
+        return [];
+    const accounts = [];
+    const ns = currentSession.namespaces.eip155;
+    if (!ns)
+        return [];
+    for (const entry of ns.accounts) {
+        // format: "eip155:1:0xabc..."
+        const parts = entry.split(":");
+        if (parts.length === 3 && /^0x[a-fA-F0-9]{40}$/.test(parts[2])) {
+            accounts.push(parts[2]);
+        }
+    }
+    return accounts;
+}
+/** Send an `eth_sendTransaction` request. Ledger Live shows it, user signs on device, we get tx hash back. */
+export async function requestSendTransaction(tx) {
+    const c = await getSignClient();
+    if (!currentSession) {
+        throw new Error("No active WalletConnect session. Pair Ledger Live first via `pair_ledger_live` or `recon-crypto-mcp-setup`.");
+    }
+    const chainId = CHAIN_IDS[tx.chain];
+    const from = tx.from ?? (await getConnectedAccounts())[0];
+    if (!from)
+        throw new Error("Cannot determine sender address from WalletConnect session.");
+    const request = {
+        topic: currentSession.topic,
+        chainId: `eip155:${chainId}`,
+        request: {
+            method: "eth_sendTransaction",
+            params: [
+                {
+                    from,
+                    to: tx.to,
+                    data: tx.data,
+                    value: tx.value === "0" ? "0x0" : `0x${BigInt(tx.value).toString(16)}`,
+                    ...(tx.gasEstimate ? { gas: `0x${BigInt(tx.gasEstimate).toString(16)}` } : {}),
+                },
+            ],
+        },
+    };
+    const hash = (await c.request(request));
+    return hash;
+}
+export async function disconnect() {
+    const c = await getSignClient();
+    if (!currentSession)
+        return;
+    await c.disconnect({
+        topic: currentSession.topic,
+        reason: getSdkError("USER_DISCONNECTED"),
+    });
+    currentSession = null;
+    patchUserConfig({ walletConnect: { sessionTopic: undefined, pairingTopic: undefined } });
+}
+//# sourceMappingURL=walletconnect.js.map

package/dist/signing/walletconnect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walletconnect.js","sourceRoot":"","sources":["../../src/signing/walletconnect.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1,222 @@
+export type SupportedChain = "ethereum" | "arbitrum" | "polygon";
+export declare const SUPPORTED_CHAINS: readonly SupportedChain[];
+export type RpcProvider = "infura" | "alchemy" | "custom";
+/** Numeric chain IDs for the chains we support. */
+export declare const CHAIN_IDS: Record<SupportedChain, number>;
+export declare const CHAIN_ID_TO_NAME: Record<number, SupportedChain>;
+/** A token balance with optional USD valuation. */
+export interface TokenAmount {
+    token: `0x${string}`;
+    symbol: string;
+    decimals: number;
+    /** Raw integer amount as a decimal string (e.g. "1000000" for 1 USDC). */
+    amount: string;
+    /** Human-readable amount (e.g. "1.0" for 1 USDC). */
+    formatted: string;
+    valueUsd?: number;
+    priceUsd?: number;
+    /**
+     * True when we could not resolve a USD price for this token. `valueUsd` is
+     * `undefined` rather than 0, and portfolio totals will NOT include this
+     * balance — callers should flag it to the user instead of silently treating
+     * it as worthless.
+     */
+    priceMissing?: boolean;
+}
+/**
+ * Per-subsystem status reported alongside a portfolio summary, so callers can
+ * distinguish "no Aave position" (covered:true, positions empty) from "Aave
+ * fetch failed" (covered:false, errored:true) from "not attempted" (covered:
+ * false, errored:false — e.g. Morpho Blue, which requires caller-supplied
+ * market ids and so has no on-chain enumeration path from a wallet).
+ */
+export interface CoverageStatus {
+    covered: boolean;
+    errored?: boolean;
+    /** Free-form message explaining why `covered` is false when it is. */
+    note?: string;
+}
+export interface PortfolioCoverage {
+    aave: CoverageStatus;
+    compound: CoverageStatus;
+    morpho: CoverageStatus;
+    uniswapV3: CoverageStatus;
+    staking: CoverageStatus;
+    /** Number of token balances whose USD valuation could not be resolved. */
+    unpricedAssets: number;
+}
+export interface LendingPosition {
+    protocol: "aave-v3";
+    chain: SupportedChain;
+    collateral: TokenAmount[];
+    debt: TokenAmount[];
+    totalCollateralUsd: number;
+    totalDebtUsd: number;
+    netValueUsd: number;
+    /** Aave health factor (>1 safe, <1 liquidatable). Infinity if no debt. */
+    healthFactor: number;
+    /** Weighted average liquidation threshold (bps, e.g. 8250 = 82.5%). */
+    liquidationThreshold: number;
+    /** Weighted average loan-to-value (bps). */
+    ltv: number;
+}
+/**
+ * A Compound V3 (Comet) position, flattened enough to slot alongside Aave in a unified
+ * lending bucket. Kept as a thin projection of modules/compound/index.ts#CompoundPosition
+ * so the types module doesn't need to pull in compound internals.
+ */
+export interface CompoundLendingPosition {
+    protocol: "compound-v3";
+    chain: SupportedChain;
+    market: string;
+    marketAddress: `0x${string}`;
+    baseSupplied: TokenAmount | null;
+    baseBorrowed: TokenAmount | null;
+    collateral: TokenAmount[];
+    totalCollateralUsd: number;
+    totalDebtUsd: number;
+    totalSuppliedUsd: number;
+    netValueUsd: number;
+}
+/** Any lending/borrowing position reported by the portfolio aggregator. */
+export type LendingPositionUnion = LendingPosition | CompoundLendingPosition;
+export interface LPPosition {
+    protocol: "uniswap-v3";
+    chain: SupportedChain;
+    tokenId: string;
+    token0: TokenAmount;
+    token1: TokenAmount;
+    /** Fee tier in hundredths of a bip (500 = 0.05%, 3000 = 0.30%, 10000 = 1.0%). */
+    feeTier: number;
+    tickLower: number;
+    tickUpper: number;
+    currentTick: number;
+    inRange: boolean;
+    liquidity: string;
+    /**
+     * Fees that have been checkpointed into NonfungiblePositionManager.tokensOwed
+     * (e.g. by a prior collect/burn touch). Fees accrued since the last
+     * checkpoint are NOT included — to see the full collectable amount, the
+     * caller would need to simulate collect() against fork state. Treat this as
+     * a LOWER BOUND on what a collect would return.
+     */
+    tokensOwedCached0: TokenAmount;
+    tokensOwedCached1: TokenAmount;
+    /**
+     * USD value derived from token amounts computed at the current tick. This
+     * is an approximation: withdrawing the position at a different price would
+     * yield different amounts. Flagged as `valueUsdIsApproximate: true` so
+     * callers don't display this as a precise number.
+     */
+    totalValueUsd: number;
+    valueUsdIsApproximate: true;
+}
+export interface StakingPosition {
+    protocol: "lido" | "eigenlayer";
+    chain: SupportedChain;
+    stakedAmount: TokenAmount;
+    /** Current APR as a decimal (0.035 = 3.5%). */
+    apr?: number;
+    /** Optional delegation info (for EigenLayer). */
+    delegatedTo?: `0x${string}`;
+    /** Extra protocol-specific details (e.g. strategy address for EigenLayer). */
+    meta?: Record<string, string | number | boolean>;
+}
+export interface PrivilegedRole {
+    role: string;
+    holder: `0x${string}`;
+    isContract: boolean;
+    isMultisig: boolean;
+    hasTimelock: boolean;
+    timelockDelaySeconds?: number;
+}
+export interface SecurityReport {
+    address: `0x${string}`;
+    chain: SupportedChain;
+    isVerified: boolean;
+    isProxy: boolean;
+    implementation?: `0x${string}`;
+    admin?: `0x${string}`;
+    dangerousFunctions: string[];
+    privilegedRoles: PrivilegedRole[];
+}
+/** Per-wallet slice of a multi-wallet portfolio, or a stand-alone single-wallet summary. */
+export interface PortfolioSummary {
+    wallet: `0x${string}`;
+    chains: SupportedChain[];
+    walletBalancesUsd: number;
+    lendingNetUsd: number;
+    lpUsd: number;
+    stakingUsd: number;
+    totalUsd: number;
+    perChain: Record<SupportedChain, number>;
+    breakdown: {
+        native: TokenAmount[];
+        erc20: TokenAmount[];
+        lending: LendingPositionUnion[];
+        lp: LPPosition[];
+        staking: StakingPosition[];
+    };
+    coverage: PortfolioCoverage;
+}
+/** Multi-wallet portfolio aggregation. */
+export interface MultiWalletPortfolioSummary {
+    wallets: `0x${string}`[];
+    chains: SupportedChain[];
+    totalUsd: number;
+    walletBalancesUsd: number;
+    lendingNetUsd: number;
+    lpUsd: number;
+    stakingUsd: number;
+    perChain: Record<SupportedChain, number>;
+    perWallet: PortfolioSummary[];
+    coverage: PortfolioCoverage;
+}
+/** Unsigned transaction, ready to be sent to Ledger Live for signing. */
+export interface UnsignedTx {
+    chain: SupportedChain;
+    to: `0x${string}`;
+    data: `0x${string}`;
+    /** Value in wei as a decimal string (so JSON-safe). */
+    value: string;
+    from?: `0x${string}`;
+    /** Human-readable description (e.g. "Supply 1.0 USDC to Aave V3 on Ethereum"). */
+    description: string;
+    /** Decoded function name + args for display. */
+    decoded?: {
+        functionName: string;
+        args: Record<string, string>;
+    };
+    /** Estimated gas as a decimal string. */
+    gasEstimate?: string;
+    /** Estimated gas cost in USD. */
+    gasCostUsd?: number;
+    /** If this tx is a prerequisite (e.g. ERC-20 approve), the follow-up tx is in `next`. */
+    next?: UnsignedTx;
+    /**
+     * Opaque handle issued by the tx-store when the prepared tx is returned to
+     * the caller. `send_transaction` accepts ONLY this handle — raw calldata is
+     * not acceptable, which binds the signed tx to the previewed one and closes
+     * the prompt-injection → arbitrary-signing path.
+     */
+    handle?: string;
+}
+/** Shape of ~/.recon-crypto-mcp/config.json. */
+export interface UserConfig {
+    rpc: {
+        provider: RpcProvider;
+        /** API key for infura/alchemy. Ignored when provider === "custom". */
+        apiKey?: string;
+        /** Only used when provider === "custom". */
+        customUrls?: Partial<Record<SupportedChain, string>>;
+    };
+    etherscanApiKey?: string;
+    /** Optional 1inch Developer Portal API key for intra-chain swap-quote comparison. */
+    oneInchApiKey?: string;
+    walletConnect?: {
+        projectId?: string;
+        /** Topic of the active WC session (so we can resume after restart). */
+        sessionTopic?: string;
+        pairingTopic?: string;
+    };
+}

package/dist/types/index.js

@@ -0,0 +1,18 @@
+// Shared domain types used across all modules.
+export const SUPPORTED_CHAINS = [
+    "ethereum",
+    "arbitrum",
+    "polygon",
+];
+/** Numeric chain IDs for the chains we support. */
+export const CHAIN_IDS = {
+    ethereum: 1,
+    arbitrum: 42161,
+    polygon: 137,
+};
+export const CHAIN_ID_TO_NAME = {
+    1: "ethereum",
+    42161: "arbitrum",
+    137: "polygon",
+};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAI/C,MAAM,CAAC,MAAM,gBAAgB,GAA8B;IACzD,UAAU;IACV,UAAU;IACV,SAAS;CACD,CAAC;AAIX,mDAAmD;AACnD,MAAM,CAAC,MAAM,SAAS,GAAmC;IACvD,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,KAAK;IACf,OAAO,EAAE,GAAG;CACb,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAmC;IAC9D,CAAC,EAAE,UAAU;IACb,KAAK,EAAE,UAAU;IACjB,GAAG,EAAE,SAAS;CACf,CAAC"}

package/package.json

@@ -0,0 +1,134 @@
+{
+  "name": "recon-crypto-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for AI agents (Claude Code, Claude Desktop, Cursor) to manage a self-custodial crypto portfolio through a Ledger hardware wallet. Reads on-chain wallet balances, ENS, token prices, and DeFi positions across Ethereum/Arbitrum/Polygon (Aave V3, Compound V3, Morpho Blue, Uniswap V3 LP, Lido stETH, EigenLayer), surfaces liquidation/health-factor alerts and protocol risk scores, then prepares unsigned EVM transactions (supply, borrow, repay, withdraw, stake, unstake, native/ERC-20 send, and LiFi-routed swaps and cross-chain bridges) that the user signs on their Ledger device via WalletConnect — private keys never leave the hardware wallet.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "recon-crypto-mcp": "dist/index.js",
+    "recon-crypto-mcp-setup": "dist/setup.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "setup": "node dist/setup.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "anthropic",
+    "claude",
+    "claude-code",
+    "claude-desktop",
+    "cursor",
+    "ai-agent",
+    "ai-agents",
+    "agent-tools",
+    "llm-tools",
+    "ledger",
+    "ledger-live",
+    "ledger-nano",
+    "hardware-wallet",
+    "self-custody",
+    "non-custodial",
+    "walletconnect",
+    "walletconnect-v2",
+    "crypto",
+    "cryptocurrency",
+    "crypto-portfolio",
+    "portfolio-management",
+    "portfolio-tracker",
+    "wallet",
+    "wallet-management",
+    "web3",
+    "blockchain",
+    "defi",
+    "defi-portfolio",
+    "defi-agent",
+    "onchain",
+    "onchain-agent",
+    "transaction-signing",
+    "tx-signing",
+    "unsigned-transactions",
+    "ethereum",
+    "arbitrum",
+    "polygon",
+    "evm",
+    "erc20",
+    "erc-20",
+    "ens",
+    "aave",
+    "aave-v3",
+    "compound",
+    "compound-v3",
+    "morpho",
+    "morpho-blue",
+    "uniswap",
+    "uniswap-v3",
+    "lido",
+    "steth",
+    "eigenlayer",
+    "liquid-staking",
+    "restaking",
+    "lending",
+    "borrowing",
+    "liquidation",
+    "health-factor",
+    "yield",
+    "staking",
+    "staking-rewards",
+    "swap",
+    "dex-aggregator",
+    "bridge",
+    "cross-chain",
+    "lifi",
+    "li-fi",
+    "1inch",
+    "token-prices",
+    "defillama",
+    "etherscan",
+    "smart-contract-security",
+    "protocol-risk",
+    "risk-assessment",
+    "gnosis-safe",
+    "multisig",
+    "timelock"
+  ],
+  "homepage": "https://github.com/szhygulin/recon-crypto-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/szhygulin/recon-crypto-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/szhygulin/recon-crypto-mcp/issues"
+  },
+  "author": "Viacheslav Zhygulin",
+  "license": "MIT",
+  "dependencies": {
+    "@lifi/sdk": "^3.16.3",
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@walletconnect/sign-client": "^2.17.0",
+    "@walletconnect/utils": "^2.17.0",
+    "qrcode-terminal": "^0.12.0",
+    "viem": "^2.21.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/qrcode-terminal": "^0.12.2",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  }
+}