@michaleffffff/mcp-trading-server 3.0.10 → 3.0.16

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## 3.0.16 - 2026-03-18
+
+### Fixed
+- Improved MCP-side validation UX:
+  - `executionFeeToken` now fails early with a clear `INVALID_PARAM` when callers pass the zero address, and points users to the real pool `quoteToken`.
+  - `open_position_simple` no longer returns a generic numeric parse error when `collateralAmount` is omitted; it now explains that `collateralAmount` is still required and suggests an approximate value from `size`, `price`, and `leverage`.
+
+## 3.0.15 - 2026-03-18
+
+### Fixed
+- Hardened trading parameter compatibility with SDK `v1.0.2`:
+  - `execute_trade` / `close_position` now enforce `timeInForce=IOC` only (`0` / `IOC`).
+  - Added `poolId` ↔ `marketId` consistency validation on `execute_trade`.
+  - Added preflight size/notional validation so `size` is treated strictly as BASE quantity instead of mistaken USD order value.
+- Hardened `get_base_detail`:
+  - If SDK returns empty data for a valid active base token, MCP now falls back to market search + market detail to synthesize base metadata instead of returning false `NOT_FOUND`.
+
+## 3.0.14 - 2026-03-18
+
+### Fixed
+- Improved `open_position_simple` compatibility for MCP/LLM callers:
+  - Accepts optional `marketId` input without triggering schema rejection.
+  - Validates supplied `marketId` against the market resolved from `poolId` / `keyword`.
+  - Added regression coverage for `dryRun` calls that include `marketId`.
+
+## 3.0.13 - 2026-03-18
+
+### Changed
+- Updated docs to better reflect the consolidated toolset:
+  - Added a `Legacy Mapping` section to `README.md`
+  - Added a `Tool Discovery` workflow using `search_tools`
+  - Added a dedicated `Parameter Format Guide` with canonical examples
+- Rebuilt `TOOL_EXAMPLES.md` into a current, MCP-first example handbook with clearer payload formats for trading, liquidity, account, and discovery workflows.
+- Improved `search_tools`:
+  - Searches legacy tool names, aliases, categories, and intent phrases
+  - Returns categories, aliases, required args, and common parameter hints
+  - Returns fallback suggestions when no exact match is found
+- Updated `trading_best_practices` prompt to reference `search_tools`, consolidated tools, and tolerant enum handling.
+
+## 3.0.12 - 2026-03-18
+
+### Changed
+- Expanded MCP server-side alias normalization beyond case-insensitive enums:
+  - `direction`: supports `buy/sell`, `long/short`, `bull/bear`
+  - `action`: supports `add/remove/increase/decrease` and normalizes to `deposit/withdraw`
+  - `orderType`: supports case-insensitive `market/limit/stop/conditional`
+  - `triggerType`: supports case-insensitive `none/gte/lte`
+- This keeps tool schemas strict while making AI/tool callers more tolerant of natural-language style inputs.
+
+## 3.0.11 - 2026-03-18
+
+### Changed
+- Improved MCP argument normalization for string enums:
+  - `z.enum(...)` inputs are now matched case-insensitively at the server layer before Zod validation.
+  - Lowercase/mixed-case inputs like `open`, `history`, `all`, `base`, `quote`, `long`, `short` now normalize to canonical enum values automatically.
+- This reduces avoidable `INVALID_PARAM` errors for AI callers while preserving the same canonical tool schemas.
+
 ## 3.0.10 - 2026-03-18
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@ A production-ready MCP (Model Context Protocol) server for deep integration with
 
 # Release Notes
 
-- **Current release: 3.0.10**
+- **Current release: 3.0.16**
 - **SDK baseline**: `@myx-trade/sdk@^1.0.2` compatibility completed.
 - **Refinement**: Consolidated 40+ specialized tools into ~26 high-level unified tools.
 - **Improved UX**: Enhanced AI parameter parsing, automated unit conversion, and structured error reporting.
@@ -44,6 +44,7 @@ QUOTE_TOKEN_DECIMALS=18
 ### 📈 Market Analysis
 * **`find_pool`**: Discover active markets by keyword/symbol (e.g., "BTC", "ETH").
 * **`list_pools`**: List all tradable assets on the current chain.
+* **`search_tools`**: Discover the right MCP tool by keyword, legacy tool name, or intent phrase.
 * **`get_price`**: Fetch real-time prices (Impact Market Price or Oracle Price).
 * **`get_pool_metadata`**: Comprehensive metrics (Fees, Open Interest, Liquidity Depth).
 * **`get_kline`**: Fetch candlestick data for technical analysis.
@@ -75,6 +76,97 @@ QUOTE_TOKEN_DECIMALS=18
 
 ---
 
+# Tool Discovery
+
+When a client or LLM is unsure which tool to call:
+
+1. Use `search_tools(keyword="open order")` or `search_tools(keyword="get_market_price")`
+2. Read the returned `aliases`, `category`, and `commonArgs`
+3. Confirm market context with `find_pool`
+4. Call the recommended high-level tool instead of a removed legacy tool
+
+Examples:
+
+```json
+{ "name": "search_tools", "arguments": { "keyword": "get_open_orders" } }
+```
+
+```json
+{ "name": "search_tools", "arguments": { "keyword": "add base lp" } }
+```
+
+---
+
+# Parameter Format Guide
+
+Use these conventions when generating tool arguments:
+
+- `poolId`: Prefer a real hex pool id from `find_pool` or `list_pools`
+- `keyword`: Use a market symbol like `"BTC"`, `"ETH"`, `"ARB"`
+- `direction`: `LONG` / `SHORT` are canonical; lowercase and aliases like `buy` / `sell` are tolerated
+- `status`: `OPEN` / `HISTORY` / `ALL` are canonical; lowercase is tolerated
+- `poolType`: `BASE` / `QUOTE` are canonical; lowercase is tolerated
+- `orderType`: `MARKET` / `LIMIT` / `STOP` / `CONDITIONAL`
+- `timeInForce`: SDK `v1.0.2` currently supports `IOC` only, so use `0` or `"IOC"`
+- `size`: base token quantity, not USD notional; expected order value is usually `collateralAmount * leverage`
+- `executionFeeToken`: must be a real token address; zero address is rejected. Use the pool `quoteToken`
+- Human units: `"100"` means 100 USDC or 100 token units depending on field
+- Raw units: `"raw:1000000"` means exact on-chain integer units
+
+Examples:
+
+```json
+{
+  "name": "get_orders",
+  "arguments": { "status": "OPEN", "limit": 20 }
+}
+```
+
+```json
+{
+  "name": "manage_liquidity",
+  "arguments": {
+    "poolId": "0x...",
+    "poolType": "BASE",
+    "action": "deposit",
+    "amount": 1000,
+    "slippage": 0.01
+  }
+}
+```
+
+```json
+{
+  "name": "open_position_simple",
+  "arguments": {
+    "keyword": "ARB",
+    "direction": "LONG",
+    "collateralAmount": "100",
+    "leverage": 5,
+    "orderType": "LIMIT",
+    "price": "2.5"
+  }
+}
+```
+
+---
+
+# Legacy Mapping
+
+Common old-to-new tool mappings:
+
+- `get_market_price` / `get_oracle_price` -> `get_price`
+- `get_market_detail` / `get_pool_info` / `get_liquidity_info` / `get_pool_level_config` -> `get_pool_metadata`
+- `get_pool_list` / `get_pool_symbol_all` -> `list_pools`
+- `search_market` / `get_pool_by_symbol` -> `find_pool`
+- `get_open_orders` / `get_order_history` -> `get_orders`
+- `get_positions` / `get_position_history` -> `get_positions_all`
+- `cancel_order` / `cancel_all_orders` -> `cancel_orders`
+- `set_tp_sl` / `update_order_tp_sl` -> `manage_tp_sl`
+- `get_account` / `get_account_info` / `get_balances` / `get_margin_balance` -> `get_account_snapshot`
+
+---
+
 # Documentation
 
 For detailed implementation examples and parameter guides, see:

package/TOOL_EXAMPLES.md

@@ -1,150 +1,389 @@
-# MYX MCP Tool Examples Handbook (v3.0.4)
+# MYX MCP Tool Examples Handbook (v3.0.15)
 
-This guide provides practical payload examples for the consolidated toolset. 
-All examples follow the MCP format: `{ "name": "...", "arguments": { ... } }`.
+This guide provides practical MCP payload examples for the current unified toolset.
+All examples use the MCP format:
+
+```json
+{ "name": "tool_name", "arguments": { "...": "..." } }
+```
+
+---
+
+## Discovery First
+
+### `search_tools`
+Find the right tool by intent phrase, old tool name, or keyword.
+
+```json
+{
+  "name": "search_tools",
+  "arguments": { "keyword": "get_open_orders" }
+}
+```
+
+```json
+{
+  "name": "search_tools",
+  "arguments": { "keyword": "add base lp" }
+}
+```
+
+### `find_pool`
+Resolve a market keyword to a tradable `poolId`.
+
+```json
+{
+  "name": "find_pool",
+  "arguments": { "keyword": "ETH", "limit": 5 }
+}
+```
+
+### `list_pools`
+Browse all current markets on the active chain.
+
+```json
+{
+  "name": "list_pools",
+  "arguments": {}
+}
+```
 
 ---
 
-## 🟢 Trading Operations
+## Trading
+
+### `open_position_simple`
+Recommended high-level entry tool.
 
-### `open_position_simple` (Recommended)
-High-level tool that computes size and fees automatically.
 ```json
 {
   "name": "open_position_simple",
   "arguments": {
-    "keyword": "BTC",
+    "keyword": "ARB",
+    "marketId": "0x...",
     "direction": "LONG",
     "collateralAmount": "100",
-    "leverage": 10,
-    "tpPrice": "75000",
-    "slPrice": "62000"
+    "leverage": 5,
+    "orderType": "LIMIT",
+    "price": "2.5",
+    "tpPrice": "2.9",
+    "slPrice": "2.2"
   }
 }
 ```
 
-### `cancel_orders` (Unified)
-Supports three modes: single ID, all in a pool, or all in account.
+`marketId` is optional on `open_position_simple`. If supplied, it is validated against the market resolved from `poolId` or `keyword`.
+`size` is always the base-asset quantity, not the USD notional. For example, a 500 USD order at price 1200 implies `size ≈ 0.416666...`.
+`collateralAmount` remains required on `open_position_simple`; if omitted, MCP now returns an actionable suggestion instead of a generic parse error.
+
+Raw-units example:
+
 ```json
-// Mode 1: Specific IDs
 {
-  "name": "cancel_orders",
-  "arguments": { "orderIds": ["0x123...", "0x456..."] }
+  "name": "open_position_simple",
+  "arguments": {
+    "poolId": "0x...",
+    "direction": "SHORT",
+    "collateralAmount": "raw:100000000",
+    "leverage": 10,
+    "orderType": "MARKET"
+  }
 }
+```
 
-// Mode 2: Pool-wide
+### `execute_trade`
+Low-level increase-order tool when you want full control.
+
+```json
 {
-  "name": "cancel_orders",
-  "arguments": { "poolId": "BTC" }
+  "name": "execute_trade",
+  "arguments": {
+    "poolId": "0x...",
+    "marketId": "0x...",
+    "direction": "LONG",
+    "orderType": "LIMIT",
+    "price": "2500",
+    "size": "0.2",
+    "collateralAmount": "100",
+    "timeInForce": 0,
+    "leverage": 5
+  }
 }
+```
+
+`timeInForce` should be `0` (or `"IOC"` in string form) for SDK `v1.0.2`.
+`executionFeeToken` must be a real token address; do not pass the zero address. Use the pool `quoteToken`.
 
-// Mode 3: Global
+### `close_position`
+Close or reduce a position. Use `ALL` for a full close.
+
+```json
 {
-  "name": "cancel_orders",
-  "arguments": { "cancelAll": true }
+  "name": "close_position",
+  "arguments": {
+    "poolId": "0x...",
+    "positionId": "0x...",
+    "direction": "LONG",
+    "orderType": "MARKET",
+    "collateralAmount": "ALL",
+    "size": "ALL",
+    "price": "2200",
+    "timeInForce": 0,
+    "postOnly": false,
+    "slippagePct": "50",
+    "executionFeeToken": "0x...",
+    "leverage": 5
+  }
 }
 ```
 
 ### `manage_tp_sl`
-Update existing protection orders or set new ones for a position.
+Create or update TP/SL on an open position.
+
 ```json
 {
   "name": "manage_tp_sl",
   "arguments": {
-    "poolId": "BTC",
-    "positionId": "0xABC...",
+    "poolId": "0x...",
+    "positionId": "0x...",
+    "direction": "LONG",
     "leverage": 5,
-    "tpPrice": "80000",
-    "slPrice": "55000"
+    "tpPrice": "2800",
+    "slPrice": "2300"
   }
 }
 ```
 
-Delete both TP/SL for a position:
+Delete both TP/SL orders:
+
 ```json
 {
   "name": "manage_tp_sl",
   "arguments": {
-    "poolId": "BTC",
-    "positionId": "0xABC...",
+    "poolId": "0x...",
+    "positionId": "0x...",
     "tpPrice": "0",
     "slPrice": "0"
   }
 }
 ```
 
----
+### `cancel_orders`
+Supports single-order, pool-wide, or account-wide cancellation.
 
-## 🔵 Market Data
+```json
+{
+  "name": "cancel_orders",
+  "arguments": { "orderIds": ["123", "124"] }
+}
+```
 
-### `find_pool`
-Keyword or symbol based discovery.
 ```json
 {
-  "name": "find_pool",
-  "arguments": { "keyword": "ETH" }
+  "name": "cancel_orders",
+  "arguments": { "poolId": "0x..." }
+}
+```
+
+```json
+{
+  "name": "cancel_orders",
+  "arguments": { "cancelAll": true }
 }
 ```
 
+---
+
+## Market Data
+
 ### `get_price`
-Unified price fetching.
+Read either market or oracle price.
+
 ```json
 {
   "name": "get_price",
-  "arguments": { 
-    "poolId": "0x...", 
-    "priceType": "market" 
+  "arguments": {
+    "poolId": "0x...",
+    "priceType": "market"
+  }
+}
+```
+
+```json
+{
+  "name": "get_price",
+  "arguments": {
+    "poolId": "0x...",
+    "priceType": "oracle"
   }
 }
 ```
 
 ### `get_pool_metadata`
-Detailed pool state (Fees, Liquidity, Open Interest).
+Unified pool detail, config, and liquidity info.
+
 ```json
 {
   "name": "get_pool_metadata",
-  "arguments": { "poolId": "0x..." }
+  "arguments": {
+    "poolId": "0x...",
+    "includeConfig": true,
+    "includeLiquidity": true
+  }
+}
+```
+
+### `get_kline`
+Read chart data. Use `limit: 1` for the latest bar.
+
+```json
+{
+  "name": "get_kline",
+  "arguments": {
+    "poolId": "0x...",
+    "interval": "1m",
+    "limit": 50
+  }
+}
+```
+
+---
+
+## Liquidity
+
+### `manage_liquidity`
+Add or remove BASE/QUOTE LP.
+
+```json
+{
+  "name": "manage_liquidity",
+  "arguments": {
+    "poolId": "0x...",
+    "poolType": "BASE",
+    "action": "deposit",
+    "amount": 1000,
+    "slippage": 0.01
+  }
+}
+```
+
+Alias-friendly form also works:
+
+```json
+{
+  "name": "manage_liquidity",
+  "arguments": {
+    "poolId": "0x...",
+    "poolType": "base",
+    "action": "add",
+    "amount": 1000,
+    "slippage": 0.01
+  }
+}
+```
+
+### `get_lp_price`
+Read LP NAV price for BASE or QUOTE side.
+
+```json
+{
+  "name": "get_lp_price",
+  "arguments": {
+    "poolId": "0x...",
+    "poolType": "QUOTE"
+  }
+}
+```
+
+### `get_my_lp_holdings`
+Read current LP balances across pools.
+
+```json
+{
+  "name": "get_my_lp_holdings",
+  "arguments": {
+    "includeZero": false,
+    "maxPools": 20
+  }
 }
 ```
 
 ---
 
-## 🟡 Account & Portfolio
+## Account And Monitoring
 
 ### `get_account_snapshot`
-Unified overview. Includes wallet balances and VIP info.
+Read wallet balance, trading account info, and VIP snapshot.
+
 ```json
 {
   "name": "get_account_snapshot",
-  "arguments": { "poolId": "BTC" }
+  "arguments": {
+    "poolId": "0x..."
+  }
+}
+```
+
+### `check_account_ready`
+Pre-check whether collateral is available before trading.
+
+```json
+{
+  "name": "check_account_ready",
+  "arguments": {
+    "poolId": "0x...",
+    "collateralAmount": "100"
+  }
 }
 ```
 
 ### `get_orders`
-Unified list for both active (OPEN) and historical (HISTORY) orders.
+Read open orders, history, or both.
+
 ```json
 {
   "name": "get_orders",
-  "arguments": { 
-    "status": "ALL",
-    "limit": 10
+  "arguments": {
+    "status": "OPEN",
+    "poolId": "0x...",
+    "limit": 20
+  }
+}
+```
+
+Lowercase is also accepted:
+
+```json
+{
+  "name": "get_orders",
+  "arguments": {
+    "status": "open",
+    "limit": 20
   }
 }
 ```
 
 ### `get_positions_all`
-Current open positions and closed history.
+Read open positions, history, or both.
+
 ```json
 {
   "name": "get_positions_all",
-  "arguments": { "status": "OPEN" }
+  "arguments": {
+    "status": "ALL",
+    "poolId": "0x...",
+    "limit": 20
+  }
 }
 ```
 
 ---
 
-## 💡 Important Rules
+## Parameter Conventions
 
-1. **Unit Prefixing**: Use `human:` for readable amounts and `raw:` for exact on-chain units. Default is usually human-readable for high-level tools.
-2. **Pool Discovery**: Always run `find_pool` first to get the correct `poolId`.
-3. **Pre-trade Check**: Use `check_account_ready` to ensure enough collateral is in the trading account before opening positions.
+1. Use `find_pool` before trading if you do not already have a `poolId`.
+2. Human-readable units are allowed on high-level tools, such as `"100"` or `"0.5"`.
+3. Exact on-chain values can be passed with the `raw:` prefix.
+4. Canonical enums are still preferred:
+   `OPEN|HISTORY|ALL`, `BASE|QUOTE`, `LONG|SHORT`, `MARKET|LIMIT|STOP`.
+5. The server tolerates common lowercase and alias forms for better AI compatibility.

package/dist/prompts/tradingGuide.js

@@ -12,12 +12,12 @@ export const tradingGuidePrompt = {
                     content: {
                         type: "text",
                         text: `
-# MYX Trading MCP Best Practices (v3.0.4)
+# MYX Trading MCP Best Practices (v3.0.12)
 
 You are an expert crypto trader using the MYX Protocol. To ensure successful execution and safe handling of user funds, follow these patterns:
 
 ## 1. The Standard Workflow
-1. **Discovery**: Use \`find_pool\` with a keyword (e.g. "BTC") to get the \`poolId\`. 
+1. **Discovery**: Use \`search_tools\` if the intent is unclear, then use \`find_pool\` with a keyword (e.g. "BTC") to get the \`poolId\`. 
 2. **Context**: Use \`get_account_snapshot\` (with \`poolId\`) to check balances, trading metrics, and VIP tier. Use \`get_price\` for real-time market/oracle prices.
 3. **Pre-check**: Use \`check_account_ready\` to ensure the trading account has enough collateral.
 4. **Execution**: Prefer \`open_position_simple\` for entry. It supports Stop-Loss (\`slPrice\`) and Take-Profit (\`tpPrice\`) in one call.
@@ -26,10 +26,12 @@ You are an expert crypto trader using the MYX Protocol. To ensure successful exe
 
 ## 2. Parameter Tips
 - **Consolidated Tools**: Many legacy tools have been merged. Always use the high-level versions (e.g., \`get_price\` instead of \`get_market_price\`).
+- **Discovery**: \`search_tools\` understands legacy names like \`get_open_orders\` and intent phrases like \`add base lp\`.
 - **Unit Prefixes**: Prefer \`human:\` for readable amounts (e.g., "100" USDC) and \`raw:\` for exact on-chain units.
 - **Slippage**: Default is 100 (1%). For volatile tokens, consider 200-300 (2-3%).
 - **Fees**: Use \`get_pool_metadata\` to view current fee tiers and pool configuration.
 - **LP Strategy**: Use \`get_my_lp_holdings\` to monitor liquidity positions. Naming follows \`mBASE.QUOTE\` (e.g., \`mBTC.USDC\`).
+- **Enum Tolerance**: The server tolerates common lowercase or alias inputs such as \`open\`, \`base\`, \`buy\`, and \`add\`, but canonical forms are still preferred in documentation.
 
 Current Session:
 - Wallet: ${address}