hchain-mcp 1.0.0

package/src/tools/trade.ts

@@ -0,0 +1,197 @@
+/**
+ * Trade 模块 — CAT:[链上-Swap]
+ * DEX 聚合器经典兑换: 8 tools, 参数来源官方 API 参考
+ */
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { tradeApi } from "../adapters/onchainos.js";
+import { toResult, toError, AUTH_REQUIRED } from "../adapters/shared.js";
+import type { Auth } from "../adapters/shared.js";
+
+export function registerTradeTools(server: McpServer, auth: Auth | null): void {
+
+  server.tool("onchainos_dex_supported_chain",
+    "CAT:[链上-Swap] | ## 功能: 获取 DEX 聚合器支持的链, 返回 chainIndex/chainName/dexTokenApproveAddress\n## 场景: 兑换前确认链 + 获取 DEX Router 授权地址\n## 关键词: DEX, 链列表, chainIndex, router, approve\n## 参数:\n##   - chainIndex: 可选过滤\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~2KB\n## 关联: dexTokenApproveAddress -> onchainos_dex_approve_transaction",
+    { chainIndex: z.string().optional().describe("链索引, 可选过滤。不传返回所有链") },
+    { readOnlyHint: true },
+    async ({ chainIndex }) => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await tradeApi.supportedChain(auth, chainIndex)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_dex_all_tokens",
+    "CAT:[链上-Swap] | ## 功能: 获取链上 DEX 可交易代币列表, 返回 decimals/tokenContractAddress/tokenName/tokenSymbol/tokenLogoUrl\n## 场景: 查找代币合约地址和精度\n## 关键词: 代币列表, tokens, decimals\n## 参数:\n##   - chainIndex: 链索引(必填)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 大 ~100KB\n## 关联: onchainos_dex_supported_chain -> 本工具 -> onchainos_dex_quote",
+    { chainIndex: z.string().describe("链索引。'1'=ETH '56'=BSC '137'=Polygon '8453'=Base '501'=Solana '784'=Sui") },
+    { readOnlyHint: true },
+    async ({ chainIndex }) => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await tradeApi.allTokens(auth, chainIndex)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_dex_liquidity",
+    "CAT:[链上-Swap] | ## 功能: 获取链上流动性源列表, 返回 id/name/logo\n## 场景: 了解 DEX 覆盖范围, 用于 quote 的 dexIds/excludeDexIds 参数\n## 关键词: 流动性, liquidity, DEX列表, dexId\n## 参数:\n##   - chainIndex: 链索引(必填)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~10KB\n## 关联: 本工具选流动性 -> onchainos_dex_quote (传 dexIds/excludeDexIds)",
+    { chainIndex: z.string().describe("链索引") },
+    { readOnlyHint: true },
+    async ({ chainIndex }) => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await tradeApi.liquidity(auth, chainIndex)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_dex_quote",
+    "CAT:[链上-Swap] | ## 功能: 获取最优兑换报价, 返回 toTokenAmount/priceImpactPercent/dexRouterList/estimateGasFee/tradeFee\n## 场景: 交易前比价。返回 fromToken/toToken 含 isHoneyPot(貔貅检测)/taxRate(税率)\n## 关键词: 报价, quote, 价格影响, 路由, swapMode, exactIn, exactOut\n## 参数:\n##   - chainIndex/amount/fromTokenAddress/toTokenAddress(必填)\n##   - swapMode: exactIn(默认)/exactOut(必填)\n##   - dexIds/excludeDexIds: 流动性过滤(可选)\n##   - priceImpactProtectionPercent: 价格影响保护(可选, 默认90%)\n##   - feePercent/directRoute/singleRouteOnly/singlePoolPerHop/assetAwareRouting(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~10KB\n## 关联: onchainos_dex_all_tokens -> 本工具 -> onchainos_dex_swap / onchainos_dex_approve_transaction",
+    {
+      chainIndex: z.string().describe("链索引"),
+      amount: z.string().describe("交易数量, 含精度(最小单位)。如 1 USDT=1000000, 1 DAI=1000000000000000000"),
+      swapMode: z.enum(["exactIn","exactOut"]).optional().default("exactIn").describe("exactIn=按卖出数量报价 exactOut=按买入数量报价。exactOut仅ETH/Base/BSC/Arbitrum支持UniV2/V3"),
+      fromTokenAddress: z.string().describe("卖出代币合约地址"),
+      toTokenAddress: z.string().describe("买入代币合约地址"),
+      dexIds: z.string().optional().describe("限定流动性池 dexId, 逗号分隔。从 onchainos_dex_liquidity 获取"),
+      excludeDexIds: z.string().optional().describe("排除流动性池 dexId, 逗号分隔"),
+      priceImpactProtectionPercent: z.string().optional().describe("价格影响保护百分比(0-100)。超此值报价被拒。默认90, 设100禁用"),
+      feePercent: z.string().optional().describe("分佣百分比。Solana最大10%,其他链最大3%"),
+      excludePoolAddresses: z.string().optional().describe("过滤池子地址, 逗号分隔, 最多20个"),
+      directRoute: z.boolean().optional().describe("true=限制单一流动性池。仅Solana"),
+      singleRouteOnly: z.boolean().optional().describe("true=单路径(允许多跳多池,不并行)"),
+      singlePoolPerHop: z.boolean().optional().describe("true=每跳单池"),
+      assetAwareRouting: z.boolean().optional().describe("true=仅使用匹配资产类型的路由(U-U/U-Native)"),
+      forJitoBundle: z.boolean().optional().describe("true=排除不兼容Jito的DEX"),
+    },
+    { readOnlyHint: true },
+    async (params) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try {
+        const q: Record<string, string> = {};
+        for (const [k, v] of Object.entries(params)) { if (v !== undefined) q[k] = typeof v === "boolean" ? String(v) : v; }
+        return toResult(await tradeApi.quote(auth, q), {
+          nextSteps: [
+            { action: "如为ERC20, 先授权", tool: "onchainos_dex_approve_transaction", condition: "非原生代币需要" },
+            { action: "构建兑换交易", tool: "onchainos_dex_swap" },
+          ],
+        });
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_dex_approve_transaction",
+    "CAT:[链上-Swap] | ## 功能: 构建 ERC-20 授权交易 calldata, 返回 data/dexContractAddress/gasLimit/gasPrice\n## 场景: ERC20 Swap 前授权 DEX Router 动用代币\n## 关键词: approve, 授权, ERC20, calldata, dexContractAddress\n## 参数:\n##   - chainIndex/tokenContractAddress/approveAmount(必填)\n## 鉴权: 需要 API Key(交易)\n## 风险: WRITE - 返回 calldata\n## 返回量: 微小 ~1KB\n## 关联: onchainos_dex_quote -> 本工具 -> onchainos_gateway_broadcast",
+    {
+      chainIndex: z.string().describe("链索引"),
+      tokenContractAddress: z.string().describe("代币合约地址"),
+      approveAmount: z.string().describe("授权数量, 含精度。如授权1 USDT=1000000, 1 DAI=1000000000000000000"),
+    },
+    { destructiveHint: true, idempotentHint: true },
+    async ({ chainIndex, tokenContractAddress, approveAmount }) => {
+      if(!auth) return AUTH_REQUIRED("TRADE");
+      try {
+        return toResult(await tradeApi.approveTransaction(auth, chainIndex, tokenContractAddress, approveAmount), {
+          nextSteps: [{ action: "签名后广播", tool: "onchainos_gateway_broadcast" }],
+        });
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_dex_swap",
+    "CAT:[链上-Swap] | ## 功能: 构建兑换交易 calldata, 返回 tx(from/to/data/value/gas/gasPrice/maxPriorityFeePerGas/minReceiveAmount/maxSpendAmount/signatureData)\n## 场景: 授权后构建 swap。approveTransaction=true可一并返回授权calldata省去单独调approve\n## 关键词: swap, 兑换, calldata, 交易构建, MEV, Jito\n## 参数:\n##   - chainIndex/amount/fromTokenAddress/toTokenAddress/userWalletAddress/slippagePercent(必填)\n##   - swapMode/approveTransaction/approveAmount/feePercent/swapReceiverAddress(可选)\n##   - autoSlippage/maxAutoslippagePercent/priceImpactProtectionPercent(可选)\n##   - dexIds/excludeDexIds/excludePoolAddresses/disableRFQ/directRoute(可选)\n##   - computeUnitPrice/computeUnitLimit/tips: Solana参数(可选)\n##   - gaslimit/gasLevel: EVM gas参数(可选)\n##   - positiveSlippagePercent/positiveSlippageFeeAddress: 正滑点分佣(可选,白名单)\n## 鉴权: 需要 API Key(交易)\n## 风险: WRITE - 返回 calldata\n## 返回量: 中等 ~5KB\n## 关联: onchainos_dex_quote -> 本工具 -> onchainos_gateway_simulate -> onchainos_gateway_broadcast",
+    {
+      chainIndex: z.string().describe("链索引"),
+      amount: z.string().describe("交易数量, 含精度(最小单位)。如1 USDT=1000000"),
+      swapMode: z.enum(["exactIn","exactOut"]).optional().default("exactIn").describe("exactIn=按卖出 exactOut=按买入(仅ETH/Base/BSC/Arbitrum的UniV2/V3支持)"),
+      fromTokenAddress: z.string().describe("卖出代币地址"),
+      toTokenAddress: z.string().describe("买入代币地址"),
+      userWalletAddress: z.string().describe("用户钱包地址"),
+      slippagePercent: z.string().describe("滑点百分比。EVM:0-100, Solana:0-<100"),
+      approveTransaction: z.boolean().optional().describe("true=一并返回授权calldata(signatureData), 省去单独调approve"),
+      approveAmount: z.string().optional().describe("授权数量, 含精度。approveTransaction=true时使用"),
+      autoSlippage: z.boolean().optional().describe("true=自动滑点覆盖slippagePercent"),
+      maxAutoslippagePercent: z.string().optional().describe("自动滑点上限百分比"),
+      feePercent: z.string().optional().describe("分佣百分比。Solana最大10%, 其他链最大3%"),
+      fromTokenReferrerWalletAddress: z.string().optional().describe("fromToken分佣地址"),
+      toTokenReferrerWalletAddress: z.string().optional().describe("toToken分佣地址"),
+      swapReceiverAddress: z.string().optional().describe("接收代币地址, 默认=userWalletAddress"),
+      priceImpactProtectionPercent: z.string().optional().describe("价格影响保护(0-100,默认90)"),
+      dexIds: z.string().optional().describe("限定流动性池,逗号分隔"),
+      excludeDexIds: z.string().optional().describe("排除流动性池,逗号分隔"),
+      excludePoolAddresses: z.string().optional().describe("过滤池子地址,逗号分隔,最多20"),
+      disableRFQ: z.boolean().optional().describe("true=禁用RFQ"),
+      directRoute: z.boolean().optional().describe("true=单跳模式。Solana和EVM均支持"),
+      singleRouteOnly: z.boolean().optional().describe("true=单路径(允许多跳多池)"),
+      singlePoolPerHop: z.boolean().optional().describe("true=每跳单池"),
+      assetAwareRouting: z.boolean().optional().describe("true=仅匹配资产类型的路由"),
+      gaslimit: z.string().optional().describe("EVM gas限额(wei)。过低会导致报价失败"),
+      gasLevel: z.enum(["average","fast","slow"]).optional().describe("EVM gas等级,默认average"),
+      computeUnitPrice: z.string().optional().describe("Solana compute unit price"),
+      computeUnitLimit: z.string().optional().describe("Solana compute unit limit"),
+      tips: z.string().optional().describe("Jito tips(SOL)。0.0000000001~2。指定后signatureData返回Jito转账calldata"),
+      forJitoBundle: z.boolean().optional().describe("true=排除不兼容Jito的DEX"),
+      positiveSlippagePercent: z.string().optional().describe("正滑点分佣比例(0-10,白名单)"),
+      positiveSlippageFeeAddress: z.string().optional().describe("正滑点分佣地址(白名单)"),
+      callDataMemo: z.string().optional().describe("自定义calldata上链数据(64bytes hex,如'0x...')"),
+      maxCalldataSize: z.string().optional().describe("最大calldata大小估计值"),
+      maxAccounts: z.string().optional().describe("最大账户数估计值"),
+    },
+    { destructiveHint: true },
+    async (params) => {
+      if(!auth) return AUTH_REQUIRED("TRADE");
+      try {
+        const q: Record<string, string> = {};
+        for (const [k, v] of Object.entries(params)) { if (v !== undefined) q[k] = typeof v === "boolean" ? String(v) : v; }
+        return toResult(await tradeApi.swap(auth, q), {
+          nextSteps: [
+            { action: "如有 signatureData, 先执行授权 calldata", tool: "onchainos_gateway_broadcast", condition: "signatureData 存在时包含 approveContract+approveTxCalldata" },
+            { action: "模拟交易", tool: "onchainos_gateway_simulate", condition: "广播前建议模拟" },
+            { action: "签名后广播", tool: "onchainos_gateway_broadcast" },
+            { action: "查交易状态", tool: "onchainos_dex_swap_history" },
+          ],
+        });
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_dex_swap_instruction",
+    "CAT:[链上-Swap] | ## 功能: 获取 Solana 兑换指令(高级), 返回 instructionLists/addressLookupTableAccount/tx/routerResult\n## 场景: Solana 自定义交易组装, 可加自己的指令\n## 关键词: Solana, swap instruction, 高级, lookup table\n## 参数:\n##   - chainIndex/amount/fromTokenAddress/toTokenAddress/userWalletAddress/slippagePercent(必填)\n##   - autoSlippage/maxAutoSlippagePercent/feePercent/useTokenLedger/swapReceiverAddress(可选)\n##   - priceImpactProtectionPercent/dexIds/excludeDexIds/disableRFQ/directRoute(可选)\n##   - computeUnitPrice/computeUnitLimit: Solana gas(可选)\n##   - positiveSlippagePercent/positiveSlippageFeeAddress: 正滑点分佣(可选,白名单)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 大 ~30KB\n## 关联: Solana场景: onchainos_dex_quote -> 本工具 -> 自行签名广播",
+    {
+      chainIndex: z.string().describe("Solana固定'501'"),
+      amount: z.string().describe("卖出数量, 含精度"),
+      fromTokenAddress: z.string().describe("卖出代币Mint地址"),
+      toTokenAddress: z.string().describe("买入代币Mint地址"),
+      userWalletAddress: z.string().describe("Solana钱包地址"),
+      slippagePercent: z.string().describe("滑点百分比。Solana:0-<100"),
+      autoSlippage: z.boolean().optional().describe("true=自动滑点"),
+      maxAutoSlippagePercent: z.string().optional().describe("自动滑点上限"),
+      feePercent: z.string().optional().describe("分佣百分比。Solana最大10%"),
+      fromTokenReferrerWalletAddress: z.string().optional().describe("fromToken分佣地址"),
+      toTokenReferrerWalletAddress: z.string().optional().describe("toToken分佣地址"),
+      swapReceiverAddress: z.string().optional().describe("接收代币地址"),
+      useTokenLedger: z.boolean().optional().describe("true=执行前记录代币余额"),
+      priceImpactProtectionPercent: z.string().optional().describe("价格影响保护(0-100)"),
+      dexIds: z.string().optional().describe("限定流动性池,逗号分隔"),
+      excludeDexIds: z.string().optional().describe("排除流动性池,逗号分隔"),
+      disableRFQ: z.boolean().optional().describe("true=禁用RFQ"),
+      directRoute: z.boolean().optional().describe("true=单池路由。仅Solana"),
+      computeUnitPrice: z.string().optional().describe("Solana compute unit price"),
+      computeUnitLimit: z.string().optional().describe("Solana compute unit limit"),
+      positiveSlippagePercent: z.string().optional().describe("正滑点分佣比例(0-10,白名单)"),
+      positiveSlippageFeeAddress: z.string().optional().describe("正滑点分佣地址"),
+      forJitoBundle: z.boolean().optional().describe("true=排除不兼容Jito的DEX"),
+      excludePoolAddresses: z.string().optional().describe("过滤池子地址,逗号分隔,最多20"),
+    },
+    { readOnlyHint: true },
+    async (params) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try {
+        const q: Record<string, string> = {};
+        for (const [k, v] of Object.entries(params)) { if (v !== undefined) q[k] = typeof v === "boolean" ? String(v) : v; }
+        return toResult(await tradeApi.swapInstruction(auth, q));
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_dex_swap_history",
+    "CAT:[链上-Swap] | ## 功能: 查询兑换交易详情(状态/fromToken/toToken/txFee)\n## 场景: 广播后确认交易状态\n## 关键词: swap history, 交易状态, txHash\n## 参数:\n##   - chainIndex: 链索引(必填)\n##   - txHash: 交易哈希(必填)\n##   - isFromMyProject: 是否本项目(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~2KB\n## 关联: onchainos_gateway_broadcast -> 本工具",
+    {
+      chainIndex: z.string().describe("链索引"),
+      txHash: z.string().describe("交易哈希"),
+      isFromMyProject: z.boolean().optional().describe("true=仅查本API Key订单 false=查任意OKX DEX订单"),
+    },
+    { readOnlyHint: true },
+    async ({ chainIndex, txHash, isFromMyProject }) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try { return toResult(await tradeApi.swapHistory(auth, chainIndex, txHash, isFromMyProject)); } catch(e) { return toError(e); }
+    },
+  );
+
+}

package/src/tools/txhistory.ts

@@ -0,0 +1,51 @@
+/**
+ * 交易历史模块 — CAT:[链上-账户]
+ * 按官方文档逐端点对接
+ */
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { postTxApi } from "../adapters/onchainos.js";
+import { toResult, toError, AUTH_REQUIRED } from "../adapters/shared.js";
+import type { Auth } from "../adapters/shared.js";
+
+export function registerTxHistoryTools(server: McpServer, auth: Auth | null): void {
+
+  server.tool("onchainos_tx_history_supported_chain",
+    "CAT:[链上-账户] | ## 功能: 获取交易历史 API 支持的链, 返回 chainIndex(字符串)/name/shortName\n## 场景: 查交易历史前确认目标链是否被支持\n## 关键词: 交易历史, 链列表, tx history, chainIndex\n## 参数: 无\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~2KB\n## 关联: 本工具 -> onchainos_transaction_history / onchainos_transaction_detail",
+    {}, { readOnlyHint: true },
+    async () => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await postTxApi.supportedChain(auth)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_transaction_history",
+    "CAT:[链上-账户] | ## 功能: 查询地址6个月内交易历史, 按时间倒序, 支持130+链\n## 场景: 用户想看最近交易记录, 或分析某地址的交易行为\n## 关键词: 交易历史, tx history, 转账, 合约交互\n## 参数:\n##   - address: 钱包地址(必填)\n##   - chains: 链索引逗号分隔, 最多50个(必填)\n##   - tokenContractAddress: 代币筛选(可选)\n##   - begin/end: 时间范围 Unix毫秒(可选)\n##   - cursor: 分页游标(可选)\n##   - limit: 返回条数, 多链最多20, 单链最多100(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 大 ~100KB\n## 关联: onchainos_tx_history_supported_chain -> 本工具 -> onchainos_transaction_detail(单笔详情)",
+    {
+      address: z.string().describe("钱包地址"),
+      chains: z.string().describe("链索引, 逗号分隔, 最多50个。如 '1'=ETH '56'=BSC。从 onchainos_tx_history_supported_chain 获取"),
+      tokenContractAddress: z.string().optional().describe("代币合约地址筛选。不传=查所有代币+主链币, 传空字符串=只查主链币, 传具体地址=查该代币"),
+      begin: z.string().optional().describe("开始时间, Unix毫秒时间戳。如 '1700000000000'"),
+      end: z.string().optional().describe("结束时间, Unix毫秒时间戳"),
+      cursor: z.string().optional().describe("分页游标。首次不传, 后续从返回值取"),
+      limit: z.string().optional().describe("返回条数。多链默认20最多20, 单链默认20最多100"),
+    },
+    { readOnlyHint: true },
+    async ({ address, chains, tokenContractAddress, begin, end, cursor, limit }) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try { return toResult(await postTxApi.transactions(auth, address, chains, tokenContractAddress, begin, end, cursor, limit)); } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_transaction_detail",
+    "CAT:[链上-账户] | ## 功能: 根据 txHash 查询单笔交易详情, 含 internalTransactionDetails/tokenTransferDetails\n## 场景: 看某笔交易的 gas 消耗、内部交易、代币转移明细\n## 关键词: 交易详情, tx detail, hash, 内部交易, token transfer\n## 参数:\n##   - chainIndex: 链索引字符串(必填)\n##   - txHash: 交易哈希(必填)\n##   - itype: 交易层级类型(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~10KB\n## 关联: onchainos_transaction_history -> 本工具 -> onchainos_portfolio_overview(关联地址分析)",
+    {
+      chainIndex: z.string().describe("链索引(字符串)。如 '1'=ETH '42161'=Arbitrum"),
+      txHash: z.string().describe("交易哈希。从 onchainos_transaction_history 返回值或广播返回获取"),
+      itype: z.enum(["0","1","2"]).optional().describe("交易层级: '0'=外层主链币转移 '1'=合约内层主链币转移 '2'=token转移。不传查所有"),
+    },
+    { readOnlyHint: true },
+    async ({ chainIndex, txHash, itype }) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try { return toResult(await postTxApi.transactionDetail(auth, chainIndex, txHash, itype)); } catch(e) { return toError(e); }
+    },
+  );
+
+}

package/src/tools/ws.ts

@@ -0,0 +1,72 @@
+/**
+ * WebSocket 模块 — CAT:[链上-行情]/[链上-Swap]
+ * 管理 WS 连接生命周期: connect → subscribe → (数据stderr日志) → unsubscribe → disconnect
+ *
+ * ⚠️ MCP Tool 限制: WS 是长连接推送, Tool 是请求-响应。
+ * subscribe 后数据通过 stderr 日志输出, 供 Agent 读取。
+ */
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { wsConnect, wsSubscribe, wsUnsubscribe, wsDisconnect } from "../adapters/onchainos-ws.js";
+import { toResult, toError, AUTH_REQUIRED } from "../adapters/shared.js";
+import type { Auth } from "../adapters/shared.js";
+
+export function registerWsTools(server: McpServer, auth: Auth | null): void {
+
+  server.tool("onchainos_ws_connect",
+    "CAT:[链上-WS] | ## 功能: 建立 WebSocket 连接并登录\n## 场景: 需要实时推送数据(价格/K线/交易/信号)时先调此工具\n## 关键词: WebSocket, 连接, 实时, 登录\n## 参数: 无(使用 API Key 自动登录)\n## 鉴权: 需要 API Key\n## 风险: READ\n## 返回量: 微小 ~1KB\n## 关联: 本工具 -> onchainos_ws_subscribe -> onchainos_ws_unsubscribe -> onchainos_ws_disconnect",
+    {}, { readOnlyHint: true },
+    async () => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try { const connId = await wsConnect(auth); return toResult({ connId, status: "connected" }); } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_ws_subscribe",
+    "CAT:[链上-WS] | ## 功能: 订阅 WebSocket 频道, 数据实时推送到 stderr 日志\n## 场景: 订阅价格/流通/K线/交易/信号/Memepump/地址追踪\n## 关键词: WebSocket, subscribe, 订阅, 实时推送\n## 参数:\n##   - channel: 频道名(必填)\n##   - chainIndex: 链索引(必填)\n##   - tokenContractAddress: 代币地址(价格/流通/K线/交易频道必填)\n## 鉴权: 需先调 onchainos_ws_connect\n## 风险: READ\n## 返回量: 微小 ~1KB\n## 关联: onchainos_ws_connect -> 本工具",
+    {
+      channel: z.string().describe("频道名: price/price-info/trades/dex-token-candle1m/dex-token-candle1H/dex-market-new-signal-openapi/dex-market-memepump-new-token-openapi/dex-market-memepump-update-metrics-openapi/address-tracker-activity/kol_smartmoney-tracker-activity"),
+      chainIndex: z.string().describe("链索引"),
+      tokenContractAddress: z.string().optional().describe("代币合约地址(小写)。price/price-info/trades/candle频道必填, 信号/Memepump频道不需要"),
+      walletAddress: z.string().optional().describe("钱包地址。仅 address-tracker-activity 频道需要, 最多200个地址"),
+    },
+    { readOnlyHint: true },
+    async ({ channel, chainIndex, tokenContractAddress, walletAddress }) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try {
+        const ch: Record<string, string> = { channel, chainIndex };
+        if (tokenContractAddress) ch.tokenContractAddress = tokenContractAddress;
+        if (walletAddress) ch.walletAddress = walletAddress;
+        await wsSubscribe(ch as any);
+        return toResult({ channel, chainIndex, status: "subscribed" }, {
+          warnings: ["数据将通过 stderr 日志实时推送, 标签 [WS-DATA]"],
+        });
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_ws_unsubscribe",
+    "CAT:[链上-WS] | ## 功能: 取消订阅 WebSocket 频道\n## 场景: 不再需要某个频道的实时数据\n## 关键词: WebSocket, unsubscribe, 取消订阅\n## 参数:\n##   - channel/chainIndex/tokenContractAddress: 同 subscribe\n## 鉴权: 需已连接\n## 风险: READ\n## 返回量: 微小 ~1KB\n## 关联: onchainos_ws_subscribe -> 本工具",
+    {
+      channel: z.string().describe("频道名"),
+      chainIndex: z.string().describe("链索引"),
+      tokenContractAddress: z.string().optional().describe("代币地址"),
+    },
+    { readOnlyHint: true },
+    async ({ channel, chainIndex, tokenContractAddress }) => {
+      try {
+        const ch: Record<string, string> = { channel, chainIndex };
+        if (tokenContractAddress) ch.tokenContractAddress = tokenContractAddress;
+        await wsUnsubscribe(ch as any);
+        return toResult({ channel, status: "unsubscribed" });
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_ws_disconnect",
+    "CAT:[链上-WS] | ## 功能: 断开 WebSocket 连接\n## 场景: 不再需要实时数据时关闭连接\n## 关键词: WebSocket, disconnect, 断开\n## 参数: 无\n## 鉴权: 无\n## 风险: READ\n## 返回量: 微小 ~1KB\n## 关联: 关闭所有订阅并断开",
+    {}, { readOnlyHint: true },
+    async () => { wsDisconnect(); return toResult({ status: "disconnected" }); },
+  );
+
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}