@0xmonaco/mcp-server 1.0.32 → 1.0.33-develop.c485f61

package/README.md

@@ -2,16 +2,40 @@
 
 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.
+Works in **public-only mode** with zero configuration. Add a private key to enable
+authenticated tools — scoped by a [capability profile](#capability-profiles) so that
+supplying a key does **not** blindly unlock the entire tool set.
 
 ## 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)                                |
+| Variable               | Required                     | Description                                |
+|------------------------|------------------------------|--------------------------------------------|
+| `MONACO_PRIVATE_KEY`   | No                           | Wallet private key (`0x...`) — enables authenticated tools        |
+| `MONACO_CLIENT_ID`     | With `MONACO_PRIVATE_KEY`    | Monaco application client ID                                      |
+| `MONACO_NETWORK`       | With `MONACO_PRIVATE_KEY`    | `mainnet` \| `development` \| `staging` \| `local`. **Must be explicit when a private key is set** — the server refuses to default to `mainnet` for an authenticated session. Defaults to `mainnet` only for public-only mode. |
+| `MONACO_CAPABILITY`    | No                           | `read` \| `market-maker` \| `full`. Authenticated default: `read`. See [capability profiles](#capability-profiles). |
+| `MONACO_TOOL_ALLOWLIST`| No                           | Comma-separated tool names to enable on top of the profile (explicit per-tool opt-in, e.g. a single fund-movement tool). |
+| `MONACO_TOOL_DENYLIST` | No                           | Comma-separated tool names to disable. Wins over the profile and the allowlist. |
+| `MONACO_RPC_URL`       | No                           | Sei RPC URL (defaults per network)                                |
+
+## Capability profiles
+
+`MONACO_CAPABILITY` bounds which authenticated tools the server registers. A tool that
+is not permitted by the active profile (and not named in `MONACO_TOOL_ALLOWLIST`) is
+**never registered** — this is an authorization control, not an advisory tool
+annotation.
+
+| Profile        | Tools enabled                                                                 |
+|----------------|-------------------------------------------------------------------------------|
+| `read`         | Authenticated read-only queries — profile, balances, orders, movements, fee tier, vault allowance. No state changes. **Default when authenticated** — supplying a key alone grants no write authority. |
+| `market-maker` | `read` + order placement / cancel / replace + the testnet faucet. Opt in to let an agent make markets. No fund movement. |
+| `full`         | `market-maker` + fund movement and privilege mutations (vault approve/deposit/withdraw, `transfer_rewards`). Opt-in only. |
+
+Order placement, cancel, replace, and close require `MONACO_CAPABILITY=market-maker` or
+higher — the default `read` profile cannot mutate anything. Fund-movement and privilege
+tools additionally require `full`; enable them with `MONACO_CAPABILITY=full`, or opt a
+single tool in with `MONACO_TOOL_ALLOWLIST` (e.g. `MONACO_TOOL_ALLOWLIST=vault_withdraw`).
+Grant `full` only when you intend an agent to move funds — especially on `mainnet`.
 
 ### Networks
 
@@ -45,9 +69,10 @@ Market data, orderbook, trades, and docs search — no wallet required.
 }
 ```
 
-### Full access (with authentication)
+### Authenticated mode
 
-All tools including trading, deposits, withdrawals, and profile.
+Authenticated read-only tools under the default `read` profile. `MONACO_NETWORK` is
+**required** here — the server will not default an authenticated session to `mainnet`.
 
 ```json
 {
@@ -56,6 +81,7 @@ All tools including trading, deposits, withdrawals, and profile.
       "command": "npx",
       "args": ["-y", "@0xmonaco/mcp-server"],
       "env": {
+        "MONACO_NETWORK": "staging",
         "MONACO_PRIVATE_KEY": "0x...",
         "MONACO_CLIENT_ID": "your-client-id"
       }
@@ -64,77 +90,179 @@ All tools including trading, deposits, withdrawals, and profile.
 }
 ```
 
-To connect to the public testnet, add `MONACO_NETWORK=staging` to the `env` block. RPC URLs default automatically per network but can be overridden with `MONACO_RPC_URL`.
+Trading and fund movement stay **off** here. Add `"MONACO_CAPABILITY": "market-maker"`
+to place / cancel / replace orders, or `"MONACO_CAPABILITY": "full"` to also enable
+fund-movement tools (vault deposit/withdraw, `transfer_rewards`). A single fund-movement
+tool can be opted in with `"MONACO_TOOL_ALLOWLIST": "vault_withdraw"` instead of `full`.
+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 |
+Public tools require no credentials. Authenticated tools require `MONACO_PRIVATE_KEY`,
+`MONACO_CLIENT_ID`, and `MONACO_NETWORK`, and are further gated by the active
+[capability profile](#capability-profiles) — the profile column shows the minimum
+profile each tool needs.
+
+<!-- BEGIN GENERATED TOOLS — source: typescript-sdks/packages/mcp-server/src/manifest.ts; regenerate with `bun run mcp-docs:gen` -->
+
+### Search
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `search_docs` | Public | Search the Monaco documentation for protocol, SDK, trading, and development guides. |
+
+### Market
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `get_trading_pairs` | Public | List trading pairs with optional filters (market type, base/quote token, active status). |
+| `get_trading_pair_by_symbol` | Public | Look up a trading pair by symbol (e.g. `BTC/USDC`). |
+| `get_candlesticks` | Public | Fetch OHLCV candlestick data for a trading pair. |
+| `get_market_metadata` | Public | Get tick size, minimum order size, and trading rules for a pair. |
+| `get_screener` | Public | Screen trading pairs with market stats (price, volume, change), filtered by market type, category, and active status. |
+| `get_market_stats` | Public | Get exchange-wide life-to-date cumulative volume and trade count across all markets. |
+
+### Perp market data
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `get_perp_market_config` | Public | Get a perpetual market's configuration (leverage limits, margin requirements, funding parameters). |
+| `get_perp_market_summary` | Public | Get a perpetual market's live summary (mark/index price, funding rate, open interest, 24h stats). |
+| `get_mark_price` | Public | Get the current mark price for a perpetual market. |
+| `get_index_price` | Public | Get the current index (oracle) price for a perpetual market. |
+| `get_funding_state` | Public | Get the current funding rate and next funding time for a perpetual market. |
+| `get_open_interest` | Public | Get the current open interest for a perpetual market. |
+| `get_funding_history` | Public | List historical funding-rate records for a perpetual market. |
+| `get_all_funding_history` | Public | List historical funding-rate records across all perpetual markets. |
+
+### Orderbook
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `get_orderbook` | Public | Fetch a current orderbook snapshot with bids and asks. |
+
+### Trades
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `get_trades` | Public | Fetch historical trades for a trading pair. |
+
+### Trading
+
+Order reads (`get_orders`, `get_order`) are available under `read`; the mutations below require `market-maker` or higher.
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `place_limit_order` | `market-maker` | Place a limit order with price, quantity, and time-in-force. |
+| `place_market_order` | `market-maker` | Place a market order. |
+| `replace_order` | `market-maker` | Modify an existing order's price and/or quantity. |
+| `cancel_order` | `market-maker` | Cancel a single order by ID. |
+| `batch_cancel_orders` | `market-maker` | Cancel multiple orders by ID. |
+| `batch_cancel_all_orders` | `market-maker` | Cancel all open orders, optionally filtered to a trading pair. |
+| `batch_close_all_positions` | `market-maker` | Close all open perpetual positions with market reduce-only orders (best-effort, optional pair filter). |
+| `get_orders` | `read` | List your orders with optional filters. |
+| `get_order` | `read` | Get details for a specific order by ID. |
+
+### Positions
+
+Position reads are available under `read`; `close_position` requires `market-maker`, and margin add/reduce move collateral and require `full`.
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `get_positions` | `read` | List your perpetual positions with optional filters (margin account, trading pair, status). |
+| `get_position` | `read` | Get details for a specific perpetual position by ID. |
+| `get_position_risk` | `read` | Get liquidation price, margin ratio, and risk metrics for a perpetual position. |
+| `get_position_history` | `read` | List historical (closed/reduced) perpetual position records with optional filters. |
+| `get_position_pnl_history` | `read` | Get the PnL history time series for a perpetual position over an interval. |
+| `close_position` | `market-maker` | Close a perpetual position with a market, limit, or IOC reduce order. |
+| `add_position_margin` | `full` | Add isolated margin collateral to a perpetual position. |
+| `reduce_position_margin` | `full` | Withdraw isolated margin collateral from a perpetual position back to the account. |
+
+### Portfolio
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `get_portfolio_summary` | `read` | Get your authoritative portfolio summary (equity, PnL, exposure) over a period. |
+| `get_portfolio_performance` | `read` | Get your portfolio performance time series over a period. |
+| `get_portfolio_realized_pnl` | `read` | Get your realized PnL breakdown over a period. |
+| `get_portfolio_assets` | `read` | Get your per-asset portfolio allocation and balances over a period. |
+| `get_portfolio_margin` | `read` | Get your portfolio margin overview (collateral, maintenance margin, health). |
+
+### Margin accounts
+
+Reads and risk simulations are available under `read`; collateral transfers move funds and require the `full` profile (or an explicit allowlist entry).
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `get_margin_accounts` | `read` | List your margin accounts with optional filters (state, trading pair). |
+| `get_parent_margin_account_summary` | `read` | Get your parent (cross) margin account summary. |
+| `get_available_collateral` | `read` | Get available (unlocked) collateral for allocating to margin accounts or risk buckets. |
+| `get_parent_margin_account_movements` | `read` | List collateral movements for your parent (cross) margin account. |
+| `simulate_parent_margin_order_risk` | `read` | Preview the risk impact of a prospective order against your parent (cross) margin account (read-only simulation). |
+| `simulate_risk_bucket_order_risk` | `read` | Preview the risk impact of a prospective order for a new or existing risk bucket (read-only simulation). |
+| `transfer_collateral_to_parent_margin_account` | `full` | Move collateral from spot into your parent (cross) margin account. |
+| `transfer_collateral_from_parent_margin_account` | `full` | Move collateral out of your parent (cross) margin account back to spot. |
+| `transfer_collateral_to_risk_bucket` | `full` | Allocate collateral into an isolated or cross risk bucket. |
+
+### Profile
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `get_profile` | `read` | Fetch your core profile (address, username, account type, withdrawal status). |
+| `get_balances` | `read` | List token balances with pagination. |
+| `get_balance_by_asset` | `read` | Get balance for a specific asset. |
+| `get_movements` | `read` | Fetch transaction and movement history with optional filters. |
+| `get_user_trades` | `read` | List your own trade fills with optional filters and cursor pagination. |
+| `get_funding_payments` | `read` | List your perpetual funding payments with optional filters (trading pair, position, margin account). |
+
+### Fees
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `simulate_fees` | `read` | Simulate fees for an order before placing it. |
+| `get_my_fee_tier` | `read` | Get your current fee tier, rolling 14-day volumes, and a pair's fee schedule. |
+
+### Vault
+
+Fund-movement tools require the `full` profile (or an explicit allowlist entry); the allowance and pending-withdrawal reads are available under `read`.
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `vault_approve` | `full` | Approve the vault contract to spend a token. |
+| `vault_deposit` | `full` | Deposit tokens into the vault (optional `target`: `spot` default, or `margin` to route into collateral). |
+| `vault_withdraw` | `full` | Withdraw tokens from the vault. |
+| `vault_get_allowance` | `read` | Check current token allowance for the vault. |
+| `vault_needs_approval` | `read` | Check whether an approval transaction is needed before depositing. |
+| `get_pending_withdrawals` | `read` | List your pending withdrawals still awaiting on-chain root confirmation. |
+
+### Faucet
+
+Testnet only — the faucet tools are never registered on `mainnet`.
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `request_faucet` | `market-maker` (non-mainnet) | Request test tokens for all trading pairs. |
+| `get_faucet_info` | `read` (non-mainnet) | Check remaining faucet quota, next-request time, and recent mint history. |
+
+### Trader codes & rewards
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `get_trader_code_info` | Public | Look up a trader code's details (no credentials required). |
+| `check_trader_code_availability` | Public | Public advisory check of whether a custom PitPass TraderCode handle is available (no credentials required). |
+| `get_my_trader_code` | `read` | Fetch your own trader code. |
+| `set_trader_code` | `market-maker` | Claim or edit your custom (vanity) PitPass TraderCode handle. |
+| `clear_trader_code` | `market-maker` | Clear your custom PitPass TraderCode handle, reverting to the wallet-derived default. |
+| `get_rewards_balance` | `read` | Fetch your PitPass rewards-bucket balances across reward tokens. |
+| `transfer_rewards` | `full` | Move your earned PitPass rewards from the rewards bucket into your own tradeable balance (ledger-only). |
+
+### Market pulse
+
+| Tool | Profile | Description |
+|------|---------|-------------|
+| `get_pulse` | Public | Get the latest market-pulse news feed: AI-synthesized, per-asset headlines with sentiment tags. |
+
+<!-- END GENERATED TOOLS -->
+
+_This inventory is generated from the tool manifest. Do not edit it by hand — edit
+`src/manifest.ts` and run `bun run mcp-docs:gen`._