MCP Ethereum Address Info Server

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
• Running the Server
• Available Endpoints
• Using the SSE Endpoint
• Testing with Curl
• Example Workflow

Setup

1. Clone the repository:
   git clone <repository-url> cd mcp-0x-address
2. Install dependencies:
   npm install
3. Create a .env file with the following variables:
   MCP_PORT=3002

Running the Server

Start the HTTP MCP server:

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

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

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:

Replace YOUR_CLIENT_ID with the client ID you received when connecting to the SSE endpoint.

4. Unsubscribe from Address Updates

5. Trigger an Address Update

To trigger an address update (which will be sent to subscribed clients), call the get-address-info tool:

6. Check Server Health

7. Test the Ping Tool

Example Workflow

Here's a complete workflow for testing the SSE functionality:

1. Start the server:
   npm run start:http
2. In a new terminal, connect to the SSE endpoint:
   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:
   curl -X POST \ http://localhost:3002/sse/subscribe/client-1234567890abcdef \ -H "Content-Type: application/json" \ -d '{"addresses": ["0x742d35Cc6634C0532925a3b844Bc454e4438f44e"]}'
5. Trigger an address update:
   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:

Save this as test_sse.sh, make it executable with chmod +x test_sse.sh, and run it with ./test_sse.sh.