Skip to content

Latest commit

 

History

History
437 lines (323 loc) · 8.35 KB

README.md

File metadata and controls

437 lines (323 loc) · 8.35 KB

Saros MCP Server

Model Context Protocol (MCP) Server for Saros DeFi - Exposes Saros SDK functionality as AI-accessible tools

License: MIT Node.js Version

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

cd saros-mcp-server
npm install

Running the Server

# Start the MCP server
npm start

# Development mode with auto-reload
npm run dev

Testing

# Run the test client
npm test

Usage Examples

Using with Claude Desktop

Add to your Claude Desktop MCP settings:

{
  "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
  2. Copy your bot token
  3. Set environment variable:
export BOT_TOKEN="your_telegram_bot_token"
  1. Run the bot:
node examples/telegram-bot.js
  1. Chat with your bot:
/start
/wallet 5UrM9csUEDBeBqMZTuuZyHRNhbRW4vQ1MgKJDrKU1U2v
/positions
/rebalance 5
/analytics

Programmatic Usage

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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/:
export async function myNewTool(args, services) {
  const { param1, param2 } = args;

  // Tool logic here

  return {
    content: [{
      type: "text",
      text: "Result text"
    }]
  };
}
  1. Register in src/index.js:
// 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

# 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

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)

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

Support

Built with ❤️ for the Saros Hackathon