@michaleffffff/mcp-trading-server 2.9.9 → 3.0.1

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 3.0.1 - 2026-03-17
+
+### Added
+- `extractErrorMessage` utility for cleaner error reporting across all tools.
+
+### Changed
+- `manage_liquidity` now performs strict SDK code validation before finalizing transactions.
+- `cancel_all_orders` improved to handle comma-separated and JSON-array strings for `orderIds`.
+- Integrated meaningful error extraction into `marketInfo`, `manageLiquidity`, and `updateOrderTpSl`.
+
+## 3.0.0 - 2026-03-17
+
+### Breaking Changes
+- Removed legacy account balance tools:
+  - `get_account_info`
+  - `get_balances`
+  - `get_margin_balance`
+- Added unified replacement:
+  - `get_account`
+
+### Added
+- `TOOL_EXAMPLES.md` handbook with practical examples for all exposed tools.
+- Standardized AI-friendly error envelope with `status/error/code/hint/action`.
+
+### Changed
+- Updated prompts and README to use `get_account` and the new examples handbook.
+- Improved `search_market` behavior for empty keyword usage.
+- Read-only tool responses now surface non-zero SDK `code` as structured MCP errors.
+- `get_account` now supports partial snapshots (`meta.partial=true`) when one section fails.
+- Regression suite now validates `get_account` and handles optional `cancel_all_orders` mutation path safely.

package/README.md

@@ -1,4 +1,4 @@
-# MYX MCP Trading Server v2
+# MYX MCP Trading Server
 
 A production-ready MCP (Model Context Protocol) server that exposes tools, resources, and prompts for AI agents.
 
@@ -6,6 +6,15 @@ This server allows AI assistants (like Claude Desktop, Cursor, etc.) to securely
 
 ---
 
+# Release Notes
+
+- Current release: **3.0.0**
+- Breaking change: `get_account_info`, `get_balances`, and `get_margin_balance` were removed.
+- Replacement: use `get_account` for unified wallet + trading-account balance view.
+- Detailed history: `CHANGELOG.md`
+
+---
+
 # Features
 
 * MCP compliant server
@@ -115,7 +124,8 @@ The server will run using `stdio` transport and can be connected by any MCP-comp
 2. **Configure env**: Copy `.env.example` to `.env` and fill in `PRIVATE_KEY`, `RPC_URL`, etc.
 3. **Start the server**: Run `npm run build` then `npm run start` (use `npm run dev` for development).
 4. **Configure your MCP client**: Set `command/args/env` in your MCP client (see Claude Desktop example below).
-5. **Common flow**: Use `search_market` to get `poolId`, then optionally `get_market_price` / `get_oracle_price` to view prices, and finally use `open_position_simple` (recommended) to open a position.
+5. **Common flow**: Use `search_market` (or `get_market_list`) to get `poolId`, then optionally `get_market_price` / `get_oracle_price` to view prices, and finally use `open_position_simple` (recommended) to open a position.
+6. **Tool examples**: See `TOOL_EXAMPLES.md` for practical examples for every tool, common workflows, and parameter-unit guidance.
 
 **Minimal open position example:**
 
@@ -151,6 +161,58 @@ The server will run using `stdio` transport and can be connected by any MCP-comp
 - **Price**: `"price"` is human by default and will be converted to **30-decimal** format internally. Use `raw:` to pass a 30-decimal integer directly.
 - **Slippage**: `slippagePct` uses 4-decimal raw units: `100` = `1%`, `50` = `0.5%`, `1000` = `10%`.
 - **Note**: Some account-transfer tools (e.g. `account_deposit`, `account_withdraw`, `check_approval`) use **raw integer strings**.
+- **`adjust_margin` units**: human amount is supported (e.g. `"1"` means 1 quote token). For exact atomic amount, use `raw:` (e.g. `"raw:1"`).
+
+## P0 Reliability Contract (AI-friendly)
+
+Starting with P0, tool failures are normalized to a structured JSON envelope:
+
+```json
+{
+  "status": "error",
+  "error": {
+    "tool": "execute_trade",
+    "code": "INVALID_PARAM",
+    "message": "Invalid arguments for tool \"execute_trade\".",
+    "hint": "Fix \"positionId\": positionId must be empty string for new position, or a bytes32 hex string.",
+    "action": "Call list_tools and resend valid arguments.",
+    "details": {
+      "issues": [
+        {
+          "field": "positionId",
+          "code": "custom",
+          "message": "positionId must be empty string for new position, or a bytes32 hex string."
+        }
+      ]
+    }
+  }
+}
+```
+
+Common error codes:
+- `INVALID_PARAM`: input schema/field error.
+- `INSUFFICIENT_BALANCE`: wallet or trading-account amount is not enough.
+- `INSUFFICIENT_ALLOWANCE`: token approval/allowance is insufficient.
+- `NOT_FOUND`: bad tool name or bad identifiers (`poolId`, `orderId`, `marketId`).
+- `TIMEOUT`: tx confirmation/query timeout.
+- `NETWORK_ERROR`: RPC or network issue.
+
+Search behavior in P0:
+- `search_market` now accepts empty `keyword` and returns active markets.
+- When `search_market` returns empty/unstable data, server-side fallback uses SDK `api.getMarketList()` and `api.getPoolList()` to rebuild active-market results.
+- For robust discovery, you can also call `get_market_list` directly.
+
+Example:
+
+```json
+{
+  "name": "search_market",
+  "arguments": {
+    "keyword": "",
+    "limit": 20
+  }
+}
+```
 
 ---
 
@@ -223,7 +285,9 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 # Tools
 
-The server exposes 38 tools categorized for AI:
+The server exposes 39 tools categorized for AI:
+
+For practical tool-by-tool examples, see: `TOOL_EXAMPLES.md`
 
 ### Trading Operations
 * **open_position_simple**: High-level open position helper (recommended). Computes price/size/tradingFee internally.
@@ -231,8 +295,9 @@ The server exposes 38 tools categorized for AI:
 * **close_position**: Close an open position.
 * **close_all_positions**: Emergency: close ALL open positions in a pool at once.
 * **cancel_order**: Cancel an open order by its order ID.
-* **cancel_all_orders**: Cancel multiple open orders by order IDs (use `get_open_orders` first to get IDs).
+* **cancel_all_orders**: Cancel open orders by IDs (supports array, JSON-array string, comma string, or single ID; use `get_open_orders` first).
 * **set_tp_sl**: Set take profit and stop loss prices for an open position.
+* **update_order_tp_sl**: Update TP/SL fields for an existing order. Accepts boolean-like values for `useOrderCollateral` / `isTpSlOrder`.
 * **adjust_margin**: Adjust the margin (collateral) of an open position.
 * **get_user_trading_fee_rate**: Query current maker/taker fee rates by asset class and risk tier.
 * **get_network_fee**: Query estimated network fee requirements for a market.
@@ -243,17 +308,22 @@ The server exposes 38 tools categorized for AI:
 * **get_oracle_price**: Get the current EVM oracle price for a specific pool.
 * **get_kline_latest_bar**: Get only the latest bar for an interval.
 * **get_all_tickers**: Get all ticker snapshots in one request.
-* **get_market_list**, **get_market_list_raw**, **get_kline**, **get_pool_info**...
+* **get_market_list**, **get_market_list_raw**, **get_kline**, **get_pool_info**... (`get_pool_info` auto-retries with oracle/ticker price on divide-by-zero reads)
 * **get_pool_symbol_all**, **get_base_detail**, **get_pool_level_config**...
 
 ### Account & Portfolio
 * **get_positions**: Get all open positions for the current account.
-* **get_balances**: Get the account balances for different tokens.
+* **get_account**: Unified account snapshot. Clearly separates **wallet balance** and **trading-account balance** (provide `poolId` for full trading-account metrics).
 * **get_account_vip_info**: Query account VIP tier details.
-* **position_history**, **open_orders**...
+* **get_position_history**, **get_open_orders**, **get_order_history**...
+
+`get_account` note:
+- `poolId` omitted: wallet-focused snapshot only.
+- `poolId` provided: wallet + trading-account + margin snapshot.
+- If one section fails (wallet or trading-account), the tool may return a **partial** snapshot with `meta.partial=true` and section-level `error` details.
 
 ### Liquidity Provision (LP)
-* **manage_liquidity**: Add or withdraw liquidity from a BASE or QUOTE pool.
+* **manage_liquidity**: Add or withdraw liquidity from a BASE or QUOTE pool (aliases: `add/remove/increase/decrease` are supported).
 * **create_perp_market**: Create a new perpetual trading pair.
 
 ---
@@ -297,6 +367,35 @@ Example MCP client usage workflow:
 3. Call the `search_market` tool (e.g., `keyword: "ETH"`) to retrieve the `poolId`.
 4. Call `open_position_simple` passing the retrieved `poolId` to open a 10x long position.
 
+## Limit Order Lifecycle (P0)
+
+Use this query/mutation loop for limit-order management:
+
+1. Place order with `execute_trade` (`orderType=LIMIT`).
+2. Query active orders with `get_open_orders`.
+3. If still pending, you can cancel/update order-level fields; if filled into a position, prefer `set_tp_sl` for position TP/SL.
+4. Check historical fills/cancellations with `get_order_history`.
+5. Cancel one order via `cancel_order` or batch via `cancel_all_orders`.
+
+Minimal query examples:
+
+```json
+{
+  "name": "get_open_orders",
+  "arguments": {}
+}
+```
+
+```json
+{
+  "name": "get_order_history",
+  "arguments": {
+    "poolId": "0x...",
+    "limit": 20
+  }
+}
+```
+
 Example integration scripts are located in:
 `examples/basicUsage.ts`