# RustChain MCP Server

An MCP (Model Context Protocol) server for RustChain that allows Claude Code and other MCP-capable clients to query the blockchain and perform core actions directly from the terminal.

## Features

### Required Tools (Implemented)
- ✅ `rustchain_balance` - Get RTC balance of any address
- ✅ `rustchain_miners` - List active miners on the network
- ✅ `rustchain_epoch` - Get current epoch information
- ✅ `rustchain_health` - Check health status of all nodes
- ✅ `rustchain_transfer` - Transfer RTC (requires private key)

### Bonus Tools (Implemented)
- ✅ `rustchain_ledger` - View recent transactions
- ✅ `rustchain_bounties` - Get open bounty information

## Installation

### Prerequisites
- Node.js 18+
- npm or yarn

### Install from Source

```bash
# Clone the repository
git clone https://github.com/Async777/rustchain-mcp-server.git
cd rustchain-mcp-server

# Install dependencies
npm install

# Build the project
npm run build
```

## Configuration

### Add to Claude Code

```bash
# Add the MCP server to Claude Code
claude mcp add rustchain node /path/to/rustchain-mcp-server/dist/index.js
```

Or manually edit your Claude Code configuration:

```json
{
  "mcpServers": {
    "rustchain": {
      "command": "node",
      "args": ["/path/to/rustchain-mcp-server/dist/index.js"]
    }
  }
}
```

## Usage Examples

Once configured, you can use these tools in Claude Code:

```
# Check your balance
What is my RTC balance for address RTCc29259460d01e6aca70b16f044852dddd0369c0d?

# List miners
Show me the top 5 miners on RustChain

# Check network health
Is the RustChain network healthy?

# Get epoch info
What is the current epoch?

# View recent transactions
Show me the last 10 ledger entries
```

## Node Configuration

The server uses the following node priority:

1. **Primary**: `https://50.28.86.131`
2. **Fallback 1**: `https://rustchain.org`
3. **Fallback 2**: `https://node2.rustchain.org`

If the primary node is unavailable, the server automatically tries fallback nodes.

## API Endpoints Used

| Tool | Endpoint |
|------|----------|
| rustchain_balance | `GET /wallet/balance?miner_id={address}` |
| rustchain_miners | `GET /miners?limit={n}` |
| rustchain_epoch | `GET /epoch/current` |
| rustchain_health | `GET /health` |
| rustchain_transfer | `POST /wallet/transfer` |
| rustchain_ledger | `GET /ledger?limit={n}` |

## Security Notes

- **Private Keys**: The `rustchain_transfer` tool requires your private key. Only use this in secure environments.
- **Node Verification**: The server validates node health before performing sensitive operations.
- **Fallback Protection**: If all nodes are unreachable, operations fail gracefully with clear error messages.

## Development

```bash
# Run in development mode (auto-rebuild)
npm run dev

# Build for production
npm run build

# Start the server
npm start
```

## Bounty Information

This project was built for RustChain Bounty #1152:
- **Bounty**: 75-100 RTC
- **Scope**: MCP Server for RustChain
- **Repository**: https://github.com/Scottcjn/rustchain-bounties/issues/1152

## License

MIT

## Author

Async777
- Wallet: RTCc29259460d01e6aca70b16f044852dddd0369c0d