@aihubspot/agent-trade-mcp 0.1.5 → 0.1.7

package/README.md

@@ -25,7 +25,7 @@ Use `spot_prepare_market_buy` or `margin_prepare_market_buy` only with `quoteAmo
 
 Before any order preview, MCP lazily loads `/sapi/v2/symbols` once per local profile and caches the symbol rules in memory for five minutes. Known quantity/price precision and limit-order minimum violations are rejected before confirmation.
 
-## Ticker response
+## Read response
 
 All read tools return `{ "ok": true, "data": ... }` in one of these stable forms:
 
@@ -33,4 +33,16 @@ All read tools return `{ "ok": true, "data": ... }` in one of these stable forms
 - Objects: `{ "dataType": "object", "value": { ... } }`
 - Scalars: `{ "dataType": "scalar", "value": "..." }`
 
-`market_get_ticker` additionally exposes `data.tickers` as an alias of `data.items`. Check `data.dataType` before formatting; do not infer raw OpenAPI nesting.
+MCP clients that support the current protocol also receive the same envelope in `structuredContent`, validated by each read tool's output schema. Check `data.dataType` before formatting; do not infer raw OpenAPI nesting.
+
+## Bounded market analysis
+
+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_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.
+- `market_get_klines_summary`: period change, high/low, latest candle, and up to 100 candles. It defaults to `60min`; formal intervals are `1min`, `5min`, `15min`, `30min`, `60min`, `1day`, `1week`, and `1month`.
+
+The complete raw symbols endpoint is intentionally CLI-only because its payload is too large for Agent contexts. Raw ticker, depth, trades, and kline tools remain available only when an exact payload is explicitly needed. Raw trades are capped at 100 rows; raw klines support the upstream maximum of 300 rows.

package/dist/index.js

@@ -434,8 +434,8 @@ async function normalizeOpenApiBaseUrl(value) {
   if (url.hostname.toLowerCase() === "localhost") {
     throw new AiHubError("AI_HUB_UNSAFE_OPENAPI_URL", "Localhost is not allowed as an OpenAPI base URL.");
   }
-  const records = isIP(url.hostname) ? [{ address: url.hostname }] : await lookup(url.hostname, { all: true, verbatim: true });
-  if (records.length === 0 || records.some((record) => blockedIp(record.address))) {
+  const records2 = isIP(url.hostname) ? [{ address: url.hostname }] : await lookup(url.hostname, { all: true, verbatim: true });
+  if (records2.length === 0 || records2.some((record2) => blockedIp(record2.address))) {
     throw new AiHubError("AI_HUB_UNSAFE_OPENAPI_URL", "OpenAPI base URL must resolve only to public addresses.");
   }
   url.pathname = url.pathname.replace(/\/+$/, "");
@@ -444,10 +444,10 @@ async function normalizeOpenApiBaseUrl(value) {
 function defaultConfig() {
   return { version: 1, default_profile: "default", profiles: {} };
 }
-function parseConfig(text) {
+function parseConfig(text2) {
   let parsed;
   try {
-    parsed = parse(text);
+    parsed = parse(text2);
   } catch (error) {
     throw new AiHubError("AI_HUB_CONFIG_PARSE_ERROR", `Cannot parse config.toml: ${error instanceof Error ? error.message : "unknown error"}`);
   }
@@ -570,11 +570,11 @@ function strictObject(input, allowedKeys) {
   if (!input || typeof input !== "object" || Array.isArray(input)) {
     throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "Tool input must be an object.");
   }
-  const record = input;
-  for (const key of Object.keys(record)) {
+  const record2 = input;
+  for (const key of Object.keys(record2)) {
     if (!allowedKeys.includes(key)) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", `Unknown argument "${key}".`);
   }
-  return record;
+  return record2;
 }
 function requiredString(input, name) {
   const value = input[name];
@@ -866,134 +866,248 @@ 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", "AI_HUB_OPENAPI_BUSINESS_ERROR"];
-var marketTools = [
-  {
-    name: "market_ping",
-    title: "Test OpenAPI Connection",
-    description: "Test the configured tenant OpenAPI connection.",
-    cliPath: ["market", "ping"],
-    module: "spot-common",
-    access: "public",
-    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", "AI_HUB_OPENAPI_BUSINESS_ERROR"],
-    validate: (input) => {
-      strictObject(input, []);
-      return {};
-    },
-    handler: (_input, context) => context.api.ping()
-  },
-  {
-    name: "market_get_server_time",
-    title: "Get Server Time",
-    description: "Get server time from the configured tenant OpenAPI.",
-    cliPath: ["market", "time"],
-    module: "spot-common",
-    access: "public",
-    operation: "read",
-    riskLevel: "low",
-    inputSchema: { type: "object", additionalProperties: false },
-    errorCodes: readErrors,
-    validate: (input) => strictObject(input, []),
-    handler: (_input, context) => context.api.time()
-  },
-  {
-    name: "market_get_symbols",
-    title: "Get Spot Symbols",
-    description: "Get spot symbols from the configured tenant OpenAPI.",
-    cliPath: ["market", "symbols"],
-    module: "spot-common",
-    access: "public",
-    operation: "read",
-    riskLevel: "low",
-    inputSchema: { type: "object", additionalProperties: false },
-    errorCodes: readErrors,
-    validate: (input) => strictObject(input, []),
-    handler: (_input, context) => context.api.symbols()
-  },
-  {
-    name: "market_get_ticker",
-    title: "Get Spot Ticker",
-    description: "Get spot ticker data. Pass symbol or symbols when filtering is needed. The raw OpenAPI response is a ticker array.",
-    cliPath: ["market", "ticker"],
-    module: "spot-common",
-    access: "public",
-    operation: "read",
-    riskLevel: "low",
-    inputSchema: { type: "object", properties: { symbol: { type: "string" }, symbols: { type: "string" }, timeZone: { type: "string" } }, additionalProperties: false },
-    errorCodes: readErrors,
-    validate: (input) => {
-      const value = strictObject(input, ["symbol", "symbols", "timeZone"]);
-      return { symbol: optionalString(value, "symbol"), symbols: optionalString(value, "symbols"), timeZone: optionalString(value, "timeZone") };
-    },
-    handler: (input, context) => context.api.ticker(input)
-  },
-  {
-    name: "market_get_depth",
-    title: "Get Spot Depth",
-    description: "Get the spot order book for one symbol.",
-    cliPath: ["market", "depth"],
-    module: "spot-common",
-    access: "public",
-    operation: "read",
-    riskLevel: "low",
-    inputSchema: { type: "object", properties: { symbol: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 100 } }, required: ["symbol"], additionalProperties: false },
-    errorCodes: readErrors,
-    validate: (input) => {
-      const value = strictObject(input, ["symbol", "limit"]);
-      return { symbol: requiredString(value, "symbol"), limit: optionalInteger(value, "limit", 20, 1, 100) };
-    },
-    handler: (input, context) => {
-      const value = input;
-      return context.api.depth(value.symbol, value.limit);
-    }
-  },
-  {
-    name: "market_get_trades",
-    title: "Get Recent Spot Trades",
-    description: "Get recent spot trades for one symbol.",
-    cliPath: ["market", "trades"],
-    module: "spot-common",
-    access: "public",
-    operation: "read",
-    riskLevel: "low",
-    inputSchema: { type: "object", properties: { symbol: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 1e3 } }, required: ["symbol"], additionalProperties: false },
-    errorCodes: readErrors,
-    validate: (input) => {
-      const value = strictObject(input, ["symbol", "limit"]);
-      return { symbol: requiredString(value, "symbol"), limit: optionalInteger(value, "limit", 100, 1, 1e3) };
-    },
-    handler: (input, context) => {
-      const value = input;
-      return context.api.trades(value.symbol, value.limit);
+// ../core/src/tools/market-summaries.ts
+function record(value, message) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new AiHubError("AI_HUB_OPENAPI_INVALID_RESPONSE", message);
+  }
+  return value;
+}
+function records(value, message) {
+  if (!Array.isArray(value) || value.some((item) => !item || typeof item !== "object" || Array.isArray(item))) {
+    throw new AiHubError("AI_HUB_OPENAPI_INVALID_RESPONSE", message);
+  }
+  return value;
+}
+function text(value) {
+  return value === void 0 || value === null ? null : String(value);
+}
+function finiteNumber(value) {
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function parseDecimal(value) {
+  const match = /^([+-]?)(\d+)(?:\.(\d+))?$/.exec(value);
+  return match ? { sign: match[1] === "-" ? -1n : 1n, whole: match[2] ?? "0", fraction: match[3] ?? "" } : null;
+}
+function formatScaledDecimal(value, scale) {
+  const sign = value < 0n ? "-" : "";
+  const absolute = (value < 0n ? -value : value).toString().padStart(scale + 1, "0");
+  if (!scale) return `${sign}${absolute}`;
+  const whole = absolute.slice(0, -scale);
+  const fraction = absolute.slice(-scale).replace(/0+$/, "");
+  return fraction ? `${sign}${whole}.${fraction}` : `${sign}${whole}`;
+}
+function sumDecimalStrings(values) {
+  const parsed = values.map(parseDecimal).filter((value) => value !== null);
+  if (!parsed.length) return "0";
+  const scale = Math.max(...parsed.map((value) => value.fraction.length));
+  const sum = parsed.reduce((total, value) => total + value.sign * BigInt(`${value.whole}${value.fraction.padEnd(scale, "0")}`), 0n);
+  return formatScaledDecimal(sum, scale);
+}
+function subtractDecimalStrings(left, right) {
+  const leftValue = parseDecimal(left);
+  const rightValue = parseDecimal(right);
+  if (!leftValue || !rightValue) return null;
+  const scale = Math.max(leftValue.fraction.length, rightValue.fraction.length);
+  const toScaled = (value) => value.sign * BigInt(`${value.whole}${value.fraction.padEnd(scale, "0")}`);
+  return formatScaledDecimal(toScaled(leftValue) - toScaled(rightValue), scale);
+}
+function numericMaximum(values, field) {
+  const numbers = values.map((item) => finiteNumber(item[field])).filter((item) => item !== null);
+  return numbers.length ? String(Math.max(...numbers)) : null;
+}
+function numericMinimum(values, field) {
+  const numbers = values.map((item) => finiteNumber(item[field])).filter((item) => item !== null);
+  return numbers.length ? String(Math.min(...numbers)) : null;
+}
+function compareByNumericField(field, direction) {
+  return (left, right) => {
+    const leftValue = finiteNumber(left[field]);
+    const rightValue = finiteNumber(right[field]);
+    if (leftValue === null && rightValue === null) return 0;
+    if (leftValue === null) return 1;
+    if (rightValue === null) return -1;
+    return direction === "asc" ? leftValue - rightValue : rightValue - leftValue;
+  };
+}
+function tickerItem(value) {
+  return {
+    symbol: text(value.symbol),
+    last: text(value.last),
+    rose: text(value.rose),
+    amount: text(value.amount),
+    vol: text(value.vol),
+    high: text(value.high),
+    low: text(value.low),
+    time: text(value.time)
+  };
+}
+function tickerRows(value) {
+  if (Array.isArray(value)) return records(value, "Ticker response must be an array.");
+  const payload = record(value, "Ticker response must be an array.");
+  if (Array.isArray(payload.items)) return records(payload.items, "Ticker response items must be an array.");
+  throw new AiHubError("AI_HUB_OPENAPI_INVALID_RESPONSE", "Ticker response must be an array.");
+}
+function quoteFromSymbol(symbol) {
+  if (!symbol) return null;
+  const parts = symbol.split("/");
+  return parts.length === 2 ? parts[1]?.toUpperCase() ?? null : null;
+}
+function summarizeTickers(value, options) {
+  const quoteAsset = options.quoteAsset.toUpperCase();
+  const rows2 = tickerRows(value).filter((item) => quoteFromSymbol(text(item.symbol)) === quoteAsset);
+  const bySymbol = new Map(rows2.map((item) => [text(item.symbol)?.toUpperCase(), item]));
+  const watchlistSymbols = ["BTC", "ETH", "SOL", "XRP", "DOGE", "BNB", "ADA"];
+  const watchlist = watchlistSymbols.map((asset) => bySymbol.get(`${asset}/${quoteAsset}`)).filter((item) => Boolean(item)).map(tickerItem);
+  const limit = options.limit;
+  return {
+    quoteAsset,
+    totalSymbols: rows2.length,
+    watchlist,
+    topGainers: [...rows2].sort(compareByNumericField("rose", "desc")).slice(0, limit).map(tickerItem),
+    topLosers: [...rows2].sort(compareByNumericField("rose", "asc")).slice(0, limit).map(tickerItem),
+    topByQuoteVolume: [...rows2].sort(compareByNumericField("amount", "desc")).slice(0, limit).map(tickerItem)
+  };
+}
+function summarizeSymbols(value, options) {
+  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;
+    const rank = (item) => {
+      const symbol = (text(item.SymbolName) ?? text(item.symbol) ?? "").toUpperCase();
+      return symbol.startsWith(`${query}/`) ? 0 : symbol.startsWith(query) ? 1 : 2;
+    };
+    return rank(left) - rank(right);
+  });
+  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)
+  }));
+  return {
+    totalSymbols: rows2.length,
+    matchedSymbols: matches.length,
+    quoteAssetCounts: [...quoteAssetCounts.entries()].sort((left, right) => right[1] - left[1]).map(([asset, count]) => ({ asset, count })),
+    items
+  };
+}
+function level(value) {
+  if (!Array.isArray(value)) return { price: null, quantity: null };
+  return { price: text(value[0]), quantity: text(value[1]) };
+}
+function summarizeDepth(value, symbol) {
+  const payload = record(value, "Depth response must be an object.");
+  const bids = Array.isArray(payload.bids) ? payload.bids : [];
+  const asks = Array.isArray(payload.asks) ? payload.asks : [];
+  const bestBid = level(bids[0]);
+  const bestAsk = level(asks[0]);
+  const bidPrice = finiteNumber(bestBid.price);
+  const askPrice = finiteNumber(bestAsk.price);
+  const spread = typeof bestBid.price !== "string" || typeof bestAsk.price !== "string" ? null : subtractDecimalStrings(bestAsk.price, bestBid.price);
+  const midPrice = bidPrice === null || askPrice === null ? null : (askPrice + bidPrice) / 2;
+  return {
+    symbol,
+    time: text(payload.time),
+    bestBid,
+    bestAsk,
+    spread,
+    spreadRatio: spread === null || !midPrice ? null : String(Number(spread) / midPrice),
+    bids: bids.map(level),
+    asks: asks.map(level)
+  };
+}
+function summarizeTrades(value, symbol) {
+  const payload = record(value, "Trades response must be an object.");
+  const rows2 = records(payload.list, "Trades response must contain a list array.");
+  let buyCount = 0;
+  let sellCount = 0;
+  const buyQuantities = [];
+  const sellQuantities = [];
+  for (const item of rows2) {
+    const quantity = text(item.qty);
+    if (text(item.side)?.toUpperCase() === "BUY") {
+      buyCount += 1;
+      if (quantity) buyQuantities.push(quantity);
+    } else if (text(item.side)?.toUpperCase() === "SELL") {
+      sellCount += 1;
+      if (quantity) sellQuantities.push(quantity);
     }
-  },
-  {
-    name: "market_get_klines",
-    title: "Get Spot Klines",
-    description: "Get spot candlestick data for one symbol and interval.",
-    cliPath: ["market", "klines"],
-    module: "spot-common",
-    access: "public",
-    operation: "read",
-    riskLevel: "low",
-    inputSchema: { type: "object", properties: { symbol: { type: "string" }, interval: { type: "string" }, startTime: { type: "integer" }, endTime: { type: "integer" }, timezone: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 1e3 } }, required: ["symbol", "interval"], additionalProperties: false },
-    errorCodes: readErrors,
-    validate: (input) => {
-      const value = strictObject(input, ["symbol", "interval", "startTime", "endTime", "timezone", "limit"]);
-      const startTime = value.startTime === void 0 ? void 0 : optionalInteger(value, "startTime", 0, 0, Number.MAX_SAFE_INTEGER);
-      const endTime = value.endTime === void 0 ? void 0 : optionalInteger(value, "endTime", 0, 0, Number.MAX_SAFE_INTEGER);
-      return { symbol: requiredString(value, "symbol"), interval: requiredString(value, "interval"), startTime, endTime, timezone: optionalString(value, "timezone"), limit: optionalInteger(value, "limit", 100, 1, 1e3) };
-    },
-    handler: (input, context) => context.api.klines(input)
   }
-];
+  return {
+    symbol,
+    count: rows2.length,
+    lastPrice: text(rows2[0]?.price),
+    highPrice: numericMaximum(rows2, "price"),
+    lowPrice: numericMinimum(rows2, "price"),
+    buyCount,
+    sellCount,
+    buyQuantity: sumDecimalStrings(buyQuantities),
+    sellQuantity: sumDecimalStrings(sellQuantities),
+    recentTrades: rows2.map((item) => ({
+      id: text(item.id),
+      side: text(item.side),
+      price: text(item.price),
+      quantity: text(item.qty),
+      time: text(item.time)
+    }))
+  };
+}
+function summarizeKlines(value, symbol, interval) {
+  const rows2 = records(value, "Klines response must be an array.");
+  const newest = rows2[0];
+  const oldest = rows2[rows2.length - 1];
+  const oldestOpen = finiteNumber(oldest?.open);
+  const newestClose = finiteNumber(newest?.close);
+  return {
+    symbol,
+    interval,
+    count: rows2.length,
+    periodOpen: text(oldest?.open),
+    latestClose: text(newest?.close),
+    changeRatio: oldestOpen === null || !oldestOpen || newestClose === null ? null : String((newestClose - oldestOpen) / oldestOpen),
+    high: numericMaximum(rows2, "high"),
+    low: numericMinimum(rows2, "low"),
+    latestCandle: newest ? {
+      time: text(newest.idx),
+      open: text(newest.open),
+      close: text(newest.close),
+      high: text(newest.high),
+      low: text(newest.low),
+      volume: text(newest.vol)
+    } : null,
+    candles: rows2.map((item) => ({
+      time: text(item.idx),
+      open: text(item.open),
+      close: text(item.close),
+      high: text(item.high),
+      low: text(item.low),
+      volume: text(item.vol)
+    }))
+  };
+}
 
 // ../core/src/tools/symbol-rules.ts
-var CACHE_TTL_MS = 5 * 60 * 1e3;
+var CACHE_TTL_MS = 60 * 60 * 1e3;
 var cache = /* @__PURE__ */ new Map();
 var pendingLoads = /* @__PURE__ */ new Map();
 function cacheKey(context) {
@@ -1037,22 +1151,25 @@ function parseRules(response) {
   }
   return result2;
 }
-async function loadRules(context) {
+async function loadSnapshot(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 };
+    const entry = { response, 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 getCachedSymbols(context) {
+  return (await loadSnapshot(context)).response;
+}
 async function getSymbolRule(context, symbol) {
-  const entry = await loadRules(context);
+  const entry = await loadSnapshot(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;
@@ -1108,6 +1225,269 @@ async function preflightSymbolOrder(context, order) {
   return rule;
 }
 
+// ../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 KLINE_INTERVALS = ["1min", "5min", "15min", "30min", "60min", "1day", "1week", "1month"];
+var KLINE_INTERVAL_ALIASES = {
+  "1m": "1min",
+  "5m": "5min",
+  "15m": "15min",
+  "30m": "30min",
+  "60m": "60min",
+  "1h": "60min",
+  "1d": "1day",
+  "1w": "1week",
+  "1mo": "1month",
+  "1M": "1month"
+};
+var klineIntervalDescription = "Kline interval. Supported values: 1min, 5min, 15min, 30min, 60min, 1day, 1week, 1month. Use 60min, not 1h.";
+var klineTimezoneDescription = "Optional timezone such as UTC+08 or UTC-09. Defaults to UTC+08. The upstream API applies timezone-specific data only to periods above 60min.";
+function normalizeKlineInterval(value) {
+  const trimmed = value.trim();
+  const normalized = KLINE_INTERVAL_ALIASES[trimmed] ?? trimmed.toLowerCase();
+  if (KLINE_INTERVALS.includes(normalized)) return normalized;
+  throw new AiHubError("AI_HUB_INVALID_ARGUMENT", `interval must be one of: ${KLINE_INTERVALS.join(", ")}. Use 60min, not 1h.`);
+}
+function validateKlineInput(input, options) {
+  const value = strictObject(input, ["symbol", "interval", "startTime", "endTime", "timezone", "limit"]);
+  const startTime = value.startTime === void 0 ? void 0 : optionalInteger(value, "startTime", 0, 0, Number.MAX_SAFE_INTEGER);
+  const endTime = value.endTime === void 0 ? void 0 : optionalInteger(value, "endTime", 0, 0, Number.MAX_SAFE_INTEGER);
+  if (startTime !== void 0 && endTime !== void 0 && startTime > endTime) {
+    throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "startTime must be less than or equal to endTime.");
+  }
+  return {
+    symbol: requiredString(value, "symbol"),
+    interval: value.interval === void 0 && options.summary ? "60min" : normalizeKlineInterval(requiredString(value, "interval")),
+    startTime,
+    endTime,
+    timezone: optionalString(value, "timezone"),
+    limit: optionalInteger(value, "limit", options.summary ? 20 : 50, 1, options.summary ? 100 : 300)
+  };
+}
+var marketTools = [
+  {
+    name: "market_ping",
+    title: "Test OpenAPI Connection",
+    description: "Test the configured tenant OpenAPI connection.",
+    cliPath: ["market", "ping"],
+    module: "spot-common",
+    access: "public",
+    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", "AI_HUB_OPENAPI_BUSINESS_ERROR"],
+    validate: (input) => {
+      strictObject(input, []);
+      return {};
+    },
+    handler: (_input, context) => context.api.ping()
+  },
+  {
+    name: "market_get_server_time",
+    title: "Get Server Time",
+    description: "Get server time from the configured tenant OpenAPI.",
+    cliPath: ["market", "time"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => strictObject(input, []),
+    handler: (_input, context) => context.api.time()
+  },
+  {
+    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.",
+    cliPath: ["market", "symbols"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    mcpVisible: false,
+    inputSchema: { type: "object", additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => strictObject(input, []),
+    handler: (_input, context) => getCachedSymbols(context)
+  },
+  {
+    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.",
+    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 },
+    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) };
+    },
+    handler: async (input, context) => {
+      const value = input;
+      return summarizeSymbols(await getCachedSymbols(context), value);
+    }
+  },
+  {
+    name: "market_get_ticker",
+    title: "Get Spot Ticker",
+    description: "Get exact raw spot ticker data for one symbol or an explicitly requested symbol list. For an all-market overview, use market_get_ticker_summary instead.",
+    cliPath: ["market", "ticker"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { symbol: { type: "string" }, symbols: { type: "string" }, timeZone: { type: "string" } }, additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => {
+      const value = strictObject(input, ["symbol", "symbols", "timeZone"]);
+      const symbol = optionalString(value, "symbol");
+      const symbols = optionalString(value, "symbols");
+      if (!symbol && !symbols) throw new AiHubError("AI_HUB_INVALID_ARGUMENT", "market_get_ticker requires symbol or symbols. Use market_get_ticker_summary for all-market data.");
+      return { symbol, symbols, timeZone: optionalString(value, "timeZone") };
+    },
+    handler: (input, context) => context.api.ticker(input)
+  },
+  {
+    name: "market_get_ticker_summary",
+    title: "Get Spot Market Summary",
+    description: "Return a bounded all-market overview: a core-asset watchlist plus gainers, losers, and quote-volume leaders. Use this for requests such as market ticker, market overview, movers, or most-active symbols.",
+    cliPath: ["market", "ticker-summary"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { quoteAsset: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => {
+      const value = strictObject(input, ["quoteAsset", "limit"]);
+      return { quoteAsset: optionalString(value, "quoteAsset") ?? "USDT", limit: optionalInteger(value, "limit", 5, 1, 20) };
+    },
+    handler: async (input, context) => {
+      const value = input;
+      return summarizeTickers(await context.api.ticker(), value);
+    }
+  },
+  {
+    name: "market_get_depth",
+    title: "Get Spot Depth",
+    description: "Get the spot order book for one symbol.",
+    cliPath: ["market", "depth"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { symbol: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 100 } }, required: ["symbol"], additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => {
+      const value = strictObject(input, ["symbol", "limit"]);
+      return { symbol: requiredString(value, "symbol"), limit: optionalInteger(value, "limit", 20, 1, 100) };
+    },
+    handler: (input, context) => {
+      const value = input;
+      return context.api.depth(value.symbol, value.limit);
+    }
+  },
+  {
+    name: "market_get_depth_summary",
+    title: "Get Spot Order Book Summary",
+    description: "Get a bounded order-book view with best bid, best ask, spread, and requested levels. Prefer this to market_get_depth for Agent analysis.",
+    cliPath: ["market", "depth-summary"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { symbol: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, required: ["symbol"], additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => {
+      const value = strictObject(input, ["symbol", "limit"]);
+      return { symbol: requiredString(value, "symbol"), limit: optionalInteger(value, "limit", 10, 1, 20) };
+    },
+    handler: async (input, context) => {
+      const value = input;
+      return summarizeDepth(await context.api.depth(value.symbol, value.limit), value.symbol);
+    }
+  },
+  {
+    name: "market_get_trades",
+    title: "Get Recent Spot Trades",
+    description: "Get recent spot trades for one symbol.",
+    cliPath: ["market", "trades"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { symbol: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 100 } }, required: ["symbol"], additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => {
+      const value = strictObject(input, ["symbol", "limit"]);
+      return { symbol: requiredString(value, "symbol"), limit: optionalInteger(value, "limit", 20, 1, 100) };
+    },
+    handler: (input, context) => {
+      const value = input;
+      return context.api.trades(value.symbol, value.limit);
+    }
+  },
+  {
+    name: "market_get_trades_summary",
+    title: "Get Recent Spot Trades Summary",
+    description: "Get a bounded recent-trades view with price range, buy/sell counts and quantities, plus the requested recent sample. Prefer this to market_get_trades for Agent analysis.",
+    cliPath: ["market", "trades-summary"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { symbol: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 50 } }, required: ["symbol"], additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => {
+      const value = strictObject(input, ["symbol", "limit"]);
+      return { symbol: requiredString(value, "symbol"), limit: optionalInteger(value, "limit", 20, 1, 50) };
+    },
+    handler: async (input, context) => {
+      const value = input;
+      return summarizeTrades(await context.api.trades(value.symbol, value.limit), value.symbol);
+    }
+  },
+  {
+    name: "market_get_klines",
+    title: "Get Spot Klines",
+    description: "Get raw spot candlestick data for one symbol and a supported interval. Use market_get_klines_summary for Agent analysis.",
+    cliPath: ["market", "klines"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { symbol: { type: "string", description: "Spot symbol, for example ETHUSDT or ETH/USDT." }, interval: { type: "string", enum: KLINE_INTERVALS, description: klineIntervalDescription }, startTime: { type: "integer", description: "Optional inclusive Unix timestamp in milliseconds." }, endTime: { type: "integer", description: "Optional inclusive Unix timestamp in milliseconds." }, timezone: { type: "string", description: klineTimezoneDescription }, limit: { type: "integer", minimum: 1, maximum: 300, description: "Number of newest-first candles. The upstream maximum is 300." } }, required: ["symbol", "interval"], additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => {
+      return validateKlineInput(input, { summary: false });
+    },
+    handler: (input, context) => context.api.klines(input)
+  },
+  {
+    name: "market_get_klines_summary",
+    title: "Get Spot Klines Summary",
+    description: "Get a bounded candle analysis with period change, high/low, latest candle, and a caller-limited candle sample. Defaults to 60min. Prefer this to market_get_klines for Agent analysis.",
+    cliPath: ["market", "klines-summary"],
+    module: "spot-common",
+    access: "public",
+    operation: "read",
+    riskLevel: "low",
+    inputSchema: { type: "object", properties: { symbol: { type: "string", description: "Spot symbol, for example ETHUSDT or ETH/USDT." }, interval: { type: "string", enum: KLINE_INTERVALS, description: `${klineIntervalDescription} Defaults to 60min when omitted.` }, startTime: { type: "integer", description: "Optional inclusive Unix timestamp in milliseconds." }, endTime: { type: "integer", description: "Optional inclusive Unix timestamp in milliseconds." }, timezone: { type: "string", description: klineTimezoneDescription }, limit: { type: "integer", minimum: 1, maximum: 100, description: "Number of candles included in the bounded analysis." } }, required: ["symbol"], additionalProperties: false },
+    errorCodes: readErrors,
+    validate: (input) => {
+      return validateKlineInput(input, { summary: true });
+    },
+    handler: async (input, context) => {
+      const value = input;
+      return summarizeKlines(await context.api.klines(value), value.symbol, value.interval);
+    }
+  }
+];
+
 // ../core/src/tools/margin-tools.ts
 function validateMarginSemanticOrder(input) {
   const value = strictObject(input, ["symbol", "side", "type", "quoteAmount", "baseQuantity", "price", "newClientOrderId", "isolated"]);
@@ -2126,16 +2506,36 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 var CAPABILITIES_TOOL = "system_get_capabilities";
 var CONFIRM_ACTION_TOOL = "confirm_action";
+var READ_RESULT_OUTPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    ok: { type: "boolean", const: true },
+    data: {
+      type: "object",
+      properties: {
+        dataType: { type: "string", enum: ["array", "object", "scalar", "null"] },
+        items: { type: "array" },
+        count: { type: "integer", minimum: 0 },
+        value: {}
+      },
+      required: ["dataType"]
+    }
+  },
+  required: ["ok", "data"]
+};
 function result(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
-function formatMcpData(toolName, data) {
+function toMcpReadResult(data) {
+  const payload = { ok: true, data };
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], structuredContent: payload };
+}
+function formatMcpData(data) {
   if (Array.isArray(data)) {
     return {
       dataType: "array",
       items: data,
-      count: data.length,
-      ...toolName === "market_get_ticker" ? { tickers: data } : {}
+      count: data.length
     };
   }
   if (data === null || data === void 0) return { dataType: "null", value: null };
@@ -2150,8 +2550,9 @@ function toMcpTool(tool) {
   return {
     name: tool.name,
     title: tool.title,
-    description: `${tool.description}${tool.operation === "read" ? " Successful MCP output is always { ok: true, data: ... }. For list results, use data.items and data.count (market_get_ticker also provides data.tickers); for object results, use data.value. Check data.dataType before formatting." : ""}`,
+    description: `${tool.description}${tool.operation === "read" ? " Successful MCP output is structured as { ok: true, data: ... }. For list results, use data.items and data.count; for object results, use data.value. Check data.dataType before formatting." : ""}`,
     inputSchema: tool.inputSchema,
+    ...tool.operation === "read" ? { outputSchema: READ_RESULT_OUTPUT_SCHEMA } : {},
     annotations: {
       readOnlyHint: tool.operation === "read",
       destructiveHint: tool.riskLevel === "high",
@@ -2160,6 +2561,9 @@ function toMcpTool(tool) {
     }
   };
 }
+function isMcpVisible(tool) {
+  return tool.mcpVisible !== false;
+}
 function prepareToolName(tool) {
   const [prefix, ...rest] = tool.name.split("_");
   return `${prefix ?? "spot"}_prepare_${rest.join("_")}`;
@@ -2177,10 +2581,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.5" },
+    { name: "ai-hub-agent-trade", version: "0.1.7" },
     {
       capabilities: { tools: {} },
-      instructions: "Every successful tool response is JSON text in the envelope { ok: true, data: ... }. All read-tool data is normalized: dataType=array means use data.items and data.count; dataType=object or scalar means use data.value; dataType=null means no value. market_get_ticker also provides data.tickers as an alias of data.items. Inspect data.dataType before formatting and never assume undocumented nested keys. Prepare/confirm tools return their documented action payload directly in data. For every state-changing action, call only a spot_prepare_* or margin_prepare_* tool first and show its exact summary to the user. Stop and wait for a new, explicit user confirmation message. Only then call confirm_action with that new message verbatim in userConfirmation. Never call prepare and confirm consecutively for one user instruction; never infer confirmation from prior intent, silence, or an Agent-generated message. For spot and margin orders, MARKET BUY always uses quoteAmount (the quote asset to spend); MARKET SELL uses baseQuantity (the base asset to sell). Never reinterpret a requested base quantity as quoteAmount."
+      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. 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 () => ({
@@ -2192,7 +2596,7 @@ function createServer(profileName, readOnly) {
         inputSchema: { type: "object", additionalProperties: false },
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
       },
-      ...registry.list({ readOnly }).flatMap((tool) => tool.operation === "write" ? [toPrepareMcpTool(tool)] : [toMcpTool(tool)]),
+      ...registry.list({ readOnly }).filter(isMcpVisible).flatMap((tool) => tool.operation === "write" ? [toPrepareMcpTool(tool)] : [toMcpTool(tool)]),
       ...readOnly ? [] : [{
         name: CONFIRM_ACTION_TOOL,
         title: "Confirm Prepared Action",
@@ -2211,7 +2615,7 @@ function createServer(profileName, readOnly) {
           data: {
             profile: { name: context.profile.name, host: new URL(context.profile.openApiBaseUrl).host, configVersion: context.profile.configVersion },
             readOnly,
-            capabilities: registry.capabilities(context, { readOnly })
+            capabilities: registry.capabilities(context, { readOnly }).filter((capability) => isMcpVisible(registry.byName(capability.name)))
           }
         });
       }
@@ -2222,12 +2626,16 @@ function createServer(profileName, readOnly) {
         }
         return result({ ok: true, data: await writeExecutor.confirm(input.confirmationId, input.userConfirmation, context) });
       }
-      const preparedTool = registry.list({ readOnly: false }).find((tool) => tool.operation === "write" && prepareToolName(tool) === request.params.name);
+      const preparedTool = registry.list({ readOnly: false }).find((tool2) => tool2.operation === "write" && prepareToolName(tool2) === request.params.name);
       if (preparedTool) {
         return result({ ok: true, data: await writeExecutor.prepare(preparedTool.name, request.params.arguments ?? {}, context) });
       }
+      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.`);
+      }
       const data = await registry.execute(request.params.name, request.params.arguments ?? {}, context, { readOnly });
-      return result({ ok: true, data: formatMcpData(request.params.name, data) });
+      return toMcpReadResult(formatMcpData(data));
     } catch (error) {
       return toMcpErrorResult(error);
     }

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@aihubspot/agent-trade-mcp",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Local stdio MCP server for AI Hub spot trading tools",
   "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/exhcange/ai-hub-agent-trade",
+    "directory": "packages/mcp"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",