@aihubspot/agent-trade-mcp 0.1.8 → 0.1.10

package/README.md

@@ -23,7 +23,7 @@ Setup registers the currently installed MCP binary through its absolute Node run
 
 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.
+Before any order preview, MCP lazily loads `/sapi/v2/symbols` once per local profile and caches the symbol rules for one hour in memory and an isolated local cache. Known quantity/price precision and limit-order minimum violations are rejected before confirmation.
 
 ## Read response
 
@@ -39,7 +39,10 @@ MCP clients that support the current protocol also receive the same envelope in
 
 Use these tools for requests that would otherwise return a broad market payload:
 
-- `market_search_symbols`: bounded symbol search and metadata. Use this for every MCP symbol lookup; it returns matching rows in `data.value.items`.
+- `market_get_symbol_overview`: counts by quote asset and a small sample. Use this first for a generic request to list trading pairs.
+- `market_list_symbols`: a paged, optionally quote-asset-filtered list without order-rule metadata.
+- `market_search_symbols`: required-keyword lookup with at most 20 basic matching rows. Do not use it for a generic pair list.
+- `market_get_symbol_info`: exact precision and minimum order rules for one symbol only.
 - `market_get_ticker_summary`: watchlist, gainers, losers, and quote-volume leaders.
 - `market_get_depth_summary`: best bid/ask, spread, and up to 20 levels per side.
 - `market_get_trades_summary`: price range, buy/sell statistics, and up to 50 recent trades.

package/dist/index.js

@@ -56,6 +56,9 @@ function loadStoredCredentials(apiKey, secretKey) {
 
 // ../core/src/confirmation.ts
 import { createHash as createHash2, randomUUID } from "crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
 function stableJson(value) {
   if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
   if (value && typeof value === "object") {
@@ -66,6 +69,37 @@ function stableJson(value) {
 function hash(input) {
   return createHash2("sha256").update(stableJson({ action: input.action, payload: input.payload, context: input.context })).digest("hex");
 }
+function createPending(input, ttlMs, now) {
+  return {
+    ...input,
+    confirmationId: randomUUID(),
+    requestHash: hash(input),
+    expiresAtMs: now() + ttlMs
+  };
+}
+function preparedAction(pending) {
+  return {
+    confirmationId: pending.confirmationId,
+    expiresAt: new Date(pending.expiresAtMs).toISOString(),
+    requestHash: pending.requestHash,
+    action: pending.action,
+    summary: pending.summary,
+    requiresNewUserConfirmation: true,
+    nextStep: "Stop and wait for a new explicit user confirmation message. Do not confirm from the same user instruction that prepared this request."
+  };
+}
+function confirmPending(pending, userConfirmation, context, now) {
+  if (typeof userConfirmation !== "string" || !userConfirmation.trim()) {
+    throw new AiHubError("AI_HUB_CONFIRMATION_REQUIRED", "A non-empty new explicit user confirmation message is required before a state-changing request can execute.");
+  }
+  if (pending.expiresAtMs < now()) {
+    throw new AiHubError("AI_HUB_CONFIRMATION_EXPIRED", "Confirmation has expired.");
+  }
+  if (stableJson(pending.context) !== stableJson(context)) {
+    throw new AiHubError("AI_HUB_CONFIRMATION_CONTEXT_CHANGED", "Profile, OpenAPI base URL, configuration, or credentials changed after prepare.");
+  }
+  return { action: pending.action, payload: pending.payload, requestHash: pending.requestHash };
+}
 var ConfirmationService = class {
   constructor(ttlMs = 5 * 60 * 1e3, now = () => Date.now()) {
     this.ttlMs = ttlMs;
@@ -75,19 +109,9 @@ var ConfirmationService = class {
   now;
   actions = /* @__PURE__ */ new Map();
   prepare(input) {
-    const expiresAtMs = this.now() + this.ttlMs;
-    const confirmationId = randomUUID();
-    const requestHash = hash(input);
-    this.actions.set(confirmationId, { ...input, confirmationId, requestHash, expiresAtMs, consumed: false });
-    return {
-      confirmationId,
-      expiresAt: new Date(expiresAtMs).toISOString(),
-      requestHash,
-      action: input.action,
-      summary: input.summary,
-      requiresNewUserConfirmation: true,
-      nextStep: "Stop and wait for a new explicit user confirmation message. Do not call confirm_action from the same user instruction that prepared this request."
-    };
+    const pending = createPending(input, this.ttlMs, this.now);
+    this.actions.set(pending.confirmationId, { ...pending, consumed: false });
+    return preparedAction(pending);
   }
   confirm(confirmationId, userConfirmation, context) {
     if (typeof userConfirmation !== "string" || !userConfirmation.trim()) {
@@ -96,17 +120,9 @@ var ConfirmationService = class {
     const pending = this.actions.get(confirmationId);
     if (!pending) throw new AiHubError("AI_HUB_CONFIRMATION_NOT_FOUND", "Confirmation was not found or has already been consumed.");
     if (pending.consumed) throw new AiHubError("AI_HUB_CONFIRMATION_CONSUMED", "Confirmation has already been consumed.");
-    if (pending.expiresAtMs < this.now()) {
-      this.actions.delete(confirmationId);
-      throw new AiHubError("AI_HUB_CONFIRMATION_EXPIRED", "Confirmation has expired.");
-    }
-    if (stableJson(pending.context) !== stableJson(context)) {
-      this.actions.delete(confirmationId);
-      throw new AiHubError("AI_HUB_CONFIRMATION_CONTEXT_CHANGED", "Profile, OpenAPI base URL, configuration, or credentials changed after prepare.");
-    }
     pending.consumed = true;
     this.actions.delete(confirmationId);
-    return { action: pending.action, payload: pending.payload, requestHash: pending.requestHash };
+    return confirmPending(pending, userConfirmation, context, this.now);
   }
 };
 
@@ -394,16 +410,16 @@ var AiHubSpotApi = class {
 // ../core/src/config.ts
 import { createHash as createHash3 } from "crypto";
 import { lookup } from "dns/promises";
-import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
-import { homedir } from "os";
-import { dirname, join } from "path";
+import { chmod as chmod2, mkdir as mkdir2, readFile as readFile2, rename as rename2, writeFile as writeFile2 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { dirname, join as join2 } from "path";
 import { isIP } from "net";
 import { parse, stringify } from "smol-toml";
 var CONFIG_DIRECTORY = ".ai-hub";
 var CONFIG_FILENAME = "config.toml";
 var PROFILE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
-function configFilePath(home = homedir()) {
-  return join(home, CONFIG_DIRECTORY, CONFIG_FILENAME);
+function configFilePath(home = homedir2()) {
+  return join2(home, CONFIG_DIRECTORY, CONFIG_FILENAME);
 }
 function validateProfileName(name) {
   if (!PROFILE_NAME.test(name)) {
@@ -467,7 +483,7 @@ var ConfigStore = class {
   filePath;
   async read() {
     try {
-      return parseConfig(await readFile(this.filePath, "utf8"));
+      return parseConfig(await readFile2(this.filePath, "utf8"));
     } catch (error) {
       if (error.code === "ENOENT") return defaultConfig();
       throw error;
@@ -538,13 +554,13 @@ var ConfigStore = class {
   }
   async write(config) {
     const directory = dirname(this.filePath);
-    await mkdir(directory, { recursive: true, mode: 448 });
-    await chmod(directory, 448);
+    await mkdir2(directory, { recursive: true, mode: 448 });
+    await chmod2(directory, 448);
     const temporaryPath = `${this.filePath}.${process.pid}.tmp`;
-    await writeFile(temporaryPath, stringify(config), { mode: 384 });
-    await chmod(temporaryPath, 384);
-    await rename(temporaryPath, this.filePath);
-    await chmod(this.filePath, 384);
+    await writeFile2(temporaryPath, stringify(config), { mode: 384 });
+    await chmod2(temporaryPath, 384);
+    await rename2(temporaryPath, this.filePath);
+    await chmod2(this.filePath, 384);
   }
 };
 
@@ -1032,47 +1048,112 @@ function summarizeTickers(value, options) {
     topByQuoteVolume: [...rows2].sort(compareByNumericField("amount", "desc")).slice(0, limit).map(tickerItem)
   };
 }
-function summarizeSymbols(value, options) {
+function normalizedSymbol(value) {
+  return value.replaceAll("/", "").trim().toUpperCase();
+}
+function parsedSymbolRows(value) {
   const payload = record(value, "Symbols response must be an object.");
   const rows2 = records(payload.symbols, "Symbols response must contain a symbols array.");
-  const query = options.query?.trim().toUpperCase();
-  const quoteAsset = options.quoteAsset?.trim().toUpperCase();
-  const matches = rows2.filter((item) => {
-    const symbol = text(item.SymbolName) ?? text(item.symbol) ?? "";
-    const quote = text(item.quoteAsset)?.toUpperCase();
-    return (!query || symbol.toUpperCase().includes(query)) && (!quoteAsset || quote === quoteAsset);
-  });
-  const sortedMatches = [...matches].sort((left, right) => {
-    if (!query) return 0;
+  return rows2.map((item) => {
+    const apiSymbol = text(item.symbol);
+    const symbol = text(item.SymbolName) ?? apiSymbol ?? "";
+    return {
+      symbol,
+      apiSymbol,
+      baseAsset: text(item.baseAssetName) ?? text(item.baseAsset),
+      quoteAsset: text(item.quoteAssetName) ?? text(item.quoteAsset),
+      pricePrecision: item.pricePrecision ?? null,
+      quantityPrecision: item.quantityPrecision ?? null,
+      limitVolumeMin: text(item.limitVolumeMin),
+      limitPriceMin: text(item.limitPriceMin),
+      limitAmountMin: text(item.limitAmountMin)
+    };
+  }).filter((item) => Boolean(item.symbol));
+}
+function quoteAssetCounts(rows2) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const item of rows2) {
+    const quote = item.quoteAsset?.toUpperCase();
+    if (quote) counts.set(quote, (counts.get(quote) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])).map(([asset, count]) => ({ asset, count }));
+}
+function basicSymbolItem(item) {
+  return {
+    symbol: item.symbol,
+    apiSymbol: item.apiSymbol,
+    baseAsset: item.baseAsset,
+    quoteAsset: item.quoteAsset
+  };
+}
+function fullSymbolItem(item) {
+  return {
+    ...basicSymbolItem(item),
+    pricePrecision: item.pricePrecision,
+    quantityPrecision: item.quantityPrecision,
+    limitVolumeMin: item.limitVolumeMin,
+    limitPriceMin: item.limitPriceMin,
+    limitAmountMin: item.limitAmountMin
+  };
+}
+function sortSymbolMatches(rows2, query) {
+  const normalizedQuery = query?.trim().toUpperCase();
+  return [...rows2].sort((left, right) => {
+    if (!normalizedQuery) return left.symbol.localeCompare(right.symbol);
     const rank = (item) => {
-      const symbol = (text(item.SymbolName) ?? text(item.symbol) ?? "").toUpperCase();
-      return symbol.startsWith(`${query}/`) ? 0 : symbol.startsWith(query) ? 1 : 2;
+      const symbol = item.symbol.toUpperCase();
+      return symbol.startsWith(`${normalizedQuery}/`) ? 0 : symbol.startsWith(normalizedQuery) ? 1 : 2;
     };
-    return rank(left) - rank(right);
+    return rank(left) - rank(right) || left.symbol.localeCompare(right.symbol);
   });
-  const quoteAssetCounts = /* @__PURE__ */ new Map();
-  for (const item of rows2) {
-    const quote = text(item.quoteAsset)?.toUpperCase();
-    if (quote) quoteAssetCounts.set(quote, (quoteAssetCounts.get(quote) ?? 0) + 1);
-  }
-  const items = sortedMatches.slice(0, options.limit).map((item) => ({
-    symbol: text(item.SymbolName) ?? text(item.symbol),
-    apiSymbol: text(item.symbol),
-    baseAsset: text(item.baseAssetName) ?? text(item.baseAsset),
-    quoteAsset: text(item.quoteAssetName) ?? text(item.quoteAsset),
-    pricePrecision: item.pricePrecision ?? null,
-    quantityPrecision: item.quantityPrecision ?? null,
-    limitVolumeMin: text(item.limitVolumeMin),
-    limitPriceMin: text(item.limitPriceMin),
-    limitAmountMin: text(item.limitAmountMin)
-  }));
+}
+function summarizeSymbolOverview(value, options) {
+  const rows2 = parsedSymbolRows(value);
   return {
     totalSymbols: rows2.length,
+    quoteAssetCounts: quoteAssetCounts(rows2),
+    sampleSymbols: sortSymbolMatches(rows2).slice(0, options.limit).map((item) => item.symbol)
+  };
+}
+function listSymbols(value, options) {
+  const allRows = parsedSymbolRows(value);
+  const quoteAsset = options.quoteAsset?.trim().toUpperCase();
+  const matches = sortSymbolMatches(allRows.filter((item) => !quoteAsset || item.quoteAsset?.toUpperCase() === quoteAsset));
+  const items = matches.slice(options.offset, options.offset + options.limit).map(basicSymbolItem);
+  const nextOffset = options.offset + items.length;
+  return {
+    totalSymbols: allRows.length,
     matchedSymbols: matches.length,
-    quoteAssetCounts: [...quoteAssetCounts.entries()].sort((left, right) => right[1] - left[1]).map(([asset, count]) => ({ asset, count })),
+    quoteAsset: quoteAsset ?? null,
+    offset: options.offset,
+    limit: options.limit,
+    nextOffset: nextOffset < matches.length ? nextOffset : null,
     items
   };
 }
+function searchSymbols(value, options) {
+  const allRows = parsedSymbolRows(value);
+  const query = options.query.trim().toUpperCase();
+  const quoteAsset = options.quoteAsset?.trim().toUpperCase();
+  const matches = allRows.filter((item) => {
+    const symbol = item.symbol.toUpperCase();
+    const apiSymbol = item.apiSymbol?.toUpperCase() ?? "";
+    return (symbol.includes(query) || apiSymbol.includes(query)) && (!quoteAsset || item.quoteAsset?.toUpperCase() === quoteAsset);
+  });
+  const sortedMatches = sortSymbolMatches(matches, query);
+  return {
+    matchedSymbols: matches.length,
+    query,
+    quoteAsset: quoteAsset ?? null,
+    items: sortedMatches.slice(0, options.limit).map(basicSymbolItem)
+  };
+}
+function getSymbolInfo(value, symbol) {
+  const target = normalizedSymbol(symbol);
+  const item = parsedSymbolRows(value).find((row) => normalizedSymbol(row.symbol) === target || row.apiSymbol !== null && normalizedSymbol(row.apiSymbol) === target);
+  if (!item) throw new AiHubError("AI_HUB_SYMBOL_NOT_FOUND", `Symbol "${symbol}" was not returned by the configured tenant OpenAPI symbols endpoint.`);
+  return fullSymbolItem(item);
+}
 function level(value) {
   if (!Array.isArray(value)) return { price: null, quantity: null };
   return { price: text(value[0]), quantity: text(value[1]) };
@@ -1169,13 +1250,53 @@ function summarizeKlines(value, symbol, interval) {
 }
 
 // ../core/src/tools/symbol-rules.ts
+import { createHash as createHash4 } from "crypto";
+import { chmod as chmod3, mkdir as mkdir3, readFile as readFile3, rename as rename3, rm as rm2, writeFile as writeFile3 } from "fs/promises";
+import { homedir as homedir3 } from "os";
+import { join as join3 } from "path";
 var CACHE_TTL_MS = 60 * 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) {
+function persistentCacheEnabled() {
+  return process.env.AI_HUB_DISABLE_PERSISTENT_CACHE !== "1";
+}
+function persistentCacheDirectory() {
+  return process.env.AI_HUB_CACHE_DIR ?? join3(homedir3(), ".ai-hub", "cache");
+}
+function persistentCachePath(key) {
+  const hash2 = createHash4("sha256").update(key).digest("hex");
+  return join3(persistentCacheDirectory(), `symbols-${hash2}.json`);
+}
+async function loadPersistentSnapshot(key) {
+  if (!persistentCacheEnabled()) return void 0;
+  try {
+    const parsed = JSON.parse(await readFile3(persistentCachePath(key), "utf8"));
+    if (typeof parsed.expiresAt !== "number" || !Number.isFinite(parsed.expiresAt) || parsed.expiresAt <= Date.now() || !("response" in parsed)) return void 0;
+    return { expiresAt: parsed.expiresAt, response: parsed.response, rules: parseRules(parsed.response) };
+  } catch {
+    return void 0;
+  }
+}
+async function persistSnapshot(key, entry) {
+  if (!persistentCacheEnabled()) return;
+  const directory = persistentCacheDirectory();
+  const filePath = persistentCachePath(key);
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await mkdir3(directory, { recursive: true, mode: 448 });
+    await chmod3(directory, 448);
+    await writeFile3(temporaryPath, JSON.stringify({ expiresAt: entry.expiresAt, response: entry.response }), { mode: 384 });
+    await chmod3(temporaryPath, 384);
+    await rename3(temporaryPath, filePath);
+    await chmod3(filePath, 384);
+  } catch {
+    await rm2(temporaryPath, { force: true }).catch(() => void 0);
+  }
+}
+function normalizedSymbol2(symbol) {
   return symbol.replaceAll("/", "").trim().toUpperCase();
 }
 function stringValue(value) {
@@ -1202,7 +1323,7 @@ function parseRules(response) {
   for (const row of rows(response)) {
     const symbol = stringValue(row.symbol);
     if (!symbol) continue;
-    result2.set(normalizedSymbol(symbol), {
+    result2.set(normalizedSymbol2(symbol), {
       symbol,
       quantityPrecision: nonNegativeInteger(row.quantityPrecision),
       pricePrecision: nonNegativeInteger(row.pricePrecision),
@@ -1219,11 +1340,18 @@ async function loadSnapshot(context) {
   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 load = (async () => {
+    const persisted = await loadPersistentSnapshot(key);
+    if (persisted) {
+      cache.set(key, persisted);
+      return persisted;
+    }
+    const response = await context.api.symbols();
     const entry = { response, rules: parseRules(response), expiresAt: Date.now() + CACHE_TTL_MS };
     cache.set(key, entry);
+    await persistSnapshot(key, entry);
     return entry;
-  }).finally(() => pendingLoads.delete(key));
+  })().finally(() => pendingLoads.delete(key));
   pendingLoads.set(key, load);
   return load;
 }
@@ -1232,7 +1360,7 @@ async function getCachedSymbols(context) {
 }
 async function getSymbolRule(context, symbol) {
   const entry = await loadSnapshot(context);
-  const rule = entry.rules.get(normalizedSymbol(symbol));
+  const rule = entry.rules.get(normalizedSymbol2(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;
 }
@@ -1289,6 +1417,7 @@ async function preflightSymbolOrder(context, order) {
 
 // ../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", "AI_HUB_OPENAPI_BUSINESS_ERROR"];
+var symbolReadErrors = [...readErrors, "AI_HUB_SYMBOL_NOT_FOUND"];
 var KLINE_INTERVALS = ["1min", "5min", "15min", "30min", "60min", "1day", "1week", "1month"];
 var KLINE_INTERVAL_ALIASES = {
   "1m": "1min",
@@ -1361,7 +1490,7 @@ var marketTools = [
   {
     name: "market_get_symbols",
     title: "Get Spot Symbols",
-    description: "Get complete spot symbol metadata from the configured tenant OpenAPI. Use market_search_symbols for browsing or filtering, because this response may be large.",
+    description: "Get complete spot symbol metadata from the configured tenant OpenAPI. Use market_get_symbol_overview, market_list_symbols, market_search_symbols, or market_get_symbol_info for Agent-facing symbol requests, because this response may be large.",
     cliPath: ["market", "symbols"],
     module: "spot-common",
     access: "public",
@@ -1373,26 +1502,81 @@ var marketTools = [
     validate: (input) => strictObject(input, []),
     handler: (_input, context) => getCachedSymbols(context)
   },
+  {
+    name: "market_get_symbol_overview",
+    title: "Get Spot Symbol Overview",
+    description: "Get a small overview of all configured spot symbols: total count, quote-asset counts, and a bounded sample of display symbols. Use this for generic requests such as listing available trading pairs.",
+    cliPath: ["market", "symbols-overview"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { limit: { type: "integer", minimum: 1, maximum: 20, description: "Number of sample display symbols. Defaults to 12." } }, additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => {
+      const value = strictObject(input, ["limit"]);
+      return { limit: optionalInteger(value, "limit", 12, 1, 20) };
+    },
+    handler: async (input, context) => summarizeSymbolOverview(await getCachedSymbols(context), input)
+  },
+  {
+    name: "market_list_symbols",
+    title: "List Spot Symbols",
+    description: "List one bounded page of configured spot symbols, optionally restricted to a quote asset. This response excludes precision and trading-rule metadata. Use market_get_symbol_info for one exact symbol's rules.",
+    cliPath: ["market", "symbols-list"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { quoteAsset: { type: "string" }, offset: { type: "integer", minimum: 0, description: "Zero-based page offset. Defaults to 0." }, limit: { type: "integer", minimum: 1, maximum: 50, description: "Page size. Defaults to 20." } }, additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => {
+      const value = strictObject(input, ["quoteAsset", "offset", "limit"]);
+      return {
+        quoteAsset: optionalString(value, "quoteAsset"),
+        offset: optionalInteger(value, "offset", 0, 0, Number.MAX_SAFE_INTEGER),
+        limit: optionalInteger(value, "limit", 20, 1, 50)
+      };
+    },
+    handler: async (input, context) => listSymbols(await getCachedSymbols(context), input)
+  },
   {
     name: "market_search_symbols",
     title: "Search Spot Symbols",
-    description: "Search the configured tenant's spot symbols and return a bounded metadata result. In MCP, matching rows are at data.value.items. Use this instead of market_get_symbols unless complete raw metadata is explicitly required.",
+    description: "Search configured spot symbols by a required keyword and return a small matching set without trading-rule metadata. Use market_list_symbols for browsing, or market_get_symbol_info for exact precision and minimum rules.",
     cliPath: ["market", "symbols-search"],
     module: "spot-common",
     access: "public",
     operation: "read",
     riskLevel: "low",
-    inputSchema: { type: "object", properties: { query: { type: "string" }, quoteAsset: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 50 } }, additionalProperties: false },
+    inputSchema: { type: "object", properties: { query: { type: "string", minLength: 1, description: "Required asset or symbol keyword, for example BTC." }, quoteAsset: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, required: ["query"], additionalProperties: false },
     errorCodes: readErrors,
     validate: (input) => {
       const value = strictObject(input, ["query", "quoteAsset", "limit"]);
-      return { query: optionalString(value, "query"), quoteAsset: optionalString(value, "quoteAsset"), limit: optionalInteger(value, "limit", 20, 1, 50) };
+      return { query: requiredString(value, "query"), quoteAsset: optionalString(value, "quoteAsset"), limit: optionalInteger(value, "limit", 10, 1, 20) };
     },
     handler: async (input, context) => {
       const value = input;
-      return summarizeSymbols(await getCachedSymbols(context), value);
+      return searchSymbols(await getCachedSymbols(context), value);
     }
   },
+  {
+    name: "market_get_symbol_info",
+    title: "Get Spot Symbol Information",
+    description: "Get the exact configured spot symbol's trading-rule metadata, including price and quantity precision plus minimum order constraints. Requires an exact symbol such as BTCUSDT or BTC/USDT.",
+    cliPath: ["market", "symbol-info"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { symbol: { type: "string", minLength: 1 } }, required: ["symbol"], additionalProperties: false },
+    errorCodes: symbolReadErrors,
+    validate: (input) => {
+      const value = strictObject(input, ["symbol"]);
+      return { symbol: requiredString(value, "symbol") };
+    },
+    handler: async (input, context) => getSymbolInfo(await getCachedSymbols(context), input.symbol)
+  },
   {
     name: "market_get_ticker",
     title: "Get Spot Ticker",
@@ -2343,7 +2527,7 @@ var ToolRegistry = class {
     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({
+    return await confirmations.prepare({
       action: tool.name,
       payload: preflightInput,
       context: confirmationContext(context),
@@ -2643,10 +2827,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.8" },
+    { name: "ai-hub-agent-trade", version: "0.1.10" },
     {
       capabilities: { tools: {} },
-      instructions: "Every successful read-tool response provides both JSON text and MCP structuredContent 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. Inspect data.dataType before formatting and never assume undocumented nested keys. For symbol lookup, use market_search_symbols. It returns an object whose bounded matches are at data.value.items; the complete raw symbols payload is intentionally unavailable in MCP. For broad market questions, call market_get_ticker_summary, market_get_depth_summary, market_get_trades_summary, or market_get_klines_summary instead of fetching large raw payloads. Account types are fixed: 1=Spot, 2=Isolated Margin, 3=Cross Margin, 4=C2C, 5=Derivatives. Never call account type 2 Derivatives. For Spot to Derivatives, use account_prepare_transfer with fromAccount=EXCHANGE and toAccount=FUTURE. Use wallet_prepare_universal_transfer for margin or C2C; account type 2 requires its isolated-margin trading pair in symbol. 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."
+      instructions: "Every successful read-tool response provides both JSON text and MCP structuredContent 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. Inspect data.dataType before formatting and never assume undocumented nested keys. For a generic trading-pair list, call market_get_symbol_overview first; it returns only counts and a small sample. For paged or quote-asset browsing, use market_list_symbols. Use market_search_symbols only when the user gave a keyword; query is required. Use market_get_symbol_info only for exact precision and minimum rules. Do not use a symbol search as a generic all-symbol list. The complete raw symbols payload is intentionally unavailable in MCP. For broad market questions, call market_get_ticker_summary, market_get_depth_summary, market_get_trades_summary, or market_get_klines_summary instead of fetching large raw payloads. Account types are fixed: 1=Spot, 2=Isolated Margin, 3=Cross Margin, 4=C2C, 5=Derivatives. Never call account type 2 Derivatives. For Spot to Derivatives, use account_prepare_transfer with fromAccount=EXCHANGE and toAccount=FUTURE. Use wallet_prepare_universal_transfer for margin or C2C; account type 2 requires its isolated-margin trading pair in symbol. 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 () => ({
@@ -2694,7 +2878,7 @@ function createServer(profileName, readOnly) {
       }
       const tool = registry.byName(request.params.name, { readOnly });
       if (!isMcpVisible(tool)) {
-        throw new AiHubError("AI_HUB_TOOL_NOT_AVAILABLE", `Tool "${request.params.name}" is not available through MCP. Use market_search_symbols for symbol lookup.`);
+        throw new AiHubError("AI_HUB_TOOL_NOT_AVAILABLE", `Tool "${request.params.name}" is not available through MCP. Use market_get_symbol_overview, market_list_symbols, market_search_symbols, or market_get_symbol_info instead.`);
       }
       const data = await registry.execute(request.params.name, request.params.arguments ?? {}, context, { readOnly });
       return toMcpReadResult(formatMcpData(data));

package/package.json

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