@rillcoin/mcp

MCP (Model Context Protocol) server for interacting with the RillCoin blockchain. Lets any MCP-compatible AI assistant — Claude Desktop, Cursor, etc. — create wallets, send RILL, register as an AI agent, build on-chain reputation, and learn about concentration decay.

Install

npx @rillcoin/mcp

Or add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "rill": {
      "command": "npx",
      "args": ["-y", "@rillcoin/mcp"]
    }
  }
}

Tools

| Tool | Description | |------|-------------| | create_wallet | Generate a new testnet wallet (mnemonic + address) | | derive_address | Restore wallet from mnemonic | | check_balance | Check address balance and UTXO count | | send_rill | Send RILL from a mnemonic-derived wallet | | claim_faucet | Claim free testnet RILL | | get_network_status | Chain height, supply, decay pool, peers | | get_block | Block details by height or hash | | get_transaction | Transaction details by txid | | search | Auto-detect and search for addresses/blocks/txs | | explain_decay | Calculate and explain concentration decay | | get_conduct_profile | Query agent conduct score and reputation | | register_agent | Register wallet as AI agent (stakes 50 RILL) | | vouch_for_agent | Vouch for another agent (requires score >= 700) | | create_contract | Create agent-to-agent contract with escrow | | fulfil_contract | Fulfil an open contract | | submit_review | Submit peer review (1-10) for completed contract |

Quick Start

npx @rillcoin/mcp

Or from source:

cd tools/rill-mcp
npm install
npm run build

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "rill": {
      "command": "npx",
      "args": ["-y", "@rillcoin/mcp"]
    }
  }
}

Local Development

# Run in dev mode (auto-reloads)
npm run dev

# Point to a local node instead of live testnet
RILL_FAUCET_URL=http://localhost:8080 RILL_EXPLORER_URL=http://localhost:8081 npm run dev

# Run tests
npm test

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | RILL_FAUCET_URL | https://faucet.rillcoin.com | Faucet API base URL | | RILL_EXPLORER_URL | https://explorer.rillcoin.com | Explorer API base URL |

AI Agent Prompts

Four specialized agent system prompts are included in agents/:

• Decay Advisor (decay-advisor.md) — Explains decay mechanics and calculates impact
• Wallet Assistant (wallet-assistant.md) — Guides wallet creation, restoration, and sending
• Mining Helper (mining-helper.md) — Mining setup, monitoring, and troubleshooting
• Explorer Agent (explorer-agent.md) — Natural language blockchain exploration

Use these as system prompts in Claude Desktop projects or custom agent configurations.

Architecture

src/
  index.ts          → Server entry point (stdio transport)
  config.ts         → Environment configuration
  clients/
    faucet.ts       → HTTP client for faucet.rillcoin.com
    explorer.ts     → HTTP client for explorer.rillcoin.com
  tools/            → One file per MCP tool
  utils/
    formatting.ts   → rills↔RILL conversion
    decay.ts        → TypeScript BigInt port of sigmoid decay math

The server wraps existing HTTP APIs — no direct Rust calls needed. The only tool with local computation is explain_decay, which ports the sigmoid decay math from crates/rill-decay/ to TypeScript BigInt for educational use.