# Saros MCP Server

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](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**