@aicoin/opendata-mcp 1.0.1 → 1.0.2

package/.env.example

@@ -1,9 +1,7 @@
 # AiCoin OpenData MCP - API credentials
-# NOTE: AiCoin 后台的字段名和这里的变量名是反的！
-#   后台 "api_key"    → 填到 AICOIN_ACCESS_KEY（用作 AccessKeyId）
-#   后台 "access_key" → 填到 AICOIN_ACCESS_SECRET（用作 HMAC 签名密钥）
-AICOIN_ACCESS_KEY=your_api_key_from_aicoin
-AICOIN_ACCESS_SECRET=your_access_key_from_aicoin
+# 从 https://www.aicoin.com/openapi 获取
+AICOIN_ACCESS_KEY_ID=your_access_key_id
+AICOIN_ACCESS_SECRET=your_access_secret
 
-# Optional: API base URL (default: https://open.aicoin.com/api/v2)
-# AICOIN_BASE_URL=https://open.aicoin.com/api/v2
+# Optional: API base URL (default: https://open.aicoin.com)
+# AICOIN_BASE_URL=https://open.aicoin.com

package/README.md

@@ -22,7 +22,7 @@ npm start
 ## Environment Variables
 
 ```bash
-AICOIN_ACCESS_KEY=your_access_key_id
+AICOIN_ACCESS_KEY_ID=your_access_key_id
 AICOIN_ACCESS_SECRET=your_access_secret
 ```
 
@@ -156,9 +156,7 @@ AICOIN_ACCESS_SECRET=your_access_secret
 
 ## Client Configuration
 
-> **Note:** AiCoin 后台字段名和环境变量是反的：
-> - 后台 `api_key` → `AICOIN_ACCESS_KEY`
-> - 后台 `access_key` → `AICOIN_ACCESS_SECRET`
+> Get your API credentials at [AiCoin OpenAPI](https://www.aicoin.com/openapi)
 
 ### Claude Desktop
 
@@ -171,8 +169,8 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
       "command": "npx",
       "args": ["-y", "@aicoin/opendata-mcp"],
       "env": {
-        "AICOIN_ACCESS_KEY": "your_api_key_from_aicoin",
-        "AICOIN_ACCESS_SECRET": "your_access_key_from_aicoin"
+        "AICOIN_ACCESS_KEY_ID": "your_access_key_id",
+        "AICOIN_ACCESS_SECRET": "your_access_secret"
       }
     }
   }
@@ -190,8 +188,8 @@ Add to `.cursor/mcp.json`:
       "command": "npx",
       "args": ["-y", "@aicoin/opendata-mcp"],
       "env": {
-        "AICOIN_ACCESS_KEY": "your_api_key_from_aicoin",
-        "AICOIN_ACCESS_SECRET": "your_access_key_from_aicoin"
+        "AICOIN_ACCESS_KEY_ID": "your_access_key_id",
+        "AICOIN_ACCESS_SECRET": "your_access_secret"
       }
     }
   }
@@ -214,8 +212,8 @@ Add to `.vscode/mcp.json`:
       "command": "npx",
       "args": ["-y", "@aicoin/opendata-mcp"],
       "env": {
-        "AICOIN_ACCESS_KEY": "your_api_key_from_aicoin",
-        "AICOIN_ACCESS_SECRET": "your_access_key_from_aicoin"
+        "AICOIN_ACCESS_KEY_ID": "your_access_key_id",
+        "AICOIN_ACCESS_SECRET": "your_access_secret"
       }
     }
   }

package/build/index.js

@@ -28,11 +28,11 @@ function generateSignature(accessKeyId, accessSecret) {
 // src/client/api.ts
 var DOMAIN = process.env.AICOIN_BASE_URL || "https://open.aicoin.com";
 function getCredentials() {
-  const key = process.env.AICOIN_ACCESS_KEY;
+  const key = process.env.AICOIN_ACCESS_KEY_ID || process.env.AICOIN_ACCESS_KEY;
   const secret = process.env.AICOIN_ACCESS_SECRET;
   if (!key || !secret) {
     throw new Error(
-      "Missing AICOIN_ACCESS_KEY or AICOIN_ACCESS_SECRET"
+      "Missing AICOIN_ACCESS_KEY_ID or AICOIN_ACCESS_SECRET. Register at https://www.aicoin.com/openapi to get your API credentials."
     );
   }
   return { key, secret };
@@ -2248,6 +2248,196 @@ function registerHyperliquidTools(server2) {
   );
 }
 
+// src/tools/guide.ts
+import { z as z6 } from "zod";
+function registerGuideTools(server2) {
+  server2.tool(
+    "guide_get_api_key",
+    "Guide user to register AiCoin account and generate OpenAPI key. Call this when API returns 401/403 or credentials are missing.",
+    {},
+    async () => {
+      const guide = `# AiCoin OpenAPI Key Setup Guide
+
+## Step 1: Register / Login
+Visit https://www.aicoin.com and create an account (or log in).
+
+## Step 2: Go to OpenAPI Management
+Visit https://www.aicoin.com/openapi to manage your API keys.
+
+## Step 3: Create API Key
+Click "Create Key" and select your desired tier:
+
+| Tier | Price | Rate Limit | Features |
+|------|-------|------------|----------|
+| Basic | Free | 10 req/min | Market data, news, basic indicators |
+| Normal | \xA599/mo | 60 req/min | + Funding rate, liquidation data |
+| Premium | \xA5299/mo | 120 req/min | + Depth data, whale tracking |
+| Professional | \xA5999/mo | 300 req/min | + Full depth, all features |
+
+## Step 4: Configure MCP Server
+After creating the key, you will get two values:
+- **accessKeyId** \u2014 your public key ID
+- **accessSecret** \u2014 your signing secret
+
+Add them to your MCP client config:
+
+\`\`\`json
+{
+  "mcpServers": {
+    "aicoin-opendata": {
+      "command": "npx",
+      "args": ["-y", "@aicoin/opendata-mcp"],
+      "env": {
+        "AICOIN_ACCESS_KEY_ID": "<your accessKeyId>",
+        "AICOIN_ACCESS_SECRET": "<your accessSecret>"
+      }
+    }
+  }
+}
+\`\`\`
+
+After updating the config, restart your MCP client to apply.`;
+      return {
+        content: [{ type: "text", text: guide }]
+      };
+    }
+  );
+  server2.tool(
+    "guide_upgrade_tier",
+    "Guide user to upgrade API tier when current tier lacks permission for certain endpoints. Call this when API returns 403 or feature is tier-restricted.",
+    {
+      current_error: z6.string().optional().describe("The error message received"),
+      endpoint: z6.string().optional().describe("The endpoint that returned 403")
+    },
+    async ({ current_error, endpoint }) => {
+      const guide = `# AiCoin API Tier Upgrade Guide
+
+## Current Issue
+${current_error ? `Error: ${current_error}` : "Your current API tier does not have permission for this endpoint."}
+${endpoint ? `Endpoint: ${endpoint}` : ""}
+
+## API Tier Comparison
+
+| Feature | Basic (Free) | Normal (\xA599) | Premium (\xA5299) | Professional (\xA5999) |
+|---------|:---:|:---:|:---:|:---:|
+| Market tickers & K-lines | \u2705 | \u2705 | \u2705 | \u2705 |
+| News & flash | \u2705 | \u2705 | \u2705 | \u2705 |
+| Index data | \u2705 | \u2705 | \u2705 | \u2705 |
+| Funding rate history | \u274C | \u2705 | \u2705 | \u2705 |
+| Liquidation data | \u274C | \u2705 | \u2705 | \u2705 |
+| OI history | \u274C | \u2705 | \u2705 | \u2705 |
+| Whale order tracking | \u274C | \u274C | \u2705 | \u2705 |
+| Depth data | \u274C | \u274C | \u2705 | \u2705 |
+| Strategy signals | \u274C | \u274C | \u274C | \u2705 |
+| Full depth & grouped | \u274C | \u274C | \u274C | \u2705 |
+
+## How to Upgrade
+1. Visit https://www.aicoin.com/openapi
+2. Go to your API key management page
+3. Click "Upgrade" on your current key
+4. Select the tier that includes the features you need
+5. Complete payment
+
+After upgrading, your existing key will be automatically upgraded. No config changes needed.`;
+      return {
+        content: [{ type: "text", text: guide }]
+      };
+    }
+  );
+  server2.tool(
+    "guide_setup_ccxt_trade",
+    "Guide user to set up the AiCoin Trade MCP server (CCXT-based) for executing trades. Includes exchange API key setup and local proxy configuration.",
+    {
+      exchange: z6.string().optional().describe(
+        "Target exchange: binance, okx, bybit, bitget, gate, huobi, pionex, hyperliquid"
+      )
+    },
+    async ({ exchange }) => {
+      const ex = exchange?.toLowerCase() || "binance";
+      const needsPass = ex === "okx" || ex === "bitget";
+      const EX = ex.toUpperCase();
+      let keyBlock = `${EX}_API_KEY=your_api_key
+${EX}_SECRET=your_secret`;
+      if (needsPass) keyBlock += `
+${EX}_PASSPHRASE=your_passphrase`;
+      let envJson = `        "${EX}_API_KEY": "<your_api_key>",
+        "${EX}_SECRET": "<your_secret>"`;
+      if (needsPass) {
+        envJson += `,
+        "${EX}_PASSPHRASE": "<your_passphrase>"`;
+      }
+      const guide = getTradeGuide(ex, EX, keyBlock, envJson);
+      return {
+        content: [{ type: "text", text: guide }]
+      };
+    }
+  );
+}
+function getExchangeGuide(ex) {
+  const guides = {
+    binance: '1. Log in to https://www.binance.com\n2. Go to Account \u2192 API Management\n3. Create API key, enable "Spot Trading" permission\n4. Recommended: set IP whitelist',
+    okx: '1. Log in to https://www.okx.com\n2. Go to Account \u2192 API \u2192 Create API Key\n3. Set passphrase, enable "Trade" permission\n4. Note: OKX requires a passphrase in addition to key/secret',
+    bybit: '1. Log in to https://www.bybit.com\n2. Go to Account \u2192 API Management\n3. Create API key with "Trade" permission',
+    bitget: '1. Log in to https://www.bitget.com\n2. Go to Account \u2192 API Management\n3. Create API key with passphrase, enable "Trade"\n4. Note: Bitget requires a passphrase',
+    gate: '1. Log in to https://www.gate.io\n2. Go to Account \u2192 API Management\n3. Create API key with "Spot Trade" permission',
+    huobi: '1. Log in to https://www.huobi.com\n2. Go to Account \u2192 API Management\n3. Create API key with "Trade" permission',
+    pionex: "1. Log in to https://www.pionex.com\n2. Go to Account \u2192 API Management\n3. Create API key",
+    hyperliquid: "1. Visit https://app.hyperliquid.xyz\n2. Connect your wallet\n3. Go to API \u2192 Generate API Key"
+  };
+  return guides[ex] || guides.binance;
+}
+function getTradeGuide(ex, EX, keyBlock, envJson) {
+  return `# AiCoin Trade MCP Setup Guide (CCXT)
+
+> All API keys are stored locally only. They are never sent to AiCoin servers.
+
+## Step 1: Get Exchange API Key
+
+${getExchangeGuide(ex)}
+
+\`\`\`
+${keyBlock}
+\`\`\`
+
+## Step 2: Proxy Configuration
+
+Many exchanges require proxy access in certain regions.
+If you are in mainland China or behind a firewall, you likely need a local proxy.
+
+- If YES: set \`USE_PROXY=true\` and \`PROXY_URL\` (default: \`http://127.0.0.1:7890\`)
+- If NO: set \`USE_PROXY=false\` or leave it unset
+
+Common proxy ports:
+- Clash: 7890
+- V2Ray: 10808
+- Shadowsocks: 1080
+
+## Step 3: Configure MCP Client
+
+\`\`\`json
+{
+  "mcpServers": {
+    "aicoin-trade": {
+      "command": "npx",
+      "args": ["-y", "@aicoin/trade-mcp"],
+      "env": {
+        "DEFAULT_EXCHANGE": "${ex}",
+${envJson},
+        "USE_PROXY": "true",
+        "PROXY_URL": "http://127.0.0.1:7890"
+      }
+    }
+  }
+}
+\`\`\`
+
+## Security Notes
+- API keys are stored in your local MCP config only
+- Never share your secret key with anyone
+- Enable IP whitelist on the exchange if possible
+- For trading, enable "Trade" permission; disable "Withdraw"`;
+}
+
 // src/tools/index.ts
 function registerAllTools(server2) {
   registerCoinTools(server2);
@@ -2255,6 +2445,7 @@ function registerAllTools(server2) {
   registerMarketTools(server2);
   registerFeatureTools(server2);
   registerHyperliquidTools(server2);
+  registerGuideTools(server2);
 }
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicoin/opendata-mcp",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "AiCoin OpenData MCP Server - crypto market data via AiCoin Open API",
   "main": "build/index.js",
   "type": "module",