README.md•5.84 kB
# MCP Ethereum Address Info Server
This server provides information about Ethereum addresses across multiple chains using the Model Context Protocol (MCP). It includes a Server-Sent Events (SSE) endpoint for real-time updates.
## Table of Contents
- [Setup](#setup)
- [Running the Server](#running-the-server)
- [Available Endpoints](#available-endpoints)
- [Using the SSE Endpoint](#using-the-sse-endpoint)
- [Testing with Curl](#testing-with-curl)
- [Example Workflow](#example-workflow)
## Setup
1. Clone the repository:
```bash
git clone <repository-url>
cd mcp-0x-address
```
2. Install dependencies:
```bash
npm install
```
3. Create a `.env` file with the following variables:
```
MCP_PORT=3002
```
## Running the Server
Start the HTTP MCP server:
```bash
npm run start:http
```
This will start the server on port 3002 (or the port specified in your `.env` file).
## Available Endpoints
The server provides the following endpoints:
- `GET /health` - Server health check
- `POST /mcp` - MCP endpoint for tool calls
- `GET /sse` - Server-Sent Events endpoint for real-time updates
- `GET /sse/clients` - Get information about connected SSE clients
- `POST /sse/subscribe/:clientId` - Subscribe to address updates
- `POST /sse/unsubscribe/:clientId` - Unsubscribe from address updates
## Using the SSE Endpoint
The SSE endpoint allows clients to receive real-time updates from the server. Here's how to use it:
1. Connect to the SSE endpoint
2. Get your client ID from the connection response
3. Subscribe to specific addresses
4. Receive real-time updates for those addresses
## Testing with Curl
### 1. Connect to the SSE Endpoint
```bash
curl -N http://localhost:3002/sse
```
This will establish a connection to the SSE endpoint and start receiving events. The connection will remain open until you manually terminate it.
### 2. Check Connected Clients
```bash
curl http://localhost:3002/sse/clients
```
### 3. Subscribe to Address Updates
After connecting to the SSE endpoint, you'll receive a client ID. Use that ID to subscribe to address updates:
```bash
curl -X POST \
http://localhost:3002/sse/subscribe/YOUR_CLIENT_ID \
-H "Content-Type: application/json" \
-d '{"addresses": ["0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"]}'
```
Replace `YOUR_CLIENT_ID` with the client ID you received when connecting to the SSE endpoint.
### 4. Unsubscribe from Address Updates
```bash
curl -X POST \
http://localhost:3002/sse/unsubscribe/YOUR_CLIENT_ID \
-H "Content-Type: application/json" \
-d '{"addresses": ["0x742d35Cc6634C0532925a3b844Bc454e4438f44e"]}'
```
### 5. Trigger an Address Update
To trigger an address update (which will be sent to subscribed clients), call the `get-address-info` tool:
```bash
curl -X POST \
http://localhost:3002/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get-address-info",
"arguments": {
"address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}
}
}'
```
### 6. Check Server Health
```bash
curl http://localhost:3002/health
```
### 7. Test the Ping Tool
```bash
curl -X POST \
http://localhost:3002/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "ping",
"arguments": {}
}
}'
```
## Example Workflow
Here's a complete workflow for testing the SSE functionality:
1. Start the server:
```bash
npm run start:http
```
2. In a new terminal, connect to the SSE endpoint:
```bash
curl -N http://localhost:3002/sse
```
You'll receive a response like:
```
data: {"type":"connection","clientId":"client-1234567890abcdef","message":"Connected to MCP SSE endpoint","timestamp":"2023-01-01T00:00:00.000Z"}
```
3. Note the `clientId` from the response.
4. In another terminal, subscribe to address updates:
```bash
curl -X POST \
http://localhost:3002/sse/subscribe/client-1234567890abcdef \
-H "Content-Type: application/json" \
-d '{"addresses": ["0x742d35Cc6634C0532925a3b844Bc454e4438f44e"]}'
```
5. Trigger an address update:
```bash
curl -X POST \
http://localhost:3002/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get-address-info",
"arguments": {
"address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}
}
}'
```
6. In the terminal where you're connected to the SSE endpoint, you'll see updates for the address.
## Automated Testing Script
For a more automated test, you can use this bash script:
```bash
#!/bin/bash
# Start SSE connection in the background and capture the output
curl -N http://localhost:3002/sse > sse_output.txt &
SSE_PID=$!
# Wait a moment for the connection to establish
sleep 2
# Extract the client ID from the output
CLIENT_ID=$(grep -o '"clientId":"[^"]*"' sse_output.txt | head -1 | cut -d'"' -f4)
if [ -z "$CLIENT_ID" ]; then
echo "Failed to get client ID"
kill $SSE_PID
exit 1
fi
echo "Connected with client ID: $CLIENT_ID"
# Subscribe to an address
curl -X POST \
http://localhost:3002/sse/subscribe/$CLIENT_ID \
-H "Content-Type: application/json" \
-d '{"addresses": ["0x742d35Cc6634C0532925a3b844Bc454e4438f44e"]}'
echo "Subscribed to address. Waiting for updates..."
echo "Press Ctrl+C to stop"
# Keep the script running to see updates
tail -f sse_output.txt
# Clean up on exit
trap "kill $SSE_PID; rm sse_output.txt" EXIT
```
Save this as `test_sse.sh`, make it executable with `chmod +x test_sse.sh`, and run it with `./test_sse.sh`.