@0xmonaco/mcp-server 1.0.32 → 1.0.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +205 -80
  2. package/dist/bin.js +99 -99
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -2,16 +2,40 @@
2
2
 
3
3
  MCP server for the Monaco SDK — gives AI assistants access to the Monaco protocol on Sei.
4
4
 
5
- Works in **public-only mode** with zero configuration. Add a private key to unlock trading, deposits, withdrawals, and other authenticated tools.
5
+ Works in **public-only mode** with zero configuration. Add a private key to enable
6
+ authenticated tools — scoped by a [capability profile](#capability-profiles) so that
7
+ supplying a key does **not** blindly unlock the entire tool set.
6
8
 
7
9
  ## Configuration
8
10
 
9
- | Variable | Required | Description |
10
- |----------------------|----------|--------------------------------------------|
11
- | `MONACO_PRIVATE_KEY` | No | Wallet private key (`0x...`) — enables authenticated tools |
12
- | `MONACO_CLIENT_ID` | No | Monaco application client ID — required with `MONACO_PRIVATE_KEY` |
13
- | `MONACO_NETWORK` | No | Network to connect to (default: `mainnet`) |
14
- | `MONACO_RPC_URL` | No | Sei RPC URL (defaults per network) |
11
+ | Variable | Required | Description |
12
+ |------------------------|------------------------------|--------------------------------------------|
13
+ | `MONACO_PRIVATE_KEY` | No | Wallet private key (`0x...`) — enables authenticated tools |
14
+ | `MONACO_CLIENT_ID` | With `MONACO_PRIVATE_KEY` | Monaco application client ID |
15
+ | `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. |
16
+ | `MONACO_CAPABILITY` | No | `read` \| `market-maker` \| `full`. Authenticated default: `read`. See [capability profiles](#capability-profiles). |
17
+ | `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). |
18
+ | `MONACO_TOOL_DENYLIST` | No | Comma-separated tool names to disable. Wins over the profile and the allowlist. |
19
+ | `MONACO_RPC_URL` | No | Sei RPC URL (defaults per network) |
20
+
21
+ ## Capability profiles
22
+
23
+ `MONACO_CAPABILITY` bounds which authenticated tools the server registers. A tool that
24
+ is not permitted by the active profile (and not named in `MONACO_TOOL_ALLOWLIST`) is
25
+ **never registered** — this is an authorization control, not an advisory tool
26
+ annotation.
27
+
28
+ | Profile | Tools enabled |
29
+ |----------------|-------------------------------------------------------------------------------|
30
+ | `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. |
31
+ | `market-maker` | `read` + order placement / cancel / replace + the testnet faucet. Opt in to let an agent make markets. No fund movement. |
32
+ | `full` | `market-maker` + fund movement and privilege mutations (vault approve/deposit/withdraw, `transfer_rewards`). Opt-in only. |
33
+
34
+ Order placement, cancel, replace, and close require `MONACO_CAPABILITY=market-maker` or
35
+ higher — the default `read` profile cannot mutate anything. Fund-movement and privilege
36
+ tools additionally require `full`; enable them with `MONACO_CAPABILITY=full`, or opt a
37
+ single tool in with `MONACO_TOOL_ALLOWLIST` (e.g. `MONACO_TOOL_ALLOWLIST=vault_withdraw`).
38
+ Grant `full` only when you intend an agent to move funds — especially on `mainnet`.
15
39
 
16
40
  ### Networks
17
41
 
@@ -45,9 +69,10 @@ Market data, orderbook, trades, and docs search — no wallet required.
45
69
  }
46
70
  ```
47
71
 
48
- ### Full access (with authentication)
72
+ ### Authenticated mode
49
73
 
50
- All tools including trading, deposits, withdrawals, and profile.
74
+ Authenticated read-only tools under the default `read` profile. `MONACO_NETWORK` is
75
+ **required** here — the server will not default an authenticated session to `mainnet`.
51
76
 
52
77
  ```json
53
78
  {
@@ -56,6 +81,7 @@ All tools including trading, deposits, withdrawals, and profile.
56
81
  "command": "npx",
57
82
  "args": ["-y", "@0xmonaco/mcp-server"],
58
83
  "env": {
84
+ "MONACO_NETWORK": "staging",
59
85
  "MONACO_PRIVATE_KEY": "0x...",
60
86
  "MONACO_CLIENT_ID": "your-client-id"
61
87
  }
@@ -64,77 +90,176 @@ All tools including trading, deposits, withdrawals, and profile.
64
90
  }
65
91
  ```
66
92
 
67
- 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`.
93
+ Trading and fund movement stay **off** here. Add `"MONACO_CAPABILITY": "market-maker"`
94
+ to place / cancel / replace orders, or `"MONACO_CAPABILITY": "full"` to also enable
95
+ fund-movement tools (vault deposit/withdraw, `transfer_rewards`). A single fund-movement
96
+ tool can be opted in with `"MONACO_TOOL_ALLOWLIST": "vault_withdraw"` instead of `full`.
97
+ RPC URLs default automatically per network but can be overridden with `MONACO_RPC_URL`.
68
98
 
69
99
  ## Tools
70
100
 
71
- ### Search (public)
72
-
73
- | Tool | Description |
74
- |---------------|---------------------------------|
75
- | `search_docs` | Search the Monaco documentation |
76
-
77
- ### Market (public)
78
-
79
- | Tool | Description |
80
- |------------------------------|--------------------------------------------|
81
- | `get_trading_pairs` | List trading pairs with optional filters |
82
- | `get_trading_pair_by_symbol` | Look up a pair by symbol (e.g. `BTC/USDC`) |
83
- | `get_candlesticks` | OHLCV candlestick data |
84
- | `get_market_metadata` | Tick size, min order size, trading rules |
85
-
86
- ### Orderbook (public)
87
-
88
- | Tool | Description |
89
- |-----------------|-------------------------------------------|
90
- | `get_orderbook` | Current orderbook snapshot with bids/asks |
91
-
92
- ### Trades (public)
93
-
94
- | Tool | Description |
95
- |--------------|------------------------------|
96
- | `get_trades` | Historical trades for a pair |
97
-
98
- ### Trading (authenticated)
99
-
100
- | Tool | Description |
101
- |---------------------------|--------------------------|
102
- | `place_limit_order` | Place a limit order |
103
- | `place_market_order` | Place a market order |
104
- | `cancel_order` | Cancel an order by ID |
105
- | `batch_cancel_orders` | Cancel multiple orders |
106
- | `batch_cancel_all_orders` | Cancel all open orders |
107
- | `replace_order` | Modify an existing order |
108
- | `get_orders` | List orders with filters |
109
- | `get_order` | Get order details by ID |
110
-
111
- ### Profile (authenticated)
112
-
113
- | Tool | Description |
114
- |------------------------|-----------------------------------------|
115
- | `get_profile` | User profile, balances, recent activity |
116
- | `get_balances` | Token balances with pagination |
117
- | `get_balance_by_asset` | Balance for a specific asset |
118
- | `get_movements` | Transaction history |
119
-
120
- ### Fees (authenticated)
121
-
122
- | Tool | Description |
123
- |-----------------|---------------------------------------|
124
- | `simulate_fees` | Simulate fees before placing an order |
125
-
126
- ### Vault (authenticated + on-chain)
127
-
128
- | Tool | Description |
129
- |------------------------|--------------------------------|
130
- | `vault_approve` | Approve vault to spend tokens |
131
- | `vault_deposit` | Deposit tokens into the vault |
132
- | `vault_withdraw` | Withdraw tokens from the vault |
133
- | `vault_get_allowance` | Check current token allowance |
134
- | `vault_needs_approval` | Check if approval is needed |
135
-
136
- ### Faucet (authenticated, non-mainnet only)
137
-
138
- | Tool | Description |
139
- |------------------|------------------------------------------|
140
- | `request_faucet` | Request test funds for all trading pairs |
101
+ Public tools require no credentials. Authenticated tools require `MONACO_PRIVATE_KEY`,
102
+ `MONACO_CLIENT_ID`, and `MONACO_NETWORK`, and are further gated by the active
103
+ [capability profile](#capability-profiles) — the profile column shows the minimum
104
+ profile each tool needs.
105
+
106
+ <!-- BEGIN GENERATED TOOLS — source: typescript-sdks/packages/mcp-server/src/manifest.ts; regenerate with `bun run mcp-docs:gen` -->
107
+
108
+ ### Search
109
+
110
+ | Tool | Profile | Description |
111
+ |------|---------|-------------|
112
+ | `search_docs` | Public | Search the Monaco documentation for protocol, SDK, trading, and development guides. |
113
+
114
+ ### Market
115
+
116
+ | Tool | Profile | Description |
117
+ |------|---------|-------------|
118
+ | `get_trading_pairs` | Public | List trading pairs with optional filters (market type, base/quote token, active status). |
119
+ | `get_trading_pair_by_symbol` | Public | Look up a trading pair by symbol (e.g. `BTC/USDC`). |
120
+ | `get_candlesticks` | Public | Fetch OHLCV candlestick data for a trading pair. |
121
+ | `get_market_metadata` | Public | Get tick size, minimum order size, and trading rules for a pair. |
122
+ | `get_screener` | Public | Screen trading pairs with market stats (price, volume, change), filtered by market type, category, and active status. |
123
+ | `get_market_stats` | Public | Get exchange-wide life-to-date cumulative volume and trade count across all markets. |
124
+
125
+ ### Perp market data
126
+
127
+ | Tool | Profile | Description |
128
+ |------|---------|-------------|
129
+ | `get_perp_market_config` | Public | Get a perpetual market's configuration (leverage limits, margin requirements, funding parameters). |
130
+ | `get_perp_market_summary` | Public | Get a perpetual market's live summary (mark/index price, funding rate, open interest, 24h stats). |
131
+ | `get_mark_price` | Public | Get the current mark price for a perpetual market. |
132
+ | `get_index_price` | Public | Get the current index (oracle) price for a perpetual market. |
133
+ | `get_funding_state` | Public | Get the current funding rate and next funding time for a perpetual market. |
134
+ | `get_open_interest` | Public | Get the current open interest for a perpetual market. |
135
+ | `get_funding_history` | Public | List historical funding-rate records for a perpetual market. |
136
+ | `get_all_funding_history` | Public | List historical funding-rate records across all perpetual markets. |
137
+
138
+ ### Orderbook
139
+
140
+ | Tool | Profile | Description |
141
+ |------|---------|-------------|
142
+ | `get_orderbook` | Public | Fetch a current orderbook snapshot with bids and asks. |
143
+
144
+ ### Trades
145
+
146
+ | Tool | Profile | Description |
147
+ |------|---------|-------------|
148
+ | `get_trades` | Public | Fetch historical trades for a trading pair. |
149
+
150
+ ### Trading
151
+
152
+ Order reads (`get_orders`, `get_order`) are available under `read`; the mutations below require `market-maker` or higher.
153
+
154
+ | Tool | Profile | Description |
155
+ |------|---------|-------------|
156
+ | `place_limit_order` | `market-maker` | Place a limit order with price, quantity, and time-in-force. |
157
+ | `place_market_order` | `market-maker` | Place a market order. |
158
+ | `replace_order` | `market-maker` | Modify an existing order's price and/or quantity. |
159
+ | `cancel_order` | `market-maker` | Cancel a single order by ID. |
160
+ | `batch_cancel_orders` | `market-maker` | Cancel multiple orders by ID. |
161
+ | `batch_cancel_all_orders` | `market-maker` | Cancel all open orders, optionally filtered to a trading pair. |
162
+ | `batch_close_all_positions` | `market-maker` | Close all open perpetual positions with market reduce-only orders (best-effort, optional pair filter). |
163
+ | `get_orders` | `read` | List your orders with optional filters. |
164
+ | `get_order` | `read` | Get details for a specific order by ID. |
165
+
166
+ ### Positions
167
+
168
+ Position reads are available under `read`; `close_position` requires `market-maker`, and margin add/reduce move collateral and require `full`.
169
+
170
+ | Tool | Profile | Description |
171
+ |------|---------|-------------|
172
+ | `get_positions` | `read` | List your perpetual positions with optional filters (margin account, trading pair, status). |
173
+ | `get_position` | `read` | Get details for a specific perpetual position by ID. |
174
+ | `get_position_risk` | `read` | Get liquidation price, margin ratio, and risk metrics for a perpetual position. |
175
+ | `get_position_history` | `read` | List historical (closed/reduced) perpetual position records with optional filters. |
176
+ | `get_position_pnl_history` | `read` | Get the PnL history time series for a perpetual position over an interval. |
177
+ | `close_position` | `market-maker` | Close a perpetual position with a market, limit, or IOC reduce order. |
178
+ | `add_position_margin` | `full` | Add isolated margin collateral to a perpetual position. |
179
+ | `reduce_position_margin` | `full` | Withdraw isolated margin collateral from a perpetual position back to the account. |
180
+
181
+ ### Portfolio
182
+
183
+ | Tool | Profile | Description |
184
+ |------|---------|-------------|
185
+ | `get_portfolio_summary` | `read` | Get your authoritative portfolio summary (equity, PnL, exposure) over a period. |
186
+ | `get_portfolio_performance` | `read` | Get your portfolio performance time series over a period. |
187
+ | `get_portfolio_realized_pnl` | `read` | Get your realized PnL breakdown over a period. |
188
+ | `get_portfolio_assets` | `read` | Get your per-asset portfolio allocation and balances over a period. |
189
+ | `get_portfolio_margin` | `read` | Get your portfolio margin overview (collateral, maintenance margin, health). |
190
+
191
+ ### Margin accounts
192
+
193
+ Reads and risk simulations are available under `read`; collateral transfers move funds and require the `full` profile (or an explicit allowlist entry).
194
+
195
+ | Tool | Profile | Description |
196
+ |------|---------|-------------|
197
+ | `get_margin_accounts` | `read` | List your margin accounts with optional filters (state, trading pair). |
198
+ | `get_parent_margin_account_summary` | `read` | Get your parent (cross) margin account summary. |
199
+ | `get_available_collateral` | `read` | Get available (unlocked) collateral for allocating to margin accounts or risk buckets. |
200
+ | `get_parent_margin_account_movements` | `read` | List collateral movements for your parent (cross) margin account. |
201
+ | `simulate_parent_margin_order_risk` | `read` | Preview the risk impact of a prospective order against your parent (cross) margin account (read-only simulation). |
202
+ | `simulate_risk_bucket_order_risk` | `read` | Preview the risk impact of a prospective order for a new or existing risk bucket (read-only simulation). |
203
+ | `transfer_collateral_to_parent_margin_account` | `full` | Move collateral from spot into your parent (cross) margin account. |
204
+ | `transfer_collateral_from_parent_margin_account` | `full` | Move collateral out of your parent (cross) margin account back to spot. |
205
+ | `transfer_collateral_to_risk_bucket` | `full` | Allocate collateral into an isolated or cross risk bucket. |
206
+
207
+ ### Profile
208
+
209
+ | Tool | Profile | Description |
210
+ |------|---------|-------------|
211
+ | `get_profile` | `read` | Fetch your core profile (address, username, account type, withdrawal status). |
212
+ | `get_balances` | `read` | List token balances with pagination. |
213
+ | `get_balance_by_asset` | `read` | Get balance for a specific asset. |
214
+ | `get_movements` | `read` | Fetch transaction and movement history with optional filters. |
215
+ | `get_user_trades` | `read` | List your own trade fills with optional filters and cursor pagination. |
216
+ | `get_funding_payments` | `read` | List your perpetual funding payments with optional filters (trading pair, position, margin account). |
217
+
218
+ ### Fees
219
+
220
+ | Tool | Profile | Description |
221
+ |------|---------|-------------|
222
+ | `simulate_fees` | `read` | Simulate fees for an order before placing it. |
223
+ | `get_my_fee_tier` | `read` | Get your current fee tier, rolling 14-day volumes, and a pair's fee schedule. |
224
+
225
+ ### Vault
226
+
227
+ Fund-movement tools require the `full` profile (or an explicit allowlist entry); the allowance and pending-withdrawal reads are available under `read`.
228
+
229
+ | Tool | Profile | Description |
230
+ |------|---------|-------------|
231
+ | `vault_approve` | `full` | Approve the vault contract to spend a token. |
232
+ | `vault_deposit` | `full` | Deposit tokens into the vault (optional `target`: `spot` default, or `margin` to route into collateral). |
233
+ | `vault_withdraw` | `full` | Withdraw tokens from the vault. |
234
+ | `vault_get_allowance` | `read` | Check current token allowance for the vault. |
235
+ | `vault_needs_approval` | `read` | Check whether an approval transaction is needed before depositing. |
236
+ | `get_pending_withdrawals` | `read` | List your pending withdrawals still awaiting on-chain root confirmation. |
237
+
238
+ ### Faucet
239
+
240
+ Testnet only — the faucet tools are never registered on `mainnet`.
241
+
242
+ | Tool | Profile | Description |
243
+ |------|---------|-------------|
244
+ | `request_faucet` | `market-maker` (non-mainnet) | Request test tokens for all trading pairs. |
245
+ | `get_faucet_info` | `read` (non-mainnet) | Check remaining faucet quota, next-request time, and recent mint history. |
246
+
247
+ ### Trader codes & rewards
248
+
249
+ | Tool | Profile | Description |
250
+ |------|---------|-------------|
251
+ | `get_trader_code_info` | Public | Look up a trader code's details (no credentials required). |
252
+ | `get_my_trader_code` | `read` | Fetch your own trader code. |
253
+ | `get_rewards_balance` | `read` | Fetch your PitPass rewards-bucket balances across reward tokens. |
254
+ | `transfer_rewards` | `full` | Move your earned PitPass rewards from the rewards bucket into your own tradeable balance (ledger-only). |
255
+
256
+ ### Market pulse
257
+
258
+ | Tool | Profile | Description |
259
+ |------|---------|-------------|
260
+ | `get_pulse` | Public | Get the latest market-pulse news feed: AI-synthesized, per-asset headlines with sentiment tags. |
261
+
262
+ <!-- END GENERATED TOOLS -->
263
+
264
+ _This inventory is generated from the tool manifest. Do not edit it by hand — edit
265
+ `src/manifest.ts` and run `bun run mcp-docs:gen`._