@michaleffffff/mcp-trading-server 3.0.10 → 3.0.15

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 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.15**
 - **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,96 @@ 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`
+- 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,387 @@
-# 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...`.
+
+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`.
 
-// 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}

package/dist/server.js

@@ -168,9 +168,88 @@ function coerceStringToStringArray(input) {
     }
     return input;
 }
+function coerceEnumString(input, values) {
+    if (typeof input !== "string")
+        return input;
+    const normalizedInput = input.trim().toLowerCase();
+    if (!normalizedInput)
+        return input;
+    const stringValues = values.filter((value) => typeof value === "string");
+    const matched = stringValues.find((value) => value.toLowerCase() === normalizedInput);
+    return matched ?? input;
+}
+function normalizeCommonStringAlias(key, input) {
+    if (typeof input !== "string")
+        return input;
+    const normalizedInput = input.trim().toLowerCase();
+    if (!normalizedInput)
+        return input;
+    const aliasMap = {
+        status: {
+            open: "OPEN",
+            history: "HISTORY",
+            all: "ALL",
+        },
+        poolType: {
+            base: "BASE",
+            quote: "QUOTE",
+        },
+        direction: {
+            buy: "LONG",
+            long: "LONG",
+            bull: "LONG",
+            sell: "SHORT",
+            short: "SHORT",
+            bear: "SHORT",
+        },
+        action: {
+            add: "deposit",
+            increase: "deposit",
+            deposit: "deposit",
+            remove: "withdraw",
+            decrease: "withdraw",
+            withdraw: "withdraw",
+        },
+        orderType: {
+            market: "MARKET",
+            limit: "LIMIT",
+            stop: "STOP",
+            conditional: "CONDITIONAL",
+        },
+        triggerType: {
+            none: "NONE",
+            gte: "GTE",
+            lte: "LTE",
+        },
+        priceType: {
+            market: "market",
+            oracle: "oracle",
+        },
+    };
+    return aliasMap[key]?.[normalizedInput] ?? input;
+}
+function readEnumValues(schema) {
+    if (!schema?._def)
+        return [];
+    const entries = schema._def.entries;
+    if (entries && typeof entries === "object") {
+        return Object.values(entries);
+    }
+    const values = schema._def.values;
+    if (Array.isArray(values)) {
+        return values;
+    }
+    return [];
+}
 function coerceBySchema(value, schema) {
     const unwrapped = unwrapSchema(schema);
     const type = unwrapped?._def?.type;
+    if (type === "enum") {
+        return coerceEnumString(value, readEnumValues(unwrapped));
+    }
+    if (type === "nativeEnum") {
+        return coerceEnumString(value, Object.values(unwrapped?._def?.values ?? {}));
+    }
     if (type === "boolean") {
         return coerceBooleanString(value);
     }
@@ -183,7 +262,18 @@ function coerceBySchema(value, schema) {
     if (type === "union") {
         const options = Array.isArray(unwrapped?._def?.options) ? unwrapped._def.options : [];
         for (const option of options) {
-            const optionType = unwrapSchema(option)?._def?.type;
+            const unwrappedOption = unwrapSchema(option);
+            const optionType = unwrappedOption?._def?.type;
+            if (optionType === "enum") {
+                const coerced = coerceEnumString(value, readEnumValues(unwrappedOption));
+                if (typeof coerced === "string" && coerced !== value)
+                    return coerced;
+            }
+            if (optionType === "nativeEnum") {
+                const coerced = coerceEnumString(value, Object.values(unwrappedOption?._def?.values ?? {}));
+                if (typeof coerced === "string" && coerced !== value)
+                    return coerced;
+            }
             if (optionType === "boolean") {
                 const coerced = coerceBooleanString(value);
                 if (typeof coerced === "boolean")
@@ -207,7 +297,8 @@ function normalizeToolArgsBySchema(rawArgs, schema) {
     for (const [key, fieldSchema] of Object.entries(schema)) {
         if (!Object.prototype.hasOwnProperty.call(source, key))
             continue;
-        normalized[key] = coerceBySchema(source[key], fieldSchema);
+        const aliasedValue = normalizeCommonStringAlias(key, source[key]);
+        normalized[key] = coerceBySchema(aliasedValue, fieldSchema);
     }
     return normalized;
 }
@@ -370,7 +461,7 @@ function zodSchemaToJsonSchema(zodSchema) {
     };
 }
 // ─── MCP Server ───
-const server = new Server({ name: "myx-mcp-trading-server", version: "3.0.10" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "myx-mcp-trading-server", version: "3.0.15" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // List tools
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
@@ -491,7 +582,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    logger.info("🚀 MYX Trading MCP Server v3.0.10 running (stdio, pure on-chain, prod ready)");
+    logger.info("🚀 MYX Trading MCP Server v3.0.15 running (stdio, pure on-chain, prod ready)");
 }
 main().catch((err) => {
     logger.error("Fatal Server Startup Error", err);

package/dist/services/tradeService.js

@@ -1,10 +1,12 @@
 import { Direction, OrderType, TriggerType } from "@myx-trade/sdk";
+import { formatUnits } from "ethers";
 import { getChainId, getQuoteToken, getQuoteDecimals } from "../auth/resolveClient.js";
 import { ensureUnits } from "../utils/units.js";
 import { normalizeAddress } from "../utils/address.js";
 import { normalizeSlippagePct4dp } from "../utils/slippage.js";
 import { finalizeMutationResult } from "../utils/mutationResult.js";
 import { extractErrorMessage } from "../utils/errorMessage.js";
+import { mapTimeInForce } from "../utils/mappings.js";
 function resolveDirection(direction) {
     if (typeof direction === "string") {
         const text = direction.trim().toUpperCase();
@@ -104,6 +106,54 @@ function toBigIntOrZero(value) {
         return 0n;
     }
 }
+const ORDER_VALUE_SCALE = 1000000n;
+const DECIMAL_INPUT_RE = /^\d+(\.\d+)?$/;
+function parseScaledDecimal(value, scale, label) {
+    const text = String(value ?? "").trim();
+    if (!text)
+        throw new Error(`${label} is required.`);
+    if (!DECIMAL_INPUT_RE.test(text)) {
+        throw new Error(`${label} must be numeric.`);
+    }
+    const [integerPart, fractionPart = ""] = text.split(".");
+    const normalizedFraction = fractionPart.slice(0, scale).padEnd(scale, "0");
+    return BigInt(`${integerPart}${normalizedFraction}`);
+}
+function absBigInt(value) {
+    return value < 0n ? -value : value;
+}
+function computeQuoteNotionalRaw(sizeRaw, priceRaw30, baseDecimals, quoteDecimals) {
+    const numerator = sizeRaw * priceRaw30 * (10n ** BigInt(quoteDecimals));
+    const denominator = 10n ** BigInt(baseDecimals + 30);
+    return numerator / denominator;
+}
+function computeRecommendedSizeRaw(targetQuoteRaw, priceRaw30, baseDecimals, quoteDecimals) {
+    const numerator = targetQuoteRaw * (10n ** BigInt(baseDecimals + 30));
+    const denominator = priceRaw30 * (10n ** BigInt(quoteDecimals));
+    return numerator / denominator;
+}
+function validateIncreaseOrderEconomics(args) {
+    const collateralRawBig = BigInt(args.collateralRaw);
+    const sizeRawBig = BigInt(args.sizeRaw);
+    const priceRawBig = BigInt(args.priceRaw30);
+    if (collateralRawBig <= 0n || sizeRawBig <= 0n || priceRawBig <= 0n)
+        return;
+    const leverageScaled = parseScaledDecimal(args.leverage, 6, "leverage");
+    const targetQuoteRaw = (collateralRawBig * leverageScaled) / ORDER_VALUE_SCALE;
+    const actualQuoteRaw = computeQuoteNotionalRaw(sizeRawBig, priceRawBig, args.baseDecimals, args.quoteDecimals);
+    const deltaRaw = absBigInt(actualQuoteRaw - targetQuoteRaw);
+    const minToleranceRaw = args.quoteDecimals >= 2 ? 10n ** BigInt(args.quoteDecimals - 2) : 1n;
+    const pctToleranceRaw = targetQuoteRaw / 100n;
+    const toleranceRaw = pctToleranceRaw > minToleranceRaw ? pctToleranceRaw : minToleranceRaw;
+    if (deltaRaw <= toleranceRaw)
+        return;
+    const recommendedSizeRaw = computeRecommendedSizeRaw(targetQuoteRaw, priceRawBig, args.baseDecimals, args.quoteDecimals);
+    const targetHuman = formatUnits(targetQuoteRaw, args.quoteDecimals);
+    const actualHuman = formatUnits(actualQuoteRaw, args.quoteDecimals);
+    const recommendedSizeHuman = formatUnits(recommendedSizeRaw, args.baseDecimals);
+    const priceHuman = formatUnits(priceRawBig, 30);
+    throw new Error(`Invalid size semantics: size is BASE quantity, not USD notional. collateralAmount*leverage implies ≈${targetHuman} quote, but size*price implies ≈${actualHuman} quote. At price ${priceHuman}, recommended size is ≈${recommendedSizeHuman}.`);
+}
 async function resolveDecimalsForUpdateOrder(client, chainId, marketId, poolIdHint) {
     let baseDecimals = 18;
     let quoteDecimals = getQuoteDecimals();
@@ -199,6 +249,15 @@ export async function openPosition(client, address, args) {
     const sizeRaw = ensureUnits(args.size, baseDecimals, "size", { allowImplicitRaw: false });
     const priceRaw = ensureUnits(args.price, 30, "price", { allowImplicitRaw: false });
     const tradingFeeRaw = ensureUnits(args.tradingFee, quoteDecimals, "tradingFee", { allowImplicitRaw: false });
+    validateIncreaseOrderEconomics({
+        collateralRaw,
+        sizeRaw,
+        priceRaw30: priceRaw,
+        leverage: args.leverage,
+        baseDecimals,
+        quoteDecimals,
+    });
+    const timeInForce = mapTimeInForce(args.timeInForce);
     // --- Auto-Deposit Logic (Strict) ---
     const allowAutoDeposit = args.autoDeposit !== false;
     console.log(`[tradeService] Checking marginBalance for ${address} in pool ${args.poolId}...`);
@@ -247,7 +306,7 @@ export async function openPosition(client, address, args) {
         collateralAmount: collateralRaw,
         size: sizeRaw,
         price: priceRaw,
-        timeInForce: args.timeInForce,
+        timeInForce,
         postOnly: args.postOnly,
         slippagePct: normalizeSlippagePct4dp(args.slippagePct),
         executionFeeToken,
@@ -282,6 +341,7 @@ export async function closePosition(client, address, args) {
     }
     const baseDecimals = poolData.baseDecimals || 18;
     const quoteDecimals = poolData.quoteDecimals || 6;
+    const timeInForce = mapTimeInForce(args.timeInForce);
     return client.order.createDecreaseOrder({
         chainId,
         address,
@@ -293,7 +353,7 @@ export async function closePosition(client, address, args) {
         collateralAmount: ensureUnits(args.collateralAmount, quoteDecimals, "collateralAmount", { allowImplicitRaw: false }),
         size: ensureUnits(args.size, baseDecimals, "size", { allowImplicitRaw: false }),
         price: ensureUnits(args.price, 30, "price", { allowImplicitRaw: false }),
-        timeInForce: args.timeInForce,
+        timeInForce,
         postOnly: args.postOnly,
         slippagePct: normalizeSlippagePct4dp(args.slippagePct),
         executionFeeToken,

package/dist/tools/closePosition.js

@@ -41,7 +41,7 @@ export const closePositionTool = {
         collateralAmount: z.union([z.string(), z.number()]).describe("Collateral amount (human/raw). Also supports ALL/FULL/MAX to use live position collateral raw."),
         size: z.union([z.string(), z.number()]).describe("Position size (human/raw). Also supports ALL/FULL/MAX for exact full-close raw size."),
         price: z.union([z.string(), z.number()]).describe("Price (human or 30-dec raw units)"),
-        timeInForce: z.coerce.number().int().describe("TimeInForce: 0=GTC, 1=IOC, 2=FOK"),
+        timeInForce: z.union([z.number(), z.string()]).describe("SDK v1.0.2 supports IOC only. Use 0 or 'IOC'."),
         postOnly: z.coerce.boolean().describe("Post-only flag"),
         slippagePct: z.coerce.string().default("50").describe(SLIPPAGE_PCT_4DP_DESC),
         executionFeeToken: z.string().describe("Execution fee token address"),

package/dist/tools/executeTrade.js

@@ -23,7 +23,7 @@ export const executeTradeTool = {
         collateralAmount: z.union([z.string(), z.number()]).describe("Collateral. e.g. '100' or 'raw:100000000' (6 decimals for USDC)."),
         size: z.union([z.string(), z.number()]).describe("Notional size in base tokens. e.g. '0.5' BTC or 'raw:50000000'."),
         price: z.union([z.string(), z.number()]).describe("Execution or Limit price. e.g. '65000' or 'raw:...'"),
-        timeInForce: z.coerce.number().int().describe("0=GTC, 1=IOC, 2=FOK"),
+        timeInForce: z.union([z.number(), z.string()]).describe("SDK v1.0.2 supports IOC only. Use 0 or 'IOC'."),
         postOnly: z.coerce.boolean().describe("If true, order only executes as Maker."),
         slippagePct: z.coerce.string().default("50").describe(`${SLIPPAGE_PCT_4DP_DESC}. Default is 50 (0.5%).`),
         executionFeeToken: z.string().optional().describe("Address of token to pay gas/execution fees (typically USDC). Default is pool quoteToken."),
@@ -50,6 +50,11 @@ export const executeTradeTool = {
             const poolData = poolResponse?.data || (poolResponse?.marketId ? poolResponse : null);
             if (!poolData)
                 throw new Error(`Could not find pool metadata for ID: ${poolId}`);
+            const resolvedMarketId = String(poolData.marketId ?? "").trim();
+            const requestedMarketId = String(args.marketId ?? "").trim();
+            if (resolvedMarketId && requestedMarketId && resolvedMarketId.toLowerCase() !== requestedMarketId.toLowerCase()) {
+                throw new Error(`Invalid marketId: marketId mismatch for poolId=${poolId}. Provided=${requestedMarketId}, resolved=${resolvedMarketId}.`);
+            }
             const baseDecimals = Number(poolData.baseDecimals ?? 18);
             const quoteDecimals = Number(poolData.quoteDecimals ?? 6);
             const mappedDirection = mapDirection(args.direction);

package/dist/tools/getBaseDetail.js

@@ -2,9 +2,87 @@ import { z } from "zod";
 import { resolveClient, getChainId } from "../auth/resolveClient.js";
 import { normalizeAddress } from "../utils/address.js";
 import { extractErrorMessage } from "../utils/errorMessage.js";
+function collectRows(input) {
+    if (Array.isArray(input))
+        return input.flatMap(collectRows);
+    if (!input || typeof input !== "object")
+        return [];
+    if (input.poolId || input.pool_id || input.marketId || input.market_id)
+        return [input];
+    return Object.values(input).flatMap(collectRows);
+}
 function isNonEmptyObject(value) {
     return !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length > 0;
 }
+async function findBaseDetailFromMarkets(client, chainId, baseAddress) {
+    let rows = [];
+    try {
+        const searchRes = await client.markets.searchMarket({ chainId, keyword: "", limit: 2000 });
+        rows = collectRows(searchRes?.data ?? searchRes);
+    }
+    catch {
+        rows = [];
+    }
+    if (rows.length === 0) {
+        try {
+            const poolListRes = await client.api?.getPoolList?.();
+            rows = collectRows(poolListRes?.data ?? poolListRes);
+        }
+        catch {
+            rows = [];
+        }
+    }
+    const normalized = baseAddress.toLowerCase();
+    const matched = rows.find((row) => String(row?.baseToken ?? row?.baseAddress ?? "").trim().toLowerCase() === normalized);
+    if (!matched)
+        return null;
+    const poolId = String(matched?.poolId ?? matched?.pool_id ?? "").trim();
+    if (!poolId) {
+        return {
+            chainId,
+            baseAddress,
+            baseToken: baseAddress,
+            baseSymbol: matched?.baseSymbol ?? null,
+            baseDecimals: matched?.baseDecimals ?? matched?.base_decimals ?? null,
+            baseTokenIcon: matched?.baseTokenIcon ?? matched?.base_token_icon ?? null,
+            marketId: matched?.marketId ?? matched?.market_id ?? null,
+            poolId: null,
+            source: "market_search_fallback",
+        };
+    }
+    try {
+        const detailRes = await client.markets.getMarketDetail({ chainId, poolId });
+        const detail = detailRes?.data || (detailRes?.marketId ? detailRes : null);
+        if (detail) {
+            return {
+                chainId,
+                baseAddress,
+                baseToken: detail.baseToken ?? baseAddress,
+                baseSymbol: detail.baseSymbol ?? matched?.baseSymbol ?? null,
+                baseDecimals: detail.baseDecimals ?? matched?.baseDecimals ?? matched?.base_decimals ?? null,
+                baseTokenIcon: detail.baseTokenIcon ?? matched?.baseTokenIcon ?? null,
+                quoteSymbol: detail.quoteSymbol ?? matched?.quoteSymbol ?? null,
+                marketId: detail.marketId ?? matched?.marketId ?? null,
+                poolId: detail.poolId ?? poolId,
+                source: "market_detail_fallback",
+            };
+        }
+    }
+    catch {
+    }
+    return {
+        chainId,
+        baseAddress,
+        baseToken: baseAddress,
+        baseSymbol: matched?.baseSymbol ?? null,
+        baseDecimals: matched?.baseDecimals ?? matched?.base_decimals ?? null,
+        baseTokenIcon: matched?.baseTokenIcon ?? matched?.base_token_icon ?? null,
+        quoteSymbol: matched?.quoteSymbol ?? null,
+        marketId: matched?.marketId ?? matched?.market_id ?? null,
+        poolId,
+        source: "market_search_fallback",
+    };
+}
 function buildReadErrorPayload(args, messageLike, code = "SDK_READ_ERROR") {
     const chainId = args.chainId ?? getChainId();
     const message = extractErrorMessage(messageLike, "Failed to read base token detail.");
@@ -44,10 +122,18 @@ export const getBaseDetailTool = {
                 return { content: [{ type: "text", text: JSON.stringify(body, (_, v) => typeof v === "bigint" ? v.toString() : v, 2) }], isError: true };
             }
             if (payload === null || payload === undefined) {
+                const fallback = await findBaseDetailFromMarkets(client, chainId, baseAddress);
+                if (fallback) {
+                    return { content: [{ type: "text", text: JSON.stringify({ status: "success", data: fallback }, null, 2) }] };
+                }
                 const body = buildReadErrorPayload({ ...args, baseAddress }, "get_base_detail returned empty data.", "NOT_FOUND");
                 return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }], isError: true };
             }
             if (typeof payload === "object" && !Array.isArray(payload) && !isNonEmptyObject(payload)) {
+                const fallback = await findBaseDetailFromMarkets(client, chainId, baseAddress);
+                if (fallback) {
+                    return { content: [{ type: "text", text: JSON.stringify({ status: "success", data: fallback }, null, 2) }] };
+                }
                 const body = buildReadErrorPayload({ ...args, baseAddress }, "get_base_detail returned an empty object.", "NOT_FOUND");
                 return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }], isError: true };
             }

package/dist/tools/openPositionSimple.js

@@ -39,6 +39,7 @@ export const openPositionSimpleTool = {
     schema: {
         poolId: z.string().optional().describe("Hex Pool ID. Provide either poolId or keyword."),
         keyword: z.string().optional().describe('Recommended: Market keyword, e.g. "BTC", "ETH", "XRP".'),
+        marketId: z.string().optional().describe("Optional market config hash. If provided, it must match the market resolved from poolId/keyword."),
         direction: z.any().describe("0=LONG, 1=SHORT, or strings like 'BUY'/'SELL'/'LONG'/'SHORT'."),
         collateralAmount: z.coerce
             .string()
@@ -92,6 +93,10 @@ export const openPositionSimpleTool = {
             const marketId = String(detail.marketId ?? "").trim();
             if (!marketId)
                 throw new Error(`marketId missing from market detail for poolId=${poolId}`);
+            const requestedMarketId = String(args.marketId ?? "").trim();
+            if (requestedMarketId && requestedMarketId.toLowerCase() !== marketId.toLowerCase()) {
+                throw new Error(`marketId mismatch for poolId=${poolId}. Provided=${requestedMarketId}, resolved=${marketId}.`);
+            }
             const baseDecimals = Number(detail.baseDecimals ?? 18);
             const quoteDecimals = Number(detail.quoteDecimals ?? 6);
             const quoteToken = String(detail.quoteToken ?? "").trim();

package/dist/tools/searchTools.js

@@ -1,30 +1,255 @@
 import { z } from "zod";
 import * as allTools from "./index.js";
+const TOOL_DISCOVERY_META = {
+    find_pool: {
+        category: "market-discovery",
+        aliases: ["search_market", "get_pool_by_symbol", "find market", "find symbol"],
+        intents: ["discover market", "lookup pool", "resolve pool id"],
+        commonArgs: ["keyword"],
+    },
+    list_pools: {
+        category: "market-discovery",
+        aliases: ["get_pool_list", "get_pool_symbol_all", "all pools"],
+        intents: ["browse markets", "list tradable pools"],
+    },
+    get_price: {
+        category: "market-data",
+        aliases: ["get_market_price", "get_oracle_price", "price"],
+        intents: ["read market price", "read oracle price"],
+        commonArgs: ["poolId", "priceType"],
+    },
+    get_pool_metadata: {
+        category: "market-data",
+        aliases: ["get_market_detail", "get_pool_info", "get_liquidity_info", "get_pool_level_config"],
+        intents: ["inspect pool", "read liquidity", "read config"],
+        commonArgs: ["poolId", "includeLiquidity", "includeConfig"],
+    },
+    get_kline: {
+        category: "market-data",
+        aliases: ["candles", "ohlcv", "chart"],
+        intents: ["read kline", "read candlestick"],
+        commonArgs: ["poolId", "interval", "limit"],
+    },
+    open_position_simple: {
+        category: "trading",
+        aliases: ["open trade", "open position", "quick trade"],
+        intents: ["open long", "open short", "trade with tp sl"],
+        commonArgs: ["poolId|keyword", "direction", "collateralAmount", "leverage", "orderType"],
+    },
+    execute_trade: {
+        category: "trading",
+        aliases: ["create increase order", "advanced trade"],
+        intents: ["low-level open order", "custom increase order"],
+        commonArgs: ["poolId", "marketId", "direction", "orderType", "size", "price"],
+    },
+    close_position: {
+        category: "trading",
+        aliases: ["reduce position", "close trade"],
+        intents: ["close long", "close short"],
+        commonArgs: ["poolId", "positionId", "direction", "orderType", "size"],
+    },
+    close_all_positions: {
+        category: "trading",
+        aliases: ["panic close", "emergency close"],
+        intents: ["close everything", "flatten exposure"],
+        commonArgs: ["poolId|keyword"],
+    },
+    manage_tp_sl: {
+        category: "trading",
+        aliases: ["set tp sl", "update tp sl", "delete tp sl"],
+        intents: ["set stop loss", "set take profit", "cancel protection"],
+        commonArgs: ["poolId", "positionId|orderId", "tpPrice", "slPrice"],
+    },
+    cancel_orders: {
+        category: "trading",
+        aliases: ["cancel_all_orders", "cancel order", "revoke order"],
+        intents: ["cancel pending orders", "clear orders"],
+        commonArgs: ["orderIds|poolId|cancelAll"],
+    },
+    manage_liquidity: {
+        category: "liquidity",
+        aliases: ["add lp", "remove lp", "deposit liquidity", "withdraw liquidity"],
+        intents: ["add base lp", "add quote lp", "withdraw lp"],
+        commonArgs: ["poolId", "poolType", "action", "amount", "slippage"],
+    },
+    get_lp_price: {
+        category: "liquidity",
+        aliases: ["lp nav", "pool token price"],
+        intents: ["read lp nav", "read lp token price"],
+        commonArgs: ["poolId", "poolType"],
+    },
+    get_my_lp_holdings: {
+        category: "liquidity",
+        aliases: ["my lp", "lp balances"],
+        intents: ["list my liquidity", "portfolio lp"],
+    },
+    get_account_snapshot: {
+        category: "account",
+        aliases: ["get_account", "get_account_info", "balances overview"],
+        intents: ["check balances", "account overview"],
+        commonArgs: ["poolId"],
+    },
+    get_orders: {
+        category: "account",
+        aliases: ["get_open_orders", "order history"],
+        intents: ["list orders", "pending orders", "filled orders"],
+        commonArgs: ["status", "poolId", "limit"],
+    },
+    get_positions_all: {
+        category: "account",
+        aliases: ["get_positions", "position history"],
+        intents: ["list positions", "open positions", "closed positions"],
+        commonArgs: ["status", "poolId", "limit"],
+    },
+    get_trade_flow: {
+        category: "account",
+        aliases: ["account flow", "tx history"],
+        intents: ["read trade history", "activity feed"],
+    },
+    account_deposit: {
+        category: "account",
+        aliases: ["deposit margin", "transfer to trading"],
+        intents: ["fund trading account"],
+        commonArgs: ["amount", "tokenAddress"],
+    },
+    account_withdraw: {
+        category: "account",
+        aliases: ["withdraw margin", "transfer to wallet"],
+        intents: ["withdraw trading funds"],
+        commonArgs: ["poolId", "amount", "isQuoteToken"],
+    },
+    check_account_ready: {
+        category: "account",
+        aliases: ["precheck balance", "ready to trade"],
+        intents: ["validate collateral", "pre-trade check"],
+        commonArgs: ["poolId|keyword", "collateralAmount"],
+    },
+    search_tools: {
+        category: "utils",
+        aliases: ["find tool", "discover tool"],
+        intents: ["which tool should i use", "tool discovery"],
+        commonArgs: ["keyword"],
+    },
+};
+function normalizeText(value) {
+    return String(value ?? "").trim().toLowerCase();
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter(Boolean))];
+}
+function scoreTextMatch(query, candidate, weight) {
+    if (!candidate)
+        return 0;
+    if (candidate === query)
+        return weight + 6;
+    if (candidate.startsWith(query))
+        return weight + 3;
+    if (candidate.includes(query))
+        return weight;
+    return 0;
+}
+function isOptionalField(field) {
+    return Boolean(field?.isOptional?.()) || field?._def?.type === "optional" || field?._def?.type === "default";
+}
+function getFieldDescription(field) {
+    return String(field?._def?.description ?? "").trim();
+}
+function summarizeSchema(schema) {
+    if (!schema)
+        return { required: [], optional: [] };
+    const entries = Object.entries(schema);
+    const required = entries.filter(([, field]) => !isOptionalField(field)).map(([name]) => name);
+    const optional = entries.filter(([, field]) => isOptionalField(field)).map(([name]) => name);
+    return { required, optional };
+}
 export const searchToolsTool = {
     name: "search_tools",
-    description: "[UTILS] Search for available tools by keyword in their name or description.",
+    description: "[UTILS] Search for available tools by keyword, legacy tool name, or intent. Returns categories, aliases, and common parameters.",
     schema: {
-        keyword: z.string().describe("Keyword to search for in tool names or descriptions."),
+        keyword: z.string().describe("Keyword, old tool name, or intent phrase to search for."),
     },
     handler: async (args) => {
         try {
-            const keyword = args.keyword.toLowerCase();
+            const keyword = normalizeText(args.keyword);
             const tools = Object.values(allTools);
             const matches = tools
-                .filter(t => (t.name && t.name.toLowerCase().includes(keyword)) ||
-                (t.description && t.description.toLowerCase().includes(keyword)))
-                .map(t => ({
-                name: t.name,
-                description: t.description,
-                // We only return name and description to keep it concise
-            }));
+                .map((tool) => {
+                const meta = TOOL_DISCOVERY_META[tool.name] ?? { category: "general" };
+                const schemaSummary = summarizeSchema(tool.schema);
+                const aliases = uniqueStrings(meta.aliases ?? []);
+                const intents = uniqueStrings(meta.intents ?? []);
+                const score = scoreTextMatch(keyword, normalizeText(tool.name), 18) +
+                    scoreTextMatch(keyword, normalizeText(tool.description), 10) +
+                    aliases.reduce((sum, alias) => sum + scoreTextMatch(keyword, normalizeText(alias), 12), 0) +
+                    intents.reduce((sum, intent) => sum + scoreTextMatch(keyword, normalizeText(intent), 9), 0) +
+                    scoreTextMatch(keyword, normalizeText(meta.category), 4);
+                return {
+                    tool,
+                    meta,
+                    schemaSummary,
+                    aliases,
+                    intents,
+                    score,
+                };
+            })
+                .filter((entry) => entry.score > 0)
+                .sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name))
+                .map((entry) => {
+                const commonArgs = uniqueStrings([
+                    ...(entry.meta.commonArgs ?? []),
+                    ...entry.schemaSummary.required.slice(0, 4),
+                ]);
+                const commonArgsWithHints = commonArgs.map((name) => {
+                    const baseName = name.split("|")[0];
+                    const field = entry.tool.schema?.[baseName];
+                    const description = getFieldDescription(field);
+                    return description ? `${name}: ${description}` : name;
+                });
+                return {
+                    name: entry.tool.name,
+                    category: entry.meta.category,
+                    description: entry.tool.description,
+                    aliases: entry.aliases,
+                    intents: entry.intents,
+                    requiredArgs: entry.schemaSummary.required,
+                    commonArgs: commonArgsWithHints,
+                };
+            });
             if (matches.length === 0) {
-                return { content: [{ type: "text", text: `No tools found matching: ${args.keyword}` }] };
+                const suggestions = tools
+                    .map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    category: TOOL_DISCOVERY_META[tool.name]?.category ?? "general",
+                }))
+                    .sort((a, b) => a.name.localeCompare(b.name))
+                    .slice(0, 8);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                status: "success",
+                                data: {
+                                    count: 0,
+                                    keyword: args.keyword,
+                                    message: `No tools found matching: ${args.keyword}`,
+                                    suggestions,
+                                },
+                            }, null, 2),
+                        }],
+                };
             }
             return {
                 content: [{
                         type: "text",
-                        text: JSON.stringify({ status: "success", count: matches.length, tools: matches }, null, 2)
+                        text: JSON.stringify({
+                            status: "success",
+                            data: {
+                                count: matches.length,
+                                keyword: args.keyword,
+                                tools: matches,
+                            },
+                        }, null, 2)
                     }]
             };
         }

package/dist/utils/mappings.js

@@ -170,3 +170,14 @@ export const mapTriggerType = (input) => {
         return 2;
     throw new Error(`Invalid triggerType: ${input}. Use 0/NONE, 1/GTE or 2/LTE.`);
 };
+/**
+ * SDK v1.0.2 currently exposes IOC only.
+ */
+export const mapTimeInForce = (input) => {
+    if (input === 0)
+        return 0;
+    const s = String(input ?? "").trim().toUpperCase();
+    if (s === "0" || s === "IOC")
+        return 0;
+    throw new Error(`Invalid timeInForce: ${input}. SDK v1.0.2 currently supports IOC only, use 0/IOC.`);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaleffffff/mcp-trading-server",
-  "version": "3.0.10",
+  "version": "3.0.15",
   "type": "module",
   "bin": {
     "myx-mcp": "dist/server.js"