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
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
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