Enhance README with comprehensive documentation for Liquidswap MCP Server
- Expanded the README to include an overview of the Liquidswap MCP server and its features. - Added detailed sections on available tools, installation instructions, configuration, development scripts, and API integration. - Included usage examples and security considerations for better user guidance.
This commit is contained in:
odiinnn committed
1 parent
1edd44507c
commit
9f520dc860
1 file changed
+201
-2
@@ -1,7 +1,206 @@
|
|||||||
Liquidswap MCP server
|
# 🌊 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
|
||||||
```
|
```
|
||||||
yarn build
|
|
||||||
|
|
||||||
|
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
|
yarn start
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## ⚙️ Configuration
|
||||||
|
|
||||||
|
### MCP Client Configuration
|
||||||
|
|
||||||
|
To use this server with an MCP client, add the following configuration to your MCP settings:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"liquidswap-mcp": {
|
||||||
|
"command": "node",
|
||||||
|
"args": ["/path/to/liquidswap-mcp/build/index.js"],
|
||||||
|
"env": {
|
||||||
|
"SSE_PORT": "3000"
|
||||||
|
},
|
||||||
|
"disabled": false,
|
||||||
|
"autoApprove": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Replace `/path/to/liquidswap-mcp/build/index.js` with the actual path to your built server.
|
||||||
|
|
||||||
|
### 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*
|
||||||
Reference in new issue
Block a user