npm package: @orqusio/orqus-mcp
Description: MCP server for Orqus blockchain — query chain state, manage OIP20 tokens, OIP451 policies, and debug transactions
Author: Felixx9527
Latest version: 0.2.0

# orqus-mcp

MCP (Model Context Protocol) server for the [Orqus](https://orqus.io) blockchain. Provides AI-powered tools for querying chain state, managing OIP20 tokens, OIP451 policies, and debugging transactions.

## Install

```bash
npm install @orqusio/orqus-mcp
```

## Usage with Claude Code

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "orqus": {
      "command": "npx",
      "args": ["@orqusio/orqus-mcp"],
      "env": {
        "ORQUS_RPC_URL": "https://rpc-test.orqus.io/"
      }
    }
  }
}
```

Or for development:

```json
{
  "mcpServers": {
    "orqus": {
      "command": "npx",
      "args": ["tsx", "/path/to/orqus-mcp/src/index.ts"],
      "env": {
        "ORQUS_RPC_URL": "https://rpc-test.orqus.io/"
      }
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ORQUS_RPC_URL` | `https://rpc-test.orqus.io/` | RPC endpoint URL |

All tools also accept optional `rpcUrl` and `chainId` parameters to override per-call.

## Tools (19)

### Chain & Block
| Tool | Description |
|------|-------------|
| `chain_status` | Latest block number, chain ID, base fee, gas limit |
| `get_block` | Block details by number or hash |

### Transaction
| Tool | Description |
|------|-------------|
| `get_transaction` | Transaction details, receipt, and decoded event logs |
| `debug_transaction` | Revert reason analysis, fee breakdown, diagnostic hints |

### Account & Fee Token
| Tool | Description |
|------|-------------|
| `check_account` | Fee token, balance, KYC status |
| `fee_token_info` | Whitelist status, exchange rate, gas allowance |
| `set_fee_token` | Set fee token for gas payment (pass 0x0 to clear) |

### OIP20 Token (ERC20 superset)
| Tool | Description |
|------|-------------|
| `token_info` | Name, symbol, decimals, currency, supply, paused, policy |
| `create_token` | Create token via OIP20 Factory (anyone can create) |
| `mint_token` | Mint tokens (requires ISSUER_ROLE) |
| `transfer_token` | Transfer tokens (subject to OIP451/OIP4512 compliance) |
| `approve_token` | Approve token spending allowance |

### OIP20 Roles (RBAC)
| Tool | Description |
|------|-------------|
| `check_role` | Check roles on a token (ADMIN, ISSUER, PAUSE, UNPAUSE, BURN_BLOCKED) |
| `grant_role` | Grant a role (requires admin of that role) |
| `revoke_role` | Revoke a role (requires admin of that role) |

### OIP451 Policy & Compliance
| Tool | Description |
|------|-------------|
| `compliance_check` | OIP451 authorization + OIP4512 per-token KYC status |
| `create_policy` | Create WHITELIST or BLACKLIST policy (anyone can create) |

### Utility
| Tool | Description |
|------|-------------|
| `create_wallet` | Generate a new random wallet for testing |
| `get_wallet_address` | Derive address from private key |

## System Contract Addresses

| Contract | Address |
|----------|---------|
| OUSD (INNER_USD) | `0x6f20000000000000000000000000000000000000` |
| FeeManager | `0x6ffe000000000000000000000000000000000000` |
| TokenRateOracle | `0x6f6f000000000000000000000000000000000000` |
| OIP451 Registry | `0x6f45100000000000000000000000000000000000` |
| OIP4512 Compliance | `0x6f45120000000000000000000000000000000000` |
| OIP20 Factory | `0x6ffc000000000000000000000000000000000000` |

## Key Concepts

- **No native token**: Orqus uses OIP20 fee tokens for gas payment, not ETH
- **Fee token model**: `eth_getBalance` returns MAX; gas fees are deducted from OIP20 tokens via FeeManager
- **OIP4512 KYC**: Per-token, 0=not_passed (subject to tokenLimit), 1=passed (exempt)
- **Exchange rate**: token_per_USD scaled by 1e6 (e.g. 7820000 = 7.82 tokens per USD)
- **Gas allowance**: `balance * 1e12 * 1e6 / (baseFee * rate)`

## License

MIT