# ValueRouter MCP Server

A Model Context Protocol (MCP) server that provides AI agents with comprehensive cross-chain USDC bridging capabilities through ValueRouter. This server enables AI agents to seamlessly bridge USDC across multiple blockchain networks including Ethereum, Solana, Sui, and Cosmos ecosystem chains.

## Features

- **Multi-Chain Support**: Bridge USDC across 15+ blockchain networks
- **Real-Time Quotes**: Get accurate bridging quotes with fees and timing estimates
- **Transaction Simulation**: Prepare bridge transactions without execution
- **Status Tracking**: Monitor bridge transaction progress in real-time
- **Balance Queries**: Check user token balances across all supported chains
- **Fee Estimation**: Calculate bridge fees and gas costs

## Supported Chains

### Mainnet

- **Ethereum** (Chain ID: 1)
- **Arbitrum One** (Chain ID: 42161)
- **Optimism** (Chain ID: 10)
- **Polygon** (Chain ID: 137)
- **Avalanche C-Chain** (Chain ID: 43114)
- **Base** (Chain ID: 8453)
- **Solana** (Chain ID: 'solana')
- **Sui** (Chain ID: 'sui')
- **Noble** (Chain ID: 'noble-1')
- **Osmosis** (Chain ID: 'osmosis-1')
- **Evmos** (Chain ID: 'evmos_9001-2')
- **Sei** (Chain ID: 'pacific-1')
- **Coreum** (Chain ID: 'coreum-mainnet-1')
- **dYdX** (Chain ID: 'dydx-mainnet-1')

### Testnet

- **Goerli** (Chain ID: 5)
- **Sepolia** (Chain ID: 11155111)
- **Solana Devnet** (Chain ID: 'solana-devnet')
- **Sui Testnet** (Chain ID: 'sui-testnet')
- **Noble Testnet** (Chain ID: 'grand-1')
- **Avalanche Fuji** (Chain ID: 43113)
- **Arbitrum Goerli** (Chain ID: 421613)
- **Optimism Goerli** (Chain ID: 420)
- **Polygon Mumbai** (Chain ID: 80001)

## Installation

```bash
npm install @valuerouter/mcp-server
```

## Usage

### Starting the Server

```bash
npx @valuerouter/mcp-server
```

### Environment Variables

Create a `.env` file in your project root:

```env
# RPC URLs (replace with your API keys)
ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/YOUR_INFURA_KEY
ARBITRUM_RPC_URL=https://arb1.arbitrum.io/rpc
OPTIMISM_RPC_URL=https://mainnet.optimism.io
POLYGON_RPC_URL=https://polygon-rpc.com
AVALANCHE_RPC_URL=https://api.avax.network/ext/bc/C/rpc
BASE_RPC_URL=https://mainnet.base.org
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SUI_RPC_URL=https://fullnode.mainnet.sui.io:443

# Optional: API keys for better performance
ALCHEMY_API_KEY=your_alchemy_key
INFURA_API_KEY=your_infura_key
QUICKNODE_API_KEY=your_quicknode_key
```

## Available Tools

### 1. `get_supported_chains`

Get all supported chains for USDC bridging.

**Parameters:**

- `includeTestnets` (boolean, optional): Include testnet chains (default: false)

**Example:**

```json
{
  "name": "get_supported_chains",
  "arguments": {
    "includeTestnets": false
  }
}
```

**Response:**

```json
{
  "chains": [
    {
      "chainId": 1,
      "name": "Ethereum",
      "symbol": "ETH",
      "decimals": 18,
      "explorerUrl": "https://etherscan.io",
      "isTestnet": false,
      "networkType": "mainnet",
      "usdcAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
    }
  ],
  "count": 14
}
```

### 2. `get_supported_tokens`

Get supported tokens for bridging.

**Parameters:**

- `chainId` (number|string, optional): Specific chain ID to get tokens for
- `includeTestnets` (boolean, optional): Include testnet tokens (default: false)

**Example:**

```json
{
  "name": "get_supported_tokens",
  "arguments": {
    "chainId": 1,
    "includeTestnets": false
  }
}
```

### 3. `get_bridge_quote`

Get a quote for bridging USDC between chains.

**Parameters:**

- `fromChainId` (number|string): Source chain ID
- `toChainId` (number|string): Destination chain ID
- `fromToken` (object): Source token details
- `toToken` (object): Destination token details
- `amount` (string): Amount to bridge in smallest unit (wei, lamports, etc.)
- `slippageBps` (number, optional): Slippage tolerance in basis points (default: 100)
- `userAddress` (string, optional): User address for better quote accuracy

**Example:**

```json
{
  "name": "get_bridge_quote",
  "arguments": {
    "fromChainId": 1,
    "toChainId": 42161,
    "fromToken": {
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "chainId": 1,
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6
    },
    "toToken": {
      "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "chainId": 42161,
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6
    },
    "amount": "1000000",
    "slippageBps": 100
  }
}
```

**Response:**

```json
{
  "fromChainId": 1,
  "toChainId": 42161,
  "fromAmount": "1000000",
  "toAmount": "999500",
  "toAmountMin": "998501",
  "bridgeFee": "500",
  "gasFee": "10000000000000000",
  "totalFee": "10000000000000500",
  "estimatedTime": "480",
  "priceImpact": "0.01",
  "route": {
    "steps": [
      {
        "type": "bridge",
        "chainId": 1,
        "fromToken": {...},
        "toToken": {...},
        "amount": "1000000",
        "protocol": "ValueRouter"
      }
    ]
  },
  "validUntil": 1703958743123
}
```

### 4. `execute_bridge`

Execute a bridge transaction (simulation only).

**Parameters:**

- `fromChainId` (number|string): Source chain ID
- `toChainId` (number|string): Destination chain ID
- `fromToken` (object): Source token details
- `toToken` (object): Destination token details
- `amount` (string): Amount to bridge
- `recipientAddress` (string): Recipient address on destination chain
- `userAddress` (string): User address initiating the transaction
- `slippageBps` (number, optional): Slippage tolerance in basis points
- `memo` (string, optional): Memo for Cosmos chains

**Example:**

```json
{
  "name": "execute_bridge",
  "arguments": {
    "fromChainId": 1,
    "toChainId": 42161,
    "fromToken": {
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "chainId": 1,
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6
    },
    "toToken": {
      "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "chainId": 42161,
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6
    },
    "amount": "1000000",
    "recipientAddress": "0x742d35Cc6634C0532925a3b8D45c07F9624f8b4c",
    "userAddress": "0x742d35Cc6634C0532925a3b8D45c07F9624f8b4c",
    "slippageBps": 100
  }
}
```

**Response:**

```json
{
  "transactionHash": "simulated-1703958743123-abc123def",
  "fromChainId": 1,
  "toChainId": 42161,
  "status": "pending",
  "explorerUrl": "https://etherscan.io/tx/simulated-1703958743123-abc123def",
  "estimatedCompletionTime": "600",
  "trackingId": "simulated-1703958743123-abc123def",
  "warning": "This is a simulation only. To execute the transaction, use the returned transaction data with your wallet.",
  "simulationOnly": true
}
```

### 5. `get_transaction_status`

Get the status of a bridge transaction.

**Parameters:**

- `transactionHash` (string): Transaction hash to check status for
- `fromChainId` (number|string): Source chain ID
- `toChainId` (number|string): Destination chain ID

**Example:**

```json
{
  "name": "get_transaction_status",
  "arguments": {
    "transactionHash": "simulated-1703958743123-abc123def",
    "fromChainId": 1,
    "toChainId": 42161
  }
}
```

**Response:**

```json
{
  "transactionHash": "simulated-1703958743123-abc123def",
  "fromChainId": 1,
  "toChainId": 42161,
  "status": "attesting",
  "steps": [
    {
      "name": "Simulation",
      "status": "completed",
      "timestamp": 1703958773123
    },
    {
      "name": "Bridge Scanning",
      "status": "completed",
      "timestamp": 1703958803123
    },
    {
      "name": "Circle Attestation",
      "status": "processing",
      "timestamp": 1703958863123
    }
  ],
  "fromTxHash": "simulated-1703958743123-abc123def"
}
```

### 6. `get_user_balance`

Get user token balance on a specific chain.

**Parameters:**

- `chainId` (number|string): Chain ID to check balance on
- `tokenAddress` (string): Token contract address
- `userAddress` (string): User address to check balance for

**Example:**

```json
{
  "name": "get_user_balance",
  "arguments": {
    "chainId": 1,
    "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "userAddress": "0x742d35Cc6634C0532925a3b8D45c07F9624f8b4c"
  }
}
```

**Response:**

```json
{
  "chainId": 1,
  "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "balance": "1000000000",
  "decimals": 6,
  "symbol": "USDC",
  "formattedBalance": "1000.0"
}
```

### 7. `estimate_bridge_fees`

Estimate fees for a bridge transaction.

**Parameters:**

- `fromChainId` (number|string): Source chain ID
- `toChainId` (number|string): Destination chain ID
- `amount` (string): Amount to bridge
- `tokenAddress` (string, optional): Token address (defaults to USDC)

**Example:**

```json
{
  "name": "estimate_bridge_fees",
  "arguments": {
    "fromChainId": 1,
    "toChainId": 42161,
    "amount": "1000000"
  }
}
```

**Response:**

```json
{
  "bridgeFee": "500",
  "gasFee": "10000000000000000",
  "totalFee": "10000000000000500"
}
```

## Error Handling

All tools return structured error responses when something goes wrong:

```json
{
  "error": "Unsupported chain: 999",
  "code": "UNSUPPORTED_CHAIN",
  "details": "Chain ID 999 is not supported by ValueRouter"
}
```

Common error codes:

- `UNSUPPORTED_CHAIN`: Chain is not supported
- `INVALID_TOKEN`: Token address is invalid
- `INSUFFICIENT_BALANCE`: User has insufficient balance
- `QUOTE_ERROR`: Failed to get quote
- `BRIDGE_ERROR`: Failed to prepare bridge transaction
- `STATUS_ERROR`: Failed to get transaction status
- `BALANCE_ERROR`: Failed to get balance

## Chain-Specific Notes

### Ethereum & EVM Chains

- Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for native ETH
- Gas fees are in wei (18 decimals)
- Bridge fees are 0.05% (5 basis points)

### Solana

- Use `So11111111111111111111111111111111111111112` for native SOL
- Gas fees are in lamports (9 decimals)
- Requires WSOL wrapping for bridging

### Sui

- Use `0x2::sui::SUI` for native SUI
- Gas fees are in MIST (9 decimals)
- Supports Move-based tokens

### Cosmos Chains

- Use denomination strings like `uusdc`, `uosmo`, etc.
- Gas fees vary by chain
- Supports IBC transfers

## Integration Examples

### Basic Bridge Flow

```javascript
// 1. Get supported chains
const chains = await callTool('get_supported_chains', {})

// 2. Get user balance
const balance = await callTool('get_user_balance', {
  chainId: 1,
  tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  userAddress: '0x742d35Cc6634C0532925a3b8D45c07F9624f8b4c'
})

// 3. Get bridge quote
const quote = await callTool('get_bridge_quote', {
  fromChainId: 1,
  toChainId: 42161,
  fromToken: {
    address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    chainId: 1,
    symbol: 'USDC',
    name: 'USD Coin',
    decimals: 6
  },
  toToken: {
    address: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
    chainId: 42161,
    symbol: 'USDC',
    name: 'USD Coin',
    decimals: 6
  },
  amount: '1000000'
})

// 4. Execute bridge (simulation)
const bridge = await callTool('execute_bridge', {
  fromChainId: 1,
  toChainId: 42161,
  fromToken: quote.fromToken,
  toToken: quote.toToken,
  amount: '1000000',
  recipientAddress: '0x742d35Cc6634C0532925a3b8D45c07F9624f8b4c',
  userAddress: '0x742d35Cc6634C0532925a3b8D45c07F9624f8b4c'
})

// 5. Track transaction status
const status = await callTool('get_transaction_status', {
  transactionHash: bridge.transactionHash,
  fromChainId: 1,
  toChainId: 42161
})
```

## Security Considerations

- **Simulation Only**: The `execute_bridge` tool only simulates transactions and returns transaction data. It does not execute real transactions.
- **Address Validation**: All addresses are validated before processing
- **Amount Validation**: Amounts are validated to prevent overflow errors
- **RPC Security**: Use secure RPC endpoints and API keys
- **Rate Limiting**: Implement rate limiting for production use

## Development

### Building

```bash
npm run build
```

### Testing

```bash
npm run test
```

### Linting

```bash
npm run lint
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Support

For support and questions:

- GitHub Issues: [ValueRouter MCP Server Issues](https://github.com/valuerouter/mcp-server/issues)
- Discord: [ValueRouter Community](https://discord.gg/valuerouter)
- Documentation: [ValueRouter Docs](https://docs.valuerouter.com)

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for release history.