# Blockchain MCP Server DEMO

A comprehensive Model Context Protocol (MCP) server for interacting with multiple EVM-compatible blockchains. This server provides tools and resources for blockchain data access and analysis.

## Features

### 🔗 Multi-Chain Support
- **Ethereum Mainnet** (Chain ID: 1)
<!-- - **Polygon** (Chain ID: 137)  
- **BNB Smart Chain** (Chain ID: 56)
- **Arbitrum One** (Chain ID: 42161)
- **Optimism** (Chain ID: 10)
- **Avalanche C-Chain** (Chain ID: 43114)
- **Fantom Opera** (Chain ID: 250) -->
- **Conflux eSpace** (Chain ID: 1030)

### 🛠️ Tools (POST-like endpoints)
1. **`get_chains`** - Get list of supported blockchain networks
2. **`get_rpc_methods`** - Get supported RPC method list  
3. **`call_rpc`** - Execute arbitrary RPC method calls
4. **`get_latest_block`** - Get latest block number for a chain
5. **`get_transaction`** - Get transaction details by hash
6. **`get_address`** - Get address balance and information
7. **`get_block`** - Get block information by number

### 📚 Resources (GET-like endpoints)
1. **`blockchain://transaction/{hash}`** - Fetch transaction details (cross-chain search)
2. **`blockchain://block/{chainId}/{number}`** - Fetch block information
3. **`blockchain://address/{chainId}/{address}`** - Fetch address information and balance
4. **`blockchain://chains`** - List all supported blockchain networks

## Technology Stack

- **TypeScript** - Type-safe development
- **Viem** - Modern Ethereum library with excellent TypeScript support
- **Model Context Protocol (MCP)** - Standardized AI-blockchain communication
- **Zod** - Runtime type validation

## Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd blockchain-mcp-server
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

4. Start the server:
```bash
npm start
```

## Usage Examples

### Tools

#### Get supported chains
```typescript
// 获取所有支持的区块链网络
await callTool("get_chains", {});
```

#### Get transaction information
```typescript
// 获取交易信息
await callTool("get_transaction", {
  hash: "0x1234567890abcdef...",
  chainId: 1  // optional, will search all chains if not provided
});
```

#### Get address information
```typescript
// 获取地址信息
await callTool("get_address", {
  address: "0x742de6d65963b2c3a5e8e3b8c7cb56c6f78e0c00",
  chainId: 1
});
```

#### Execute RPC call
```typescript
// 获取以太坊主网最新区块号
await callTool("call_rpc", {
  method: "eth_blockNumber",
  params: [],
  chainId: 1
});

// 获取地址余额
await callTool("call_rpc", {
  method: "eth_getBalance", 
  params: ["0x742de6d65963b2c3a5e8e3b8c7cb56c6f78e0c00", "latest"],
  chainId: 1
});
```

### Resources

#### Access transaction data
```typescript
// 跨链查询交易 (will search all supported chains)
const txResource = await getResource("blockchain://transaction/0x1234567890abcdef...");
```

#### Access block data
```typescript
// 获取以太坊主网特定区块
const block = await getResource("blockchain://block/1/19000000");

// 获取Polygon特定区块
const polygonBlock = await getResource("blockchain://block/137/12345678");
```

#### Access address data
```typescript
// 获取地址信息
const addressInfo = await getResource("blockchain://address/1/0x742de6d65963b2c3a5e8e3b8c7cb56c6f78e0c00");
```

#### Access supported chains
```typescript
// 获取所有支持的区块链网络
const chains = await getResource("blockchain://chains");
```

## Supported RPC Methods

The server supports the following standard Ethereum JSON-RPC methods:

- `eth_getBalance` - Get account balance
- `eth_getTransactionByHash` - Get transaction by hash
- `eth_getTransactionReceipt` - Get transaction receipt
- `eth_getBlockByNumber` - Get block by number
- `eth_getBlockByHash` - Get block by hash  
- `eth_getTransactionCount` - Get account nonce
- `eth_getCode` - Get contract code
- `eth_call` - Execute contract call
- `eth_estimateGas` - Estimate gas for transaction
- `eth_gasPrice` - Get current gas price
- `eth_blockNumber` - Get latest block number
- `eth_chainId` - Get chain ID
- `net_version` - Get network version
- `web3_clientVersion` - Get client version

## API Reference

### Tools

#### `get_chains`
Returns a list of all supported blockchain networks.

**Parameters:** None

**Response:**
```json
[
  {
    "chainId": 1,
    "name": "Ethereum Mainnet",
    "symbol": "ETH",
    "rpcUrls": [...],
    "blockExplorerUrls": [...],
    "nativeCurrency": {...}
  }
]
```

#### `get_transaction`
Get detailed transaction information.

**Parameters:**
- `hash` (string): Transaction hash
- `chainId` (number, optional): Chain ID to search on

**Response:**
```json
{
  "hash": "0x...",
  "blockNumber": 19000000,
  "from": "0x...",
  "to": "0x...",
  "value": "1.0",
  "gasPrice": "0.00002",
  "gasUsed": "21000",
  "chainId": 1,
  "status": 1
}
```

#### `get_address`
Get address balance and information.

**Parameters:**
- `address` (string): Ethereum address
- `chainId` (number): Chain ID

**Response:**
```json
{
  "address": "0x...",
  "balance": "10.5",
  "nonce": 42,
  "code": null,
  "chainId": 1
}
```

#### `call_rpc`
Execute arbitrary RPC method calls.

**Parameters:**
- `method` (string): RPC method name
- `params` (array, optional): Method parameters
- `chainId` (number, optional): Chain ID (default: 1)

**Response:** Raw RPC response

## Error Handling

The server includes comprehensive error handling:

- **Network failures**: Automatic failover between RPC endpoints
- **Invalid parameters**: Input validation using Zod schemas
- **Chain unavailability**: Graceful handling when chains are down
- **Transaction not found**: Cross-chain search with clear error messages

## Architecture

```
src/
├── index.ts              # Main MCP server implementation
├── blockchain-service.ts # Blockchain interaction service (using viem)
├── config.ts            # Chain configurations and constants
└── types.ts             # TypeScript interfaces and schemas
```

### Key Components

1. **BlockchainService**: Manages connections to multiple EVM chains using viem clients
2. **MCP Server**: Exposes tools and resources following MCP specification
3. **Type Safety**: Full TypeScript support with Zod validation and viem's excellent types
4. **Multi-chain Support**: Seamless interaction across different networks

### Why Viem?

This project uses [viem](https://viem.sh/) instead of ethers for several advantages:

- **Better TypeScript Support**: Native TypeScript with strict typing
- **Modern API**: Functional approach with better tree-shaking
- **Performance**: Optimized for speed and bundle size
- **Reliability**: Built-in retry logic and better error handling
- **Future-proof**: Actively maintained with cutting-edge features

## Testing

You can test the server using the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## Configuration

The server automatically connects to multiple blockchain networks using public RPC endpoints. You can customize RPC endpoints by modifying the `src/config.ts` file.

### Adding New Chains

To add support for new EVM-compatible chains, update the `SUPPORTED_CHAINS` object in `src/config.ts`:

```typescript
export const SUPPORTED_CHAINS: Record<number, ChainConfig> = {
  // ... existing chains
  
  // New chain example
  YOUR_CHAIN_ID: {
    chainId: YOUR_CHAIN_ID,
    name: "Your Chain Name",
    symbol: "TOKEN",
    rpcUrls: [
      "https://rpc.yourchain.com",
      "https://backup-rpc.yourchain.com"
    ],
    blockExplorerUrls: ["https://explorer.yourchain.com"],
    nativeCurrency: {
      name: "Your Token",
      symbol: "TOKEN",
      decimals: 18
    }
  }
};
```

## Contributing

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

## License

MIT License - see LICENSE file for details.

## Support

For questions or issues, please open an issue on the GitHub repository.