npm package: @qelt/mcp-server
Description: Official QELT Blockchain MCP Server — AI agent gateway for QELT blockchain, QXMP Oracle, Uniswap v4, and Mainnet Indexer
Author: QELT Labs
Latest version: 1.0.1

# @qelt/mcp-server

Official **QELT Blockchain MCP Server** — the universal AI agent gateway for the QELT blockchain ecosystem.

Provides 40 tools, 9 resources, and 5 guided prompts covering:

- 🔗 **QELT Blockchain** — Direct JSON-RPC interaction (blocks, transactions, balances, contract calls)
- 📊 **Mainnet Indexer** — Enriched blockchain data queries (address history, token balances, tx count)
- 🏛️ **QXMP Oracle** — Real-world asset valuations, proof-of-reserve verification ($1.1T in assets)
- 🦄 **Uniswap v4** — DEX pool state, positions, swaps, liquidity, WQELT wrapping
- ✅ **Contract Verification** — Submit and query verified smart contracts
- 🌐 **Network Info** — Chain configuration, endpoints, health, MetaMask config

## Quick Start

### Claude Desktop / Cursor (stdio)

Add to your MCP configuration (`claude_desktop_config.json` or `mcp.json`):

```json
{
  "mcpServers": {
    "qelt": {
      "command": "npx",
      "args": ["@qelt/mcp-server"]
    }
  }
}
```

### Remote Agents (HTTP + SSE)

```bash
npx @qelt/mcp-server --transport http --port 3000
```

The server exposes:
- `GET /sse` — SSE endpoint for MCP connection
- `POST /message` — MCP message endpoint
- `GET /health` — Health check
- `GET /` — Server info

## Tools Reference

### Blockchain Tools (11 tools)

| Tool | Description |
|------|-------------|
| `qelt_getBlockNumber` | Get latest block number |
| `qelt_getBlock` | Get block by number or hash |
| `qelt_getBalance` | Get native QELT balance |
| `qelt_getTransaction` | Get transaction by hash |
| `qelt_getTransactionReceipt` | Get transaction receipt with logs |
| `qelt_call` | Execute read-only contract call |
| `qelt_sendTransaction` | Broadcast signed raw transaction |
| `qelt_estimateGas` | Estimate gas for a transaction |
| `qelt_getLogs` | Get event logs with filters |
| `qelt_getCode` | Check if address is a contract |
| `qelt_getTransactionCount` | Get nonce for an address |

### Indexer Tools (9 tools)

| Tool | Description |
|------|-------------|
| `indexer_getLatestBlock` | Latest block with transactions |
| `indexer_getBlock` | Block by number or hash |
| `indexer_getBlocks` | Paginated block list |
| `indexer_getTransaction` | Transaction details by hash |
| `indexer_getTransactionReceipt` | Transaction receipt with logs |
| `indexer_getTransactionCount` | Total on-chain transaction count |
| `indexer_getAddressTransactions` | All transactions for an address |
| `indexer_getAddressTokens` | ERC20 token balances for address |
| `indexer_getAccountBalances` | All balances (native + tokens) |

### QXMP Oracle Tools (5 tools)

| Tool | Description |
|------|-------------|
| `oracle_getAssets` | All RWA assets with valuations & proof status |
| `oracle_getAsset` | Single asset full details |
| `oracle_getStats` | Portfolio statistics & breakdowns |
| `oracle_getHealth` | Oracle API health check |
| `oracle_verifyProofOnChain` | Verify proof directly on QELT blockchain |

### Uniswap v4 Tools (9 tools)

| Tool | Description |
|------|-------------|
| `uniswap_getContractAddresses` | All Uniswap v4 contract addresses |
| `uniswap_getPoolState` | Pool state (price, tick, liquidity) |
| `uniswap_getPositionInfo` | Liquidity position by NFT ID |
| `uniswap_executeSwap` | Execute swap (pre-signed tx) |
| `uniswap_addLiquidity` | Add liquidity (pre-signed tx) |
| `uniswap_removeLiquidity` | Remove liquidity (pre-signed tx) |
| `uniswap_collectFees` | Collect trading fees (pre-signed tx) |
| `uniswap_wrapQELT` | Wrap QELT → WQELT (pre-signed tx) |
| `uniswap_unwrapQELT` | Unwrap WQELT → QELT (pre-signed tx) |

### Contract Verification Tools (6 tools)

| Tool | Description |
|------|-------------|
| `contract_submitVerification` | Submit single-file verification |
| `contract_submitMultiVerification` | Submit multi-file verification |
| `contract_getVerificationStatus` | Check verification job status |
| `contract_getVerifiedContract` | Get verified contract details + ABI |
| `contract_getCompilerVersions` | List available compiler versions |
| `contract_getEvmVersions` | List supported EVM versions |

### Network Info Tools (4 tools)

| Tool | Description |
|------|-------------|
| `network_getInfo` | Comprehensive network information |
| `network_getEndpoints` | All RPC/WS/Explorer endpoints |
| `network_getHealth` | Indexer health and sync status |
| `network_getMetaMaskConfig` | MetaMask-compatible network config |

## Resources

Agents can read these static/semi-static data resources:

| URI | Description |
|-----|-------------|
| `qelt://network/mainnet` | Mainnet configuration |
| `qelt://network/testnet` | Testnet configuration |
| `qelt://contracts/uniswap-v4` | Uniswap v4 addresses |
| `qelt://contracts/oracle` | QXMP Oracle addresses |
| `qelt://docs/blockchain` | Blockchain technical specs |
| `qelt://docs/indexer-api` | Indexer API reference |
| `qelt://docs/oracle-api` | Oracle API reference |
| `qelt://docs/uniswap` | Uniswap v4 guide |
| `qelt://docs/contract-verification` | Verification guide |

## Prompts

Guided multi-step workflows:

| Prompt | Description |
|--------|-------------|
| `verify_rwa_reserves` | Verify RWA asset reserves via QXMP Oracle |
| `swap_tokens` | Execute token swap on Uniswap v4 |
| `check_portfolio` | Comprehensive portfolio overview |
| `explore_transaction` | Deep-dive into a transaction |
| `deploy_and_verify` | Deploy and verify a smart contract |

## Network Information

| Parameter | Mainnet | Testnet |
|-----------|---------|---------|
| Chain ID | 770 (0x302) | 771 (0x303) |
| RPC | https://mainnet.qelt.ai | https://testnet.qelt.ai |
| Archive RPC | https://archivem.qelt.ai | https://archive.qelt.ai |
| Indexer | https://mnindexer.qelt.ai | https://tnindexer.qelt.ai |
| Explorer | https://qeltscan.ai | https://testnet.qeltscan.ai |
| Block Time | 5 seconds | 5 seconds |
| Consensus | QBFT (5 validators) | QBFT |
| Gas Fees | Zero base fee (~$0.002/tx) | Free |

## Security

This MCP server is a **stateless gateway**:

- ❌ **No private keys** — The server never stores or manages private keys
- ✅ **Pre-signed transactions** — Write operations accept already-signed raw transaction hex
- ✅ **Read-only by default** — Most tools are read-only queries
- ✅ **Built-in caching** — Respects upstream rate limits with intelligent caching
- ✅ **No authentication required** — All upstream APIs are public

## Development

```bash
# Clone and install
git clone https://github.com/qelt/mcp-server.git
cd qelt-mcp-server
npm install

# Run in dev mode (stdio)
npm run dev

# Run in dev mode (HTTP)
npm run dev:http

# Build for production
npm run build

# Start production server
npm start
```

## Architecture

```
Agent → MCP Protocol → Tool Router → Cache → Rate Limiter → Upstream APIs
                                                              ├── QELT RPC
                                                              ├── Indexer API
                                                              ├── QXMP Oracle
                                                              └── On-chain contracts
```

## License

MIT