bitget-mcp-server 1.0.1 → 1.0.2

package/README.md

@@ -1,33 +1,65 @@
-# bitget-mcp-server
+<p align="center">
+  <img src="https://img.bitgetimg.com/multiLang/web/d54dfa8d6e4ccc3b1d42.svg" alt="Bitget" width="200" />
+</p>
 
-[![npm version](https://img.shields.io/npm/v/bitget-mcp-server.svg)](https://www.npmjs.com/package/bitget-mcp-server)
-[![license](https://img.shields.io/npm/l/bitget-mcp-server.svg)](https://www.npmjs.com/package/bitget-mcp-server)
-[![node](https://img.shields.io/node/v/bitget-mcp-server.svg)](https://www.npmjs.com/package/bitget-mcp-server)
+<h1 align="center">Bitget MCP Server</h1>
 
-[Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the **Bitget** cryptocurrency exchange. Connects AI assistants (Cursor, Claude, etc.) to Bitget's V2 REST API for market data, spot/futures trading, account management, and more.
+<p align="center">
+  <strong>Connect AI assistants to Bitget — trade, query, and manage your crypto portfolio through natural language.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/bitget-mcp-server"><img src="https://img.shields.io/npm/v/bitget-mcp-server.svg?style=flat-square&color=cb3837" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/bitget-mcp-server"><img src="https://img.shields.io/npm/dm/bitget-mcp-server.svg?style=flat-square&color=blue" alt="npm downloads" /></a>
+  <a href="https://www.npmjs.com/package/bitget-mcp-server"><img src="https://img.shields.io/node/v/bitget-mcp-server.svg?style=flat-square&color=43853d" alt="node version" /></a>
+  <a href="https://www.npmjs.com/package/bitget-mcp-server"><img src="https://img.shields.io/npm/l/bitget-mcp-server.svg?style=flat-square" alt="license" /></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=flat-square" alt="MCP compatible" /></a>
+  <a href="https://www.bitget.com"><img src="https://img.shields.io/badge/Exchange-Bitget-00b897?style=flat-square" alt="Bitget" /></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#available-modules">Modules</a> •
+  <a href="#tool-highlights">Tools</a> •
+  <a href="#configuration">Configuration</a> •
+  <a href="#security">Security</a>
+</p>
+
+---
+
+## What is this?
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives AI assistants — **Cursor**, **Claude Desktop**, **Windsurf**, and others — direct access to the Bitget cryptocurrency exchange.
+
+> **One config, 56+ tools.** Ask your AI to check prices, place trades, manage positions, and more.
+
+---
 
 ## Features
 
-- **57 tools** covering spot, futures, margin, copy trading, convert, earn, P2P, broker, and account management
-- **Read-only mode** (`--read-only`) to disable all write/trade operations
-- **Module filtering** (`--modules`) to expose only the tools you need
-- **Dynamic capability detection** — unavailable modules (e.g. earn) are auto-hidden from AI tool lists
-- **Structured error responses** with machine-readable error codes and suggestions
-- **`system_get_capabilities`** tool for agent-first capability discovery
-- **Client-side rate limiting** with token bucket per endpoint
-- **HMAC-SHA256 authentication** for private endpoints
-- **Proxy support** via `all_proxy` / `http_proxy` / `https_proxy` environment variables
+| | Feature | Description |
+|---|---------|-------------|
+| **56+ tools** | Full API coverage | Spot, futures, margin, copy trading, convert, earn, P2P, broker |
+| **Read-only mode** | `--read-only` flag | Disable all write/trade operations for safe exploration |
+| **Module filtering** | `--modules` flag | Expose only the tools you need |
+| **Smart detection** | Dynamic capabilities | Unavailable modules auto-hidden from AI tool lists |
+| **Agent-first** | `system_get_capabilities` | Machine-readable capability discovery for agent planning |
+| **Rate limiting** | Token bucket | Client-side rate limiting per endpoint prevents API abuse |
+| **Auth** | HMAC-SHA256 | Industry-standard Bitget API authentication |
+| **Structured errors** | Error codes + suggestions | Machine-parseable errors with actionable suggestions |
+
+---
 
 ## Quick Start
 
 ### Prerequisites
 
-- Node.js >= 18
-- A [Bitget API key](https://www.bitget.com/account/newapi) with appropriate permissions
+- **Node.js** >= 18
+- A [**Bitget API key**](https://www.bitget.com/account/newapi) with appropriate permissions
 
-### Cursor / Claude Desktop (recommended)
+### Cursor
 
-Add to your MCP configuration (e.g. `.cursor/mcp.json`):
+Add to `.cursor/mcp.json` in your project root:
 
 ```json
 {
@@ -45,14 +77,16 @@ Add to your MCP configuration (e.g. `.cursor/mcp.json`):
 }
 ```
 
-### Read-Only Mode (no trading)
+### Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
 ```json
 {
   "mcpServers": {
     "bitget": {
       "command": "npx",
-      "args": ["-y", "bitget-mcp-server", "--modules", "all", "--read-only"],
+      "args": ["-y", "bitget-mcp-server", "--modules", "all"],
       "env": {
         "BITGET_API_KEY": "your-api-key",
         "BITGET_SECRET_KEY": "your-secret-key",
@@ -63,47 +97,98 @@ Add to your MCP configuration (e.g. `.cursor/mcp.json`):
 }
 ```
 
-### With Proxy
+### Read-Only Mode
+
+For safe exploration without trading risk:
 
 ```json
 {
   "mcpServers": {
     "bitget": {
       "command": "npx",
-      "args": ["-y", "bitget-mcp-server", "--modules", "all"],
+      "args": ["-y", "bitget-mcp-server", "--modules", "all", "--read-only"],
       "env": {
         "BITGET_API_KEY": "your-api-key",
         "BITGET_SECRET_KEY": "your-secret-key",
-        "BITGET_PASSPHRASE": "your-passphrase",
-        "all_proxy": "http://127.0.0.1:7890"
+        "BITGET_PASSPHRASE": "your-passphrase"
       }
     }
   }
 }
 ```
 
+---
+
 ## Available Modules
 
 | Module | Tools | Description |
-|--------|-------|-------------|
-| `spot` | 13 | Spot market data + trading |
-| `futures` | 14 | Futures market data + trading + position management |
+|:-------|:-----:|:------------|
+| `spot` | 13 | Spot market data + order placement & management |
+| `futures` | 14 | Futures market data + trading + leverage + positions |
 | `account` | 8 | Assets, transfers, withdrawals, deposits, sub-accounts |
-| `margin` | 7 | Margin trading, borrow/repay |
-| `copytrading` | 5 | Copy trading (futures + spot), auto trader selection |
-| `convert` | 3 | Coin conversion with real-time quotes |
-| `earn` | 3 | Savings & staking products (auto-detected availability) |
-| `p2p` | 2 | P2P merchant list and orders |
+| `margin` | 7 | Cross/isolated margin trading, borrow & repay |
+| `copytrading` | 5 | Copy trading with auto trader selection |
+| `convert` | 3 | Coin conversion with real-time quoted prices |
+| `earn` | 3 | Savings & staking (auto-detected availability) |
+| `p2p` | 2 | P2P merchant list and order history |
 | `broker` | 3 | Broker account and API key management |
 
-Default modules: `spot`, `futures`, `account`. Use `--modules all` to enable everything.
+> **Default:** `spot`, `futures`, `account`. Use `--modules all` to enable everything.
+
+---
 
-## CLI Options
+## Tool Highlights
+
+### Market Data *(no auth required)*
+
+| Tool | Description |
+|:-----|:------------|
+| `spot_get_ticker` / `futures_get_ticker` | Real-time price and 24h stats |
+| `spot_get_depth` / `futures_get_depth` | Live order book |
+| `spot_get_candles` / `futures_get_candles` | K-line / candlestick data |
+| `futures_get_funding_rate` | Current and historical funding rates |
+| `futures_get_open_interest` | Open interest by symbol |
+
+### Trading
+
+| Tool | Description |
+|:-----|:------------|
+| `spot_place_order` / `futures_place_order` | Place single or batch orders |
+| `spot_place_plan_order` | Trigger / stop-loss / take-profit orders |
+| `futures_set_leverage` | Adjust leverage per symbol |
+| `futures_get_positions` | View current open positions |
+
+### Account & Transfers
+
+| Tool | Description |
+|:-----|:------------|
+| `get_account_assets` | Balances across all account types |
+| `transfer` | Internal transfers between spot, futures, funding |
+| `get_deposit_address` | Generate deposit addresses |
+| `withdraw` | On-chain withdrawals |
+
+### Copy Trading
+
+| Tool | Description |
+|:-----|:------------|
+| `copy_get_traders` | Browse available elite traders |
+| `copy_place_order` | Follow a trader (auto-selects when `traderId` omitted) |
+
+### Agent Utilities
+
+| Tool | Description |
+|:-----|:------------|
+| `system_get_capabilities` | Full module availability snapshot for planning |
+
+---
+
+## Configuration
+
+### CLI Options
 
 ```
-Usage: bitget-mcp-server [options]
+bitget-mcp-server [options]
 
-Options:
   --modules <list>     Comma-separated modules (default: spot,futures,account)
                        Use "all" to load all modules
   --read-only          Disable all write/trade operations
@@ -111,51 +196,30 @@ Options:
   --version            Show version
 ```
 
-## Environment Variables
+### Environment Variables
 
 | Variable | Required | Description |
-|----------|----------|-------------|
-| `BITGET_API_KEY` | For private endpoints | Bitget API key |
-| `BITGET_SECRET_KEY` | For private endpoints | Bitget secret key |
-| `BITGET_PASSPHRASE` | For private endpoints | Bitget API passphrase |
+|:---------|:---------|:------------|
+| `BITGET_API_KEY` | Yes * | Bitget API key |
+| `BITGET_SECRET_KEY` | Yes * | Bitget secret key |
+| `BITGET_PASSPHRASE` | Yes * | Bitget API passphrase |
 | `BITGET_API_BASE_URL` | No | API base URL (default: `https://api.bitget.com`) |
 | `BITGET_TIMEOUT_MS` | No | Request timeout in ms (default: `15000`) |
-| `all_proxy` | No | Proxy URL for all requests |
-
-## Tool Highlights
-
-### Market Data (no auth required)
-- `spot_get_ticker` / `futures_get_ticker` — Real-time price
-- `spot_get_depth` / `futures_get_depth` — Order book
-- `spot_get_candles` / `futures_get_candles` — K-line data
-- `futures_get_funding_rate` — Funding rate history
-- `futures_get_open_interest` — Open interest
-
-### Trading
-- `spot_place_order` / `futures_place_order` — Place orders (single or batch)
-- `spot_place_plan_order` — Trigger/stop orders
-- `futures_set_leverage` — Adjust leverage
-- `futures_get_positions` — Current positions
 
-### Account
-- `get_account_assets` — Balances across all account types
-- `transfer` — Internal transfers between accounts
-- `get_deposit_address` — Deposit addresses
+> \* Required for private endpoints. Public market data tools work without auth.
 
-### Copy Trading
-- `copy_place_order` — Auto-selects trader when `traderId` is omitted
-- `copy_get_traders` — Browse available traders
-
-### Agent Utilities
-- `system_get_capabilities` — Full module availability snapshot for agent planning
+---
 
 ## Security
 
-- API credentials are passed via environment variables, never hardcoded
-- `--read-only` mode prevents all write operations at the server level
-- All private requests use HMAC-SHA256 signatures
-- Rate limiting prevents accidental API abuse
+- API credentials are passed via **environment variables**, never hardcoded or logged
+- **`--read-only` mode** prevents all write operations at the server level
+- All private requests are signed with **HMAC-SHA256**
+- **Client-side rate limiting** prevents accidental API abuse
+- Structured error responses never leak credentials or internal state
+
+---
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/dist/index.js

@@ -6,7 +6,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/constants.ts
 var SERVER_NAME = "bitget-mcp-server";
-var SERVER_VERSION = "1.0.1";
+var SERVER_VERSION = "1.0.2";
 var MODULES = [
   "spot",
   "futures",