@michaleffffff/mcp-trading-server 2.9.2 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 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:**
 
@@ -152,6 +162,57 @@ The server will run using `stdio` transport and can be connected by any MCP-comp
 - **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**.
 
+## 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
+  }
+}
+```
+
 ---
 
 ## Secure Deployment Template (Systemd Example)
@@ -223,7 +284,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.
@@ -248,9 +311,14 @@ The server exposes 38 tools categorized for AI:
 
 ### 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.
@@ -297,6 +365,34 @@ 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. Check historical fills/cancellations with `get_order_history`.
+4. 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`
 

package/TOOL_EXAMPLES.md

@@ -0,0 +1,536 @@
+# MYX MCP Tool Examples Handbook
+
+This handbook is designed for AI assistants and integrators.
+It includes:
+- clear parameter unit rules,
+- common end-to-end workflows,
+- at least one practical call example for every exposed tool.
+
+> All examples use MCP call payload shape:
+> `{ "name": "<tool_name>", "arguments": { ... } }`
+
+---
+
+## 1) Parameter Units & Precision (Important)
+
+- **Human-readable by default** (many trading tools): `"100"` means 100 quote tokens (e.g., USDC).
+- **Raw-unit override**: use `"raw:<integer>"` when supported by the tool.
+- **Price precision**: many low-level trading paths expect **30-decimal raw price**.
+- **Token amount precision**: depends on token decimals (e.g., USDC often 6).
+- **Slippage (`slippagePct`)**: 4-decimal integer style (e.g., `100 = 1%`, `50 = 0.5%`).
+- **Approval tool** (`check_approval`) uses **raw integer amount**.
+
+---
+
+## 2) Common Operation Flows
+
+## Flow A: Discover Market → Open Position (Recommended)
+1. `search_market` (keyword or empty keyword list)
+2. `get_market_detail` / `get_market_price`
+3. `get_account` (with `poolId`)
+4. `open_position_simple` (preferred high-level execution)
+
+## Flow B: Limit Order Lifecycle
+1. `execute_trade` with `orderType=LIMIT`
+2. `get_open_orders`
+3. `get_order_history`
+4. `cancel_order` or `cancel_all_orders`
+
+## Flow C: Balance Troubleshooting
+1. `get_account` (without `poolId`) → wallet view
+2. `get_account` (with `poolId`) → trading-account + margin
+3. `account_deposit` / `account_withdraw` as needed
+
+---
+
+## 3) Tool-by-Tool Practical Examples
+
+## Trading Operations
+
+### `open_position_simple`
+```json
+{
+  "name": "open_position_simple",
+  "arguments": {
+    "keyword": "BTC",
+    "direction": "LONG",
+    "collateralAmount": "100",
+    "leverage": 5,
+    "orderType": "MARKET",
+    "autoDeposit": false,
+    "dryRun": true
+  }
+}
+```
+
+### `execute_trade`
+```json
+{
+  "name": "execute_trade",
+  "arguments": {
+    "poolId": "0xPOOL_ID",
+    "positionId": "",
+    "orderType": "MARKET",
+    "direction": "LONG",
+    "collateralAmount": "100",
+    "size": "0.01",
+    "price": "65000",
+    "timeInForce": 0,
+    "postOnly": false,
+    "slippagePct": "100",
+    "executionFeeToken": "0xQUOTE_TOKEN",
+    "leverage": 5,
+    "tradingFee": "raw:100000",
+    "marketId": "0xMARKET_ID"
+  }
+}
+```
+
+### `close_position`
+```json
+{
+  "name": "close_position",
+  "arguments": {
+    "poolId": "0xPOOL_ID",
+    "positionId": "0xPOSITION_ID",
+    "orderType": "MARKET",
+    "direction": "LONG",
+    "collateralAmount": "0",
+    "size": "0.01",
+    "price": "65000",
+    "timeInForce": 0,
+    "postOnly": false,
+    "slippagePct": "100",
+    "executionFeeToken": "0xQUOTE_TOKEN",
+    "leverage": 5
+  }
+}
+```
+
+### `close_all_positions`
+```json
+{
+  "name": "close_all_positions",
+  "arguments": {
+    "poolId": "0xPOOL_ID",
+    "slippagePct": "200"
+  }
+}
+```
+
+### `cancel_order`
+```json
+{
+  "name": "cancel_order",
+  "arguments": {
+    "orderId": "0xORDER_ID"
+  }
+}
+```
+
+### `cancel_all_orders`
+```json
+{
+  "name": "cancel_all_orders",
+  "arguments": {
+    "orderIds": [
+      "0xORDER_ID_1",
+      "0xORDER_ID_2"
+    ]
+  }
+}
+```
+
+### `set_tp_sl`
+```json
+{
+  "name": "set_tp_sl",
+  "arguments": {
+    "poolId": "0xPOOL_ID",
+    "positionId": "0xPOSITION_ID",
+    "direction": "LONG",
+    "leverage": 5,
+    "executionFeeToken": "0xQUOTE_TOKEN",
+    "tpTriggerType": "GTE",
+    "tpPrice": "70000",
+    "tpSize": "0.01",
+    "slTriggerType": "LTE",
+    "slPrice": "60000",
+    "slSize": "0.01",
+    "slippagePct": "100"
+  }
+}
+```
+
+### `update_order_tp_sl`
+```json
+{
+  "name": "update_order_tp_sl",
+  "arguments": {
+    "orderId": "0xORDER_ID",
+    "marketId": "0xMARKET_ID",
+    "size": "0.01",
+    "price": "65000",
+    "tpPrice": "70000",
+    "tpSize": "0.005",
+    "slPrice": "60000",
+    "slSize": "0.005",
+    "useOrderCollateral": true,
+    "quoteToken": "0xQUOTE_TOKEN"
+  }
+}
+```
+
+### `adjust_margin`
+```json
+{
+  "name": "adjust_margin",
+  "arguments": {
+    "poolId": "0xPOOL_ID",
+    "positionId": "0xPOSITION_ID",
+    "adjustAmount": "1000000"
+  }
+}
+```
+
+### `check_approval`
+```json
+{
+  "name": "check_approval",
+  "arguments": {
+    "amount": "100000000",
+    "autoApprove": false
+  }
+}
+```
+
+### `get_user_trading_fee_rate`
+```json
+{
+  "name": "get_user_trading_fee_rate",
+  "arguments": {
+    "assetClass": 1,
+    "riskTier": 1
+  }
+}
+```
+
+### `get_network_fee`
+```json
+{
+  "name": "get_network_fee",
+  "arguments": {
+    "marketId": "0xMARKET_ID"
+  }
+}
+```
+
+## Market Data
+
+### `search_market`
+```json
+{
+  "name": "search_market",
+  "arguments": {
+    "keyword": "ETH",
+    "limit": 10
+  }
+}
+```
+
+### `search_market` (list active markets)
+```json
+{
+  "name": "search_market",
+  "arguments": {
+    "keyword": "",
+    "limit": 20
+  }
+}
+```
+Note: this tool may internally fallback to SDK `api.getMarketList()` / `api.getPoolList()` when direct search is empty.
+
+### `get_market_list`
+```json
+{
+  "name": "get_market_list",
+  "arguments": {
+    "limit": 50
+  }
+}
+```
+
+### `get_market_list_raw`
+```json
+{
+  "name": "get_market_list_raw",
+  "arguments": {}
+}
+```
+
+### `get_pool_list`
+```json
+{
+  "name": "get_pool_list",
+  "arguments": {}
+}
+```
+
+### `get_market_detail`
+```json
+{
+  "name": "get_market_detail",
+  "arguments": {
+    "poolId": "BTC"
+  }
+}
+```
+
+### `get_pool_info`
+```json
+{
+  "name": "get_pool_info",
+  "arguments": {
+    "poolId": "0xPOOL_ID"
+  }
+}
+```
+
+### `get_liquidity_info`
+```json
+{
+  "name": "get_liquidity_info",
+  "arguments": {
+    "poolId": "0xPOOL_ID",
+    "marketPrice": "6500000000000000000000000000000000"
+  }
+}
+```
+
+### `get_pool_level_config`
+```json
+{
+  "name": "get_pool_level_config",
+  "arguments": {
+    "poolId": "0xPOOL_ID"
+  }
+}
+```
+
+### `get_market_price`
+```json
+{
+  "name": "get_market_price",
+  "arguments": {
+    "poolId": "0xPOOL_ID"
+  }
+}
+```
+
+### `get_oracle_price`
+```json
+{
+  "name": "get_oracle_price",
+  "arguments": {
+    "poolId": "0xPOOL_ID"
+  }
+}
+```
+
+### `get_kline`
+```json
+{
+  "name": "get_kline",
+  "arguments": {
+    "poolId": "0xPOOL_ID",
+    "interval": "15m",
+    "limit": 100
+  }
+}
+```
+
+### `get_kline_latest_bar`
+```json
+{
+  "name": "get_kline_latest_bar",
+  "arguments": {
+    "poolId": "0xPOOL_ID",
+    "interval": "1m"
+  }
+}
+```
+
+### `get_all_tickers`
+```json
+{
+  "name": "get_all_tickers",
+  "arguments": {}
+}
+```
+
+### `get_pool_symbol_all`
+```json
+{
+  "name": "get_pool_symbol_all",
+  "arguments": {}
+}
+```
+
+### `get_base_detail`
+```json
+{
+  "name": "get_base_detail",
+  "arguments": {
+    "baseAddress": "0xBASE_TOKEN"
+  }
+}
+```
+
+## Account & Query
+
+### `get_account`
+```json
+{
+  "name": "get_account",
+  "arguments": {
+    "poolId": "0xPOOL_ID"
+  }
+}
+```
+
+If one section fails, check `data.meta.partial` and section-level `error` fields.
+
+### `get_account` (wallet-only view)
+```json
+{
+  "name": "get_account",
+  "arguments": {}
+}
+```
+
+### `get_positions`
+```json
+{
+  "name": "get_positions",
+  "arguments": {}
+}
+```
+
+### `get_open_orders`
+```json
+{
+  "name": "get_open_orders",
+  "arguments": {}
+}
+```
+
+### `get_order_history`
+```json
+{
+  "name": "get_order_history",
+  "arguments": {
+    "poolId": "0xPOOL_ID",
+    "limit": 20
+  }
+}
+```
+
+### `get_position_history`
+```json
+{
+  "name": "get_position_history",
+  "arguments": {
+    "poolId": "0xPOOL_ID",
+    "limit": 20
+  }
+}
+```
+
+### `get_trade_flow`
+```json
+{
+  "name": "get_trade_flow",
+  "arguments": {
+    "limit": 20
+  }
+}
+```
+
+### `get_account_vip_info`
+```json
+{
+  "name": "get_account_vip_info",
+  "arguments": {}
+}
+```
+
+### `account_deposit`
+```json
+{
+  "name": "account_deposit",
+  "arguments": {
+    "amount": "100",
+    "tokenAddress": "0xQUOTE_TOKEN"
+  }
+}
+```
+
+### `account_withdraw`
+```json
+{
+  "name": "account_withdraw",
+  "arguments": {
+    "poolId": "0xPOOL_ID",
+    "amount": "50",
+    "isQuoteToken": true
+  }
+}
+```
+
+## Liquidity / LP
+
+### `manage_liquidity`
+```json
+{
+  "name": "manage_liquidity",
+  "arguments": {
+    "action": "deposit",
+    "poolType": "QUOTE",
+    "poolId": "0xPOOL_ID",
+    "amount": 100,
+    "slippage": 0.01
+  }
+}
+```
+
+### `get_lp_price`
+```json
+{
+  "name": "get_lp_price",
+  "arguments": {
+    "poolType": "QUOTE",
+    "poolId": "0xPOOL_ID"
+  }
+}
+```
+
+### `create_perp_market`
+```json
+{
+  "name": "create_perp_market",
+  "arguments": {
+    "baseToken": "0xBASE_TOKEN",
+    "marketId": "0xMARKET_CONFIG_HASH"
+  }
+}
+```
+
+---
+
+## 4) Practical Tips for AI Agents
+
+- Always discover/validate `poolId` before mutation tools.
+- Prefer `open_position_simple` for new-position UX unless strict low-level control is required.
+- Before trading, call `get_account` and `check_approval`.
+- For limit-order support conversations, include `get_open_orders` and `get_order_history` in the loop.
+- If any mutation fails, read structured error fields: `error.code`, `error.hint`, `error.action`.