# Sandcastle MCP

A read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for Sandcastle leveraged liquidity positions.

It gives MCP clients structured access to curated Sandcastle deployments, live Uniswap V3 and Morpho market state, owner position health, and concentrated-liquidity payoff simulation on Robinhood Chain.

## Tools

| Tool | What it returns |
| --- | --- |
| `list_markets` | Curated markets, tokens, pools, factories, oracles, LLTVs, and market IDs |
| `get_market` | Live pool price/liquidity and stored Morpho supply, borrow, and utilization |
| `get_positions` | Active Position Accounts for an owner, with NFT inventory, debt, equity, leverage, and oracle-based health |
| `simulate_payoff` | LP value, debt value, equity, PnL, and return on equity across terminal prices |

The server also exposes `sandcastle://deployments/robinhood` as a static MCP resource.

## Safety boundary

This server cannot sign or submit transactions. It contains no wallet, private-key, approval, swap, borrow, repay, rebalance, or liquidation methods. Its network activity is limited to JSON-RPC reads and a public GraphQL index.

The USD figures and payoff curves are estimates:

- USDG is treated as $1.
- Token USD prices use current configured pool spot prices.
- Morpho totals are the values stored at the market's last update.
- Payoff simulation excludes fees, interest, rewards, slippage, gas, and liquidation penalties.

Do not use the outputs as executable quotes or transaction parameters.

## Requirements

- Node.js 20 or newer
- npm

## Install and build

```bash
git clone https://github.com/Gnome101/sandcastle-mcp.git
cd sandcastle-mcp
npm install
npm run build
```

The default public RPC and public Sandcastle subgraph work without credentials. You can override either endpoint:

```bash
export ROBINHOOD_RPC_URL=https://your-robinhood-chain-rpc.example
export SANDCASTLE_SUBGRAPH_URL=https://your-subgraph.example/graphql
```

## Connect from Codex

Add this to `~/.codex/config.toml`, replacing the path with the absolute path to your clone:

```toml
[mcp_servers.sandcastle]
command = "node"
args = ["/absolute/path/to/sandcastle-mcp/dist/src/index.js"]
```

To pass a private RPC through the MCP process:

```toml
[mcp_servers.sandcastle]
command = "node"
args = ["/absolute/path/to/sandcastle-mcp/dist/src/index.js"]
env_vars = ["ROBINHOOD_RPC_URL"]
```

Restart Codex after changing the configuration.

## Connect from Claude Desktop

Add the server under `mcpServers` in Claude Desktop's configuration:

```json
{
  "mcpServers": {
    "sandcastle": {
      "command": "node",
      "args": ["/absolute/path/to/sandcastle-mcp/dist/src/index.js"]
    }
  }
}
```

## Development

```bash
npm run typecheck
npm test
npm run smoke
```

`npm test` exercises the math and the actual MCP tool protocol through linked in-memory client/server transports. `npm run smoke` reads the primary WETH/USDG pool and Morpho market from Robinhood Chain.

To inspect the server interactively:

```bash
npx @modelcontextprotocol/inspector --web node dist/src/index.js
```

## Current scope

The initial release covers the seven curated Uniswap V3 markets currently configured by Sandcastle on Robinhood Chain (chain ID 4663). Uniswap V4 and transaction execution are outside this release.

## License

[MIT](LICENSE)