liquidswap-mcp/README.md

# 🌊 Liquidswap MCP Server

A **Model Context Protocol (MCP) server** that provides comprehensive access to **Liquidswap** - the leading decentralized exchange on the **Aptos blockchain**. This server enables AI models and applications to interact with Liquidswap's pools, tokens, and user balances through a standardized interface.

## 🚀 Features

- **Real-time Data Access**: Get live information about tokens, pools, and user balances
- **Historical Analytics**: Access historical APR and TVL data for in-depth analysis
- **User Balance Tracking**: Query token balances for any Aptos address
- **MCP Standard Compliance**: Seamlessly integrates with MCP-compatible AI tools and applications
- **TypeScript Support**: Fully typed for better development experience

## 🛠️ Available Tools

### 1. **Get Tokens** (`get_tokens`)
Retrieves all tokens registered on Liquidswap.

**Parameters:** None  
**Returns:** Complete list of registered tokens with metadata (name, symbol, decimals, logo, etc.)

### 2. **Get Pools** (`get_pools`)  
Fetches all liquidity pools available on Liquidswap.

**Parameters:** None  
**Returns:** List of all registered pools including concentrated liquidity pools

### 3. **Get User Balances** (`get_balances_by_address`)
Queries token balances for a specific Aptos address.

**Parameters:**
- `address` (string): Aptos address to query balances for

**Returns:** Token balances with enriched metadata including LP token details

### 4. **Get Historical APRs** (`get_pools_historical_aprs`)
Retrieves historical Annual Percentage Rate (APR) data for all pools.

**Parameters:**
- `daysAgo` (number): Number of days back to fetch data (max: 365 days)

**Returns:** Historical APR data for all pools within the specified timeframe

### 5. **Get Historical TVLs** (`get_pools_historical_tvls`)
Fetches historical Total Value Locked (TVL) data for all pools.

**Parameters:**
- `daysAgo` (number): Number of days back to fetch data (max: 365 days)

**Returns:** Historical TVL data for all pools within the specified timeframe

## 📦 Installation

### Prerequisites
- **Node.js** (v18 or higher)
- **Yarn** package manager
- **Aptos API key** (for balance queries)

### Setup

1. **Clone the repository:**
```bash
git clone https://gitlab.mind-dev.com/ai-lab/liquidswap-mcp.git
cd liquidswap-mcp
```

2. **Install dependencies:**
```bash
yarn install
```

3. **Configure environment variables:**
Create a `.env` file in the root directory:
```bash
# Required for user balance queries
APTOS_API_KEY=your_aptos_api_key_here

# Optional: Custom Liquidswap API URL (defaults to https://api.liquidswap.com)
BE_URL=https://api.liquidswap.com

# Optional: SSE port (defaults to 3001)
SSE_PORT=3000
```

4. **Build the project:**
```bash
yarn build
```

5. **Start the server:**
```bash
yarn start
```

## ⚙️ Configuration

### MCP Client Configuration

Production deployed server url - [https://lsmcp.dev.mind-dev.com/sse](https://lsmcp.dev.mind-dev.com/sse)

To use this server with an MCP client, add the following configuration to your MCP settings:

```json
{
  "mcpServers": {
    "liquidswap-mcp": {
      "url": "https://lsmcp.dev.mind-dev.com/sse", // or replace with local hosted, http://localhost:3002/sse
      "env": {}
    }
  }
}
```

### Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `APTOS_API_KEY` | Aptos Labs API key for blockchain queries | Yes (for balance queries) | - |
| `BE_URL` | Liquidswap backend API URL | No | `https://api.liquidswap.com` |
| `SSE_PORT` | Server-Sent Events port for MCP transport | No | `3001` |

## 🔧 Development

### Available Scripts

```bash
# Build the project
yarn build

# Start the server
yarn start

# Run linting
yarn lint

# Fix linting issues
yarn lint:fix

# Format code
yarn format

# Development with auto-reload
yarn dev  # If available
```

### Project Structure

```
src/
├── core/           # Core Liquidswap API integration
├── tools/          # MCP tool implementations
│   ├── get-tokens/
│   ├── get-pools/
│   ├── get-balances-by-address/
│   ├── get-pools-historical-aprs/
│   └── get-pools-historical-tvls/
├── resources/      # MCP resources
├── transports/     # MCP transport layer
└── types/          # TypeScript type definitions
```

## 🌐 API Integration

This server integrates with:
- **Liquidswap API** (`https://api.liquidswap.com`) - For pools, tokens, and analytics data
- **Aptos GraphQL API** (`https://api.mainnet.aptoslabs.com/v1/graphql`) - For user balance queries

## 🤝 Usage Examples

Once configured with an MCP client, you can use natural language to interact with Liquidswap:

- *"Show me all available tokens on Liquidswap"*
- *"What are the current liquidity pools?"*
- *"Get the token balances for address 0x123..."*
- *"Show me the historical APR data for the last 30 days"*
- *"What was the TVL trend over the past week?"*

## 🔒 Security & Privacy

- API keys are handled securely through environment variables
- No sensitive data is logged or stored
- All requests are made directly to official Aptos and Liquidswap APIs
- The server operates in read-only mode with no transaction capabilities

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

## 👨‍💻 Author

**odiinnn**

## 🔗 Related Links

- [Liquidswap Website](https://liquidswap.com)
- [Aptos Blockchain](https://aptos.dev)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Aptos Labs API](https://aptos.dev/apis)

---

*Built with ❤️ for the Aptos ecosystem*