@0xmonaco/mcp-server 0.5.6 → 0.5.8

package/README.md

@@ -0,0 +1,142 @@
+# @0xmonaco/mcp-server
+
+MCP server for the Monaco SDK — gives AI assistants access to the Monaco protocol on Sei.
+
+Works in **public-only mode** with zero configuration. Add a private key to unlock trading, deposits, withdrawals, and other authenticated tools.
+
+## Configuration
+
+| Variable             | Required | Description                                |
+|----------------------|----------|--------------------------------------------|
+| `MONACO_PRIVATE_KEY` | No       | Wallet private key (`0x...`) — enables authenticated tools        |
+| `MONACO_CLIENT_ID`   | No       | Monaco application client ID — required with `MONACO_PRIVATE_KEY` |
+| `MONACO_NETWORK`     | No       | Network to connect to (default: `mainnet`)                        |
+| `MONACO_RPC_URL`     | No       | Sei RPC URL (defaults per network)                                |
+
+### Networks
+
+Set `MONACO_NETWORK` to one of the following:
+
+| Network             | API URL                         | Default RPC URL                        |
+|---------------------|---------------------------------|----------------------------------------|
+| `mainnet` (default) | `https://api.monaco.xyz`        | `https://evm-rpc.sei-apis.com`         |
+| `development`       | `https://develop.apimonaco.xyz` | `https://evm-rpc-testnet.sei-apis.com` |
+| `staging`           | `https://staging.apimonaco.xyz` | `https://evm-rpc-testnet.sei-apis.com` |
+| `local`             | `http://localhost:8080`         | `http://localhost:8545`                |
+
+## Installation
+
+Add the following to your MCP config:
+
+- **Cursor** — `~/.cursor/mcp.json`
+- **Windsurf** — `~/.codeium/windsurf/mcp_config.json`
+- **Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+
+### Public-only mode (no env vars needed)
+
+Market data, orderbook, trades, and docs search — no wallet required.
+
+```json
+{
+  "mcpServers": {
+    "monaco": {
+      "command": "npx",
+      "args": ["-y", "@0xmonaco/mcp-server"]
+    }
+  }
+}
+```
+
+### Full access (with authentication)
+
+All tools including trading, deposits, withdrawals, and profile.
+
+```json
+{
+  "mcpServers": {
+    "monaco": {
+      "command": "npx",
+      "args": ["-y", "@0xmonaco/mcp-server"],
+      "env": {
+        "MONACO_PRIVATE_KEY": "0x...",
+        "MONACO_CLIENT_ID": "your-client-id"
+      }
+    }
+  }
+}
+```
+
+To connect to a non-mainnet network, add `MONACO_NETWORK` to the `env` block (`mainnet`, `development`, `staging`, `local`). RPC URLs default automatically per network but can be overridden with `MONACO_RPC_URL`.
+
+## Tools
+
+### Search (public)
+
+| Tool          | Description                     |
+|---------------|---------------------------------|
+| `search_docs` | Search the Monaco documentation |
+
+### Market (public)
+
+| Tool                         | Description                                |
+|------------------------------|--------------------------------------------|
+| `get_trading_pairs`          | List trading pairs with optional filters   |
+| `get_trading_pair_by_symbol` | Look up a pair by symbol (e.g. `BTC/USDC`) |
+| `get_candlesticks`           | OHLCV candlestick data                     |
+| `get_market_metadata`        | Tick size, min order size, trading rules   |
+
+### Orderbook (public)
+
+| Tool            | Description                               |
+|-----------------|-------------------------------------------|
+| `get_orderbook` | Current orderbook snapshot with bids/asks |
+
+### Trades (public)
+
+| Tool         | Description                  |
+|--------------|------------------------------|
+| `get_trades` | Historical trades for a pair |
+
+### Trading (authenticated)
+
+| Tool                      | Description              |
+|---------------------------|--------------------------|
+| `place_limit_order`       | Place a limit order      |
+| `place_market_order`      | Place a market order     |
+| `cancel_order`            | Cancel an order by ID    |
+| `batch_cancel_orders`     | Cancel multiple orders   |
+| `batch_cancel_all_orders` | Cancel all open orders   |
+| `replace_order`           | Modify an existing order |
+| `get_orders`              | List orders with filters |
+| `get_order`               | Get order details by ID  |
+
+### Profile (authenticated)
+
+| Tool                   | Description                             |
+|------------------------|-----------------------------------------|
+| `get_profile`          | User profile, balances, recent activity |
+| `get_balances`         | Token balances with pagination          |
+| `get_balance_by_asset` | Balance for a specific asset            |
+| `get_movements`        | Transaction history                     |
+
+### Fees (authenticated)
+
+| Tool            | Description                           |
+|-----------------|---------------------------------------|
+| `simulate_fees` | Simulate fees before placing an order |
+
+### Vault (authenticated + on-chain)
+
+| Tool                   | Description                    |
+|------------------------|--------------------------------|
+| `vault_approve`        | Approve vault to spend tokens  |
+| `vault_deposit`        | Deposit tokens into the vault  |
+| `vault_withdraw`       | Withdraw tokens from the vault |
+| `vault_get_allowance`  | Check current token allowance  |
+| `vault_needs_approval` | Check if approval is needed    |
+
+### Faucet (authenticated, non-mainnet only)
+
+| Tool             | Description                              |
+|------------------|------------------------------------------|
+| `request_faucet` | Request test funds for all trading pairs |