louiza-labs/fresh-pears

fresh-pears

PairPulse — Real-time DEX pair discovery and analysis for AI-native crypto tooling via MCP (Model Context Protocol)

fresh-pears is an MCP server that monitors decentralized exchange (DEX) pair creation events on Ethereum and Base. It dynamically discovers factory contracts and provides AI agents with real-time access to new liquidity pools for memecoin tracking, arbitrage opportunities, and on-chain analysis.

Features

• 🔍 Dynamic Factory Discovery — Automatically discovers active DEX factories via Etherscan/BaseScan APIs
• ⚡ Real-time Monitoring — Tracks Uniswap V2 and V3 pair/pool creation events
• 🌐 Multi-chain Support — Ethereum Mainnet and Base networks
• 🤖 MCP Integration — Native Model Context Protocol server for AI agent tooling
• 🛡️ Heuristic Analysis — Built-in safety scoring for discovered pairs
• 🚀 Fast & Lightweight — Built with Bun and TypeScript

Installation

npm install fresh-pears
# or
bun add fresh-pears

Prerequisites

• Bun runtime (recommended) or Node.js 18+
• Ethereum Mainnet RPC endpoint
• Base Mainnet RPC endpoint
• Etherscan API key (optional, for factory discovery)
• Basescan API key (optional, for factory discovery)

Quick Start

1. Install Dependencies

bun install

2. Set Environment Variables

Create a .env file or export variables:

# Required: RPC endpoints
export RPC_ETHEREUM=https://mainnet.infura.io/v3/YOUR_KEY
export RPC_BASE=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY

# Optional: For dynamic factory discovery
export ETHERSCAN_API=your_etherscan_api_key
export BASESCAN_API=your_basescan_api_key

3. Run the MCP Server

bun run dev

The server will start on http://localhost:4000/mcp

4. Connect Your MCP Client

Configure your MCP client to connect to the server endpoint. Example with Claude Desktop:

{
  "mcpServers": {
    "fresh-pears": {
      "url": "http://localhost:4000/mcp"
    }
  }
}

MCP Tools

The server exposes the following tools for AI agents:

getLatestBlock

Returns the latest block number for a given chain.

Parameters:

• chain (string): "ethereum" or "base"

Response:

{
  "chain": "ethereum",
  "blockNumber": 21000000
}

refreshFactories

Discovers and caches recent factory contracts automatically. Scans the last ~5,000 blocks for PairCreated and PoolCreated events.

Parameters:

• chain (string): "ethereum" or "base"

Response:

{
  "chain": "ethereum",
  "factories": ["0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f", ...],
  "count": 5
}

getNewPairs

Fetches all new DEX pair/pool creation events in a block range. Automatically refreshes factory list if empty.

Parameters:

• chain (string): "ethereum" or "base"
• fromBlock (number): Starting block number
• toBlock (number): Ending block number

Response:

[
  {
    "kind": "v2",
    "chain": "ethereum",
    "factory": "0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f",
    "token0": "0x...",
    "token1": "0x...",
    "pairOrPool": "0x...",
    "blockNumber": 21000000,
    "txHash": "0x..."
  },
  {
    "kind": "v3",
    "chain": "ethereum",
    "factory": "0x1F98431c8aD98523631AE4a59f267346ea31F984",
    "token0": "0x...",
    "token1": "0x...",
    "pairOrPool": "0x...",
    "fee": 3000,
    "blockNumber": 21000001,
    "txHash": "0x..."
  }
]

analyzePair

Evaluates basic safety heuristics for a given pair event.

Parameters:

• event (object): A PairEvent object from getNewPairs

Response:

{
  "score": 50,
  "warnings": ["Missing token addresses"]
}

Architecture

src/
├── chains/
│   ├── factories.ts      # Hardcoded factory addresses
│   └── topics.ts         # Event topic hashes
├── core/
│   ├── client.ts         # Viem RPC clients
│   ├── decode.ts         # Event decoding utilities
│   ├── discoverFactories.ts  # Dynamic factory discovery
│   ├── events.ts         # Event fetching and parsing
│   ├── heuristics.ts     # Pair safety scoring
│   ├── logs.ts           # Log utilities
│   └── rpc.ts            # RPC helpers
├── mcp/
│   └── server.ts         # MCP server implementation
├── types/
│   └── index.d.ts        # TypeScript type definitions
└── index.ts              # Entry point

How It Works

1. Factory Discovery: Scans recent blocks (last ~5,000) on Etherscan/BaseScan for PairCreated and PoolCreated events to discover active factory contracts.

2. Event Monitoring: Subscribes to factory contracts and fetches pair creation events in specified block ranges.

3. Dynamic Updates: Automatically refreshes factory lists when needed, ensuring coverage of new or recently active DEX protocols.

4. Heuristic Analysis: Evaluates pairs using basic safety checks (token address validation, fee sanity checks, etc.).

Development

# Install dependencies
bun install

# Run in development mode
bun run dev

# Build for production
bun run build

# Run tests
bun test

Project Status

This project is in active development. The API may change between versions.

License

MIT

Contributing

Contributions welcome! Please open an issue or submit a pull request.

Support

For issues, questions, or feature requests, please open an issue on GitHub.