hvip-mcp-server 0.2.55 → 0.2.57

package/README.md

@@ -1,101 +1,155 @@
 # hvip MCP Server
 
-> OKX API 全景图 —— 让任何 AI Agent 都能使用 OKX 的全部能力。
+> OKX 全部能力接入 AI —— 365 个 MCP 工具，覆盖 97.7% OKX REST API
 
 [![npm version](https://img.shields.io/npm/v/hvip-mcp-server)](https://www.npmjs.com/package/hvip-mcp-server)
 [![License](https://img.shields.io/npm/l/hvip-mcp-server)](https://github.com/okx-wallet-H/hvip-mcp/blob/master/LICENSE)
-[![GitHub stars](https://img.shields.io/github/stars/okx-wallet-H/hvip-mcp)](https://github.com/okx-wallet-H/hvip-mcp)
 
-📦 **仓库**: [github.com/okx-wallet-H/hvip-mcp](https://github.com/okx-wallet-H/hvip-mcp)
-🐛 **Issue**: [提交反馈](https://github.com/okx-wallet-H/hvip-mcp/issues/new)
-📖 **贡献**: [CONTRIBUTING.md](./CONTRIBUTING.md)
+📦 [github.com/okx-wallet-H/hvip-mcp](https://github.com/okx-wallet-H/hvip-mcp) · 🐛 [提交反馈](https://github.com/okx-wallet-H/hvip-mcp/issues/new)
 
 ---
 
-## 快速开始
+## 安装
 
-### 1. Claude Desktop 接入
+**这不是命令行工具**——hvip-mcp 是 MCP (Model Context Protocol) 服务器，由 AI 客户端在后台自动运行。你只需要在配置文件中加一行 JSON，AI 自己会启动它。
 
-在 Claude Desktop 配置中添加：
+### Claude Desktop
+
+Claude Desktop → 设置 → Developer → Edit Config：
+
+```json
+{
+  "mcpServers": {
+    "hvip": {
+      "command": "npx",
+      "args": ["-y", "hvip-mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+在项目根目录或全局 `.claude/settings.json`：
+
+```json
+{
+  "mcpServers": {
+    "hvip": {
+      "command": "npx",
+      "args": ["-y", "hvip-mcp-server@latest"]
+    }
+  }
+}
+```
+
+### VS Code / Cline / 其他 MCP 客户端
+
+在 MCP 配置中添加同样的 JSON。
+
+> **配置完需要完全退出并重启客户端**，重开后 AI 自动连接 hvip。
+
+### 需要 API Key？
+
+行情、技术指标、市场扫描等公开数据无需 Key。查看账户、下单交易需要 OKX API Key：
 
 ```json
 {
   "mcpServers": {
-    "hvip-mcp": {
+    "hvip": {
       "command": "npx",
       "args": ["-y", "hvip-mcp-server"],
       "env": {
-        "OKX_API_KEY": "<你的API Key>",
-        "OKX_SECRET_KEY": "<你的Secret Key>",
-        "OKX_PASSPHRASE": "<你的Passphrase>"
+        "OKX_API_KEY": "<你的 API Key>",
+        "OKX_SECRET_KEY": "<你的 Secret Key>",
+        "OKX_PASSPHRASE": "<你的 Passphrase>"
       }
     }
   }
 }
 ```
 
-### 2. 直接运行
+> API Key 在 [OKX 官网](https://www.okx.com) → 个人中心 → API 中创建，开通「读取」权限即可查账户，「交易」权限可下单。
 
-```bash
-npx hvip-mcp-server
-```
+---
 
-### 3. 本地开发
+## 工作流
 
-```bash
-git clone https://github.com/okx-wallet-H/hvip-mcp.git
-cd hvip-mcp
-npm install
-npm run build
-npm start
+AI 连接 hvip 后自动执行：
+
+```
+1. tools/list  →  365 个工具，但只有 agent_catalog 带完整描述
+2. agent_catalog  →  15 个域的地图（7 公开 + 8 需 Key），按需直达
+3. 用户说 "BTC 怎么样"  →  AI 调 okx_quick_market
+4. 用户说 "买 0.1 BTC"  →  AI 先预检再下单
 ```
 
+**无需手动操作，全程 AI 自己来。**
+
 ---
 
 ## 工具覆盖
 
 | 模块 | 工具数 | 说明 |
 |------|--------|------|
-| 🔹 **交易类** | 40+ | 下单/撤单/改单/批量/策略委托 |
-| 🔹 **行情类** | 30+ | Ticker/K线/深度/资金费率/标记价 |
-| 🔹 **数据类** | 50+ | 产品信息/多空比/买卖量/PCR/统计数据 |
-| 🔹 **资金类** | 40+ | 划转/提现/充值/余额/持仓/杠杆 |
-| 🔹 **策略类** | 20+ | 网格/信号/跟单/价差/RFQ |
-| 🔹 **金融类** | 15+ | 赚币/质押/借贷/法币 |
-| 🔹 **预测市场** | 9+ | 事件/市场/深度/套利检测 |
-| 🔹 **Skill 组合** | 4 | 账户全景/市场速览/下单预检/反馈 |
+| 🔹 账户 | 40+ | 余额/持仓/配置/杠杆/估值 |
+| 🔹 行情 | 17 | Ticker/K线/深度/成交 |
+| 🔹 交易 | 27 | 下单/撤单/改单/批量/平仓 |
+| 🔹 公共数据 | 34 | 产品规格/资金费率/标记价 |
+| 🔹 资金 | 18 | 划转/提现/充值/兑换 |
+| 🔹 策略委托 | 6 | 止损止盈/冰山/移动止盈 |
+| 🔹 网格 | 13 | 现货网格/合约网格/定投 |
+| 🔹 跟单 | 23 | 交易员/跟单/带单 |
+| 🔹 信号 | 10 | 信号订阅/历史信号 |
+| 🔹 价差 | 16 | 跨品种/跨期价差 |
+| 🔹 RFQ | 12 | 大宗询价/报价/成交 |
+| 🔹 金融 | 27 | 赚币/质押/借贷 |
+| 🔹 预测市场 | 36 | 事件合约/预测交易 |
+| 🔹 技术指标 | 2 | RSI/MACD/布林带等 17 种 |
+| 🔹 聪明钱 | 3 | 交易员排行榜/市场情绪 |
+| 🔹 WebSocket | 5 | 55 频道实时推送 |
+| 🔹 代码图谱 | 2 | 函数调用链/符号搜索 |
+| 🔹 系统工具 | 19 | 导航/偏好/反馈/Agent 协作 |
+
+**365 个 MCP 工具 · 覆盖 97.7% OKX REST API**
 
-**304 个 MCP 工具 · 覆盖 97.7% OKX REST API · P0 P1 全部清零**
+---
+
+## 本地开发
+
+```bash
+git clone https://github.com/okx-wallet-H/hvip-mcp.git
+cd hvip-mcp
+npm install
+npm run build
+npm start
+```
 
 ---
 
 ## 架构
 
 ```
-原子层 (300+ 工具)  →  AI Agent 直接调用
-    ↓
-Skill 组合层 (4 个) →  串联多工具，一次完成复杂任务
-    ↓
-反馈通道 → GitHub Issues → 新 Skill 需求 → AI Agent 自行实现并提 PR
+原子层 (350 工具) → [L:READ] 权限标记 → AI Agent 按需调用
+       ↓
+Skill 组合层 (13 个) → 串联多工具，一次完成复杂任务
+       ↓
+agent_catalog → 15 域地图 → 按意图路由 → 直达目标工具
 ```
 
 ---
 
 ## 贡献
 
-AI Agent 或开发者都可以贡献 Skill：
-
 1. 阅读 [`CLAUDE.md`](./CLAUDE.md) 了解项目规范
 2. 阅读 [`CONTRIBUTING.md`](./CONTRIBUTING.md) 了解提交流程
-3. Fork → 创建 Skill → 提 PR → Review → 合并
-
-每个 Skill 串联多个原子工具，解决一个具体的使用场景。
+3. Fork → 创建分支 → 开发 → `npm run build` → 提 PR
 
 ---
 
 ## 文档
 
 - [`CLAUDE.md`](./CLAUDE.md) — AI Agent 项目指南
-- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — Skill 贡献流程
-- [`docs/OKX-MCP-API对接标准-v0.1.8.md`](./docs/OKX-MCP-API对接标准-v0.1.8.md) — API 对接规范
+- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — 贡献流程
+- [`docs/OKX-MCP-API对接标准-v0.2.49.md`](./docs/OKX-MCP-API对接标准-v0.2.49.md) — API 对接规范
 - [`docs/OKX-MCP-防幻觉对接SOP-v1.0.md`](./docs/OKX-MCP-防幻觉对接SOP-v1.0.md) — 防幻觉 SOP

package/dist/index.js

@@ -37023,11 +37023,73 @@ var AgentHub = class {
   rooms = /* @__PURE__ */ new Map();
   heartbeatTimer = null;
   version = "0.0.0";
+  port = 0;
+  db = null;
+  // ── 持久化绑定 ──
+  setDB(db) {
+    this.db = db;
+    const rows = db.loadTasks();
+    for (const r of rows) {
+      this.tasks.set(r.taskId, {
+        status: r.status,
+        assignedTo: r.assignedTo || void 0,
+        claimedAt: r.claimedAt || void 0,
+        result: r.result || void 0,
+        branch: r.branch || void 0
+      });
+    }
+    if (rows.length > 0) {
+      console.log(`[AgentHub] \u4ECE DB \u6062\u590D ${rows.length} \u4E2A\u4EFB\u52A1`);
+    }
+  }
   // ── 启动 ──
   start(port, host = "0.0.0.0", version2 = "0.0.0") {
     this.version = version2;
-    this.wss = new import_websocket_server.default({ port, host });
-    console.log(`[AgentHub] WS Server v${version2} started on ws://${host}:${port}`);
+    const startWss = (p) => {
+      return new Promise((resolve2) => {
+        const wss = new import_websocket_server.default({ port: p, host });
+        let resolved = false;
+        const done = (ok) => {
+          if (!resolved) {
+            resolved = true;
+            resolve2(ok);
+          }
+        };
+        wss.on("listening", () => {
+          this.wss = wss;
+          this.port = p;
+          done(true);
+        });
+        wss.on("error", () => {
+          try {
+            wss.close();
+          } catch {
+          }
+          done(false);
+        });
+        setTimeout(() => done(false), 1e3);
+      });
+    };
+    const ports = [port, port + 1, port + 2];
+    startWss(ports[0]).then((ok) => {
+      if (!ok) return startWss(ports[1]);
+      return true;
+    }).then((ok) => {
+      if (!ok) return startWss(ports[2]);
+      return ok === true ? true : false;
+    }).then((ok) => {
+      if (!ok) {
+        process.stderr.write(`[AgentHub] WS Hub \u8DF3\u8FC7\uFF08\u7AEF\u53E3 ${ports.join("/")} \u4E0D\u53EF\u7528\uFF09
+`);
+        return;
+      }
+      process.stderr.write(`[AgentHub] WS Hub v${version2} ws://${host}:${this.port}
+`);
+      this.setupHub();
+    });
+  }
+  setupHub() {
+    if (!this.wss) return;
     this.ensureRoom("#lobby");
     this.ensureRoom("#review");
     this.wss.on("connection", (ws) => {
@@ -37035,7 +37097,8 @@ var AgentHub = class {
       ws.on("message", (raw) => {
         try {
           const msg = JSON.parse(raw.toString());
-          this.handleMessage(ws, agentId, msg);
+          const newId = this.handleMessage(ws, agentId, msg);
+          if (newId) agentId = newId;
         } catch {
           this.send(ws, { type: "error", message: "\u6D88\u606F\u683C\u5F0F\u9519\u8BEF\uFF1A\u975E JSON" });
         }
@@ -37052,7 +37115,7 @@ var AgentHub = class {
         if (now - a.lastSeen > 12e4) {
           a.ws.close();
           this.agents.delete(id);
-          console.log(`[AgentHub] Agent \u5FC3\u8DF3\u8D85\u65F6: ${id}`);
+          console.log("[AgentHub] Agent \u5FC3\u8DF3\u8D85\u65F6: " + id);
         }
       }
     }, 3e4);
@@ -37061,8 +37124,7 @@ var AgentHub = class {
   handleMessage(ws, authAgentId, msg) {
     switch (msg.type) {
       case "agent:hello":
-        this.handleHello(ws, msg);
-        break;
+        return this.handleHello(ws, msg);
       case "agent:status":
         if (authAgentId) this.handleAgentStatus(authAgentId);
         break;
@@ -37088,6 +37150,7 @@ var AgentHub = class {
       default:
         this.send(ws, { type: "error", message: `\u672A\u77E5\u6D88\u606F\u7C7B\u578B: ${msg.type}` });
     }
+    return null;
   }
   // ── Agent 注册 ──
   handleHello(ws, msg) {
@@ -37096,7 +37159,7 @@ var AgentHub = class {
     const capabilities = Array.isArray(msg.capabilities) ? msg.capabilities : [];
     if (!agentId) {
       this.send(ws, { type: "error", message: "\u7F3A\u5C11 agentId" });
-      return;
+      return "";
     }
     const existing = this.agents.get(agentId);
     if (existing) existing.ws.close();
@@ -37134,17 +37197,17 @@ var AgentHub = class {
         }
       }
     }
+    return agentId;
   }
   handleDisconnect(agentId) {
     const info = this.agents.get(agentId);
     console.log(`[AgentHub] Agent \u79BB\u7EBF: ${agentId} (${info?.name || "?"})`);
-    for (const [, room] of this.rooms) {
+    for (const [roomId, room] of this.rooms) {
       if (room.members.has(agentId)) {
         room.members.delete(agentId);
         this.sendToRoomMembers(room, {
           type: "room:member_left",
-          roomId: agentId,
-          // fixed below
+          roomId,
           agentId
         });
       }
@@ -37155,6 +37218,7 @@ var AgentHub = class {
         t.status = "unassigned";
         t.assignedTo = void 0;
         t.claimedAt = void 0;
+        this.db?.saveTask({ taskId: tid, status: "unassigned" });
         this.broadcast({ type: "task:released", taskId: tid, reason: "Agent \u79BB\u7EBF" });
       }
     }
@@ -37187,6 +37251,7 @@ var AgentHub = class {
     if (a) a.status = "working";
     this.joinRoom(agentId, `#task-${taskId}`);
     console.log(`[AgentHub] ${agentId} \u8BA4\u9886 ${taskId}`);
+    this.db?.saveTask({ taskId, status: "assigned", title: this.getTaskTitle(taskId), assignedTo: agentId, claimedAt: task.claimedAt });
     this.sendTo(agentId, {
       type: "task:assigned",
       taskId,
@@ -37212,6 +37277,7 @@ var AgentHub = class {
     const a = this.agents.get(agentId);
     if (a) a.status = "idle";
     console.log(`[AgentHub] ${agentId} \u5B8C\u6210 ${taskId}: ${result}`);
+    this.db?.saveTask({ taskId, status: "done", title: this.getTaskTitle(taskId), assignedTo: agentId, result, branch });
     this.sendToRoom(`#task-${taskId}`, agentId, `\u5DF2\u5B8C\u6210 ${taskId}: ${result} (branch: ${branch})\uFF0C\u7B49\u5F85\u5BA1\u6838\u3002`);
     this.sendToRoom("#review", agentId, `${taskId} \u63D0\u4EA4\u5B8C\u6210\uFF0Cbranch: ${branch}`);
     this.broadcast({
@@ -37243,10 +37309,12 @@ var AgentHub = class {
     if (!task) return;
     if (verdict === "approved") {
       task.status = "reviewed";
+      this.db?.saveTask({ taskId, status: "reviewed", reviewedAt: (/* @__PURE__ */ new Date()).toISOString() });
     } else {
       task.status = "unassigned";
       task.assignedTo = void 0;
       task.claimedAt = void 0;
+      this.db?.saveTask({ taskId, status: "unassigned" });
     }
     const roomId = `#task-${taskId}`;
     const msg = verdict === "approved" ? `\u2705 ${taskId} \u5BA1\u6838\u901A\u8FC7\u3002\u5DF2\u5408\u5E76\u5230 master \u5E76\u5220\u9664\u8FDC\u7A0B\u5206\u652F\u3002` : `\u274C ${taskId} \u5BA1\u6838\u4E0D\u901A\u8FC7\u3002${feedback || "\u8BF7\u4FEE\u6539\u540E\u91CD\u65B0 push\u3002"}`;
@@ -37297,6 +37365,7 @@ var AgentHub = class {
     const msg = { roomId, from, text, ts: (/* @__PURE__ */ new Date()).toISOString() };
     room.messages.push(msg);
     if (room.messages.length > MAX_ROOM_MESSAGES) room.messages.shift();
+    this.db?.saveMessage(roomId, from, text, msg.ts);
     const raw = JSON.stringify({ type: "room:message", ...msg });
     for (const agentId of room.members) {
       const a = this.agents.get(agentId);
@@ -38212,7 +38281,7 @@ async function startStdio(server, version2, auth, readOnly, skipped, skipLog) {
   await server.connect(transport);
 }
 async function main() {
-  const VERSION = "0.2.55";
+  const VERSION = "0.2.57";
   const argv = process.argv.slice(2);
   if (argv.includes("--help") || argv.includes("-h")) printHelpAndExit(VERSION);
   if (argv.includes("--version") || argv.includes("-v")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hvip-mcp-server",
-  "version": "0.2.55",
+  "version": "0.2.57",
   "description": "hvip MCP Server — 365 工具覆盖 97.7% OKX REST API，含交易/行情/资金/策略/预测市场/技术指标/Smart Money（非 OKX 官方产品）",
   "homepage": "https://github.com/okx-wallet-H/hvip-mcp",
   "repository": {