{
  "markdown": "# echoledger-mcp\n\nEchoLedger's MCP server. Analyze **live** Uniswap V2/V3, Balancer, and\nCurve stableswap pools — positions, price moves, pool health, rug\nsignals, slippage, and depeg risk — or build a portable **State Twin**\nfor off-MCP analysis, from any MCP-compatible AI client. Reads real chain\nstate via a caller-supplied RPC; the endpoint itself is authless.\n\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-streamable--http-6ea8ff)](https://modelcontextprotocol.io)\n[![Python](https://img.shields.io/badge/Python-3.11+-3776ab)](https://www.python.org)\n[![arXiv](https://img.shields.io/badge/arXiv-2605.11522-b31b1b.svg)](https://arxiv.org/abs/2605.11522)\n[![smithery badge](https://smithery.ai/badge/ic3moore/echoledger)](https://smithery.ai/servers/ic3moore/echoledger)\n\nEndpoint: **`https://mcp.echoledger.ai/mcp`** (streamable-HTTP, authless).\n\n## Install\n\n### Claude Desktop\nSettings → Integrations → Add server.\nURL: `https://mcp.echoledger.ai/mcp`\n\n### Claude Code\n```bash\nclaude mcp add --transport http echoledger https://mcp.echoledger.ai/mcp\n```\n\n### Cursor\nSettings → MCP → Add new MCP server.\nName: `echoledger` · Type: `http` · URL: `https://mcp.echoledger.ai/mcp`\n\n### Smithery\nListed at [smithery.ai/servers/ic3moore/echoledger](https://smithery.ai/servers/ic3moore/echoledger) — connect via the Smithery gateway from any supported client.\n\n## Tools\n\nThe endpoint ships **11 tools** over live Uniswap V2/V3, Balancer\nweighted (2-asset), and Curve stableswap (2-asset) pools. Two surfaces:\n\n- **10 reactive primitives** — one question, one answer, one chain read.\n  Four of them also take a **vector** input (e.g. `price_change_pcts[]`,\n  `amounts_in[]`) to sweep a whole grid/curve in one call.\n- **`BuildStateTwin`** — returns a portable State Twin (the pool's state\n  as JSON) that a client rehydrates locally to run unlimited\n  counterfactuals **off the MCP, zero further RPC**.\n\nEvery call takes `pool_address`, `rpc_url`, and `pool_type`, plus an\noptional `chain_id` guard and `block_number` pin — nothing is stored.\nEach reactive tool is protocol-specific and **advertises only the\n`pool_type` values it accepts**; pointing one at an unsupported type\nreturns a clean error before any chain read.\n\n**Full reference — params, returns, and a verified example per tool:\n[`docs/TOOLS.md`](docs/TOOLS.md).**\n\n**Scope:** the Balancer tools cover **2-asset weighted** pools; the\nstableswap tools cover **2-asset plain Curve** pools (rate-bearing pools\n— metapools, LSD — are a later release). A `stableswap` tool pointed at a\n3-coin or rate-bearing pool fails cleanly.\n\n### Uniswap V2/V3\n\n#### `AnalyzePosition`\nPnL decomposition for an LP position — impermanent loss, fees, and net.\n\n> \"Analyze my position in the V3 USDC/ETH pool.\"\n\n#### `SimulatePriceMove`\n\"What if price moves X%?\" — projected reserves, position value, and IL.\n\n> \"If ETH drops 20%, what happens to my V3 ETH/DAI position?\"\n\n#### `CheckPoolHealth`\nTVL, reserves, LP concentration, and recent activity for a pool.\n\n> \"Is this V3 pool healthy?\"\n\n#### `DetectRugSignals`\nThreshold-based rug flags on a pool's on-chain state.\n\n> \"Any rug signals on this V2 pair?\"\n\n#### `CalculateSlippage`\nSlippage, price impact, and max trade size for a given trade.\n\n> \"How much slippage on a 50 ETH buy in this V3 pool?\"\n\n### Balancer (2-asset weighted)\n\n#### `AnalyzeBalancerLP`\nPnL decomposition for a 2-asset Balancer weighted-pool position, using\nthe weighted-pool IL formula where the token weight shapes IL magnitude.\n\n> \"How is my 80/20 BAL/WETH Balancer position doing?\"\n\n#### `SimulateBalancerMove`\n\"What if the base token moves X%?\" — projected value and IL on a 2-asset\nweighted pool, weight-aware.\n\n> \"If BAL drops 30%, what happens to my BAL/WETH Balancer LP?\"\n\n### Curve stableswap (2-asset plain)\n\n#### `AnalyzeStableswapLP`\nPnL decomposition for a 2-asset Curve stableswap position via the\namplified-invariant IL formula — small depegs can produce outsized IL at\nhigh A.\n\n> \"Analyze my position in the crvUSD/USDC pool.\"\n\n#### `SimulateStableswapMove`\n\"What if the peg shifts X%?\" — projected value and IL on a 2-asset\nstableswap pool. At high A, large shocks may be physically unreachable\n(returned as null).\n\n> \"What happens to my USDC/DAI Curve LP if USDC depegs 2%?\"\n\n#### `AssessDepegRisk`\nIL across a ladder of depeg levels (default 2%, 5%, 10%, 20%, 50%) for a\n2-asset stableswap position, with an optional constant-product benchmark.\n\n> \"How exposed is my crvUSD/USDC position to a depeg?\"\n\n### State twin builder (all four pool types)\n\n#### `BuildStateTwin`\nReads a pool once and returns a **portable State Twin** — the pool's state\nas JSON (`__type__` + fields + a `content_hash`). A client rehydrates it\nlocally and runs unlimited counterfactuals (price moves, IL, slippage)\n**off the MCP, with zero further RPC** — build once, run N. Spans all four\npool types. See the twin round-trip in [`docs/TOOLS.md`](docs/TOOLS.md) and\nthe [`echoledger` package](https://github.com/echoledger/echoledger).\n\n> \"Build me a reusable twin of the USDC/ETH 0.05% pool.\"\n\n*(Honest gap: it's a single-block STATE twin — history-derived health\nmetrics stay server-side reads inside `CheckPoolHealth`/`DetectRugSignals`.)*\n\n## How it works\n\n`echoledger-mcp` reads **live** Uniswap V2/V3, Balancer, and Curve\nstableswap pool state through a caller-supplied RPC endpoint (BYO-RPC,\npassed per tool call). The endpoint is **authless** — no API key, no\naccount. Nothing is logged or stored; each call pulls state, runs the\nanalysis, and returns a typed result.\n\nThe analytics are powered by open-source [DeFiPy](https://defipy.org) —\nthe same primitives, twin, and tools that run against synthetic recipes,\nnow pointed at real pools. **The math is open; the reports are paid.**\n\n## Roadmap\n\n- **v0.2 — Balancer & Stableswap live reads** ✓ shipped. The 5\n  Balancer/Stableswap tools went live on DeFiPy 2.2's LiveProviders\n  (2-asset weighted + 2-asset plain Curve).\n- **v0.2.2 — honest schemas, vectors & the twin builder** ✓ shipped.\n  Per-tool `pool_type` enums; vectorized scenario inputs on the four\n  scenario tools; and `BuildStateTwin` — the 11th tool — for portable,\n  off-MCP twin analysis.\n- **N-asset & rate-bearing pools** — 3-asset Balancer, N-coin and\n  rate-bearing (metapool/LSD) Curve, once the upstream DeFiPy primitives\n  extend past 2 assets.\n- **Distribution polish** — OCI-package listing, DNS-verified namespace,\n  and OIDC auto-publish.\n\n## Develop\n\n```bash\npython -m venv .venv && source .venv/bin/activate\npip install -e \".[dev]\"\n```\n\nRun the server over streamable HTTP (binds to `$PORT`, default 8080):\n```bash\nPORT=8080 python -m echoledger_mcp.server      # endpoint at http://localhost:8080/mcp\n```\n\nOr over stdio for a local MCP Inspector smoke-test:\n```bash\npython -m echoledger_mcp.server --stdio\nnpx @modelcontextprotocol/inspector python -m echoledger_mcp.server --stdio\n```\n\nTests (offline — fake provider + real twin/primitives):\n```bash\npytest tests/\n```\n\nLive-RPC gate (real mainnet Uniswap V2/V3, Balancer, and Curve pools;\nneeds your own RPC):\n```bash\nECHOLEDGER_TEST_RPC_URL=\"https://eth-mainnet.example/v2/<key>\" pytest tests/test_live.py -v\n```\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).\n\nThis project adapts code from [DeFiPy](https://defipy.org) (Apache-2.0).\n\n## See also\n\n- DeFiPy (open-source substrate): https://defipy.org\n- EchoLedger: https://echoledger.ai\n- State Twins paper: https://arxiv.org/abs/2605.11522\n",
  "bytes": 7553,
  "sha": "0fc48e10f24fe2d7b336a3874c9201c6afbc221631be7134965cddab74c3a1d9",
  "repo_slug": "echoledger/echoledger-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_icmoore_echoledger_mcp_79ac1f3a/readme"
}