hchain-mcp 1.0.0

package/.env.example

@@ -0,0 +1,5 @@
+# OKX Onchain OS API 凭证
+# 获取: https://web3.okx.com/onchainos/dev-portal
+OKX_API_KEY=your_api_key_here
+OKX_SECRET_KEY=your_secret_key_here
+OKX_PASSPHRASE=your_passphrase_here

package/AGENT-MCP-RULES.md

@@ -0,0 +1,248 @@
+# Agent-First MCP 开发规则
+
+## 总纲
+
+MCP Server 的唯一用户是 AI Agent。不是给人看的，不是给前端调的。  
+所有决策从 Agent 的认知局限和能力边界出发。
+
+---
+
+## 规则 1：Token 经济学——省即是快
+
+Agent 的上下文窗口是有限资源。每个工具的 name、description、inputSchema 每轮对话都占 token。
+
+| 红线 | 标准 |
+|------|------|
+| 工具数量 | ≤20。超出用 search+execute 模式 |
+| 工具名 | ≤40 字符，纯动作动词+名词，kebab-case |
+| 描述 | 1-2 句。说什么、返回什么、不说什么 |
+| 参数数 | ≤5 必填，≤3 可选。超出拆工具 |
+| 参数描述 | 每个参数必写 `.describe()`，但一句话说清 |
+| enum 优先 | 能用 enum 就不用 string，减少 Agent 猜测 |
+
+```
+# 好
+get_quote — 获取最优 swap 报价。返回输出金额、价格影响、路由明细。不构造交易。
+
+# 坏
+get_quote — 这个工具用于获取去中心化交易所的聚合报价信息，它会查询多个流动性源...
+```
+
+---
+
+## 规则 2：零猜测——不让 Agent 蒙
+
+Agent 的弱点是不懂你的 API 内部逻辑。每个模糊点都是出错机会。
+
+- **参数永远带 `.describe()`**，告诉 Agent 这参数是什么格式、从哪来
+- **错误消息必须可执行**，不只说"错了"，要说"怎么做才对"
+- **返回值必须包含后续步骤需要的 ID**，别让 Agent 自己编
+
+```
+# 好
+"Token address 0xabc not found on chain 1. Use search_tokens to find valid addresses."
+
+# 坏
+"INVALID_ADDRESS"
+```
+
+---
+
+## 规则 3：读写分离——安全基线
+
+Agent 的宿主（Claude Code 等）依赖 `readOnlyHint` / `destructiveHint` 做自动审批决策。
+
+- **一个工具不能既读又写**
+- **所有只读工具标记 `readOnlyHint: true`**
+- **所有写操作标记 `destructiveHint: true`**
+- **写操作返回摘要而非裸数据**，让用户一眼看懂发生了什么
+
+```
+只读：get_quote, get_balance, search_tokens, get_candlesticks
+写入：build_swap, broadcast_transaction, build_approve
+```
+
+---
+
+## 规则 4：结构化返回——Agent 要的是 JSON，不是散文
+
+Agent 解析你的返回做下一步决策。返回格式必须：
+
+- **始终是合法的 JSON 字符串**（放在 `content[0].text` 里）
+- **顶层结构固定**：`{ success, data, error?, warnings?, nextSteps?, meta? }`
+- **涉及金额的字段用 string 而非 number**，避免精度丢失
+- **截断时明确告知**："返回 10/847 条，用 limit 参数翻页"
+
+```typescript
+// 标准返回结构
+{
+  success: true,
+  data: { ... },
+  warnings: ["价格影响 3.2%，偏高"],
+  nextSteps: ["如需交易，先调 build_approve_transaction，再调 build_swap_transaction"],
+  meta: { source: "api", cached: false, requestId: "xyz" }
+}
+```
+
+---
+
+## 规则 5：命名即文档
+
+Agent 靠工具名和描述做路由。命名混乱 → 调错工具 → 用户骂你。
+
+- **动词在前**：`get_`, `search_`, `build_`, `list_`
+- **`get_` vs `search_`**：get 是精确取一条，search 是模糊搜多条
+- **`list_` vs `get_`**：list 是枚举全部，get 是条件查询
+- **`build_` vs `execute_`**：build 只构造不发送，execute 直接干了
+
+```
+list_supported_chains    → 枚举所有链
+get_quote                → 拿一个报价
+search_tokens            → 模糊搜代币
+build_swap_transaction   → 构造交易，不广播
+```
+
+---
+
+## 规则 6：参数从 Agent 视角设计
+
+Agent 手里有什么信息，就用什么做参数。不要让 Agent 内部转换数据格式。
+
+- **Agent 有地址** → 参数要地址
+- **Agent 有链名** → 同时支持 chainIndex 和 chainName
+- **Agent 有上一个工具的返回** → 下一个工具的参数格式要对齐，能直接透传
+- **不要要求 Agent 自己算 decimals** → 接受人类可读数量，内部转换
+
+```
+# 好 — Agent 从 get_quote 拿到的 allowanceTarget 直接传
+build_approve_transaction({
+  tokenAddress: "0x...",       // 从搜索结果拿
+  spenderAddress: "0x...",     // 从报价的 allowanceTarget 拿
+  amount: "1000000"
+})
+
+# 坏 — 要求 Agent 自己拼
+build_approve_transaction({
+  rawCalldataParams: "0x..."
+})
+```
+
+---
+
+## 规则 7：渐进式复杂度
+
+工具分三层，Agent 按需深入：
+
+| 层 | 特征 | 示例 |
+|----|------|------|
+| L1 快速 | 0-1 参数，秒回，Agent 随手调 | `list_supported_chains` |
+| L2 核心 | 3-5 参数，业务主力 | `get_quote`, `get_balance` |
+| L3 高级 | 5+ 参数，专家才用 | `build_swap_transaction` |
+
+Agent 的典型路径：L1 探索 → L2 操作 → L3 执行。不要一上来就让 Agent 填 8 个参数。
+
+---
+
+## 规则 8：错误分级——帮 Agent 自我修正
+
+| 级别 | HTTP | 含义 | 返回 |
+|------|------|------|------|
+| 可重试 | 429/503 | 临时问题，等一下就好 | `retryAfter` 字段，Agent 知道等多久 |
+| 参数错 | 400 | Agent 传错了，修正后可重试 | 指出哪个参数错、正确格式是什么 |
+| 业务拒绝 | 422 | 逻辑上不可行（余额不足、滑点超限） | 给出替代方案 |
+| 系统错 | 500 | 不是 Agent 的问题 | 简单说明，不让 Agent 反复重试 |
+
+```json
+// 参数错误返回
+{
+  "success": false,
+  "error": {
+    "code": "INVALID_CHAIN",
+    "param": "chainIndex",
+    "message": "chainIndex '999' 不支持",
+    "fix": "调用 list_supported_chains 获取可用链列表"
+  }
+}
+```
+
+---
+
+## 规则 9：幂等与缓存——别让 Agent 等
+
+- **所有 L1 工具结果缓存**（TTL 按数据新鲜度分级）
+- **缓存在返回中透明标注** `meta: { cached: true, cachedAt: "..." }`
+- **相同参数相同结果**，Agent 可以安全重试读操作
+- **写操作永远不走缓存**
+
+| 数据 | TTL |
+|------|-----|
+| 链列表 | 300s |
+| 代币搜索 | 120s |
+| 实时价格 | 15s |
+| K线 | 30s |
+| 报价 | 不缓存 |
+| 余额 | 30s |
+
+---
+
+## 规则 10：链式提示——Agent 的导航系统
+
+Agent 不知道业务流程。当你返回 quote 时，它不知道下一步要 approve 再 swap。
+
+- **返回中包含 `nextSteps`**：人类可读的后续步骤列表
+- **每个步骤写明要调哪个工具**：Agent 可以直接执行
+- **不要强行规定**：是提示不是命令，Agent 可能因为用户意图跳过
+
+```json
+{
+  "data": { /* quote */ },
+  "nextSteps": [
+    { "action": "检查授权", "tool": "get_allowance", "params": { "tokenAddress": "...", "ownerAddress": "..." } },
+    { "action": "授权代币", "tool": "build_approve_transaction", "condition": "如果 allowance 不足" },
+    { "action": "执行交易", "tool": "build_swap_transaction", "condition": "授权完成后" }
+  ]
+}
+```
+
+---
+
+## 规则 11：不要教 Agent 做事
+
+MCP tool description 中**不能**包含对 Agent 行为的指令。这是 prompt injection，会导致 Anthropic Directory 审核被拒。
+
+```
+# 违规
+"Always call this tool before get_quote. You must check the chain first."
+
+# 合规
+"返回支持的链列表。调用 get_quote 前建议先确认目标链是否在列表中。"
+```
+
+差别：前者是命令 Agent，后者是陈述事实。
+
+---
+
+## 规则 12：传输层透明
+
+不管是 stdio 还是 HTTP，Agent 感知不到。但：
+
+- **HTTP 必须无状态**：每个请求独立，`sessionIdGenerator: undefined`
+- **超时策略**：读 15s，写 30s
+- **健康检查独立于 /mcp**：`GET /health` 返回 200，主机用它判断存活
+
+---
+
+## 检查清单
+
+每加一个工具，过一遍：
+
+- [ ] 工具名 ≤ 40 字符，动词+名词，kebab-case
+- [ ] 描述 1-2 句，说了做什么、不做什么
+- [ ] 每个参数有 `.describe()`
+- [ ] 能用 enum 的地方没用 string
+- [ ] `readOnlyHint` 或 `destructiveHint` 已标记
+- [ ] 返回是 JSON，有 `success` 字段
+- [ ] 错误返回有 `fix` 字段
+- [ ] 涉及金额用 string
+- [ ] 对应缓存 TTL 已配置（如果是读操作）
+- [ ] 如果输出能被下个工具用，加了 `nextSteps`

package/OnchainOS-API/345/257/271/346/216/245/350/247/204/350/214/203.md

@@ -0,0 +1,329 @@
+# Onchain OS API 对接开发规范
+
+> 基于 hvip MCP 代码标准 · 接收方：所有 AI 工程师
+> 阅读本文后即可开始编写 Onchain OS MCP 工具
+
+---
+
+## 一、目录结构
+
+```
+onchainos-mcp/
+  src/
+    adapters/
+      onchainos.ts      ← Onchain OS REST API 适配层
+      onchainos-ws.ts   ← 如需：Onchain OS WebSocket 适配层
+    tools/
+      onchainos.ts      ← Onchain OS MCP 工具注册
+```
+
+---
+
+## 二、9 字段描述模板（强制）
+
+每个 `server.tool()` 的描述字符串必须包含以下 9 个字段，按顺序用 `\n## ` 分隔：
+
+```typescript
+"CAT:[分类名] | ## 功能：一句话描述\n
+## 场景：用于xxx、xxx\n
+## 关键词：xxx, xxx, xxx\n
+## 参数：\n##   - paramName: 参数说明\n
+## 鉴权：PUBLIC — 公开接口，不需要 API Key | ⚠️ 需要 API Key（只读）| ⚠️ 需要 API Key（交易）\n
+## 风险：READ — 只读查询 | WRITE — 写操作\n
+## 返回量：微小 ~2KB | 中等 ~10KB | 大 ~100KB\n
+## 关联：前置工具 → 本工具 → 后续工具"
+```
+
+**9 个字段缺一不可：** `CAT:` | `功能` | `场景` | `关键词` | `参数` | `鉴权` | `风险` | `返回量` | `关联`
+
+### 参考范例
+
+```typescript
+server.tool(
+  "onchainos_get_price",
+  "CAT:[链上-行情] | ## 功能：获取指定代币在多链上的实时价格\n## 场景：用于查询代币当前币价、多链比价、发现价差机会\n## 关键词：链上行情, 代币价格, onchain price, 多链\n## 参数：\n##   - chainId: 链ID。1=ETH, 56=BSC, 137=Polygon, 8453=Base\n##   - tokenAddress: 代币合约地址（必填）\n## 鉴权：PUBLIC — 公开接口，不需要 API Key\n## 风险：READ — 只读查询，Agent 可自动调用\n## 返回量：微小 ~1KB\n## 关联：onchainos_search_token 搜索代币 → 本工具查价 → onchainos_get_pool 看流动性",
+  {
+    chainId:      z.number().int().describe("链ID。1=ETH, 56=BSC, 137=Polygon, 8453=Base"),
+    tokenAddress: z.string().describe("代币合约地址（必填）"),
+  },
+  async ({ chainId, tokenAddress }) => {
+    try {
+      const data = await onchainosApi.getPrice(chainId, tokenAddress)
+      return toResult(data)
+    } catch (e) { return toError(e) }
+  }
+)
+```
+
+---
+
+## 三、CAT 分类名
+
+Onchain OS 工具使用以下分类：
+
+| CAT 标签 | 对应 API 模块 | 示例工具 |
+|----------|-------------|---------|
+| `[链上-行情]` | Market Price / Token / Index Price | getPrice, getTokenInfo |
+| `[链上-Swap]` | DEX Swap / Quote / Bridge | getQuote, swap |
+| `[链上-账户]` | Balance / Transaction History | getBalance, getTxHistory |
+| `[链上-分析]` | Address Analysis / Portfolio | getPortfolio, getPnL |
+| `[链上-信号]` | Signal / Leaderboard / Trenches | getSignals |
+| `[链上-WS]` | WebSocket 实时频道 | subscribePrice |
+| `[链上-网关]` | Onchain Gateway / Gas / Broadcast | simulate, broadcast |
+
+---
+
+## 四、适配器模板
+
+### 4.1 公共接口（无需鉴权）
+
+在 `src/adapters/onchainos.ts` 中：
+
+```typescript
+import crypto from "node:crypto"
+
+const BASE = "https://web3.okx.com"
+
+function timestamp(): string {
+  return new Date().toISOString().replace(/(\.\d{3})\d*Z/, "$1Z")
+}
+
+function buildQuery(params: Record<string, string | number | boolean | undefined>): string {
+  const p = new URLSearchParams()
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined && v !== "") p.append(k, String(v))
+  }
+  return p.size ? "?" + p.toString() : ""
+}
+
+async function request<T>(
+  method: "GET" | "POST",
+  path: string,
+  options: {
+    params?: Record<string, string | number | boolean | undefined>
+    body?: unknown
+    auth?: { apiKey: string; secret: string; passphrase: string }
+  } = {}
+): Promise<T> {
+  const query = options.params ? buildQuery(options.params) : ""
+  const fullPath = path + query
+  const bodyStr = options.body ? JSON.stringify(options.body) : ""
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "Accept": "application/json",
+  }
+
+  if (options.auth) {
+    const ts = timestamp()
+    const msg = ts + method + fullPath + bodyStr
+    const sign = crypto.createHmac("sha256", options.auth.secret).update(msg).digest("base64")
+    headers["OK-ACCESS-KEY"] = options.auth.apiKey
+    headers["OK-ACCESS-SIGN"] = sign
+    headers["OK-ACCESS-TIMESTAMP"] = ts
+    headers["OK-ACCESS-PASSPHRASE"] = options.auth.passphrase
+  }
+
+  const res = await fetch(BASE + fullPath, {
+    method, headers,
+    ...(bodyStr ? { body: bodyStr } : {}),
+  })
+
+  if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`)
+  const json = await res.json() as { code: string; msg?: string; data?: T }
+  if (json.code !== "0") throw new Error(`OKX ${json.code}: ${json.msg ?? "unknown error"}`)
+  return (json.data ?? json) as T
+}
+
+// ── 公共接口 ──────────────────────────────────────────────
+
+export const onchainosApi = {
+  // 行情价格
+  getPrice: (chainId: number, tokenAddress: string) =>
+    request<unknown>("GET", "/api/v6/dex/market/price", { params: { chainId, tokenAddress } }),
+
+  // 搜索代币
+  searchToken: (keyword: string) =>
+    request<unknown[]>("GET", "/api/v6/dex/market/search", { params: { keyword } }),
+}
+```
+
+### 4.2 鉴权接口
+
+```typescript
+export const onchainosPrivateApi = {
+  // 余额查询
+  getBalance: (auth: Auth, address: string, chainId: number) =>
+    request<unknown[]>("GET", "/api/v6/dex/asset/balance", { params: { address, chainId }, auth }),
+
+  // Swap 下单
+  swap: (auth: Auth, body: Record<string, unknown>) =>
+    request<unknown>("POST", "/api/v6/dex/swap", { body, auth }),
+}
+```
+
+**规则：** 公开端点放 `onchainosApi`（无 `auth` 参数），鉴权端点放 `onchainosPrivateApi`（第一个参数是 `auth: Auth`）。
+
+---
+
+## 五、工具注册模板
+
+每个工具文件导出一个注册函数：
+
+```typescript
+import { z } from "zod"
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { onchainosApi, type Auth } from "../adapters/onchainos.js"
+import { toResult, toError, AUTH_REQUIRED } from "./shared.js"
+
+export function registerOnchainOSTools(server: McpServer, auth: Auth | null): void {
+
+  server.tool(
+    "onchainos_get_price",
+    "CAT:[链上-行情] | ## 功能：...\n...\n## 关联：...",
+    { /* Zod schema */ },
+    async ({ /* params */ }) => {
+      try {
+        const data = await onchainosApi.getPrice(...)
+        return toResult(data)
+      } catch (e) { return toError(e) }
+    }
+  )
+}
+```
+
+**注册到 `src/index.ts`：**
+
+```typescript
+import { registerOnchainOSTools } from "./tools/onchainos.js"
+// 在 main() 中：
+registerOnchainOSTools(server, auth)
+```
+
+---
+
+## 六、强制规则
+
+### 6.1 防幻觉（最重要）
+
+**每个端点接之前必须 curl 验证，确认返回 200 真实数据再写代码。**
+
+```bash
+# 验证端点真实存在
+curl -s "https://web3.okx.com/api/v6/dex/market/price?chainId=1&tokenAddress=0x..." \
+  -H "OK-ACCESS-KEY: $OKX_API_KEY" \
+  -H "OK-ACCESS-SIGN: ..." \
+  -H "OK-ACCESS-TIMESTAMP: ..." \
+  -H "OK-ACCESS-PASSPHRASE: ..."
+```
+
+**404 跳过，200 接。编造的端点直接拒。**
+
+### 6.2 tsIso 时间戳
+
+所有 `toResult()` 返回数据必须包含 `tsIso` 字段：
+
+```typescript
+return toResult({
+  ...data,
+  tsIso: new Date().toISOString(),
+})
+```
+
+### 6.3 错误处理
+
+```typescript
+try {
+  const data = await api.xxx()
+  return toResult(data)
+} catch (e) { return toError(e) }
+```
+
+### 6.4 枚举使用
+
+产品类型参数使用 `INST_TYPE_*` 常量，禁止硬编码：
+
+```typescript
+// ✅ 正确
+instType: z.enum(INST_TYPE_MARKET).describe("产品类型")
+
+// ❌ 错误
+instType: z.enum(["SPOT","SWAP","FUTURES"]).describe("产品类型")
+```
+
+### 6.5 分支命名
+
+```
+feat/onchainos-<feature>    新功能
+fix/onchainos-<bug>         Bug 修复
+task/onchainos-<编号>       任务池工单
+```
+
+### 6.6 提交之前
+
+```bash
+npm run build    # 必须通过
+```
+
+### 6.7 Tool 命名规范
+
+```
+onchainos_<模块>_<操作>
+```
+
+示例：
+```
+onchainos_market_price        — 行情价格
+onchainos_token_search        — 搜索代币
+onchainos_dex_quote           — DEX 报价
+onchainos_balance_total       — 总余额
+onchainos_swap_execute        — 执行 Swap
+onchainos_ws_price_subscribe  — WS 价格订阅
+```
+
+---
+
+## 七、审核检查清单
+
+提交前自查，审核员也会逐项检查：
+
+- [ ] `npm run build` 通过
+- [ ] 9 字段描述完整（CAT / 功能 / 场景 / 关键词 / 参数 / 鉴权 / 风险 / 返回量 / 关联）
+- [ ] 端点经 curl 验证存在（不是编的）
+- [ ] `tsIso` 时间戳
+- [ ] `toResult()` / `toError()` 错误处理
+- [ ] `INST_TYPE_*` 枚举（如涉及产品类型）
+- [ ] 公开端点放 `onchainosApi`，鉴权端点放 `onchainosPrivateApi`
+- [ ] Tool 命名以 `onchainos_` 前缀
+- [ ] CAT 分类标签正确
+- [ ] 分支名符合规范
+- [ ] 不修改无关文件
+
+---
+
+## 八、开发流程
+
+```
+1. 阅读本文档 + CLAUDE.md
+2. 从 Onchain OS 文档选择要接的 API 模块
+3. curl 验证端点
+4. git checkout -b feat/onchainos-<模块>
+5. 写 src/adapters/onchainos.ts + src/tools/onchainos.ts
+6. npm run build
+7. git push origin feat/onchainos-<模块>
+8. 通知审核员（WS Hub 发 task:done）
+9. 等待审核 → 通过后合并
+```
+
+---
+
+## 九、参考示例
+
+| 文件 | 参考价值 |
+|------|---------|
+| `src/tools/market.ts` | 9 字段描述模板 |
+| `src/adapters/okx.ts` | `publicApi` / `privateApi` 适配器模式 |
+| `src/tools/shared.ts` | `toResult` / `toError` / `AUTH_REQUIRED` / `INST_TYPE_*` |
+| `CLAUDE.md` | 项目架构 + 开发规范 |
+| `CONTRIBUTING.md` | 分支协作流程 |
+| `docs/OKX-MCP-防幻觉对接SOP-v1.0.md` | 防幻觉标准操作流程 |

package/README.md

@@ -0,0 +1,106 @@
+# h-mcp
+
+AI-native multi-chain trading MCP Server — 99 tools, HTTP & stdio dual transport.
+
+## Install
+
+```bash
+npm install -g h-mcp
+```
+
+## Usage
+
+### stdio (local Agent)
+
+```bash
+h-mcp
+```
+
+Set API Key:
+
+```bash
+export OKX_API_KEY=xxx
+export OKX_SECRET_KEY=xxx
+export OKX_PASSPHRASE=xxx
+h-mcp
+```
+
+### HTTP (remote Agent)
+
+```bash
+h-mcp start:http
+# → http://127.0.0.1:3000
+
+# or custom port
+PORT=3099 h-mcp start:http
+```
+
+Endpoints:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/mcp` | MCP StreamableHTTP |
+| GET | `/health` | Health check |
+
+### Claude Code Config
+
+```json
+{
+  "mcpServers": {
+    "h-mcp": {
+      "command": "npx",
+      "args": ["h-mcp"],
+      "env": {
+        "OKX_API_KEY": "xxx",
+        "OKX_SECRET_KEY": "xxx",
+        "OKX_PASSPHRASE": "xxx"
+      }
+    }
+  }
+}
+```
+
+Or HTTP mode:
+
+```json
+{
+  "mcpServers": {
+    "h-mcp": {
+      "url": "http://127.0.0.1:3099/mcp"
+    }
+  }
+}
+```
+
+## Tools (99)
+
+### Phase 1 — Base APIs (95 tools)
+
+| Module | Count | Description |
+|--------|:-----:|-------------|
+| Market | 45 | Prices, candles, token info, signals, social |
+| DeFi | 14 | Yield, staking, lending, pool |
+| Trade | 8 | DEX aggregation, quote, swap |
+| Intent | 6 | Intent-based swap + auction |
+| Gateway | 6 | Gas, simulate, broadcast |
+| Payments | 5 | Agent-to-Agent payments (x402) |
+| Balance | 4 | Multi-chain balance |
+| WS | 4 | WebSocket connect/subscribe |
+| TxHistory | 3 | Transaction history |
+
+### Phase 2 — API Composition Skills (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `onchainos_skill_trade_pipeline` | One-shot swap: quote → approve → swap → simulate |
+| `onchainos_skill_risk_detect` | 4-dimension risk scan with 0-100 scoring |
+| `onchainos_skill_smart_slippage` | Volatility-based slippage recommendation |
+| `onchainos_skill_signal_aggregate` | Signal discovery with automatic risk filtering |
+
+## Supported Chains
+
+Ethereum, BSC, Polygon, Arbitrum, Base, Optimism, Solana, Sui, TON, Avalanche, Fantom, and 40+ more.
+
+## License
+
+MIT