# 🤖 Polymarket MCP Bot Analyst

> **MCP server for analyzing successful trading bots on Polymarket** — discover top traders, classify their strategies with AI, and detect bots on the world's largest prediction market.

[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?logo=typescript)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)
[![Node.js](https://img.shields.io/badge/Node.js-22+-green?logo=node.js)](https://nodejs.org/)
[![CI](https://github.com/DzimaSh/polymarket-mcp-bot-analyst/actions/workflows/ci.yml/badge.svg)](https://github.com/DzimaSh/polymarket-mcp-bot-analyst/actions/workflows/ci.yml)
[![Release](https://github.com/DzimaSh/polymarket-mcp-bot-analyst/actions/workflows/release.yml/badge.svg)](https://github.com/DzimaSh/polymarket-mcp-bot-analyst/actions/workflows/release.yml)

---

## 📋 Table of Contents

- [Overview](#overview)
- [Architecture](#architecture)
- [Tools](#tools)
- [Getting Started](#getting-started)
- [Connect to Claude Desktop](#connect-to-claude-desktop)
- [Run the Test Suite](#run-the-test-suite)
- [Project Structure](#project-structure)
- [Configuration](#configuration)

---

## Overview

This project implements a **Model Context Protocol (MCP) server** that exposes three powerful tools for analyzing trading activity on [Polymarket](https://polymarket.com). It combines real-time leaderboard data from Polymarket's Data API with LLM-powered strategy classification via OpenAI.

### Key Features

- 🏆 **Top Trader Discovery** — Fetch leaderboard rankings by timeframe
- 🧠 **AI Strategy Analysis** — Classify strategies (arbitrage, market-making, etc.) using GPT-4o-mini
- 🤖 **Bot Detection** — Heuristic + LLM-based identification of automated traders
- 📊 **Batch Reporting** — Concurrent analysis of multiple profiles
- 🔄 **Resilient API Layer** — Exponential backoff, rate-limit handling (429 + Retry-After), graceful fallbacks

---

```mermaid
graph TD
    subgraph Client ["Client Layer"]
        MCP_Client["MCP Client (e.g., Claude Desktop)"]
    end

    subgraph Server ["MCP Server Layer"]
        index["index.ts (McpServer)"]
        Validation["Zod Validation"]
    end

    subgraph Tools ["Tool Handlers"]
        Traders["traders.ts (find_top_traders)"]
        Analysis["analysis.ts (analyze_trader_strategy)"]
        Reports["reports.ts (generate_batch_report)"]
    end

    subgraph Services ["External Services & Utils"]
        PAPI["api/polymarket.ts (Polymarket Data API)"]
        LLM["utils/llm.ts (OpenAI GPT-4o-mini)"]
    end

    MCP_Client -- "stdio (JSON-RPC)" --> index
    index --> Validation
    Validation --> Traders
    Validation --> Analysis
    Validation --> Reports

    Traders --> PAPI
    Analysis --> PAPI
    Analysis --> LLM
    Reports --> Analysis
    Reports --> PAPI

    style Client fill:#f9f,stroke:#333,stroke-width:2px
    style Server fill:#bbf,stroke:#333,stroke-width:2px
    style Tools fill:#dfd,stroke:#333,stroke-width:2px
    style Services fill:#ffd,stroke:#333,stroke-width:2px
```

### Tool Execution Flow

```mermaid
sequenceDiagram
    participant C as MCP Client
    participant S as MCP Server
    participant T as Tool Handler
    participant P as Polymarket API
    participant L as OpenAI LLM

    C->>S: Call "analyze_trader_strategy"
    S->>S: Validate Input (Zod)
    S->>T: handleAnalyzeStrategy(profile_id)
    T->>P: Fetch Profile Data & PnL
    P-->>T: User Data
    T->>P: Fetch Trade History
    P-->>T: Trade History
    T->>L: Classify strategy (history)
    L-->>T: strategy_analysis (JSON)
    T-->>S: strategy_result
    S-->>C: Tool Response (JSON)
```


---

## Tools

### 1. `find_top_traders`

Fetch top-performing traders from the Polymarket leaderboard with bot detection.

| Parameter   | Type    | Description                           |
|-------------|---------|---------------------------------------|
| `limit`     | integer | Number of traders (1–50)              |
| `timeframe` | string  | `"7d"`, `"30d"`, or `"all_time"`      |

**Output:** `Array<{ profile_id, pnl, is_bot }>`

### 2. `analyze_trader_strategy`

Deep-dive analysis of a single trader using trade history + LLM classification.

| Parameter    | Type   | Description                              |
|--------------|--------|------------------------------------------|
| `profile_id` | string | Wallet address (`0x…`) or username (`@name`) |

**Output:** `{ strategy_description, risk_level, risk_justification, success_score, is_bot }`

### 3. `generate_batch_report`

Concurrent analysis of multiple profiles with error-resilient execution.

| Parameter     | Type     | Description                     |
|---------------|----------|---------------------------------|
| `profile_ids` | string[] | Array of profile IDs (1–50)     |

**Output:** `Array<{ profile_id, pnl, strategy_description, risk_level, risk_justification, success_score, is_bot }>`

---

## Getting Started

### Prerequisites

- **Node.js** ≥ 22
- **npm** ≥ 10
- **OpenAI API key** (for strategy analysis)

### Installation

```bash
# Clone the repository
git clone <your-repo-url>
cd polymarket-mcp-bot-analyst

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY
```

### Build & Run

```bash
# Build TypeScript
npm run build

# Start the MCP server (stdio transport)
npm start

# Or run directly with tsx (development)
npm run dev
```

---

## Connect to Claude Desktop

Add this server to your Claude Desktop configuration:

### macOS

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "polymarket-bot-analyst": {
      "command": "node",
      "args": ["/absolute/path/to/polymarket-mcp-bot-analyst/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}
```

### Windows

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "polymarket-bot-analyst": {
      "command": "node",
      "args": ["C:\\path\\to\\polymarket-mcp-bot-analyst\\dist\\index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}
```

After saving, **restart Claude Desktop**. The three tools will appear in the tools menu (🔨 icon).

---

## Run the Test Suite

The test runner executes all three tools against the live Polymarket API and generates the required JSON artifacts:

```bash
npm run test:run
```

This produces:

| File                       | Description                                     |
|----------------------------|-------------------------------------------------|
| `test_run.json`            | Full execution log with data for 3+ traders     |
| `performance_report.json`  | Latency metrics for each endpoint               |
| `my_report.json`           | Architectural description of each endpoint      |

---

## Project Structure

```
polymarket-mcp-bot-analyst/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types.ts              # Shared interfaces & config
│   ├── api/
│   │   └── polymarket.ts     # Polymarket Data API wrapper
│   ├── tools/
│   │   ├── traders.ts        # find_top_traders handler
│   │   ├── analysis.ts       # analyze_trader_strategy handler
│   │   └── reports.ts        # generate_batch_report handler
│   ├── utils/
│   │   └── llm.ts            # OpenAI LLM integration
│   └── test-run.ts           # Artifact generator script
├── test_run.json             # Generated test run log
├── performance_report.json   # Generated latency metrics
├── my_report.json            # Generated architecture report
├── package.json
├── tsconfig.json
├── .env.example
└── .gitignore
```

---

## Configuration

| Environment Variable | Required | Description                      |
|---------------------|----------|----------------------------------|
| `OPENAI_API_KEY`    | Yes      | OpenAI API key for GPT-4o-mini   |

### Internal Constants (in `src/types.ts`)

| Constant                       | Default   | Description                          |
|-------------------------------|-----------|--------------------------------------|
| `POLYMARKET_API_BASE`         | `https://data-api.polymarket.com` | API base URL |
| `REQUEST_TIMEOUT_MS`          | `15000`   | HTTP request timeout                 |
| `MAX_RETRIES`                 | `3`       | Max retry attempts per request       |
| `RETRY_BASE_DELAY_MS`        | `1000`    | Base delay for exponential backoff   |
| `BOT_TRADE_THRESHOLD`        | `200`     | Min trades to flag as bot            |
| `BOT_TRADES_PER_HOUR_THRESHOLD` | `10`  | Min trades/hour for bot flag         |

---

## License

MIT