# Relay Protocol MCP Server

Model Context Protocol (MCP) server for the [Relay Protocol REST API](https://docs.relay.link/references/api/) enabling cross-chain bridging and token swapping operations.

## Features

- **Cross-Chain Bridging** - Bridge tokens between 50+ blockchain networks
- **Multi-Chain Swaps** - Aggregate tokens from multiple chains into single destination
- **Real-Time Pricing** - Get current token prices across all supported chains
- **Request Monitoring** - Track execution status and transaction details
- **Currency Discovery** - Browse 1000+ supported tokens with filtering
- **Zero Configuration** - No API keys required (free public API)
- **Type Safety** - Full TypeScript support with comprehensive validation

## Quick Start

### Option 1: Local Setup (Claude Desktop)

```bash
# Install and build
pnpm install && pnpm build

# Run development server
pnpm dev

# Run production server
pnpm start
```

### Cloud Deployment (SSE transport)

Deploy to Railway, Heroku, Render, or any cloud platform:

```bash
# Build the server
pnpm build

# Start SSE server (uses PORT from environment or 3000)
pnpm start:sse

# Or for development
pnpm dev:sse
```

See [RAILWAY.md](./RAILWAY.md) for detailed Railway deployment guide.

## MCP Integration

### Stdio Transport (Local - Claude Desktop)

Add to your Claude Desktop configuration file:

**Config Location:**

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

```json
{
  "mcpServers": {
    "Relay Protocol": {
      "command": "node",
      "args": ["/absolute/path/to/relay-protocol-mcp-server/dist/index.js"]
    }
  }
}
```

### Option 2: Cloud Deployment (Railway)

**Deploy Steps:**

1. Push your code to GitHub
2. Go to [railway.app](https://railway.app) → "New Project" → "Deploy from GitHub repo"
3. Select your repository (Railway auto-detects configuration)
4. Get your deployment URL: `https://your-app.railway.app`

**Claude Desktop Configuration:**

```json
{
  "mcpServers": {
    "Relay Protocol": {
      "transport": "sse",
      "url": "https://your-app.railway.app/sse"
    }
  }
}
```

**Test Your Deployment:**

```bash
curl https://your-app.railway.app/health
# Response: {"status":"healthy","server":"Relay Protocol","version":"0.1.0","transport":"sse"}
```

**Deployment Info:**
- Free tier: $5/month credits (plenty for personal use)
- Memory usage: ~50-100MB RAM
- Auto-sleeps after 30 minutes of inactivity
- Railway CLI: `npm i -g @railway/cli` (optional)

## Available Tools (9 total)

| Tool | Purpose | Example Use Case |
|------|---------|------------------|
| `relay_get_chains` | List supported blockchain networks | "Show me all chains Relay supports" |
| `relay_get_token_price` | Get real-time token prices | "What's the price of USDC on Ethereum?" |
| `relay_get_currencies` | Discover tokens with advanced filtering | "Show verified tokens on Arbitrum" |
| `relay_get_quote` | Generate bridging/swap quotes | "Quote bridging 100 USDC from Ethereum to Polygon" |
| `relay_swap_multi_input` | Execute multi-chain swaps | "Swap ETH + USDC from multiple chains to USDC on Base" |
| `relay_get_execution_status` | Track request progress | "Check status of my bridge transaction" |
| `relay_get_requests` | Monitor request history | "Show my recent cross-chain transactions" |
| `relay_transactions_index` | Index transactions for tracking | "Register this transaction for monitoring" |
| `relay_transactions_single` | Index specific transfers/wraps | "Track this specific transfer operation" |

## Example Prompts

```text
# Bridge tokens
"Bridge 100 USDC from Ethereum to Polygon"
"What chains can I bridge USDC between?"

# Multi-chain swaps
"Swap all my USDC from Ethereum and Polygon to ETH on Arbitrum"
"Consolidate my tokens from multiple chains into USDC on Base"

# Price discovery
"Show current ETH prices across all chains"
"What's the cheapest way to get USDC on Optimism?"

# Currency discovery  
"Find all stablecoins available on Polygon"
"Show me verified tokens with bridging support"
```

## Development

```bash
pnpm typecheck    # Type checking
pnpm dev         # Development with auto-reload
pnpm build       # Production build
pnpm start       # Start production server
```

## Project Structure

```text
src/
├── client/           # HTTP client and error handling
├── tools/            # 9 MCP tool implementations  
├── types/relay.ts    # Complete TypeScript definitions
├── config.ts         # API configuration
├── index.ts          # Stdio transport (local)
└── server.ts         # SSE transport (cloud)
```

## Troubleshooting

**"No available tools" in Claude:**

1. Verify absolute path in config is correct
2. Test server: `echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js`
3. Restart Claude Desktop after config changes
4. Ensure Node.js >= 20.0.0 and `pnpm build` completed

**Connection issues:**

- Run `pnpm build` before starting
- Check server starts without errors: `pnpm dev`
- Verify JSON syntax in Claude config file

## Requirements

- Node.js >= 20.0.0
- pnpm package manager

## API Reference

Full access to [Relay Protocol REST API](https://docs.relay.link/references/api/) with TypeScript types and validation. The Relay Protocol supports:

- **50+ Blockchain Networks** including Ethereum, Polygon, Arbitrum, Optimism, Base, etc.
- **1000+ Tokens** with real-time pricing and bridging support
- **Free Public API** with no rate limits or authentication required
- **Production-Ready** infrastructure handling millions in daily volume

## License

MIT