# MCP NEAR Liquid Staking Server

A Model Context Protocol (MCP) server for interacting with liquid staking protocols on NEAR blockchain. Supports **Meta Pool** (stNEAR) and **Linear Protocol** (LiNEAR).

## Features

- **stake_near** - Stake NEAR tokens to receive liquid staking tokens (stNEAR or LiNEAR)
- **unstake** - Request unstaking of liquid tokens (starts the unbonding period)
- **withdraw** - Withdraw NEAR after the unstaking period completes
- **get_staking_info** - Query a user's staking position, balances, and pending withdrawals
- **get_pool_stats** - Get pool statistics including APY, TVL, exchange rate, and fees
- **list_validators** - List validators used by each staking pool

## Supported Protocols

| Protocol | Contract | Token | Typical APY |
|----------|----------|-------|-------------|
| Meta Pool | `meta-pool.near` | stNEAR | ~9-10% |
| Linear | `linear-protocol.near` | LiNEAR | ~10% |

## Installation

```bash
npm install
npm run build
```

## Usage

### As MCP Server

Start the server:

```bash
npm start
# or
node dist/index.js
```

The server communicates over stdio using the MCP protocol.

### MCP Configuration

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "near-liquid-staking": {
      "command": "node",
      "args": ["/path/to/mcp-near-liquid-staking/dist/index.js"]
    }
  }
}
```

## Tools

### stake_near

Stake NEAR tokens on Meta Pool or Linear.

```json
{
  "protocol": "meta-pool",
  "amount": "100",
  "accountId": "your-account.near"
}
```

Returns transaction data ready for signing. Estimated liquid tokens to receive are calculated based on current exchange rate.

### unstake

Request unstaking. Initiates the unbonding period (~48 hours / 4 epochs).

```json
{
  "protocol": "linear",
  "amount": "50",
  "accountId": "your-account.near"
}
```

### withdraw

Withdraw NEAR after the unstaking period completes.

```json
{
  "protocol": "meta-pool",
  "accountId": "your-account.near"
}
```

### get_staking_info

Get user's complete staking position.

```json
{
  "protocol": "meta-pool",
  "accountId": "your-account.near"
}
```

Response includes:
- `stakedBalance` - Total NEAR equivalent staked
- `liquidTokenBalance` - stNEAR/LiNEAR balance
- `pendingWithdrawal` - Amount in unbonding
- `withdrawableBalance` - Ready to withdraw
- `epochsUntilWithdrawable` - Epochs remaining until withdrawal

### get_pool_stats

Get pool statistics and current rates.

```json
{
  "protocol": "linear"
}
```

Response includes:
- `totalStaked` - Total NEAR staked in pool
- `exchangeRate` - Current NEAR per liquid token rate
- `apy` - Annual percentage yield
- `tvlNear` - Total value locked
- `fee` - Protocol fee percentage
- `validatorCount` - Number of validators

### list_validators

List validators used by the staking pool.

```json
{
  "protocol": "meta-pool"
}
```

## Development

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build
npm run build
```

## Testing

```bash
npm test
```

Tests cover:
- Pool stats retrieval for both protocols
- Staking info queries
- Stake/unstake/withdraw transaction preparation
- Validator listing
- Edge cases (small/large amounts)

## Architecture

```
src/
├── index.ts         # MCP server entry point with tool handlers
└── near-client.ts   # NEAR RPC client for staking operations
```

The server uses:
- `@modelcontextprotocol/sdk` - MCP server implementation
- `near-api-js` - NEAR blockchain interaction
- `zod` - Input validation

## Notes

- **Transaction Signing**: This server prepares transaction data but does not sign transactions. The consuming application must handle wallet integration and signing.
- **RPC Endpoints**: Uses public NEAR RPC endpoints. For production, consider using a dedicated RPC provider.
- **Exchange Rates**: Liquid token amounts are calculated based on current exchange rates which may vary slightly at execution time.

## License

MIT