Emercoin MCP Server - MCP Server

Emercoin MCP Server v0.2

A comprehensive Model Context Protocol (MCP) server that provides HTTP/JSON access to all Emercoin CLI functionality with integrated formatting utilities.

Features

Complete RPC Coverage: All 100+ Emercoin RPC endpoints organized by category
Formatting Integration: Built-in support for emercoin-format.py and emercoin-value.py utilities
Multiple API Styles: Category-based routes, generic RPC calls, and legacy compatibility
Enhanced Error Handling: Detailed error responses with stderr output and exit codes
Auto-Discovery: /endpoints route lists all available methods by category
Health Monitoring: Comprehensive health check with endpoint count
CORS Support: Cross-origin requests enabled
High Performance: Uses spawn for better process management

Prerequisites

Node.js 14.0.0 or higher
Python 3 (for formatting utilities)
Emercoin daemon (emercoind) running with RPC enabled
emercoin-cli in your PATH or specified via environment variable

Installation

git clone <repository>
cd emercoin-mcp-server
npm install

Configuration

Configure using environment variables:

export PORT=7331                    # Server port (default: 7331)
export EMERCOIN_CLI_PATH=emercoin-cli  # Path to emercoin-cli
export RPC_USER=your_rpc_username      # RPC username
export RPC_PASSWORD=your_rpc_password  # RPC password  
export RPC_PORT=6662                   # RPC port (default: 6662)
export RPC_HOST=127.0.0.1             # RPC host (default: 127.0.0.1)

Running the Server

npm start
# or for development with auto-reload:
npm run dev

API Endpoints

Discovery & Health

GET /health - Server health and statistics
GET /endpoints - List all available RPC methods by category

Category-Based Routes

All RPC methods are available via category-based routes:

Blockchain Operations

POST /blockchain/getblockchaininfo
POST /blockchain/getblockcount
POST /blockchain/getbestblockhash
POST /blockchain/getblock - params: ["blockhash", verbosity]
And 20+ more blockchain endpoints...

Name Operations (Emercoin's unique feature)

POST /names/name_show - params: ["name", "valuetype", "filepath"]
POST /names/name_new - params: ["name", "value", days, "toaddress", "valuetype"]
POST /names/name_update - params: ["name", "value", days, "toaddress", "valuetype"]
POST /names/name_filter - params: ["regexp", maxage, from, nb, "stat", "valuetype"]
And 10+ more name endpoints...

Wallet Operations

POST /wallet/getbalance
POST /wallet/getnewaddress - params: ["label", "address_type"]
POST /wallet/sendtoaddress - params: ["address", amount, "comment", "comment_to", ...]
POST /wallet/listtransactions
And 40+ more wallet endpoints...

Other Categories

Control: getinfo, stop, uptime, etc.
Mining: getmininginfo, getblocktemplate, etc.
Network: getpeerinfo, getnetworkinfo, etc.
Raw Transactions: createrawtransaction, signrawtransaction, etc.
Utilities: validateaddress, estimatesmartfee, etc.
Randpay: Emercoin's micropayment system
ZMQ: Notification system

Generic RPC Routes

POST /rpc/:method - Call any RPC method directly
POST /rpc - Legacy RPC passthrough

Request Format

All endpoints accept JSON with optional formatting:

{
  "params": ["param1", "param2"],
  "format": true,        // Apply emercoin-format.py
  "extractValue": true   // Apply emercoin-value.py
}

Examples

Get blockchain info:

curl -X POST http://localhost:7331/blockchain/getblockchaininfo \
  -H "Content-Type: application/json" \
  -d '{}'

Show name with formatting:

curl -X POST http://localhost:7331/names/name_show \
  -H "Content-Type: application/json" \
  -d '{"params": ["dns:emercoin.com"], "format": true}'

Extract value from name:

curl -X POST http://localhost:7331/names/name_show \
  -H "Content-Type: application/json" \
  -d '{"params": ["dns:emercoin.com"], "extractValue": true}'

Send EMC:

curl -X POST http://localhost:7331/wallet/sendtoaddress \
  -H "Content-Type: application/json" \
  -d '{"params": ["EMC_ADDRESS", 1.0, "Payment", "To John"]}'

Formatting Utilities

The server integrates two Python utilities:

emercoin-format.py

Cleans text output by replacing literal \n with actual line breaks.

emercoin-value.py

Extracts the value field from JSON responses, useful for name operations.

Enable formatting by adding "format": true or "extractValue": true to your request body.

Security Considerations

Network Security: Run behind HTTPS reverse proxy
Access Control: Use firewall rules to limit access
Credentials: Use strong RPC credentials, consider rpcauth
Port Security: Default port 7331 avoids common conflicts
Input Validation: All user input is properly escaped

Error Handling

Detailed error responses include:

Error message
stderr output from emercoin-cli
Exit code
Method name for context

Development

npm run dev  # Auto-reload on changes

License

MIT