@aihubspot/agent-trade-mcp 0.1.1 → 0.1.4

package/README.md

@@ -18,3 +18,19 @@ ai-hub-trade-mcp setup --client codex --profile default
 ```
 
 Setup registers the currently installed MCP binary through its absolute Node runtime and entrypoint path, so desktop clients do not depend on a global PATH or an unpublished `npx` package. Cursor and Claude Desktop configurations are merged with existing MCP servers through their JSON configurations. Claude Code and Codex are registered through their official CLIs; Claude Code uses user scope. Existing JSON configurations are validated, atomically updated, and backed up before their first modification. The setup command stores no API credentials; the MCP server continues to read its profile from `~/.ai-hub/config.toml`.
+
+## Spot market-order units
+
+Use `spot_prepare_market_buy` or `margin_prepare_market_buy` only with `quoteAmount` (for example, the exact USDT amount to spend for `ETHUSDT`). Use `spot_prepare_market_sell` or `margin_prepare_market_sell` only with `baseQuantity` (the exact ETH amount to sell for `ETHUSDT`). A market buy cannot guarantee an exact base-asset quantity; it must never reinterpret a requested base quantity as a quote amount.
+
+Before any order preview, MCP lazily loads `/sapi/v2/symbols` once per local profile and caches the symbol rules in memory for five minutes. Known quantity/price precision and limit-order minimum violations are rejected before confirmation.
+
+## Ticker response
+
+All read tools return `{ "ok": true, "data": ... }` in one of these stable forms:
+
+- Arrays: `{ "dataType": "array", "items": [...], "count": 500 }`
+- Objects: `{ "dataType": "object", "value": { ... } }`
+- Scalars: `{ "dataType": "scalar", "value": "..." }`
+
+`market_get_ticker` additionally exposes `data.tickers` as an alias of `data.items`. Check `data.dataType` before formatting; do not infer raw OpenAPI nesting.

package/dist/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // ../core/src/errors.ts
@@ -915,7 +917,7 @@ var marketTools = [
   {
     name: "market_get_ticker",
     title: "Get Spot Ticker",
-    description: "Get spot ticker data. Pass symbol or symbols when filtering is needed.",
+    description: "Get spot ticker data. Pass symbol or symbols when filtering is needed. The raw OpenAPI response is a ticker array.",
     cliPath: ["market", "ticker"],
     module: "spot-common",
     access: "public",
@@ -990,14 +992,186 @@ var marketTools = [
   }
 ];
 
+// ../core/src/tools/symbol-rules.ts
+var CACHE_TTL_MS = 5 * 60 * 1e3;
+var cache = /* @__PURE__ */ new Map();
+var pendingLoads = /* @__PURE__ */ new Map();
+function cacheKey(context) {
+  return `${context.profile.name}\0${context.profile.configVersion}\0${context.profile.openApiBaseUrl}`;
+}
+function normalizedSymbol(symbol) {
+  return symbol.replaceAll("/", "").trim().toUpperCase();
+}
+function stringValue(value) {
+  if (typeof value === "string" && value.trim()) return value.trim();
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return void 0;
+}
+function nonNegativeInteger(value) {
+  const result2 = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+  return Number.isInteger(result2) && result2 >= 0 ? result2 : void 0;
+}
+function rows(response) {
+  if (Array.isArray(response)) return response.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item));
+  if (!response || typeof response !== "object" || Array.isArray(response)) return [];
+  const root = response;
+  const candidates = [root.symbols, root.data, root.data?.symbols];
+  for (const candidate of candidates) {
+    if (Array.isArray(candidate)) return candidate.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item));
+  }
+  return [];
+}
+function parseRules(response) {
+  const result2 = /* @__PURE__ */ new Map();
+  for (const row of rows(response)) {
+    const symbol = stringValue(row.symbol);
+    if (!symbol) continue;
+    result2.set(normalizedSymbol(symbol), {
+      symbol,
+      quantityPrecision: nonNegativeInteger(row.quantityPrecision),
+      pricePrecision: nonNegativeInteger(row.pricePrecision),
+      limitVolumeMin: stringValue(row.limitVolumeMin),
+      limitAmountMin: stringValue(row.limitAmountMin),
+      limitPriceMin: stringValue(row.limitPriceMin)
+    });
+  }
+  return result2;
+}
+async function loadRules(context) {
+  const key = cacheKey(context);
+  const current = cache.get(key);
+  if (current && current.expiresAt > Date.now()) return current;
+  const pending = pendingLoads.get(key);
+  if (pending) return pending;
+  const load = context.api.symbols().then((response) => {
+    const entry = { rules: parseRules(response), expiresAt: Date.now() + CACHE_TTL_MS };
+    cache.set(key, entry);
+    return entry;
+  }).finally(() => pendingLoads.delete(key));
+  pendingLoads.set(key, load);
+  return load;
+}
+async function getSymbolRule(context, symbol) {
+  const entry = await loadRules(context);
+  const rule = entry.rules.get(normalizedSymbol(symbol));
+  if (!rule) throw new AiHubError("AI_HUB_SYMBOL_NOT_FOUND", `Symbol "${symbol}" was not returned by the configured tenant OpenAPI symbols endpoint.`);
+  return rule;
+}
+function decimalScale(value) {
+  return value.split(".")[1]?.length ?? 0;
+}
+function decimalParts(value) {
+  const [whole, fraction = ""] = value.split(".");
+  return { digits: BigInt(`${whole}${fraction}`.replace(/^0+(?=\d)/, "") || "0"), scale: fraction.length };
+}
+function compareDecimal(left, right) {
+  const a = decimalParts(left);
+  const b = decimalParts(right);
+  const scale = Math.max(a.scale, b.scale);
+  const leftValue = a.digits * 10n ** BigInt(scale - a.scale);
+  const rightValue = b.digits * 10n ** BigInt(scale - b.scale);
+  return leftValue === rightValue ? 0 : leftValue > rightValue ? 1 : -1;
+}
+function multipliedDecimal(left, right) {
+  const a = decimalParts(left);
+  const b = decimalParts(right);
+  const scale = a.scale + b.scale;
+  const digits = (a.digits * b.digits).toString();
+  if (scale === 0) return digits;
+  const padded = digits.padStart(scale + 1, "0");
+  return `${padded.slice(0, -scale)}.${padded.slice(-scale)}`;
+}
+function assertPrecision(name, value, precision, symbol) {
+  if (precision !== void 0 && decimalScale(value) > precision) {
+    throw new AiHubError("AI_HUB_SYMBOL_PRECISION_INVALID", `${name} for ${symbol} allows at most ${precision} decimal places; received ${value}.`);
+  }
+}
+function assertAtLeast(name, value, minimum, symbol) {
+  if (minimum && compareDecimal(value, minimum) < 0) {
+    throw new AiHubError("AI_HUB_SYMBOL_MINIMUM_NOT_MET", `${name} for ${symbol} must be at least ${minimum}; received ${value}.`);
+  }
+}
+async function preflightSymbolOrder(context, order) {
+  const rule = await getSymbolRule(context, order.symbol);
+  if (order.type === "MARKET" && order.side === "BUY" && order.quoteAmount) {
+    assertPrecision("quoteAmount", order.quoteAmount, rule.pricePrecision, rule.symbol);
+  }
+  if (order.baseQuantity) assertPrecision("baseQuantity", order.baseQuantity, rule.quantityPrecision, rule.symbol);
+  if (order.price) assertPrecision("price", order.price, rule.pricePrecision, rule.symbol);
+  if (order.type === "LIMIT" && order.baseQuantity && order.price) {
+    assertAtLeast("baseQuantity", order.baseQuantity, rule.limitVolumeMin, rule.symbol);
+    assertAtLeast("price", order.price, rule.limitPriceMin, rule.symbol);
+    if (rule.limitAmountMin && compareDecimal(rule.limitAmountMin, "0") > 0) {
+      assertAtLeast("limit order amount", multipliedDecimal(order.baseQuantity, order.price), rule.limitAmountMin, rule.symbol);
+    }
+  }
+  return rule;
+}
+
 // ../core/src/tools/margin-tools.ts
-function validateMarginOrder(input) {
-  const value = strictObject(input, ["symbol", "volume", "side", "type", "price", "newClientOrderId", "isolated"]);
+function validateMarginSemanticOrder(input) {
+  const value = strictObject(input, ["symbol", "side", "type", "quoteAmount", "baseQuantity", "price", "newClientOrderId", "isolated"]);
+  const symbol = requiredString(value, "symbol");
+  const side = requiredEnum(value, "side", ["BUY", "SELL"]);
   const type = requiredEnum(value, "type", ["LIMIT", "MARKET"]);
-  const price = optionalString(value, "price");
-  if (type === "LIMIT" && !price) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "price is required for LIMIT orders.");
-  if (type === "MARKET" && price) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "price is not allowed for MARKET orders.");
-  return { symbol: requiredString(value, "symbol"), volume: positiveDecimal(value, "volume"), side: requiredEnum(value, "side", ["BUY", "SELL"]), type, ...price ? { price } : {}, newClientOrderId: optionalClientOrderId(value), ...optionalBoolean(value, "isolated") !== void 0 ? { isolated: optionalBoolean(value, "isolated") } : {} };
+  const isolated = optionalBoolean(value, "isolated");
+  const common = { symbol, side, type, newClientOrderId: optionalClientOrderId(value), ...isolated !== void 0 ? { isolated } : {} };
+  if (type === "MARKET" && side === "BUY") {
+    if (value.baseQuantity !== void 0) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "MARKET BUY uses quoteAmount (the amount of quote asset to spend), not baseQuantity.");
+    if (value.price !== void 0) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "price is not allowed for MARKET orders.");
+    const quoteAmount = positiveDecimal(value, "quoteAmount");
+    return { ...common, volume: quoteAmount, intent: "market_buy", quoteAmount };
+  }
+  if (type === "MARKET" && side === "SELL") {
+    if (value.quoteAmount !== void 0) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "MARKET SELL uses baseQuantity (the amount of base asset to sell), not quoteAmount.");
+    if (value.price !== void 0) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "price is not allowed for MARKET orders.");
+    const baseQuantity2 = positiveDecimal(value, "baseQuantity");
+    return { ...common, volume: baseQuantity2, intent: "market_sell", baseQuantity: baseQuantity2 };
+  }
+  if (value.quoteAmount !== void 0) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "LIMIT orders use baseQuantity (the amount of base asset), not quoteAmount.");
+  const baseQuantity = positiveDecimal(value, "baseQuantity");
+  const price = positiveDecimal(value, "price");
+  return { ...common, volume: baseQuantity, price, intent: "limit", baseQuantity };
+}
+function validateMarginMarketBuy(input) {
+  const value = strictObject(input, ["symbol", "quoteAmount", "newClientOrderId", "isolated"]);
+  return validateMarginSemanticOrder({ ...value, side: "BUY", type: "MARKET" });
+}
+function validateMarginMarketSell(input) {
+  const value = strictObject(input, ["symbol", "baseQuantity", "newClientOrderId", "isolated"]);
+  return validateMarginSemanticOrder({ ...value, side: "SELL", type: "MARKET" });
+}
+function validateMarginLimitOrder(input) {
+  const value = strictObject(input, ["symbol", "side", "baseQuantity", "price", "newClientOrderId", "isolated"]);
+  return validateMarginSemanticOrder({ ...value, type: "LIMIT" });
+}
+function toMarginOpenApiOrder(order) {
+  return {
+    symbol: order.symbol,
+    volume: order.volume,
+    side: order.side,
+    type: order.type,
+    newClientOrderId: order.newClientOrderId,
+    ...order.price ? { price: order.price } : {},
+    ...order.isolated !== void 0 ? { isolated: order.isolated } : {}
+  };
+}
+function marginOrderSummary(order) {
+  return {
+    action: order.intent === "market_buy" ? "margin_market_buy" : order.intent === "market_sell" ? "margin_market_sell" : "margin_limit_order",
+    symbol: order.symbol,
+    side: order.side,
+    type: order.type,
+    ...order.quoteAmount ? { quoteAmount: order.quoteAmount, amountMeaning: "exact quote-asset amount to spend" } : {},
+    ...order.baseQuantity ? { baseQuantity: order.baseQuantity, amountMeaning: "exact base-asset quantity" } : {},
+    ...order.price ? { price: order.price } : {},
+    isolated: order.isolated ?? false,
+    newClientOrderId: order.newClientOrderId
+  };
+}
+async function preflightMarginOrder(order, context) {
+  await preflightSymbolOrder(context, order);
+  return order;
 }
 function validateMarginOrderLookup(input) {
   const value = strictObject(input, ["symbol", "orderId", "newClientOrderId", "isolated"]);
@@ -1055,22 +1229,52 @@ var marginTools = [
     handler: (input, context) => context.api.signedGet("/sapi/v2/margin/myTrades", input, signed(context))
   },
   {
-    name: "margin_place_order",
-    title: "Place Margin Order",
-    description: "Create one v2 margin order after confirmation.",
-    cliPath: ["margin", "order", "place"],
+    name: "margin_market_buy",
+    title: "Margin Market Buy by Quote Amount",
+    description: "Spend an exact quote-asset amount for an isolated or cross-margin market buy. For ETHUSDT, quoteAmount is USDT. A market buy cannot guarantee an exact base-asset quantity.",
+    cliPath: ["margin", "order", "market-buy"],
     module: "spot-margin",
     access: "signed",
     operation: "write",
     riskLevel: "high",
-    inputSchema: { type: "object", properties: { symbol: { type: "string" }, volume: { type: "string" }, side: { type: "string", enum: ["BUY", "SELL"] }, type: { type: "string", enum: ["LIMIT", "MARKET"] }, price: { type: "string" }, newClientOrderId: { type: "string" }, isolated: { type: "boolean" } }, required: ["symbol", "volume", "side", "type"], additionalProperties: false },
+    inputSchema: { type: "object", properties: { symbol: { type: "string" }, quoteAmount: { type: "string", description: "Required exact quote-asset amount to spend." }, newClientOrderId: { type: "string" }, isolated: { type: "boolean" } }, required: ["symbol", "quoteAmount"], additionalProperties: false },
     errorCodes: writeErrors,
-    validate: validateMarginOrder,
-    handler: (input, context) => context.api.signedPost("/sapi/v2/margin/order", input, signed(context)),
-    writeSummary: (input) => {
-      const value = input;
-      return { action: "margin_place_order", symbol: value.symbol, side: value.side, type: value.type, volume: value.volume, price: value.price ?? null, isolated: value.isolated ?? false, newClientOrderId: value.newClientOrderId };
-    }
+    validate: validateMarginMarketBuy,
+    preflight: preflightMarginOrder,
+    handler: (input, context) => context.api.signedPost("/sapi/v2/margin/order", toMarginOpenApiOrder(input), signed(context)),
+    writeSummary: (input) => marginOrderSummary(input)
+  },
+  {
+    name: "margin_market_sell",
+    title: "Margin Market Sell by Base Quantity",
+    description: "Sell an exact base-asset quantity at market for an isolated or cross-margin account. For ETHUSDT, baseQuantity is ETH.",
+    cliPath: ["margin", "order", "market-sell"],
+    module: "spot-margin",
+    access: "signed",
+    operation: "write",
+    riskLevel: "high",
+    inputSchema: { type: "object", properties: { symbol: { type: "string" }, baseQuantity: { type: "string", description: "Required exact base-asset quantity to sell." }, newClientOrderId: { type: "string" }, isolated: { type: "boolean" } }, required: ["symbol", "baseQuantity"], additionalProperties: false },
+    errorCodes: writeErrors,
+    validate: validateMarginMarketSell,
+    preflight: preflightMarginOrder,
+    handler: (input, context) => context.api.signedPost("/sapi/v2/margin/order", toMarginOpenApiOrder(input), signed(context)),
+    writeSummary: (input) => marginOrderSummary(input)
+  },
+  {
+    name: "margin_limit_order",
+    title: "Place Margin Limit Order",
+    description: "Place an isolated or cross-margin LIMIT BUY or SELL using an exact base-asset quantity and a limit price.",
+    cliPath: ["margin", "order", "limit"],
+    module: "spot-margin",
+    access: "signed",
+    operation: "write",
+    riskLevel: "high",
+    inputSchema: { type: "object", properties: { symbol: { type: "string" }, side: { type: "string", enum: ["BUY", "SELL"] }, baseQuantity: { type: "string", description: "Required exact base-asset quantity." }, price: { type: "string", description: "Required limit price in the quote asset." }, newClientOrderId: { type: "string" }, isolated: { type: "boolean" } }, required: ["symbol", "side", "baseQuantity", "price"], additionalProperties: false },
+    errorCodes: writeErrors,
+    validate: validateMarginLimitOrder,
+    preflight: preflightMarginOrder,
+    handler: (input, context) => context.api.signedPost("/sapi/v2/margin/order", toMarginOpenApiOrder(input), signed(context)),
+    writeSummary: (input) => marginOrderSummary(input)
   },
   {
     name: "margin_cancel_order",
@@ -1123,53 +1327,89 @@ function clientOrderId(value) {
   if (supplied) return supplied;
   return `agent_${randomUUID3().replaceAll("-", "").slice(0, 24)}`;
 }
-function validatePlaceOrder(input) {
-  const value = strictObject(input, ["symbol", "volume", "side", "type", "price", "timeInForce", "newClientOrderId", "recvWindow"]);
-  const type = orderType(value);
-  const price = optionalString(value, "price");
-  if (type === "LIMIT" && !price) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "price is required for LIMIT orders.");
-  if (type === "MARKET" && price) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "price is not allowed for MARKET orders.");
+function optionalOrderFields(value) {
   const timeInForce = optionalString(value, "timeInForce")?.toUpperCase();
   if (timeInForce && !["GTC", "IOC", "FOK"].includes(timeInForce)) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "timeInForce must be GTC, IOC, or FOK.");
+  const recvWindow = optionalString(value, "recvWindow");
   return {
-    symbol: requiredString(value, "symbol"),
-    volume: positiveDecimal2(value, "volume"),
-    side: orderSide(value),
-    type,
-    ...price ? { price } : {},
-    ...timeInForce ? { timeInForce } : {},
     newClientOrderId: clientOrderId(value),
-    ...optionalString(value, "recvWindow") ? { recvWindow: optionalString(value, "recvWindow") } : {}
+    ...recvWindow ? { recvWindow } : {},
+    ...timeInForce ? { timeInForce } : {}
   };
 }
+function validateSemanticOrder(input) {
+  const value = strictObject(input, ["symbol", "side", "type", "quoteAmount", "baseQuantity", "price", "timeInForce", "newClientOrderId", "recvWindow"]);
+  const side = orderSide(value);
+  const type = orderType(value);
+  const symbol = requiredString(value, "symbol");
+  if (type === "MARKET" && side === "BUY") {
+    if (value.baseQuantity !== void 0) {
+      throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "MARKET BUY uses quoteAmount (the amount of quote asset to spend), not baseQuantity.");
+    }
+    if (value.price !== void 0 || value.timeInForce !== void 0) {
+      throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "price and timeInForce are not allowed for MARKET orders.");
+    }
+    const quoteAmount = positiveDecimal2(value, "quoteAmount");
+    return { symbol, volume: quoteAmount, side, type, intent: "market_buy", quoteAmount, ...optionalOrderFields(value) };
+  }
+  if (type === "MARKET" && side === "SELL") {
+    if (value.quoteAmount !== void 0) {
+      throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "MARKET SELL uses baseQuantity (the amount of base asset to sell), not quoteAmount.");
+    }
+    if (value.price !== void 0 || value.timeInForce !== void 0) {
+      throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "price and timeInForce are not allowed for MARKET orders.");
+    }
+    const baseQuantity2 = positiveDecimal2(value, "baseQuantity");
+    return { symbol, volume: baseQuantity2, side, type, intent: "market_sell", baseQuantity: baseQuantity2, ...optionalOrderFields(value) };
+  }
+  if (value.quoteAmount !== void 0) {
+    throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "LIMIT orders use baseQuantity (the amount of base asset), not quoteAmount.");
+  }
+  const baseQuantity = positiveDecimal2(value, "baseQuantity");
+  const price = positiveDecimal2(value, "price");
+  return { symbol, volume: baseQuantity, side, type, price, intent: "limit", baseQuantity, ...optionalOrderFields(value) };
+}
+function validateMarketBuy(input) {
+  const value = strictObject(input, ["symbol", "quoteAmount", "newClientOrderId", "recvWindow"]);
+  return validateSemanticOrder({ ...value, side: "BUY", type: "MARKET" });
+}
+function toOpenApiOrder(order) {
+  return {
+    symbol: order.symbol,
+    volume: order.volume,
+    side: order.side,
+    type: order.type,
+    newClientOrderId: order.newClientOrderId,
+    ...order.price ? { price: order.price } : {},
+    ...order.timeInForce ? { timeInForce: order.timeInForce } : {},
+    ...order.recvWindow ? { recvWindow: order.recvWindow } : {}
+  };
+}
+function validateMarketSell(input) {
+  const value = strictObject(input, ["symbol", "baseQuantity", "newClientOrderId", "recvWindow"]);
+  return validateSemanticOrder({ ...value, side: "SELL", type: "MARKET" });
+}
+function validateLimitOrder(input) {
+  const value = strictObject(input, ["symbol", "side", "baseQuantity", "price", "timeInForce", "newClientOrderId", "recvWindow"]);
+  return validateSemanticOrder({ ...value, type: "LIMIT" });
+}
 function validateCancelOrder(input) {
   const value = strictObject(input, ["symbol", "orderId", "newClientOrderId"]);
   return { symbol: requiredString(value, "symbol"), orderId: requiredString(value, "orderId"), ...optionalString(value, "newClientOrderId") ? { newClientOrderId: optionalString(value, "newClientOrderId") } : {} };
 }
 function validateTestOrder(input) {
-  const value = strictObject(input, ["symbol", "volume", "side", "type", "price", "newClientOrderId", "recvWindow"]);
-  const type = orderType(value);
-  const price = optionalString(value, "price");
-  if (type === "LIMIT" && !price) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "price is required for LIMIT orders.");
-  if (type === "MARKET" && price) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "price is not allowed for MARKET orders.");
-  return { symbol: requiredString(value, "symbol"), volume: positiveDecimal2(value, "volume"), side: orderSide(value), type, ...price ? { price } : {}, ...optionalString(value, "newClientOrderId") ? { newClientOrderId: optionalString(value, "newClientOrderId") } : {}, ...optionalString(value, "recvWindow") ? { recvWindow: optionalString(value, "recvWindow") } : {} };
+  return toOpenApiOrder(validateSemanticOrder(input));
 }
 function validateBatchOrders(input) {
   const value = strictObject(input, ["symbol", "orders"]);
+  const symbol = requiredString(value, "symbol");
   const orders = value.orders;
   if (!Array.isArray(orders) || orders.length < 1 || orders.length > 10) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "orders must contain between 1 and 10 orders.");
-  const normalized = orders.map((item, index) => {
-    if (!item || typeof item !== "object" || Array.isArray(item)) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", `orders[${index}] must be an object.`);
-    const order = item;
-    const price = optionalString(order, "price");
-    const volume = positiveDecimal2(order, "volume");
-    const side = orderSide(order);
-    const batchType = requiredEnum(order, "batchType", ["LIMIT", "MARKET"]);
-    if (batchType === "LIMIT" && !price) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", `orders[${index}].price is required for LIMIT.`);
-    if (batchType === "MARKET" && price) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", `orders[${index}].price is not allowed for MARKET.`);
-    return { volume, side, batchType, ...price ? { price } : {} };
-  });
-  return { symbol: requiredString(value, "symbol"), orders: normalized };
+  return { symbol, orders: orders.map((order, index) => {
+    if (!order || typeof order !== "object" || Array.isArray(order)) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", `orders[${index}] must be an object.`);
+    const semantic = validateSemanticOrder({ ...order, symbol });
+    return { volume: semantic.volume, side: semantic.side, batchType: semantic.type, ...semantic.price ? { price: semantic.price } : {} };
+  }) };
 }
 function validateBatchCancel(input) {
   const value = strictObject(input, ["symbol", "orderIds"]);
@@ -1178,17 +1418,44 @@ function validateBatchCancel(input) {
   }
   return { symbol: requiredString(value, "symbol"), orderIds: value.orderIds.map((id) => id.trim()) };
 }
+function semanticOrderSummary(order) {
+  return {
+    action: order.intent === "market_buy" ? "market_buy" : order.intent === "market_sell" ? "market_sell" : "limit_order",
+    symbol: order.symbol,
+    side: order.side,
+    type: order.type,
+    ...order.quoteAmount ? { quoteAmount: order.quoteAmount, amountMeaning: "exact quote-asset amount to spend" } : {},
+    ...order.baseQuantity ? { baseQuantity: order.baseQuantity, amountMeaning: "exact base-asset quantity" } : {},
+    ...order.price ? { price: order.price } : {},
+    ...order.timeInForce ? { timeInForce: order.timeInForce } : {},
+    newClientOrderId: order.newClientOrderId
+  };
+}
+async function preflightSpotOrder(order, context) {
+  await preflightSymbolOrder(context, order);
+  return order;
+}
+async function preflightSpotBatch(input, context) {
+  await Promise.all(input.orders.map((order) => preflightSymbolOrder(context, {
+    symbol: input.symbol,
+    side: order.side,
+    type: order.batchType,
+    ...order.batchType === "MARKET" && order.side === "BUY" ? { quoteAmount: order.volume } : { baseQuantity: order.volume },
+    ...order.price ? { price: order.price } : {}
+  })));
+  return input;
+}
 var orderTools = [
   {
     name: "spot_test_order",
     title: "Test Spot Order",
-    description: "Validate one LIMIT or MARKET spot order without sending it to the matching engine.",
+    description: "Validate an order without sending it to the matching engine. MARKET BUY requires quoteAmount (quote asset to spend); MARKET SELL and LIMIT require baseQuantity. LIMIT also requires price.",
     cliPath: ["spot", "order", "test"],
     module: "spot-order",
     access: "signed",
     operation: "read",
     riskLevel: "low",
-    inputSchema: { type: "object", properties: { symbol: { type: "string" }, volume: { type: "string" }, side: { type: "string", enum: ["BUY", "SELL"] }, type: { type: "string", enum: ["LIMIT", "MARKET"] }, price: { type: "string" }, newClientOrderId: { type: "string" }, recvWindow: { type: "string" } }, required: ["symbol", "volume", "side", "type"], additionalProperties: false },
+    inputSchema: { type: "object", properties: { symbol: { type: "string" }, side: { type: "string", enum: ["BUY", "SELL"] }, type: { type: "string", enum: ["LIMIT", "MARKET"] }, quoteAmount: { type: "string", description: "Required only for MARKET BUY: exact quote-asset amount to spend." }, baseQuantity: { type: "string", description: "Required for MARKET SELL and LIMIT: exact base-asset quantity." }, price: { type: "string", description: "Required only for LIMIT." }, timeInForce: { type: "string", enum: ["GTC", "IOC", "FOK"] }, newClientOrderId: { type: "string" }, recvWindow: { type: "string" } }, required: ["symbol", "side", "type"], additionalProperties: false },
     errorCodes: signedReadErrors2,
     validate: validateTestOrder,
     handler: (input, context) => context.api.signedPost("/sapi/v2/order/test", input, signed2(context))
@@ -1213,15 +1480,16 @@ var orderTools = [
   {
     name: "spot_batch_place_orders",
     title: "Batch Place Spot Orders",
-    description: "Create up to 10 spot orders after confirmation.",
+    description: "Create up to 10 spot orders after confirmation. Each MARKET BUY item requires quoteAmount; MARKET SELL and LIMIT items require baseQuantity; LIMIT items also require price.",
     cliPath: ["spot", "order", "batch-place"],
     module: "spot-order",
     access: "signed",
     operation: "write",
     riskLevel: "high",
-    inputSchema: { type: "object", properties: { symbol: { type: "string" }, orders: { type: "array" } }, required: ["symbol", "orders"], additionalProperties: false },
+    inputSchema: { type: "object", properties: { symbol: { type: "string" }, orders: { type: "array", description: "Items use side/type plus quoteAmount for MARKET BUY, baseQuantity for MARKET SELL/LIMIT, and price for LIMIT." } }, required: ["symbol", "orders"], additionalProperties: false },
     errorCodes: writeErrors2,
     validate: validateBatchOrders,
+    preflight: preflightSpotBatch,
     handler: (input, context) => context.api.signedPost("/sapi/v2/batchOrders", input, signed2(context)),
     writeSummary: (input) => {
       const value = input;
@@ -1248,7 +1516,7 @@ var orderTools = [
   },
   {
     name: "spot_get_open_orders",
-    title: "Get Open Spot Orders",
+    title: "Get Spot Open Orders",
     description: "Get current signed spot orders.",
     cliPath: ["spot", "order", "open"],
     module: "spot-order",
@@ -1281,22 +1549,52 @@ var orderTools = [
     handler: (input, context) => context.api.getMyTrades(input, signed2(context))
   },
   {
-    name: "spot_place_order",
-    title: "Place Spot Order",
-    description: "Create one LIMIT or MARKET spot order after confirmation.",
-    cliPath: ["spot", "order", "place"],
+    name: "spot_market_buy",
+    title: "Market Buy by Quote Amount",
+    description: "Spend an exact quote-asset amount to buy at market. For ETHUSDT, quoteAmount is USDT. Do not use this tool to request a base-asset quantity such as 1 ETH; market execution cannot guarantee an exact base quantity.",
+    cliPath: ["spot", "order", "market-buy"],
     module: "spot-order",
     access: "signed",
     operation: "write",
     riskLevel: "high",
-    inputSchema: { type: "object", properties: { symbol: { type: "string" }, volume: { type: "string" }, side: { type: "string", enum: ["BUY", "SELL"] }, type: { type: "string", enum: ["LIMIT", "MARKET"] }, price: { type: "string" }, timeInForce: { type: "string", enum: ["GTC", "IOC", "FOK"] }, newClientOrderId: { type: "string" }, recvWindow: { type: "string" } }, required: ["symbol", "volume", "side", "type"], additionalProperties: false },
+    inputSchema: { type: "object", properties: { symbol: { type: "string" }, quoteAmount: { type: "string", description: "Required exact quote-asset amount to spend, e.g. 100 means spend 100 USDT for ETHUSDT." }, newClientOrderId: { type: "string" }, recvWindow: { type: "string" } }, required: ["symbol", "quoteAmount"], additionalProperties: false },
     errorCodes: writeErrors2,
-    validate: validatePlaceOrder,
-    handler: (input, context) => context.api.placeOrder(input, signed2(context)),
-    writeSummary: (input) => {
-      const value = input;
-      return { action: "place_order", symbol: value.symbol, side: value.side, type: value.type, volume: value.volume, price: value.price ?? null, timeInForce: value.timeInForce ?? null, newClientOrderId: value.newClientOrderId };
-    }
+    validate: validateMarketBuy,
+    preflight: preflightSpotOrder,
+    handler: (input, context) => context.api.placeOrder(toOpenApiOrder(input), signed2(context)),
+    writeSummary: (input) => semanticOrderSummary(input)
+  },
+  {
+    name: "spot_market_sell",
+    title: "Market Sell by Base Quantity",
+    description: "Sell an exact base-asset quantity at market. For ETHUSDT, baseQuantity is ETH.",
+    cliPath: ["spot", "order", "market-sell"],
+    module: "spot-order",
+    access: "signed",
+    operation: "write",
+    riskLevel: "high",
+    inputSchema: { type: "object", properties: { symbol: { type: "string" }, baseQuantity: { type: "string", description: "Required exact base-asset quantity to sell, e.g. 0.5 means sell 0.5 ETH for ETHUSDT." }, newClientOrderId: { type: "string" }, recvWindow: { type: "string" } }, required: ["symbol", "baseQuantity"], additionalProperties: false },
+    errorCodes: writeErrors2,
+    validate: validateMarketSell,
+    preflight: preflightSpotOrder,
+    handler: (input, context) => context.api.placeOrder(toOpenApiOrder(input), signed2(context)),
+    writeSummary: (input) => semanticOrderSummary(input)
+  },
+  {
+    name: "spot_limit_order",
+    title: "Place Limit Spot Order",
+    description: "Place a LIMIT BUY or SELL using an exact base-asset quantity and a limit price.",
+    cliPath: ["spot", "order", "limit"],
+    module: "spot-order",
+    access: "signed",
+    operation: "write",
+    riskLevel: "high",
+    inputSchema: { type: "object", properties: { symbol: { type: "string" }, side: { type: "string", enum: ["BUY", "SELL"] }, baseQuantity: { type: "string", description: "Required exact base-asset quantity." }, price: { type: "string", description: "Required limit price in the quote asset." }, timeInForce: { type: "string", enum: ["GTC", "IOC", "FOK"] }, newClientOrderId: { type: "string" }, recvWindow: { type: "string" } }, required: ["symbol", "side", "baseQuantity", "price"], additionalProperties: false },
+    errorCodes: writeErrors2,
+    validate: validateLimitOrder,
+    preflight: preflightSpotOrder,
+    handler: (input, context) => context.api.placeOrder(toOpenApiOrder(input), signed2(context)),
+    writeSummary: (input) => semanticOrderSummary(input)
   },
   {
     name: "spot_cancel_order",
@@ -1598,22 +1896,22 @@ var ToolRegistry = class {
     const validInput = tool.validate(input);
     return tool.handler(validInput, context);
   }
-  prepareWrite(name, input, context, confirmations) {
+  async prepareWrite(name, input, context, confirmations) {
     const tool = this.byName(name);
     if (tool.operation !== "write" || !tool.writeSummary) throw new AiHubError("AI_HUB_TOOL_NOT_WRITE", `Tool "${name}" is not a confirmable write Tool.`);
     const validInput = tool.validate(input);
+    const preflightInput = tool.preflight ? await tool.preflight(validInput, context) : validInput;
     return confirmations.prepare({
       action: tool.name,
-      payload: validInput,
+      payload: preflightInput,
       context: confirmationContext(context),
-      summary: tool.writeSummary(validInput)
+      summary: tool.writeSummary(preflightInput)
     });
   }
   async executeConfirmed(action, payload, context) {
     const tool = this.byName(action);
     if (tool.operation !== "write") throw new AiHubError("AI_HUB_TOOL_NOT_WRITE", `Tool "${action}" is not a write Tool.`);
-    const validInput = tool.validate(payload);
-    return tool.handler(validInput, context);
+    return tool.handler(payload, context);
   }
   capabilities(context, options = {}) {
     return this.list(options).map((tool) => ({
@@ -1831,6 +2129,19 @@ var CONFIRM_ACTION_TOOL = "confirm_action";
 function result(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
+function formatMcpData(toolName, data) {
+  if (Array.isArray(data)) {
+    return {
+      dataType: "array",
+      items: data,
+      count: data.length,
+      ...toolName === "market_get_ticker" ? { tickers: data } : {}
+    };
+  }
+  if (data === null || data === void 0) return { dataType: "null", value: null };
+  if (typeof data === "object") return { dataType: "object", value: data };
+  return { dataType: "scalar", value: data };
+}
 function toMcpErrorResult(error) {
   const payload = toAiHubErrorPayload(error);
   return { isError: true, content: [{ type: "text", text: JSON.stringify({ ok: false, ...payload }) }] };
@@ -1839,7 +2150,7 @@ function toMcpTool(tool) {
   return {
     name: tool.name,
     title: tool.title,
-    description: tool.description,
+    description: `${tool.description}${tool.operation === "read" ? " Successful MCP output is always { ok: true, data: ... }. For list results, use data.items and data.count (market_get_ticker also provides data.tickers); for object results, use data.value. Check data.dataType before formatting." : ""}`,
     inputSchema: tool.inputSchema,
     annotations: {
       readOnlyHint: tool.operation === "read",
@@ -1866,10 +2177,10 @@ function createServer(profileName, readOnly) {
   const registry = createToolRegistry();
   const writeExecutor = new ToolWriteExecutor(registry);
   const server = new Server(
-    { name: "ai-hub-agent-trade", version: "0.1.0" },
+    { name: "ai-hub-agent-trade", version: "0.1.4" },
     {
       capabilities: { tools: {} },
-      instructions: "For every state-changing action, call only a spot_prepare_* tool first and show its exact summary to the user. Stop and wait for a new, explicit user confirmation message. Only then call confirm_action with that new message verbatim in userConfirmation. Never call prepare and confirm consecutively for one user instruction; never infer confirmation from prior intent, silence, or an Agent-generated message."
+      instructions: "Every successful tool response is JSON text in the envelope { ok: true, data: ... }. All read-tool data is normalized: dataType=array means use data.items and data.count; dataType=object or scalar means use data.value; dataType=null means no value. market_get_ticker also provides data.tickers as an alias of data.items. Inspect data.dataType before formatting and never assume undocumented nested keys. Prepare/confirm tools return their documented action payload directly in data. For every state-changing action, call only a spot_prepare_* or margin_prepare_* tool first and show its exact summary to the user. Stop and wait for a new, explicit user confirmation message. Only then call confirm_action with that new message verbatim in userConfirmation. Never call prepare and confirm consecutively for one user instruction; never infer confirmation from prior intent, silence, or an Agent-generated message. For spot and margin orders, MARKET BUY always uses quoteAmount (the quote asset to spend); MARKET SELL uses baseQuantity (the base asset to sell). Never reinterpret a requested base quantity as quoteAmount."
     }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -1913,10 +2224,10 @@ function createServer(profileName, readOnly) {
       }
       const preparedTool = registry.list({ readOnly: false }).find((tool) => tool.operation === "write" && prepareToolName(tool) === request.params.name);
       if (preparedTool) {
-        return result({ ok: true, data: writeExecutor.prepare(preparedTool.name, request.params.arguments ?? {}, context) });
+        return result({ ok: true, data: await writeExecutor.prepare(preparedTool.name, request.params.arguments ?? {}, context) });
       }
       const data = await registry.execute(request.params.name, request.params.arguments ?? {}, context, { readOnly });
-      return result({ ok: true, data });
+      return result({ ok: true, data: formatMcpData(request.params.name, data) });
     } catch (error) {
       return toMcpErrorResult(error);
     }
@@ -1932,7 +2243,16 @@ function readOption(args, option) {
   if (!value || value.startsWith("--")) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", `${option} requires a value.`);
   return value;
 }
+function printUsage() {
+  process.stdout.write(
+    "AI Hub Agent Trade MCP\n\nUsage:\n  ai-hub-trade-mcp [--profile <name>] [--read-only]\n  ai-hub-trade-mcp setup --client <client> [--profile <name>]\n\nThe default command starts the local stdio MCP server.\nUse setup to register it with Cursor, Claude Desktop, Claude Code, or Codex.\n"
+  );
+}
 async function main(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    printUsage();
+    return;
+  }
   if (argv[0] === "setup") {
     const client = readOption(argv.slice(1), "--client");
     const profile = readOption(argv.slice(1), "--profile");
@@ -1953,7 +2273,15 @@ async function main(argv) {
   const server = createServer(profileName, readOnly);
   await server.connect(new StdioServerTransport());
 }
-main(process.argv.slice(2)).catch((error) => {
+function isDirectExecution() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+if (isDirectExecution()) main(process.argv.slice(2)).catch((error) => {
   const payload = error instanceof AiHubError ? { code: error.code, message: error.message } : { code: "AI_HUB_UNEXPECTED_ERROR", message: error instanceof Error ? error.message : "Unexpected error" };
   process.stderr.write(`${JSON.stringify(payload)}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aihubspot/agent-trade-mcp",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Local stdio MCP server for AI Hub spot trading tools",
   "license": "UNLICENSED",
   "type": "module",