README.md•5.42 kB
## 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
```plaintext
git clone <repository>
cd emercoin-mcp-server
npm install
```
## Configuration
Configure using environment variables:
```plaintext
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
```plaintext
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:
```plaintext
{
"params": ["param1", "param2"],
"format": true, // Apply emercoin-format.py
"extractValue": true // Apply emercoin-value.py
}
```
### Examples
#### Get blockchain info:
```plaintext
curl -X POST http://localhost:7331/blockchain/getblockchaininfo \
-H "Content-Type: application/json" \
-d '{}'
```
#### Show name with formatting:
```plaintext
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:
```plaintext
curl -X POST http://localhost:7331/names/name_show \
-H "Content-Type: application/json" \
-d '{"params": ["dns:emercoin.com"], "extractValue": true}'
```
#### Send EMC:
```plaintext
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
```plaintext
npm run dev # Auto-reload on changes
```
## License
MIT