<h1 align="center">cluby-mcp</h1>

<p align="center">
  <b>So an agent can read the protocol instead of being told about it.</b><br>
  Markets, positions and pre-trade quotes over stdio — computed by the same arithmetic the interface signs against.
</p>

<p align="center">
  <img alt="MCP" src="https://img.shields.io/badge/MCP-stdio-03926B?style=flat-square">
  <img alt="Node" src="https://img.shields.io/badge/node-22-0FAF83?style=flat-square">
  <img alt="Keys" src="https://img.shields.io/badge/holds_no_key-read_only-40C09C?style=flat-square">
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square"></a>
</p>

---

## The boundary is the point

```mermaid
flowchart LR
    A["Agent"] <-->|stdio| M["cluby-mcp<br/><i>reads only</i>"]
    M -->|"eth_call"| C["Robinhood Chain"]
    M -.->|"history only, optional"| I["Indexer"]
    A -->|"transaction"| W["User's wallet"]
    W --> C

    style M fill:#03926B,color:#fff
    style W fill:#8a6d1f,color:#fff
```

**It reads. It does not sign anything and holds no key.** An agent that wants to act gets the
numbers here and the transaction from a wallet its user controls.

That boundary is what lets this be run against a live protocol without anyone having to trust it.

Everything about the present comes from the chain. Only history and past liquidations need the
indexer, which is optional.

---

## Tools

| Tool | Answers |
|---|---|
| `list_markets` | Every market, with price, rates, and whether it actually exists on chain |
| `get_market` | One market in detail — oracle, LLTV, caps, utilisation, liquidity |
| `get_position` | A borrower's collateral, debt, health factor and liquidation price |
| `quote_borrow` | What a borrow would do, and whether it exceeds the cap the app enforces |
| `quote_multiply` | Exposure, debt, LTV, health factor and liquidation price of a leveraged position |
| `list_vaults` | The Earn side, with fee and timelock |
| `protocol_facts` | Addresses, fee split, LLTV tiers, how to take a free flash loan |

**The quotes are the same arithmetic the interface signs against**, not a second implementation that
can drift from it. Both import `@cluby/sdk`.

---

## Run it

```bash
pnpm install
CLUBY_RPC_URL=<rpc> pnpm start
```

Point a client at it:

```json
{
  "mcpServers": {
    "cluby": {
      "command": "node",
      "args": ["--experimental-strip-types", "/path/to/cluby-mcp/src/index.ts"],
      "env": { "CLUBY_RPC_URL": "https://rpc.mainnet.chain.robinhood.com" }
    }
  }
}
```

The public RPC is enough for everything except history.

---

## What a `quote_multiply` actually returns

Not a marketing number. The leverage a market can fund is bounded by exit liquidity as well as by
the tier, and the smaller bound wins:

$$\text{max multiple} = \min\left(\frac{1}{1 - \text{LLTV}},\ 1 + \frac{\text{liquidity}_{USD}}{\text{collateral value}_{USD}}\right)$$

An agent asking for 3× on a long-tail market gets told the market cannot fund it, and why — rather
than a quote that reverts when it is signed.

`bigint` values are serialised as strings, so a client never silently loses precision on a wei
amount.

---

## Layout

```
src/index.ts     tool definitions and the stdio server
src/markets.ts   describeMarket, describePosition, quoteBorrow, quoteMultiply, protocolFacts
src/chain.ts     the RPC client and the optional indexer fetch
vendor/          @cluby/config, @cluby/abi, @cluby/sdk
```

---

## Part of Cluby

| Repository | What it holds |
|---|---|
| **cluby-mcp** | ← you are here |
| [cluby-sdk](https://github.com/clubytech/cluby-sdk) | The arithmetic behind every quote |
| [cluby-lens](https://github.com/clubytech/cluby-lens) | The on-chain contract the reads go through |
| [cluby-oracles](https://github.com/clubytech/cluby-oracles) | Where the prices come from |

[cluby.cash](https://cluby.cash) · [@ClubyTech](https://x.com/ClubyTech)