@aihubspot/agent-trade-mcp 0.1.4 → 0.1.6

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.
+- `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.
+
+The raw symbol, ticker, depth, trades, and kline tools remain available only when an exact full payload is explicitly needed. Raw trades and klines are capped at 100 rows by this client.

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,6 +866,246 @@ var assetTools = [
   }
 ];
 
+// ../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);
+    }
+  }
+  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/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 = [
@@ -903,7 +1143,7 @@ var marketTools = [
   {
     name: "market_get_symbols",
     title: "Get Spot Symbols",
-    description: "Get spot symbols from the configured tenant OpenAPI.",
+    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",
@@ -914,10 +1154,30 @@ var marketTools = [
     validate: (input) => strictObject(input, []),
     handler: (_input, context) => context.api.symbols()
   },
+  {
+    name: "market_search_symbols",
+    title: "Search Spot Symbols",
+    description: "Search the configured tenant's spot symbols and return a bounded metadata result. 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 context.api.symbols(), value);
+    }
+  },
   {
     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.",
+    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",
@@ -927,10 +1187,33 @@ var marketTools = [
     errorCodes: readErrors,
     validate: (input) => {
       const value = strictObject(input, ["symbol", "symbols", "timeZone"]);
-      return { symbol: optionalString(value, "symbol"), symbols: optionalString(value, "symbols"), timeZone: optionalString(value, "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",
@@ -951,6 +1234,26 @@ var marketTools = [
       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",
@@ -960,17 +1263,37 @@ var marketTools = [
     access: "public",
     operation: "read",
     riskLevel: "low",
-    inputSchema: { type: "object", properties: { symbol: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 1e3 } }, required: ["symbol"], additionalProperties: false },
+    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", 100, 1, 1e3) };
+      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",
@@ -980,15 +1303,37 @@ var marketTools = [
     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 },
+    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: 100 } }, 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) };
+      return { symbol: requiredString(value, "symbol"), interval: requiredString(value, "interval"), startTime, endTime, timezone: optionalString(value, "timezone"), limit: optionalInteger(value, "limit", 50, 1, 100) };
     },
     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. 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" }, interval: { type: "string" }, startTime: { type: "integer" }, endTime: { type: "integer" }, timezone: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 100 } }, 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", 20, 1, 100) };
+    },
+    handler: async (input, context) => {
+      const value = input;
+      return summarizeKlines(await context.api.klines(value), value.symbol, value.interval);
+    }
   }
 ];
 
@@ -2126,16 +2471,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 +2515,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",
@@ -2177,10 +2543,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.4" },
+    { name: "ai-hub-agent-trade", version: "0.1.6" },
     {
       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 broad market questions, call market_search_symbols, 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 () => ({
@@ -2227,7 +2593,7 @@ function createServer(profileName, readOnly) {
         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: 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.4",
+  "version": "0.1.6",
   "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",