README.md•12.7 kB
# 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.