README.md•8.55 kB
# Saros MCP Server
> **Model Context Protocol (MCP) Server for Saros DeFi** - Exposes Saros SDK functionality as AI-accessible tools
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
## Overview
This project implements a **Model Context Protocol (MCP) server** that wraps the Saros DeFi SDK, enabling AI agents, bots, and dashboards to interact with Saros liquidity pools, farms, and analytics through natural language or simple tool calls.
## Features
### Core MCP Tools
- **`get_lp_positions`** - Retrieve all liquidity pool positions for a wallet
- **`simulate_rebalance`** - Simulate LP rebalancing based on IL threshold
- **`portfolio_analytics`** - Comprehensive portfolio metrics and risk assessment
- **`get_farm_positions`** - View farming positions and claimable rewards
- **`swap_quote`** - Get swap quotes with price impact and slippage
### Demo Clients
- **Test Client** - Command-line testing tool
- **Telegram Bot** - Interactive bot for portfolio management
## Quick Start
### Installation
```bash
cd saros-mcp-server
npm install
```
### Running the Server
```bash
# Start the MCP server
npm start
# Development mode with auto-reload
npm run dev
```
### Testing
```bash
# Run the test client
npm test
```
## Usage Examples
### Using with Claude Desktop
Add to your Claude Desktop MCP settings:
```json
{
"mcpServers": {
"saros": {
"command": "node",
"args": ["/path/to/saros-mcp-server/src/index.js"]
}
}
}
```
Then in Claude:
```
"Show me my LP positions for wallet HqB8Rf76fAwmd4qZpL81yB2SSLFzEgdoPwpWAUJ31ont"
"Analyze my portfolio for wallet HqB8Rf76fAwmd4qZpL81yB2SSLFzEgdoPwpWAUJ31ont"
"Get me a swap quote for 100 tokens from C98A4nkJXhpVZNAZdHUA95RpTF3T4whtQubL3YobiUX9 to EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v in pool 2wUvdZA8ZsY714Y5wUL9fkFmupJGGwzui2N74zqJWgty"
```
**Real Working Example:**
Wallet with actual LP positions: `HqB8Rf76fAwmd4qZpL81yB2SSLFzEgdoPwpWAUJ31ont` (5 active positions)
Known Saros Pools:
- C98/USDC Pool: `2wUvdZA8ZsY714Y5wUL9fkFmupJGGwzui2N74zqJWgty`
### Using with the Telegram Bot
1. Create a bot via [@BotFather](https://t.me/botfather)
2. Copy your bot token
3. Set environment variable:
```bash
export BOT_TOKEN="your_telegram_bot_token"
```
4. Run the bot:
```bash
node examples/telegram-bot.js
```
5. Chat with your bot:
```
/start
/wallet 5UrM9csUEDBeBqMZTuuZyHRNhbRW4vQ1MgKJDrKU1U2v
/positions
/rebalance 5
/analytics
```
### Programmatic Usage
```javascript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const transport = new StdioClientTransport({
command: "node",
args: ["src/index.js"],
});
const client = new Client({
name: "my-client",
version: "1.0.0",
}, {
capabilities: {},
});
await client.connect(transport);
// Call tools
const result = await client.callTool({
name: "get_lp_positions",
arguments: { wallet: "5UrM9csUEDBeBqMZTuuZyHRNhbRW4vQ1MgKJDrKU1U2v" },
});
console.log(result.content[0].text);
```
## Project Structure
```
saros-mcp-server/
├── src/
│ ├── index.js # Main MCP server
│ ├── services/
│ │ ├── pool-service.js # LP pool operations
│ │ ├── farm-service.js # Farming operations
│ │ └── analytics-service.js # Analytics & IL calculations
│ └── tools/
│ ├── get-lp-positions.js
│ ├── simulate-rebalance.js
│ ├── portfolio-analytics.js
│ ├── get-farm-positions.js
│ └── swap-quote.js
├── examples/
│ ├── test-client.js # Test client
│ └── telegram-bot.js # Telegram bot demo
├── package.json
└── README.md
```
## API Reference
### get_lp_positions
Get all liquidity pool positions for a wallet.
**Input:**
```json
{
"wallet": "string (Solana address)"
}
```
**Output:**
```
Found 2 LP position(s) for wallet: 5UrM9c...
Position 1:
- Pool: 2wUvdZ...
- LP Balance: 150.5
- Token 0: C98A4n...
- Token 1: EPjFWd...
```
### simulate_rebalance
Simulate rebalancing strategy based on impermanent loss threshold.
**Input:**
```json
{
"wallet": "string",
"threshold": "number (0-100)"
}
```
**Output:**
```
Rebalance Simulation for 5UrM9c...
IL Threshold: 5%
Positions Analyzed: 2
Recommendations: 1
1. Pool: 2wUvdZ...
- Current IL: 6.25%
- Severity: medium
- Action: Consider withdrawing - high IL detected
```
### portfolio_analytics
Get comprehensive portfolio analytics.
**Input:**
```json
{
"wallet": "string"
}
```
**Output:**
```
Portfolio Analytics for 5UrM9c...
Overview:
- Total Positions: 2
- Estimated Total Value: $1,250.00
- Average IL: 3.5%
Risk Assessment:
✅ Low Risk - Portfolio is performing well
```
### get_farm_positions
Get all farming/staking positions.
**Input:**
```json
{
"wallet": "string"
}
```
**Output:**
```
Farm Positions for 5UrM9c...
Total Farms: 1
Position 1:
- Farm: FW9hgA...
- LP Token: HVUeNV...
- Staked Amount: 100.0
- Pending Rewards:
• 50.5 C98
```
### swap_quote
Get swap quote with price impact.
**Input:**
```json
{
"poolAddress": "string",
"fromMint": "string",
"toMint": "string",
"amount": "number",
"slippage": "number (optional, default 0.5)"
}
```
**Output:**
```
Swap Quote
Input:
- Pool: 2wUvdZ...
- Amount: 100
Output:
- Expected Output: 150.5
- Minimum Output: 149.75
- Price Impact: 0.15%
- Slippage Tolerance: 0.5%
```
## Architecture
### MCP Server Layer
- Handles MCP protocol communication
- Exposes tools via stdio transport
- Routes requests to service layer
### Service Layer
- **PoolService**: LP positions, pool info, swap quotes
- **FarmService**: Staking positions, rewards
- **AnalyticsService**: IL calculations, portfolio metrics
### SDK Integration
- Uses `@saros-finance/sdk` for Solana/Saros interactions
- Wraps SDK functions with error handling
- Formats data for AI-friendly consumption
## Development
### Adding New Tools
1. Create tool handler in `src/tools/`:
```javascript
export async function myNewTool(args, services) {
const { param1, param2 } = args;
// Tool logic here
return {
content: [{
type: "text",
text: "Result text"
}]
};
}
```
2. Register in `src/index.js`:
```javascript
// In ListToolsRequestSchema handler
{
name: "my_new_tool",
description: "Tool description",
inputSchema: { /* schema */ }
}
// In CallToolRequestSchema handler
case "my_new_tool":
return await myNewTool(args, this.services);
```
### Testing
```bash
# Test with example wallet
node examples/test-client.js
# Manual testing
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node src/index.js
```
## Deployment
### Local Deployment
```bash
npm start
```
### Railway/Render
1. Create new service
2. Connect GitHub repo
3. Set build command: `npm install`
4. Set start command: `npm start`
### Docker (Optional)
```dockerfile
FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["npm", "start"]
```
## Roadmap
- [ ] Add DLMM-specific features (advanced orders, dynamic fees)
- [ ] Implement real-time price feeds
- [ ] Add transaction execution tools
- [ ] Multi-wallet management
- [ ] Historical performance tracking
- [ ] Web dashboard UI
## Contributing
Contributions welcome! Please:
1. Fork the repo
2. Create a feature branch
3. Commit changes
4. Submit a PR
## License
MIT License - see LICENSE file
## Hackathon Submission
**Project:** Saros MCP Server
**Category:** SDK Usage & Developer Tools
**Hackathon:** Saros $100K Hackathon
### Key Innovations
- First MCP server for Saros DeFi
- AI-native portfolio management
- Natural language DeFi interactions
- Foundation for autonomous trading agents
### Demo
- Test Client: `npm test`
- Telegram Bot: See examples/telegram-bot.js
- Video Walkthrough: [Link TBD]
## Resources
- [Saros Finance](https://saros.finance)
- [Saros SDK](https://github.com/coin98/saros-sdk)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP SDK Documentation](https://github.com/anthropics/mcp)
## Support
- GitHub Issues: [Report bugs](https://github.com/your-repo/issues)
- Telegram: [Community](https://t.me/saros_finance)
- Email: your-email@example.com
---
**Built with ❤️ for the Saros Hackathon**