# ChainFETCH MCP Server

A Model Context Protocol (MCP) server that provides access to [ChainFETCH](https://www.chainfetch.app) API - an AI-powered Ethereum blockchain intelligence platform with advanced semantic search capabilities.

## Features

ChainFETCH combines real-time blockchain streaming with AI-powered analysis to provide:

- **🔥 Live Block Streaming**: Real-time Ethereum block processing every ~12 seconds
- **🧠 AI-Powered Semantic Search**: Vector similarity search using Qwen3-Embedding-0.6B model
- **🤖 LLM-Enhanced Queries**: LLaMA 3.2 3B model for intelligent parameter selection
- **⚡ Multi-Modal Search**: Semantic, LLM, and JSON search options
- **🎯 Comprehensive Coverage**: Addresses, transactions, blocks, tokens, and smart contracts

## Available Tools

### Address Analysis
- `search_addresses_semantic` - AI-powered vector similarity search
- `search_addresses_json` - 150+ parameter filtering
- `search_addresses_llm` - Natural language to smart parameter selection
- `get_address_summary` - AI-generated address summaries
- `get_address_info` - Detailed address information

### Transaction Intelligence
- `search_transactions_semantic` - Semantic transaction search
- `search_transactions_json` - 254+ curated parameters
- `search_transactions_llm` - Natural language transaction queries
- `get_transaction_summary` - AI transaction summaries
- `get_transaction_info` - Detailed transaction data

### Block Analysis
- `search_blocks_semantic` - AI-powered block search
- `search_blocks_json` - 120+ block parameters
- `search_blocks_llm` - Natural language block queries
- `get_block_summary` - AI block summaries
- `get_block_info` - Detailed block information

### Token Intelligence
- `search_tokens_semantic` - Semantic token search
- `search_tokens_json` - Comprehensive token filtering
- `search_tokens_llm` - Natural language token queries
- `get_token_summary` - AI token summaries
- `get_token_info` - Detailed token information
- `get_nft_instance_info` - NFT instance details

### Smart Contract Analysis
- `search_smart_contracts_semantic` - AI contract search
- `search_smart_contracts_json` - 50+ contract parameters
- `search_smart_contracts_llm` - Natural language contract queries
- `get_smart_contract_summary` - AI contract summaries
- `get_smart_contract_info` - Detailed contract information

## Installation

### Prerequisites
- Node.js 18.0.0 or higher
- ChainFETCH API token from [chainfetch.app](https://www.chainfetch.app)

### Option 1: NPM Install (Recommended)
```bash
npm install -g chainfetch-mcp-server
```

### Option 2: From Source
```bash
git clone https://github.com/chainfetch/chainfetch-mcp-server.git
cd chainfetch-mcp-server
npm install
npm run build
npm link
```

## Configuration

### Environment Variables
Set your ChainFETCH API token:
```bash
export CHAINFETCH_API_TOKEN="your_api_token_here"
```

### For Claude Desktop
Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "chainfetch": {
      "command": "npx",
      "args": ["chainfetch-mcp-server"],
      "env": {
        "CHAINFETCH_API_TOKEN": "CHAINFETCH_API_TOKEN"
      }
    }
  }
}
```

### For Claude via ngrok (HTTP Mode)
Start the server in HTTP mode:
```bash
MCP_HTTP_MODE=true chainfetch-mcp-server
```

In another terminal, start ngrok:
```bash
ngrok http 8000
```

Configure Claude MCP Connector with:
- **Server URL**: `https://your-ngrok-url.ngrok.app/streamable-http`
- **API Key**: Your ChainFETCH API token

## Usage Examples

### Semantic Search
```javascript
// Find whale addresses
search_addresses_semantic({
  query: "whale addresses with high ETH balance and DeFi activity",
  limit: 10
})

// Find suspicious transactions
search_transactions_semantic({
  query: "high gas transactions with failed status",
  limit: 5
})
```

### Natural Language Queries
```javascript
// LLM-powered address search
search_addresses_llm({
  query: "Show me verified smart contracts deployed in the last month"
})

// LLM-powered transaction search
search_transactions_llm({
  query: "Find large value transfers between exchanges"
})
```

### Structured Filtering
```javascript
// JSON search with specific parameters
search_addresses_json({
  eth_balance_min: "10.0",
  is_contract: true,
  is_verified: true,
  transactions_count_min: 1000,
  limit: 20
})
```

### Detailed Analysis
```javascript
// Get comprehensive address information
get_address_info({
  address: "0x742D35Cc6335C06576BE5A1D5E2A7df9e7B0E8df"
})

// Get AI-generated summary
get_address_summary({
  address_hash: "0x742D35Cc6335C06576BE5A1D5E2A7df9e7B0E8df"
})
```

## API Coverage

This MCP server provides access to ChainFETCH's comprehensive API including:

- **150+ Address Parameters**: Balance, contract status, transaction counts, token holdings
- **254+ Transaction Parameters**: Value, gas, addresses, block info, token transfers
- **120+ Block Parameters**: Height, gas usage, transaction counts, miner info
- **Token Analysis**: ERC-20, ERC-721, ERC-1155 support with metadata
- **Smart Contract Intelligence**: Verification status, proxy patterns, ABI analysis

## Error Handling

The server provides detailed error messages for common issues:
- Missing API token
- Invalid addresses/hashes
- Rate limiting
- Network connectivity issues

## Development

### Local Development
```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Run in HTTP mode for testing
npm run dev:http
```

### Testing with Claude
1. Set up your API token
2. Configure Claude Desktop or use ngrok
3. Test with simple queries first
4. Use the semantic search for exploratory analysis

## Support

- **Documentation**: [ChainFETCH API Docs](https://www.chainfetch.app/docs)
- **API Access**: [Get API Token](https://www.chainfetch.app)
- **Issues**: [GitHub Issues](https://github.com/chainfetch/chainfetch-mcp-server/issues)

## License

MIT License - see LICENSE file for details.

## Changelog

### v1.0.0
- Initial release
- Full ChainFETCH API integration
- Semantic, LLM, and JSON search modes
- Address, transaction, block, token, and smart contract tools
- Claude Desktop and ngrok HTTP support