# deBridge MCP Server

A Model Context Protocol (MCP) server that provides cross-chain swap quotes using deBridge DLN protocol.

## Features

- Get crosschain swap quotes between different blockchain networks
- Read only operations (no transaction signing required)
- Fast quote fetching via deBridge API


## Installation

```bash
bun install
```

## Usage

### Running the MCP Server

Start the server for use with Claude Desktop or other MCP clients:

```bash
bun run dev
```

### Testing

Run the test suite:

```bash
bun test
```

### Building

Build the TypeScript project:

```bash
bun run build
```

Start the compiled server:

```bash
bun run start
```

## MCP Tools

### 1. `quoteSwap`

Get best cross-chain route and calldata for a potential swap via deBridge DLN.

**Parameters:**

- `srcChainId` - Source chain ID (e.g., '42161' for Arbitrum)
- `srcToken` - Token address on source chain (ERC20)
- `amount` - Amount in smallest units (wei / token decimals)
- `dstChainId` - Destination chain ID (e.g., '1' for Ethereum mainnet)
- `dstToken` - Token address on destination chain (ERC20)
- `userAddress` (optional) - Sender's wallet address (enables tx data generation)
- `recipientAddress` (optional) - Recipient address on destination chain

**Modes:**

- **Preview mode** (without addresses): Returns only estimation, no tx data
- **Full mode** (with userAddress): Returns estimation + transaction data ready to sign

**Response includes:**

- Summary with estimated destination amount and fees
- Token information (symbol, decimals)
- Transaction preview (to, data, value)
- Raw estimation data from deBridge

### 2. `getSupportedChains`

Get list of supported blockchain networks for cross-chain swaps.

**Parameters:** None

**Response includes:**

- Array of supported chains with chain IDs and names
- Total number of supported chains

### 3. `getTokensInfo`

Get information about tokens available on a specific blockchain network.

**Parameters:**

- `chainId` - Chain ID to query (e.g., '1' for Ethereum, '56' for BSC)

**Response includes:**

- List of available tokens with addresses, symbols, and decimals
- Total token count for the chain

## 4. `getOrderStatus`

Check the status of a cross-chain order by its order ID.

**Parameters:**

- `orderId` - Order ID obtained from creating an order

**Response includes:**

- Order status (Created, Fulfilled, etc.)
- Source and destination chain transaction hashes
- Order link for tracking
- Error information if applicable

## Environment Variables

Optional environment variables:

- `DLN_API_BASE` - Custom deBridge API base URL (default: `https://dln.debridge.finance/v1.0`)

## Examples

### 1. Get quote for USDC swap from Arbitrum to Ethereum (Preview Mode)

```json
{
  "srcChainId": "42161",
  "srcToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "amount": "1000000",
  "dstChainId": "1",
  "dstToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}
```

### 2. Get quote with transaction data (Full Mode)

```json
{
  "srcChainId": "42161",
  "srcToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "amount": "1000000",
  "dstChainId": "1",
  "dstToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "userAddress": "0xYourWalletAddress"
}
```

### 3. Get supported chains

No parameters needed - just call `getSupportedChains`

### 4. Get available tokens on Ethereum

```json
{
  "chainId": "1"
}
```

### 5. Check order status

```json
{
  "orderId": "0x..."
}
```

## Architecture

- `src/index.ts` - MCP server setup and tool registration
- `src/tools/` - All MCP tools implementations
  - `quoteSwap.ts` - Cross-chain swap quotes
  - `getSupportedChains.ts` - List supported chains
  - `getTokensInfo.ts` - Token information by chain
  - `getOrderStatus.ts` - Order status tracking
- `src/debridgeClient.ts` - deBridge API client
- `src/types/deBridge.ts` - TypeScript type definitions
- `src/__tests__/` - Test suite for all tools

## References

- Based on [deBridge API integrator example](https://github.com/debridge-finance/api-integrator-example)
- Uses [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)

## License

MIT