@aihubspot/agent-trade-mcp 0.1.0 → 0.1.3

package/README.md

@@ -3,3 +3,24 @@
 Install with `npm install -g @aihubspot/agent-trade-mcp`, then start `ai-hub-trade-mcp --profile default`.
 
 This package provides a local stdio MCP server. State-changing operations require a preview and a new explicit user confirmation.
+
+It reads the same local profile as the CLI from `~/.ai-hub/config.toml`. The API key and secret key are stored as plaintext in that file with mode `600`; configure them once through `ai-hub config set-credentials --profile <name>`. Do not share this file.
+
+## Client setup
+
+Register the local stdio MCP server with one supported client. The setup command is the only client-configuration entry point in this phase:
+
+```bash
+ai-hub-trade-mcp setup --client cursor --profile default
+ai-hub-trade-mcp setup --client claude-desktop --profile default
+ai-hub-trade-mcp setup --client claude-code --profile default
+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.

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
@@ -12,12 +14,30 @@ var AiHubError = class extends Error {
     this.code = code;
   }
 };
+var OpenApiBusinessError = class extends AiHubError {
+  constructor(diagnosis) {
+    super(
+      "AI_HUB_OPENAPI_BUSINESS_ERROR",
+      `OpenAPI business error ${diagnosis.upstreamCode}: ${diagnosis.upstreamMessage}`
+    );
+    this.diagnosis = diagnosis;
+    this.name = "OpenApiBusinessError";
+  }
+  diagnosis;
+};
+function toAiHubErrorPayload(error) {
+  if (error instanceof OpenApiBusinessError) {
+    return { code: error.code, ...error.diagnosis };
+  }
+  if (error instanceof AiHubError) {
+    return { code: error.code, message: error.message };
+  }
+  return { code: "AI_HUB_UNEXPECTED_ERROR", message: error instanceof Error ? error.message : "Unexpected error" };
+}
 
 // ../core/src/credential.ts
 import { createHash } from "crypto";
-import keytar from "keytar";
-var SERVICE_NAME = "ai-hub-agent-trade";
-function validate(credentials) {
+function validateApiCredentials(credentials) {
   const apiKey = credentials.apiKey.trim();
   const secretKey = credentials.secretKey.trim();
   if (!apiKey || !secretKey) {
@@ -28,28 +48,11 @@ function validate(credentials) {
 function versionOf(credentials) {
   return createHash("sha256").update(`${credentials.apiKey}\0${credentials.secretKey}`).digest("hex");
 }
-var CredentialStore = class {
-  async set(profile, credentials) {
-    const value = validate(credentials);
-    await keytar.setPassword(SERVICE_NAME, profile, JSON.stringify(value));
-    return { credentialRef: `keychain:${SERVICE_NAME}/${profile}`, credentialVersion: versionOf(value) };
-  }
-  async get(profile) {
-    const stored = await keytar.getPassword(SERVICE_NAME, profile);
-    if (!stored) return void 0;
-    let parsed;
-    try {
-      parsed = JSON.parse(stored);
-    } catch {
-      throw new AiHubError("AI_HUB_CREDENTIAL_INVALID", "Stored credentials are unreadable. Set credentials again.");
-    }
-    const credentials = validate(parsed);
-    return { ...credentials, credentialVersion: versionOf(credentials) };
-  }
-  async remove(profile) {
-    return keytar.deletePassword(SERVICE_NAME, profile);
-  }
-};
+function loadStoredCredentials(apiKey, secretKey) {
+  if (apiKey === void 0 && secretKey === void 0) return void 0;
+  const credentials = validateApiCredentials({ apiKey: apiKey ?? "", secretKey: secretKey ?? "" });
+  return { ...credentials, credentialVersion: versionOf(credentials) };
+}
 
 // ../core/src/confirmation.ts
 import { createHash as createHash2, randomUUID } from "crypto";
@@ -109,6 +112,100 @@ var ConfirmationService = class {
 
 // ../core/src/openapi.ts
 import { createHmac } from "crypto";
+
+// ../core/src/openapi-error-catalog.ts
+var globalErrors = {
+  "-1002": { reason: "API_KEY_REQUIRED", suggestedAction: "Configure credentials for the selected profile, then retry the read request." },
+  "-1003": { reason: "RATE_LIMITED", suggestedAction: "Wait before retrying. Reduce request frequency and do not retry a write automatically.", retryable: true },
+  "-1006": { reason: "WRITE_STATUS_UNKNOWN", suggestedAction: "Do not retry automatically. Query the affected order or history record before taking another action.", writeOutcomeUnknown: true },
+  "-1007": { reason: "UPSTREAM_TIMEOUT", suggestedAction: "For a write, query the affected order or history record before retrying. A read can be retried after a short delay.", retryable: true, writeOutcomeUnknown: true },
+  "-1015": { reason: "TOO_MANY_ORDERS", suggestedAction: "Reduce the number of active or requested orders before retrying." },
+  "-1020": { reason: "UNSUPPORTED_OPERATION", suggestedAction: "Use a supported command and do not substitute another operation automatically." },
+  "-1021": { reason: "INVALID_TIMESTAMP", suggestedAction: "Synchronize the local system clock, then retry the request." },
+  "-1022": { reason: "INVALID_SIGNATURE", suggestedAction: "Verify the selected profile credentials and signing configuration, then retry." },
+  "-1023": { reason: "TIMESTAMP_REQUIRED", suggestedAction: "Use the AI Hub CLI or MCP client so the request timestamp is supplied automatically." },
+  "-1024": { reason: "SIGNATURE_REQUIRED", suggestedAction: "Use the AI Hub CLI or MCP client so the request is signed automatically." },
+  "-1100": { reason: "INVALID_REQUEST_CHARACTERS", suggestedAction: "Correct the invalid request value and retry." },
+  "-1102": { reason: "MISSING_OR_MALFORMED_PARAMETER", suggestedAction: "Provide every required parameter in the documented format." },
+  "-1103": { reason: "UNKNOWN_PARAMETER", suggestedAction: "Remove unsupported parameters and use the CLI command reference." },
+  "-1111": { reason: "INVALID_PRECISION", suggestedAction: "Use the symbol's allowed price and quantity precision." },
+  "-1121": { reason: "INVALID_SYMBOL", suggestedAction: "Query supported symbols and use an exact symbol value." },
+  "-1136": { reason: "ORDER_QUANTITY_TOO_SMALL", suggestedAction: "Increase the order quantity to the symbol minimum." },
+  "-1138": { reason: "ORDER_PRICE_OUT_OF_RANGE", suggestedAction: "Use a price inside the allowed range, then create a new preview." },
+  "-1139": { reason: "MARKET_ORDER_UNSUPPORTED", suggestedAction: "Use a supported order type for the selected symbol." },
+  "-1145": { reason: "ORDER_CANNOT_BE_CANCELLED", suggestedAction: "Query the latest order status before attempting another cancellation." },
+  "-2013": { reason: "ORDER_NOT_FOUND", suggestedAction: "Verify the symbol and order ID, then query open orders if needed." },
+  "-2014": { reason: "INVALID_API_KEY_FORMAT", suggestedAction: "Replace the configured API key with a valid value." },
+  "-2015": { reason: "API_KEY_REJECTED", suggestedAction: "Verify API key permissions, IP restrictions, and the selected tenant profile." },
+  "-2016": { reason: "TRADING_DISABLED", suggestedAction: "The account is restricted. Contact the platform administrator before trying again." },
+  "-2017": { reason: "INSUFFICIENT_BALANCE", suggestedAction: "Check the available balance and reduce the requested amount before creating a new preview." },
+  "-2018": { reason: "DUPLICATE_WITHDRAWAL_REQUEST", suggestedAction: "Use a new withdrawal order ID or query withdrawal history before retrying." },
+  "-2021": { reason: "IDENTITY_VERIFICATION_REQUIRED", suggestedAction: "Complete the account verification required by the tenant before retrying." },
+  "-2022": { reason: "LIMIT_ORDER_VOLUME_TOO_SMALL", suggestedAction: "Increase the limit-order volume to the returned minimum." },
+  "-2023": { reason: "MARKET_ORDER_VOLUME_TOO_SMALL", suggestedAction: "Increase the market-order sell volume to the returned minimum." },
+  "-2024": { reason: "LIMIT_ORDER_PRICE_TOO_SMALL", suggestedAction: "Increase the limit-order price to the returned minimum." },
+  "-2025": { reason: "MARKET_ORDER_AMOUNT_TOO_SMALL", suggestedAction: "Increase the market-order buy amount to the returned minimum." },
+  "-2026": { reason: "BUY_AMOUNT_TOO_LARGE", suggestedAction: "Reduce the buy amount before creating a new preview." },
+  "-2027": { reason: "SELL_AMOUNT_TOO_LARGE", suggestedAction: "Reduce the sell amount before creating a new preview." },
+  "-2029": { reason: "LIMIT_ORDER_NOTIONAL_TOO_SMALL", suggestedAction: "Increase the limit-order notional amount to the returned minimum." },
+  "-2030": { reason: "TRANSFER_NOT_FOUND", suggestedAction: "Verify the transfer ID, or query by the documented source and destination accounts." },
+  "-2031": { reason: "TRANSFER_TYPE_UNSUPPORTED", suggestedAction: "Use a supported source and destination account combination." },
+  "-2033": { reason: "ASSET_TRANSFER_FAILED", suggestedAction: "Query transfer history before attempting another transfer." },
+  "-2034": { reason: "SUB_ACCOUNT_RELATION_NOT_FOUND", suggestedAction: "Use a sub-account that belongs to the authenticated parent account." },
+  "-2035": { reason: "SUB_ACCOUNT_API_KEY_NOT_FOUND", suggestedAction: "Verify the sub-account API key identifier before retrying." },
+  "-2036": { reason: "SUB_ACCOUNT_PERMISSION_DENIED", suggestedAction: "Use a parent-account credential with the required sub-account permission." },
+  "-2037": { reason: "SUB_ACCOUNT_CREATION_FAILED", suggestedAction: "Check the sub-account limit and requested identifier before creating a new preview." },
+  "-2038": { reason: "SUB_ACCOUNT_UPDATE_FAILED", suggestedAction: "Query the latest sub-account state before retrying the update." },
+  "-2040": { reason: "SUB_ACCOUNT_CREDENTIAL_REQUIRED", suggestedAction: "Use the sub-account credential required by this endpoint." },
+  "10001": { reason: "USER_ACCOUNT_LOCKED", suggestedAction: "The account is restricted. Contact the platform administrator." },
+  "10004": { reason: "USER_NOT_AUTHENTICATED", suggestedAction: "Configure valid credentials for the selected profile." },
+  "10005": { reason: "PERMISSION_DENIED", suggestedAction: "Verify the API key permissions and the tenant feature permission." },
+  "10006": { reason: "TENANT_PERMISSION_DENIED", suggestedAction: "Ask the tenant administrator to enable this capability." },
+  "21018": { reason: "SUB_ACCOUNT_NOT_FOUND", suggestedAction: "List sub-accounts and use an existing sub-account ID." },
+  "21019": { reason: "COIN_NOT_FOUND", suggestedAction: "Query supported coins and use an exact coin symbol." },
+  "21020": { reason: "SYMBOL_NOT_FOUND", suggestedAction: "Query supported symbols and use an exact symbol value." },
+  "21022": { reason: "ORDER_NOT_FOUND", suggestedAction: "Verify the order identifier and symbol, then query current orders if needed." },
+  "21024": { reason: "SUB_ACCOUNT_FEATURE_PERMISSION_DENIED", suggestedAction: "Enable the required sub-account feature permission before retrying." },
+  "21025": { reason: "SUB_ACCOUNT_LIMIT_REACHED", suggestedAction: "The parent account has reached its sub-account limit." }
+};
+var endpointErrors = {
+  "/sapi/v1/withdraw/query:10005": { reason: "WITHDRAW_HISTORY_PERMISSION_DENIED", suggestedAction: "Enable the withdrawal-history permission for this API key, then retry." },
+  "/sapi/v1/withdraw/query:-2015": { reason: "WITHDRAW_HISTORY_TRUSTED_IP_REQUIRED", suggestedAction: "Add a trusted IP to the API key before querying withdrawal history." },
+  "/sapi/v1/withdraw/query:-1004": { reason: "WITHDRAW_HISTORY_PARENT_ACCOUNT_REQUIRED", suggestedAction: "Use a parent-account credential for withdrawal history." },
+  "/sapi/v1/sub_user/asset/root_transfer_query:-2036": { reason: "ROOT_SUB_TRANSFER_PARENT_PERMISSION_REQUIRED", suggestedAction: "Use a parent-account credential that can access the requested sub-account." },
+  "/sapi/v1/sub_user/asset/transfer_query:-2034": { reason: "SUB_ACCOUNT_INTERNAL_TRANSFER_RELATION_NOT_FOUND", suggestedAction: "Use a sub-account that belongs to the authenticated parent account." },
+  "/sapi/v1/asset/subaccount/transfer_query:-2040": { reason: "PARENT_TRANSFER_SUB_ACCOUNT_REQUIRED", suggestedAction: "Run this query with the relevant sub-account credential." }
+};
+function normalizeCode(value) {
+  return String(value).trim();
+}
+function diagnoseOpenApiBusinessError(path2, upstreamCode, upstreamMessage) {
+  const code = normalizeCode(upstreamCode);
+  const definition = endpointErrors[`${path2}:${code}`] ?? globalErrors[code];
+  if (!definition) {
+    return {
+      upstreamCode: code,
+      upstreamMessage,
+      reason: "UNKNOWN_UPSTREAM_CODE",
+      suggestedAction: "Review the upstream message and endpoint. Do not retry a state-changing request automatically.",
+      retryable: false,
+      writeOutcomeUnknown: false
+    };
+  }
+  return {
+    upstreamCode: code,
+    upstreamMessage,
+    reason: definition.reason,
+    suggestedAction: definition.suggestedAction,
+    retryable: definition.retryable ?? false,
+    writeOutcomeUnknown: definition.writeOutcomeUnknown ?? false
+  };
+}
+function isOpenApiSuccessCode(value) {
+  return value === 0 || value === "0";
+}
+
+// ../core/src/openapi.ts
 function parseJsonPreservingLargeIntegers(raw) {
   let transformed = "";
   let inString = false;
@@ -155,13 +252,13 @@ function queryString(values) {
   }
   return params.toString();
 }
-function joinUrl(baseUrl, path, query) {
-  if (!path.startsWith("/")) throw new AiHubError("AI_HUB_INVALID_PATH", "OpenAPI paths must start with '/'.");
-  const url = `${baseUrl.replace(/\/+$/, "")}${path}`;
+function joinUrl(baseUrl, path2, query) {
+  if (!path2.startsWith("/")) throw new AiHubError("AI_HUB_INVALID_PATH", "OpenAPI paths must start with '/'.");
+  const url = `${baseUrl.replace(/\/+$/, "")}${path2}`;
   return query ? `${url}?${query}` : url;
 }
-function signRequest(timestamp, method, path, secretKey, query, body) {
-  const payload = `${timestamp}${method.toUpperCase()}${path}${query ? `?${query}` : ""}${body ?? ""}`;
+function signRequest(timestamp, method, path2, secretKey, query, body) {
+  const payload = `${timestamp}${method.toUpperCase()}${path2}${query ? `?${query}` : ""}${body ?? ""}`;
   return createHmac("sha256", secretKey).update(payload).digest("hex");
 }
 var AiHubSpotApi = class {
@@ -236,13 +333,13 @@ var AiHubSpotApi = class {
    * defined by the API document. Keep endpoint selection in the individual Tool
    * definition; never expose this method directly through CLI or MCP.
    */
-  signedGet(path, query, credentials) {
-    return this.request("GET", path, query, void 0, credentials);
+  signedGet(path2, query, credentials) {
+    return this.request("GET", path2, query, void 0, credentials);
   }
-  signedPost(path, body, credentials) {
-    return this.request("POST", path, {}, body, credentials);
+  signedPost(path2, body, credentials) {
+    return this.request("POST", path2, {}, body, credentials);
   }
-  async request(method, path, query = {}, body, credentials) {
+  async request(method, path2, query = {}, body, credentials) {
     const encodedQuery = queryString(query);
     const bodyString = body ? JSON.stringify(body) : void 0;
     const headers = {
@@ -255,11 +352,11 @@ var AiHubSpotApi = class {
       const timestamp = Date.now().toString();
       headers["X-CH-APIKEY"] = credentials.apiKey;
       headers["X-CH-TS"] = timestamp;
-      headers["X-CH-SIGN"] = signRequest(timestamp, method, path, credentials.secretKey, encodedQuery || void 0, bodyString);
+      headers["X-CH-SIGN"] = signRequest(timestamp, method, path2, credentials.secretKey, encodedQuery || void 0, bodyString);
     }
     let response;
     try {
-      response = await fetch(joinUrl(this.baseUrl, path, encodedQuery), {
+      response = await fetch(joinUrl(this.baseUrl, path2, encodedQuery), {
         method,
         headers,
         body: bodyString,
@@ -277,8 +374,18 @@ var AiHubSpotApi = class {
       throw new AiHubError("AI_HUB_OPENAPI_HTTP_ERROR", `OpenAPI returned HTTP ${response.status}.`);
     }
     try {
-      return parseJsonPreservingLargeIntegers(raw);
-    } catch {
+      const parsed = parseJsonPreservingLargeIntegers(raw);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        const payload = parsed;
+        if (Object.hasOwn(payload, "code") && !isOpenApiSuccessCode(payload.code)) {
+          const upstreamCode = typeof payload.code === "string" || typeof payload.code === "number" ? payload.code : String(payload.code);
+          const upstreamMessage = typeof payload.msg === "string" ? payload.msg : "OpenAPI returned a business failure without a message.";
+          throw new OpenApiBusinessError(diagnoseOpenApiBusinessError(path2, upstreamCode, upstreamMessage));
+        }
+      }
+      return parsed;
+    } catch (error) {
+      if (error instanceof OpenApiBusinessError) throw error;
       throw new AiHubError("AI_HUB_OPENAPI_INVALID_RESPONSE", "OpenAPI returned a non-JSON response.");
     }
   }
@@ -377,7 +484,11 @@ var ConfigStore = class {
     const config = await this.read();
     const normalizedUrl = await normalizeOpenApiBaseUrl(openApiBaseUrl);
     const existing = config.profiles[name];
-    config.profiles[name] = { openapi_base_url: normalizedUrl, ...existing?.credential_ref ? { credential_ref: existing.credential_ref } : {} };
+    config.profiles[name] = {
+      openapi_base_url: normalizedUrl,
+      ...existing?.api_key ? { api_key: existing.api_key } : {},
+      ...existing?.secret_key ? { secret_key: existing.secret_key } : {}
+    };
     if (Object.keys(config.profiles).length === 1) config.default_profile = name;
     await this.write(config);
     return this.resolveFrom(config, name);
@@ -386,6 +497,12 @@ var ConfigStore = class {
     const config = await this.read();
     return this.resolveFrom(config, requestedName ?? config.default_profile);
   }
+  async getCredentials(requestedName) {
+    const config = await this.read();
+    const name = requestedName ?? config.default_profile;
+    const profile = this.profileFrom(config, name);
+    return loadStoredCredentials(profile.api_key, profile.secret_key);
+  }
   async removeProfile(name) {
     validateProfileName(name);
     const config = await this.read();
@@ -394,26 +511,31 @@ var ConfigStore = class {
     if (config.default_profile === name) config.default_profile = Object.keys(config.profiles)[0] ?? "default";
     await this.write(config);
   }
-  async setCredentialRef(name, credentialRef) {
+  async setCredentials(name, credentials) {
     validateProfileName(name);
     const config = await this.read();
     const profile = config.profiles[name];
     if (!profile) throw new AiHubError("AI_HUB_PROFILE_NOT_FOUND", `Profile "${name}" does not exist.`);
-    config.profiles[name] = { ...profile, credential_ref: credentialRef };
+    const value = validateApiCredentials(credentials);
+    config.profiles[name] = { openapi_base_url: profile.openapi_base_url, api_key: value.apiKey, secret_key: value.secretKey };
     await this.write(config);
     return this.resolveFrom(config, name);
   }
   resolveFrom(config, name) {
     validateProfileName(name);
-    const profile = config.profiles[name];
-    if (!profile) throw new AiHubError("AI_HUB_PROFILE_NOT_FOUND", `Profile "${name}" does not exist.`);
+    const profile = this.profileFrom(config, name);
     return {
       name,
       openApiBaseUrl: profile.openapi_base_url,
-      credentialRef: profile.credential_ref,
       configVersion: versionOf2(config, name)
     };
   }
+  profileFrom(config, name) {
+    validateProfileName(name);
+    const profile = config.profiles[name];
+    if (!profile) throw new AiHubError("AI_HUB_PROFILE_NOT_FOUND", `Profile "${name}" does not exist.`);
+    return profile;
+  }
   async write(config) {
     const directory = dirname(this.filePath);
     await mkdir(directory, { recursive: true, mode: 448 });
@@ -428,8 +550,9 @@ var ConfigStore = class {
 
 // ../core/src/tools/execution-context.ts
 async function createToolExecutionContext(profileName) {
-  const profile = await new ConfigStore().showProfile(profileName);
-  const credentials = await new CredentialStore().get(profile.name);
+  const store = new ConfigStore();
+  const profile = await store.showProfile(profileName);
+  const credentials = await store.getCredentials(profile.name);
   return { profile, credentials, api: new AiHubSpotApi(profile.openApiBaseUrl) };
 }
 function confirmationContext(context) {
@@ -485,7 +608,7 @@ var accountTools = [
     operation: "read",
     riskLevel: "low",
     inputSchema: { type: "object", additionalProperties: false },
-    errorCodes: ["AI_HUB_CREDENTIAL_NOT_CONFIGURED", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE"],
+    errorCodes: ["AI_HUB_CREDENTIAL_NOT_CONFIGURED", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE", "AI_HUB_OPENAPI_BUSINESS_ERROR"],
     validate: (input) => strictObject(input, []),
     handler: async (_input, context) => {
       if (!context.credentials) throw new AiHubError("AI_HUB_CREDENTIAL_NOT_CONFIGURED", `Credentials are not configured for profile "${context.profile.name}".`);
@@ -496,7 +619,7 @@ var accountTools = [
 
 // ../core/src/tools/tool-utils.ts
 import { randomUUID as randomUUID2 } from "crypto";
-var signedReadErrors = ["AI_HUB_INVALID_ARGUMENT", "AI_HUB_CREDENTIAL_NOT_CONFIGURED", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE"];
+var signedReadErrors = ["AI_HUB_INVALID_ARGUMENT", "AI_HUB_CREDENTIAL_NOT_CONFIGURED", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE", "AI_HUB_OPENAPI_BUSINESS_ERROR"];
 var writeErrors = [...signedReadErrors, "AI_HUB_WRITE_CONFIRMATION_REQUIRED", "AI_HUB_CONFIRMATION_REQUIRED", "AI_HUB_CONFIRMATION_EXPIRED", "AI_HUB_CONFIRMATION_CONTEXT_CHANGED", "AI_HUB_CONFIRMATION_NOT_FOUND"];
 function signed(context) {
   if (!context.credentials) throw new AiHubError("AI_HUB_CREDENTIAL_NOT_CONFIGURED", `Credentials are not configured for profile "${context.profile.name}".`);
@@ -744,7 +867,7 @@ var assetTools = [
 ];
 
 // ../core/src/tools/market-tools.ts
-var readErrors = ["AI_HUB_INVALID_ARGUMENT", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE"];
+var readErrors = ["AI_HUB_INVALID_ARGUMENT", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE", "AI_HUB_OPENAPI_BUSINESS_ERROR"];
 var marketTools = [
   {
     name: "market_ping",
@@ -756,7 +879,7 @@ var marketTools = [
     operation: "read",
     riskLevel: "low",
     inputSchema: { type: "object", additionalProperties: false },
-    errorCodes: ["AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE"],
+    errorCodes: ["AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE", "AI_HUB_OPENAPI_BUSINESS_ERROR"],
     validate: (input) => {
       strictObject(input, []);
       return {};
@@ -869,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"]);
@@ -934,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",
@@ -973,7 +1298,7 @@ var marginTools = [
 
 // ../core/src/tools/order-tools.ts
 import { randomUUID as randomUUID3 } from "crypto";
-var signedReadErrors2 = ["AI_HUB_INVALID_ARGUMENT", "AI_HUB_CREDENTIAL_NOT_CONFIGURED", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE"];
+var signedReadErrors2 = ["AI_HUB_INVALID_ARGUMENT", "AI_HUB_CREDENTIAL_NOT_CONFIGURED", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE", "AI_HUB_OPENAPI_BUSINESS_ERROR"];
 var writeErrors2 = [...signedReadErrors2, "AI_HUB_WRITE_CONFIRMATION_REQUIRED", "AI_HUB_CONFIRMATION_REQUIRED", "AI_HUB_CONFIRMATION_EXPIRED", "AI_HUB_CONFIRMATION_CONTEXT_CHANGED", "AI_HUB_CONFIRMATION_NOT_FOUND"];
 var decimal = /^(?:0|[1-9]\d*)(?:\.\d+)?$/;
 function positiveDecimal2(value, name) {
@@ -1002,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"]);
@@ -1057,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))
@@ -1092,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;
@@ -1127,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",
@@ -1160,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",
@@ -1446,12 +1865,12 @@ var ToolRegistry = class {
   toolsByCliPath = /* @__PURE__ */ new Map();
   constructor(tools = allTools) {
     for (const tool of tools) {
-      const path = tool.cliPath.join(" ");
-      if (this.toolsByName.has(tool.name) || this.toolsByCliPath.has(path)) {
+      const path2 = tool.cliPath.join(" ");
+      if (this.toolsByName.has(tool.name) || this.toolsByCliPath.has(path2)) {
         throw new AiHubError("AI_HUB_TOOL_DUPLICATE", `Duplicate tool registration: ${tool.name}.`);
       }
       this.toolsByName.set(tool.name, tool);
-      this.toolsByCliPath.set(path, tool);
+      this.toolsByCliPath.set(path2, tool);
     }
   }
   list(options = {}) {
@@ -1464,10 +1883,10 @@ var ToolRegistry = class {
     }
     return tool;
   }
-  byCliPath(path, options = {}) {
-    const tool = this.toolsByCliPath.get(path.join(" "));
+  byCliPath(path2, options = {}) {
+    const tool = this.toolsByCliPath.get(path2.join(" "));
     if (!tool || options.readOnly && tool.operation !== "read") {
-      throw new AiHubError("AI_HUB_TOOL_NOT_AVAILABLE", `Command "${path.join(" ")}" is not available.`);
+      throw new AiHubError("AI_HUB_TOOL_NOT_AVAILABLE", `Command "${path2.join(" ")}" is not available.`);
     }
     return tool;
   }
@@ -1477,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) => ({
@@ -1532,6 +1951,176 @@ var ToolWriteExecutor = class {
   }
 };
 
+// ../core/src/setup.ts
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+var MCP_BINARY = "ai-hub-trade-mcp";
+var MCP_CLIENT_NAMES = {
+  cursor: "Cursor",
+  "claude-desktop": "Claude Desktop",
+  "claude-code": "Claude Code",
+  codex: "Codex"
+};
+var SUPPORTED_MCP_CLIENTS = Object.keys(MCP_CLIENT_NAMES);
+function runtime() {
+  const home = os.homedir();
+  return {
+    home,
+    platform: process.platform,
+    cwd: process.cwd(),
+    appData: process.env.APPDATA,
+    localAppData: process.env.LOCALAPPDATA,
+    xdgConfigHome: process.env.XDG_CONFIG_HOME
+  };
+}
+function windowsAppData(value, home) {
+  return value ?? path.join(home, "AppData", "Roaming");
+}
+function findMicrosoftStoreClaudePath(value, home) {
+  const packagesDirectory = path.join(value ?? path.join(home, "AppData", "Local"), "Packages");
+  try {
+    const packageName = fs.readdirSync(packagesDirectory).find((entry) => entry.startsWith("Claude_"));
+    if (!packageName) return void 0;
+    const configPath = path.join(
+      packagesDirectory,
+      packageName,
+      "LocalCache",
+      "Roaming",
+      "Claude",
+      "claude_desktop_config.json"
+    );
+    return fs.existsSync(configPath) || fs.existsSync(path.dirname(configPath)) ? configPath : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function getMcpClientConfigPath(client, value = runtime()) {
+  if (client === "cursor") return path.join(value.home, ".cursor", "mcp.json");
+  if (value.platform === "win32") {
+    return findMicrosoftStoreClaudePath(value.localAppData, value.home) ?? path.join(windowsAppData(value.appData, value.home), "Claude", "claude_desktop_config.json");
+  }
+  if (value.platform === "darwin") {
+    return path.join(value.home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  }
+  return path.join(value.xdgConfigHome ?? path.join(value.home, ".config"), "Claude", "claude_desktop_config.json");
+}
+function buildServerSpec(profile, launch) {
+  return {
+    name: serverName(profile),
+    command: launch.command,
+    args: [...launch.args, ...profile ? ["--profile", profile] : []]
+  };
+}
+function serverName(profile) {
+  return profile ? `${MCP_BINARY}-${profile}` : MCP_BINARY;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergeJsonMcpConfig(configPath, server) {
+  const directory = path.dirname(configPath);
+  fs.mkdirSync(directory, { recursive: true });
+  const configExists = fs.existsSync(configPath);
+  let config = {};
+  if (configExists) {
+    const raw = fs.readFileSync(configPath, "utf8");
+    try {
+      const parsed = JSON.parse(raw);
+      if (!isRecord(parsed)) throw new Error("root must be a JSON object");
+      config = parsed;
+    } catch {
+      throw new Error(`Failed to parse existing MCP configuration at ${configPath}. No changes were made.`);
+    }
+  }
+  if (config.mcpServers === void 0) {
+    config.mcpServers = {};
+  }
+  if (!isRecord(config.mcpServers)) {
+    throw new Error(`Existing MCP configuration at ${configPath} has an invalid mcpServers object. No changes were made.`);
+  }
+  if (configExists) {
+    const backupPath = `${configPath}.bak`;
+    if (!fs.existsSync(backupPath)) {
+      fs.copyFileSync(configPath, backupPath);
+      process.stdout.write(`Backup created: ${backupPath}
+`);
+    }
+  }
+  config.mcpServers[server.name] = { command: server.command, args: server.args };
+  const mode = configExists ? fs.statSync(configPath).mode & 511 : 384;
+  const temporaryPath = `${configPath}.${process.pid}.tmp`;
+  fs.writeFileSync(temporaryPath, `${JSON.stringify(config, null, 2)}
+`, { encoding: "utf8", mode });
+  fs.chmodSync(temporaryPath, mode);
+  fs.renameSync(temporaryPath, configPath);
+}
+function executeClientRegistration(command, args, value) {
+  process.stdout.write(`Running: ${command} ${args.join(" ")}
+`);
+  if (value.executeClientCommand) {
+    value.executeClientCommand(command, args);
+    return;
+  }
+  execFileSync(command, args, { stdio: "inherit" });
+}
+function jsonFileAdapter(id) {
+  return {
+    id,
+    name: MCP_CLIENT_NAMES[id],
+    install(server, value) {
+      mergeJsonMcpConfig(getMcpClientConfigPath(id, value), server);
+      process.stdout.write(`Configured ${this.name}: ${getMcpClientConfigPath(id, value)}
+Restart ${this.name} to apply changes.
+`);
+    }
+  };
+}
+function cliAdapter(id) {
+  const command = id === "claude-code" ? "claude" : "codex";
+  return {
+    id,
+    name: MCP_CLIENT_NAMES[id],
+    install(server, value) {
+      const args = [
+        "mcp",
+        "add",
+        ...id === "claude-code" ? ["--scope", "user", "--transport", "stdio"] : [],
+        server.name,
+        "--",
+        server.command,
+        ...server.args
+      ];
+      executeClientRegistration(command, args, value);
+      process.stdout.write(`Configured ${this.name} with local stdio MCP server "${server.name}".
+`);
+    }
+  };
+}
+var MCP_CLIENT_ADAPTERS = {
+  cursor: jsonFileAdapter("cursor"),
+  "claude-desktop": jsonFileAdapter("claude-desktop"),
+  "claude-code": cliAdapter("claude-code"),
+  codex: cliAdapter("codex")
+};
+function runMcpSetup(options, value = runtime()) {
+  const adapter = MCP_CLIENT_ADAPTERS[options.client];
+  if (!adapter) {
+    throw new Error(`Unknown MCP client "${options.client}". Supported clients: ${SUPPORTED_MCP_CLIENTS.join(", ")}.`);
+  }
+  const profile = options.profile ? validateProfileName(options.profile) : void 0;
+  adapter.install(buildServerSpec(profile, options.launch), value);
+}
+function printMcpSetupUsage() {
+  process.stdout.write(
+    `Usage: ${MCP_BINARY} setup --client <client> [--profile <name>]
+
+Supported clients:
+` + SUPPORTED_MCP_CLIENTS.map((client) => `  ${client.padEnd(16)} ${MCP_CLIENT_NAMES[client]}`).join("\n") + "\n"
+  );
+}
+
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -1540,8 +2129,8 @@ var CONFIRM_ACTION_TOOL = "confirm_action";
 function result(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
-function errorResult(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" };
+function toMcpErrorResult(error) {
+  const payload = toAiHubErrorPayload(error);
   return { isError: true, content: [{ type: "text", text: JSON.stringify({ ok: false, ...payload }) }] };
 }
 function toMcpTool(tool) {
@@ -1575,10 +2164,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.3" },
     {
       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: "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 () => ({
@@ -1622,12 +2211,12 @@ 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 });
     } catch (error) {
-      return errorResult(error);
+      return toMcpErrorResult(error);
     }
   });
   return server;
@@ -1641,13 +2230,45 @@ 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");
+    if (!client) {
+      printMcpSetupUsage();
+      return;
+    }
+    if (!SUPPORTED_MCP_CLIENTS.includes(client)) {
+      throw new AiHubError("AI_HUB_INVALID_ARGUMENT", `Unknown MCP client "${client}". Supported clients: ${SUPPORTED_MCP_CLIENTS.join(", ")}.`);
+    }
+    const entrypoint = process.argv[1];
+    if (!entrypoint) throw new AiHubError("AI_HUB_UNEXPECTED_ERROR", "Cannot locate the local MCP server entrypoint for client setup.");
+    runMcpSetup({ client, profile, launch: { command: process.execPath, args: [entrypoint] } });
+    return;
+  }
   const profileName = readOption(argv, "--profile");
   const readOnly = argv.includes("--read-only");
   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.0",
+  "version": "0.1.3",
   "description": "Local stdio MCP server for AI Hub spot trading tools",
   "license": "UNLICENSED",
   "type": "module",
@@ -14,12 +14,11 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "test": "tsx --test test/*.test.ts",
+    "test": "TSX_TSCONFIG_PATH=./test/tsconfig.json tsx --test test/*.test.ts",
     "clean": "rm -rf dist"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "keytar": "^7.9.0",
     "smol-toml": "^1.3.4"
   }
 }