npm package: @pond3r/mcp-backtest
Description: Model Context Protocol (MCP) server for Pond3r DeFi yield strategy backtesting
Author: Pond3r
Latest version: 1.0.12

# Pond3r MCP Server

Model Context Protocol (MCP) server for Pond3r backtest functionality. This server allows AI assistants and other MCP clients to create, execute, and analyze DeFi yield strategy backtests.

## Features

- **Create Backtests**: Define custom yield strategies with filters, selection logic, and rebalancing rules
- **Execute Backtests**: Run backtests against historical DeFiLlama yields data
- **View Results**: Access detailed metrics, portfolio values, trades, and strategy analysis
- **Authentication**: Secure API access using x-api-key authentication

## Installation

### From npm (Recommended)

```bash
npm install -g @pond3r/mcp-backtest
```

### From Source

```bash
git clone https://github.com/Pond3rxyz/pond3r-mcp
cd pond3r-mcp
npm install
npm run build
```

## Configuration

The MCP server requires the following environment variables:

- `POND3R_API_KEY` (required): Your Pond3r API key for authentication

## Usage

### Running the Server

```bash
# Development mode with auto-reload
npm run dev

# Production mode
npm start
```

### Using with Claude Code (CLI/VS Code)

After publishing to npm, install globally:

```bash
npm install -g @pond3r/mcp-backtest
```

Then configure in your Claude Code settings (`~/.claude/config.json` or via the settings menu):

```json
{
  "mcpServers": {
    "pond3r": {
      "command": "pond3r-mcp",
      "env": {
        "POND3R_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Or use `npx` without global installation:

```json
{
  "mcpServers": {
    "pond3r": {
      "command": "npx",
      "args": ["@pond3r/mcp-backtest"],
      "env": {
        "POND3R_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**Get your API key**: Visit https://backtest.pond3r.xyz/api-keys

### Using with Claude Desktop

Add the following to your Claude Desktop MCP configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

#### If installed via npm:

```json
{
  "mcpServers": {
    "pond3r": {
      "command": "npx",
      "args": ["@pond3r/mcp-backtest"],
      "env": {
        "POND3R_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

#### If running from source:

```json
{
  "mcpServers": {
    "pond3r": {
      "command": "node",
      "args": ["/path/to/pond3r-monorepo/pond3r-mcp/build/index.js"],
      "env": {
        "POND3R_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Available Tools

### 1. create_backtest

Create a new backtest with strategy configuration.

**Parameters**:
- `name` (string, required): Name of the backtest
- `description` (string, optional): Description of the strategy
- `strategy` (string, required): Strategy type (e.g., "yield_optimizer", "momentum")
- `parameters` (object, required): Complete strategy configuration

**Example**:
```json
{
  "name": "Conservative Stablecoin Yield",
  "strategy": "yield_optimizer",
  "parameters": {
    "name": "Conservative Stablecoin Strategy",
    "backtest": {
      "startDate": "2024-01-01",
      "endDate": "2024-12-31",
      "initialCapital": 10000,
      "transactionFeePercent": 0.1,
      "slippagePercent": 0.05
    },
    "selection": {
      "mode": "simple",
      "simple": {
        "method": "highest_apy"
      }
    },
    "filters": {
      "blockchains": ["Ethereum", "Arbitrum"],
      "symbols": ["USDC", "USDT", "DAI"],
      "tvlMin": 1000000
    },
    "rebalancing": {
      "frequency": "daily",
      "hour": 0
    }
  }
}
```

### 2. list_backtests

List all backtests with pagination.

**Parameters**:
- `limit` (number, optional): Maximum number of results (default: 50)
- `offset` (number, optional): Number of results to skip (default: 0)

### 3. get_backtest

Get detailed information about a specific backtest.

**Parameters**:
- `id` (string, required): UUID of the backtest

### 4. execute_backtest

Execute a backtest and get results.

**Parameters**:
- `id` (string, required): UUID of the backtest to execute

### 5. get_backtest_results

Get all results for a backtest.

**Parameters**:
- `id` (string, required): UUID of the backtest

### 6. get_backtest_result_details

Get detailed information about a specific backtest result.

**Parameters**:
- `backtestId` (string, required): UUID of the backtest
- `resultId` (string, required): UUID of the result

### 7. delete_backtest

Delete a backtest and all its results.

**Parameters**:
- `id` (string, required): UUID of the backtest to delete

## Strategy Configuration Reference

### Backtest Parameters

```typescript
{
  startDate: string;           // "YYYY-MM-DD"
  endDate: string;             // "YYYY-MM-DD"
  initialCapital: number;      // USD amount
  transactionFeePercent: number; // e.g., 0.1 for 0.1%
  slippagePercent: number;     // e.g., 0.05 for 0.05%
}
```

### Selection Strategies

**Simple Mode** - Use predefined selection methods:
- `highest_apy`: Select pool with highest current APY
- `highest_apy_7d`: Select pool with best 7-day momentum
- `risk_adjusted`: Select pool with best risk-adjusted return
- `most_stable`: Select pool with most stable yield
- `best_momentum`: Select pool with best momentum
- `largest_tvl`: Select pool with largest TVL

```json
{
  "mode": "simple",
  "simple": {
    "method": "highest_apy"
  }
}
```

**Weighted Mode** - Custom scoring based on multiple metrics:

```json
{
  "mode": "weighted",
  "weighted": {
    "apy": 50,
    "tvl": 25,
    "momentum": 15,
    "stability": 10
  }
}
```

Note: Weights must sum to 100.

### Filters

Narrow down the pool universe:

```typescript
{
  blockchains?: string[];     // e.g., ["Ethereum", "Arbitrum"]
  projects?: string[];        // e.g., ["Aave", "Compound"]
  symbols?: string[];         // e.g., ["USDC", "USDT"]
  tvlMin?: number;           // Minimum TVL in USD
  tvlMax?: number;           // Maximum TVL in USD
  ilRisks?: boolean[];       // Filter by IL risk
  exposures?: string[];      // Filter by exposure types
}
```

### Rebalancing

Configure when and how often to rebalance:

```typescript
{
  frequency: "hourly" | "daily" | "weekly" | "monthly";
  dayOfWeek?: number;        // For weekly: 0=Sunday, 6=Saturday
  dayOfMonth?: number;       // For monthly: day of month (1-31)
  hour?: number;             // Hour of day (0-23)
  cooldownHours?: number;    // Minimum hours between rebalances
  conditions?: Array<{       // Additional rebalancing conditions
    metric: string;
    threshold: number;
    operator: string;
  }>;
  requireAllConditions?: boolean;
}
```

## Example Workflow

```typescript
// 1. Create a backtest
const backtest = await create_backtest({
  name: "My Strategy",
  strategy: "yield_optimizer",
  parameters: { /* ... */ }
});

// 2. Execute the backtest
const result = await execute_backtest({
  id: backtest.id
});

// 3. View detailed results
const details = await get_backtest_result_details({
  backtestId: backtest.id,
  resultId: result.id
});

// Results include:
// - metrics: Performance metrics (returns, Sharpe ratio, etc.)
// - output.portfolio_values: Time series of portfolio value
// - output.trades: List of all trades executed
// - output.pool_performance: Performance breakdown by pool
// - output.strategy_summary: High-level strategy analysis
// - output.baseline_comparison: Comparison vs. 4% APY baseline
```

## Authentication

The MCP server uses x-api-key authentication to communicate with the Pond3r backend API. Users must obtain an API key from their Pond3r account settings and configure it in the environment variables.

To generate an API key:
1. Log into your Pond3r account
2. Navigate to Settings > API Keys
3. Generate a new API key
4. Configure it in the MCP server environment

## Development

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development
npm run watch

# Run in development mode
npm run dev
```

## License

MIT