@michaleffffff/mcp-trading-server 2.7.0 → 2.8.2

package/dist/prompts/index.js

@@ -1 +1,2 @@
 export { tradeAnalysisPrompt } from "./tradeAnalysisPrompt.js";
+export { tradingGuidePrompt } from "./tradingGuide.js";

package/dist/prompts/tradeAnalysisPrompt.js

@@ -20,7 +20,17 @@ export const tradeAnalysisPrompt = {
                         role: "user",
                         content: {
                             type: "text",
-                            text: `Please analyze my current trading positions:\n\nPositions: ${JSON.stringify(positions, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2)}\n\nMarket Context: ${args?.marketContext || "None provided"}\n\nWhat are the major risks and opportunities?`
+                            text: `Analyze this user's trading portfolio with professional rigor:
+
+Positions: ${JSON.stringify(positions, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2)}
+
+Market Context: ${args?.marketContext || "None provided"}
+
+## Analysis Requirements:
+1. **Risk Level**: Calculate current margin health and distance to liquidation price.
+2. **PnL Review**: Evaluate performance and identify if SL/TP are appropriately placed.
+3. **Actionable Suggestions**: Suggest specific size adjustments or TP/SL updates based on context.
+4. **Funding Outlook**: Brief comment on funding fee impacts if observable.`
                         }
                     }
                 ]

package/dist/prompts/tradingGuide.js

@@ -0,0 +1,43 @@
+import { resolveClient } from "../auth/resolveClient.js";
+export const tradingGuidePrompt = {
+    name: "trading_best_practices",
+    description: "Get the gold standard workflow and parameter advice for using this MCP trading server.",
+    arguments: [],
+    run: async () => {
+        const { address, chainId } = await resolveClient();
+        return {
+            messages: [
+                {
+                    role: "assistant",
+                    content: {
+                        type: "text",
+                        text: `
+# MYX Trading MCP Best Practices (v2.8.0)
+
+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 \`search_market\` with a keyword (e.g., "BTC") to find the active \`poolId\`.
+2. **Context**: Use \`get_market_price\` and \`get_account_info\` to check the current market state and your available margin.
+3. **Execution**: Prefer \`open_position_simple\` for new trades. It handles unit conversions and pool resolution automatically.
+4. **Validation**: Always check the \`verification.verified\` flag in the output. If \`false\`, read the \`cancelReason\` to explain the failure to the user.
+
+## 2. Parameter Tips
+- **Position IDs**: When opening a NEW position, \`positionId\` MUST be an empty string \`""\`.
+- **Decimals**: Human-readable units (e.g., "0.1" BTC) are default for \`open_position_simple\`. SDK-native tools often require raw units; use the \`raw:\` prefix if you need forced precision.
+- **Slippage**: Default is 100 (1%). For volatile meme tokens, consider 200-300 (2-3%).
+- **Fees**: Use \`get_user_trading_fee_rate\` to estimate fees before large trades.
+
+## 3. Self-Healing
+If a transaction reverts with a hex code, the server will attempt to decode it (e.g., "AccountInsufficientFreeAmount"). Inform the user specifically about what is missing rather than giving a generic error.
+
+Current Session:
+- Wallet: ${address}
+- Chain ID: ${chainId}
+`
+                    }
+                }
+            ]
+        };
+    }
+};

package/dist/server.js

@@ -81,7 +81,7 @@ function zodSchemaToJsonSchema(zodSchema) {
     };
 }
 // ─── MCP Server ───
-const server = new Server({ name: "myx-mcp-trading-server", version: "2.6.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "myx-mcp-trading-server", version: "2.8.2" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // List tools
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
@@ -181,7 +181,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    logger.info("🚀 MYX Trading MCP Server v2.6.0 running (stdio, pure on-chain, prod ready)");
+    logger.info("🚀 MYX Trading MCP Server v2.8.2 running (stdio, pure on-chain, prod ready)");
 }
 main().catch((err) => {
     logger.error("Fatal Server Startup Error", err);

package/dist/tools/accountInfo.js

@@ -19,13 +19,18 @@ export const getAccountInfoTool = {
                 structuredData = {
                     ...result,
                     data: {
-                        marginBalance: d[0],
-                        availableMargin: d[1],
-                        unrealizedPnL: d[2],
-                        initialMargin: d[3],
-                        maintenanceMargin: d[4],
-                        positionMargin: d[5],
-                        lastUpdateTime: d[6]
+                        freeMargin: d[0],
+                        walletBalance: d[1],
+                        freeBaseAmount: d[2],
+                        baseProfit: d[3],
+                        quoteProfit: d[4],
+                        reservedAmount: d[5],
+                        releaseTime: d[6],
+                        // Business Logic: 
+                        // tradeableMargin = freeMargin + walletBalance + (quoteProfit if releaseTime == 0)
+                        tradeableMargin: (BigInt(d[0]) + BigInt(d[1]) + (BigInt(d[6]) === 0n ? BigInt(d[4]) : 0n)).toString(),
+                        baseProfitStatus: "base token to be unlocked",
+                        quoteProfitStatus: BigInt(d[6]) > 0n ? "quote token to be unlocked" : "quote token unlocked/available"
                     }
                 };
             }

package/dist/tools/executeTrade.js

@@ -9,29 +9,29 @@ export const executeTradeTool = {
     name: "execute_trade",
     description: "Create an increase order using SDK-native parameters.",
     schema: {
-        poolId: z.string().describe("Pool ID"),
+        poolId: z.string().describe("Hex Pool ID, e.g. '0x14a19...'. Get via get_pool_list."),
         positionId: z.string().refine((value) => POSITION_ID_RE.test(value), {
             message: "positionId must be empty string for new position, or a bytes32 hex string.",
-        }).describe("Position ID: empty string for new position"),
-        orderType: z.coerce.number().int().min(0).max(3).describe("OrderType enum value"),
-        triggerType: z.coerce.number().int().min(0).max(2).describe("TriggerType enum value"),
+        }).describe("Position ID: Use empty string '' for NEW positions, or valid hex for INCREASING existing ones."),
+        orderType: z.coerce.number().int().min(0).max(3).describe("0=Market, 1=Limit, 2=Stop, 3=StopLimit"),
+        triggerType: z.coerce.number().int().min(0).max(2).describe("0=None (Market), 1=Price, 2=Trailing"),
         direction: z.coerce.number().pipe(z.union([z.literal(0), z.literal(1)])).describe("0 = LONG, 1 = SHORT"),
-        collateralAmount: z.coerce.string().describe("Collateral amount (raw or human-readable)"),
-        size: z.coerce.string().describe("Position size (raw or human-readable)"),
-        price: z.coerce.string().describe("Price (raw or human-readable, 30 decimals)"),
-        timeInForce: z.coerce.number().int().describe("TimeInForce enum value"),
-        postOnly: z.coerce.boolean().describe("Post-only flag"),
+        collateralAmount: z.coerce.string().describe("Collateral. e.g. '100' or 'raw:100000000' (6 decimals for USDC)."),
+        size: z.coerce.string().describe("Notional size in base tokens. e.g. '0.5' BTC or 'raw:50000000'."),
+        price: z.coerce.string().describe("Execution or Limit price. e.g. '65000' or 'raw:65000000000000000000000000000000000' (30 decimals)."),
+        timeInForce: z.coerce.number().int().describe("0=GTC, 1=IOC, 2=FOK"),
+        postOnly: z.coerce.boolean().describe("If true, order only executes as Maker."),
         slippagePct: z.coerce.string().refine(isValidSlippagePct4dp, {
             message: "slippagePct must be an integer in [0, 10000] with 4-decimal precision (1 = 0.01%).",
-        }).describe(SLIPPAGE_PCT_4DP_DESC),
-        executionFeeToken: z.string().describe("Execution fee token address"),
-        leverage: z.coerce.number().describe("Leverage"),
-        tpSize: z.coerce.string().optional().describe("TP size (raw or human-readable)"),
-        tpPrice: z.coerce.string().optional().describe("TP price (raw or human-readable)"),
-        slSize: z.coerce.string().optional().describe("SL size (raw or human-readable)"),
-        slPrice: z.coerce.string().optional().describe("SL price (raw or human-readable)"),
-        tradingFee: z.coerce.string().describe("Trading fee (raw units)"),
-        marketId: z.string().describe("Market ID"),
+        }).describe(`${SLIPPAGE_PCT_4DP_DESC}. Standard is 100 (1%).`),
+        executionFeeToken: z.string().describe("Address of token to pay gas/execution fees (typically USDC)."),
+        leverage: z.coerce.number().describe("Leverage multiplier, e.g., 10 for 10x."),
+        tpSize: z.coerce.string().optional().describe("Take Profit size. Use '0' to disable."),
+        tpPrice: z.coerce.string().optional().describe("Take Profit trigger price."),
+        slSize: z.coerce.string().optional().describe("Stop Loss size. Use '0' to disable."),
+        slPrice: z.coerce.string().optional().describe("Stop Loss trigger price."),
+        tradingFee: z.coerce.string().describe("Estimated fee in raw units. Fetch via get_user_trading_fee_rate."),
+        marketId: z.string().describe("Specific Market Config Hash. Fetch via get_market_list."),
     },
     handler: async (args) => {
         try {

package/dist/tools/openPositionSimple.js

@@ -37,22 +37,22 @@ export const openPositionSimpleTool = {
     name: "open_position_simple",
     description: "High-level open position helper. Computes size/price/tradingFee and submits an increase order. Human units by default; use 'raw:' prefix for raw units.",
     schema: {
-        poolId: z.string().optional().describe("Pool ID. Provide either poolId or keyword."),
-        keyword: z.string().optional().describe('Market keyword, e.g. "BTC". Provide either keyword or poolId.'),
-        direction: z.any().describe("LONG (0), SHORT (1) or string BUY/SELL/LONG/SHORT"),
+        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".'),
+        direction: z.any().describe("0=LONG, 1=SHORT, or strings like 'BUY'/'SELL'/'LONG'/'SHORT'."),
         collateralAmount: z.coerce
             .string()
-            .describe("Collateral amount in quote token units (human by default; 'raw:' prefix for raw)."),
+            .describe("Collateral. e.g. '100' (quoted in USDC) or 'raw:100000000'."),
         leverage: z.coerce.number().int().positive().describe("Leverage (integer, e.g. 5, 10)."),
-        orderType: z.union([z.string(), z.number()]).optional().describe("MARKET, LIMIT, STOP (default MARKET)."),
+        orderType: z.union([z.string(), z.number()]).optional().describe("MARKET, LIMIT, STOP (default MARKET). Strings allowed."),
         price: z.coerce
             .string()
             .optional()
-            .describe("Price (human by default; 30-dec raw with 'raw:' prefix). Required for LIMIT/STOP."),
+            .describe("Price. e.g. '62000' or 'raw:...' (30 dec). Required for LIMIT/STOP."),
         size: z.coerce
             .string()
             .optional()
-            .describe("Position size in base token units (human by default; 'raw:' prefix for raw). If omitted, computed from collateral*leverage/price."),
+            .describe("Position size. e.g. '0.5' BTC. If omitted, computed from collateral*leverage/price."),
         slippagePct: z.coerce
             .string()
             .optional()
@@ -64,13 +64,13 @@ export const openPositionSimpleTool = {
         tradingFee: z.coerce
             .string()
             .optional()
-            .describe("Trading fee in quote token units (human by default; 'raw:' prefix for raw). If omitted, computed via getUserTradingFeeRate."),
-        autoApprove: z.coerce.boolean().optional().describe("If true, auto-approve quote token spend when needed (default false)."),
-        approveMax: z.coerce.boolean().optional().describe("If autoApprove, approve MaxUint256 (default false approves exact amount)."),
+            .describe("Trading fee. e.g. '0.2' USDC or 'raw:...'. Default: computed via getUserTradingFeeRate."),
+        autoApprove: z.coerce.boolean().optional().describe("If true, auto-approve token spend (default false)."),
+        approveMax: z.coerce.boolean().optional().describe("If autoApprove, approve MaxUint256 (default false)."),
         autoDeposit: z.coerce
             .boolean()
             .optional()
-            .describe("If true, auto-deposit to margin account when marginBalance is insufficient (default false)."),
+            .describe("If true, auto-deposit to margin account if marginBalance < needed (default false)."),
         dryRun: z.coerce.boolean().optional().describe("If true, only compute params; do not send a transaction."),
     },
     handler: async (args) => {

package/dist/tools/setTpSl.js

@@ -8,20 +8,20 @@ export const setTpSlTool = {
     name: "set_tp_sl",
     description: "Create TP/SL order using SDK-native parameters.",
     schema: {
-        poolId: z.string().describe("Pool ID"),
-        positionId: z.string().describe("Position ID"),
-        direction: z.any().describe("LONG (0), SHORT (1) or string BUY/SELL/LONG/SHORT"),
-        leverage: z.coerce.number().describe("Leverage"),
-        executionFeeToken: z.string().describe("Execution fee token address"),
-        tpTriggerType: z.union([z.number(), z.string()]).optional().describe("TP trigger type (0=NONE, 1=GTE, 2=LTE)"),
-        slTriggerType: z.union([z.number(), z.string()]).optional().describe("SL trigger type (0=NONE, 1=GTE, 2=LTE)"),
+        poolId: z.string().describe("Hex Pool ID, e.g. '0x14a19...'. Get via get_pool_list."),
+        positionId: z.string().describe("Active Position ID. Get via get_positions."),
+        direction: z.any().describe("0=LONG, 1=SHORT, or strings like 'BUY'/'SELL'/'LONG'/'SHORT'."),
+        leverage: z.coerce.number().describe("Leverage multiplier, e.g., 10."),
+        executionFeeToken: z.string().describe("Address of token to pay gas/execution fees."),
+        tpTriggerType: z.union([z.number(), z.string()]).optional().describe("0=None, 1=Price (Market), 2=Trailing."),
+        slTriggerType: z.union([z.number(), z.string()]).optional().describe("0=None, 1=Price (Market), 2=Trailing."),
         slippagePct: z.coerce.string().refine(isValidSlippagePct4dp, {
             message: "slippagePct must be an integer in [0, 10000] with 4-decimal precision (1 = 0.01%).",
-        }).describe(SLIPPAGE_PCT_4DP_DESC),
-        tpPrice: z.coerce.string().optional().describe("TP price (raw or human-readable, 30 decimals)"),
-        tpSize: z.coerce.string().optional().describe("TP size (raw or human-readable)"),
-        slPrice: z.coerce.string().optional().describe("SL price (raw or human-readable, 30 decimals)"),
-        slSize: z.coerce.string().optional().describe("SL size (raw or human-readable)"),
+        }).describe(`${SLIPPAGE_PCT_4DP_DESC}. Standard is 100 (1%).`),
+        tpPrice: z.coerce.string().optional().describe("Take Profit trigger price. e.g. '2.5' or 'raw:...' (30 decimals)."),
+        tpSize: z.coerce.string().optional().describe("TP size in base tokens. Use '0' to disable."),
+        slPrice: z.coerce.string().optional().describe("Stop Loss trigger price. e.g. '2.1' or 'raw:...' (30 decimals)."),
+        slSize: z.coerce.string().optional().describe("SL size in base tokens. Use '0' to disable."),
     },
     handler: async (args) => {
         try {

package/package.json

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