Orderly MCP

🚀 Orderly Network MCP 服務器

Orderly Network MCP 服務器是一個模型上下文協議（MCP）服務器，為 Orderly Network（一個全鏈永續期貨交易基礎設施）提供文檔和 SDK 使用模式。

🚀 快速開始

使用以下命令為你的 AI 客戶端安裝 MCP 服務器：

npx @orderly.network/mcp-server init --client <client>

支持的客戶端：claude、cursor、vscode、codex、opencode

示例

# OpenCode
npx @orderly.network/mcp-server init --client opencode

# Claude Code
npx @orderly.network/mcp-server init --client claude

# Cursor
npx @orderly.network/mcp-server init --client cursor

# VS Code (搭配 Copilot)
npx @orderly.network/mcp-server init --client vscode

# 交互模式（提示選擇客戶端）
npx @orderly.network/mcp-server init

此命令將執行以下操作：

1. 為你的 AI 客戶端創建合適的配置文件。
2. 將 @orderly.network/mcp-server 作為開發依賴項進行安裝。
3. 指導你完成後續步驟。

安裝完成後：重啟你的 AI 客戶端，然後嘗試詢問：“如何連接到 Orderly Network？”

✨ 主要特性

此 MCP 服務器使 AI 助手能夠回答有關 Orderly Network 的問題，並指導開發者使用 Orderly SDK v2 構建 React 組件。

特性詳情

• 文檔搜索：查詢 Orderly 關於架構、API 和概念的文檔。
• SDK 使用模式：獲取所有 v2 鉤子（如 useOrderEntry、usePositionStream 等）的代碼示例。
• 合約地址查詢：查找所有支持鏈的智能合約地址。
• 工作流指南：逐步解釋常見的開發任務。
• 組件指南：提供構建交易 UI 組件的模式。
• API 參考：REST 和 WebSocket 端點文檔。
• 索引器 API：交易指標、賬戶事件、交易量統計和排名信息。

📦 安裝指南

快速安裝（推薦）

使用 CLI 自動配置你的 AI 客戶端：

npx @orderly.network/mcp-server init --client <client>

可用客戶端：

手動設置

如果你更喜歡手動配置，或者自動設置對你的客戶端不起作用，可以按照以下步驟操作：

前提條件

• Node.js 18 或更高版本
• Yarn（或 npm）

從源代碼進行設置

1. 克隆或創建項目：

cd orderly-mcp

2. 安裝依賴項：

yarn install

3. 構建項目：

yarn build

運行服務器

MCP 服務器支持兩種模式：

1. Stdio 模式（默認 - 適用於本地 MCP 客戶端）

適用於本地 AI 助手：

yarn start

手動配置

如果你沒有使用自動安裝程序，請將以下配置添加到你的 AI 客戶端：

Claude Code (.mcp.json)：

{
  "mcpServers": {
    "orderly": {
      "command": "npx",
      "args": ["@orderly.network/mcp-server@latest"]
    }
  }
}

Cursor (.cursor/mcp.json)：

{
  "mcpServers": {
    "orderly": {
      "command": "npx",
      "args": ["@orderly.network/mcp-server@latest"]
    }
  }
}

VS Code (.vscode/mcp.json)：

{
  "servers": {
    "orderly": {
      "command": "npx",
      "args": ["@orderly.network/mcp-server@latest"]
    }
  }
}

OpenCode (.opencode/mcp.json)：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "orderly": {
      "type": "local",
      "command": ["npx", "@orderly.network/mcp-server@latest"],
      "enabled": true
    }
  }
}

Codex (~/.codex/config.toml)：

[mcp_servers.orderly]
command = "npx"
args = ["@orderly.network/mcp-server@latest"]

2. HTTP 模式（適用於託管部署）

作為 HTTP 服務器運行以實現遠程訪問：

yarn start:http

服務器將在端口 3000（或 PORT 環境變量指定的端口）啟動：

• MCP 端點：http://localhost:3000/
• 健康檢查：http://localhost:3000/health

Docker 部署：

# 構建鏡像
docker build -t orderly-mcp .

# 運行容器
docker run -p 3000:3000 orderly-mcp

Docker 鏡像默認以無狀態 HTTP 模式運行。

開發

若要進行自動重建開發：

yarn dev

代碼質量

本項目使用 ESLint 和 Prettier 來保證代碼質量：

# 運行代碼檢查
yarn lint

# 修復代碼檢查問題
yarn lint:fix

# 格式化代碼
yarn format

# 檢查代碼格式
yarn format:check

# 類型檢查
yarn typecheck

💻 使用示例

搜索文檔

用戶：“Orderly 的金庫系統是如何工作的？”

AI 使用 search_orderly_docs 工具，查詢詞為 “vault system”
→ 返回跨鏈金庫架構的解釋

獲取 SDK 使用模式

用戶：“向我展示如何使用 useOrderEntry”

AI 使用 get_sdk_pattern 工具，模式名稱為 “useOrderEntry”
→ 返回鉤子文檔和使用示例

查找合約地址

用戶：“Arbitrum 上 USDC 的地址是什麼？”

AI 使用 get_contract_addresses 工具，鏈名為 “arbitrum”，合約類型為 “USDC”
→ 返回合約地址

解釋工作流

用戶：“我如何下第一筆訂單？”

AI 使用 explain_workflow 工具，工作流名稱為 “place-first-order”
→ 返回逐步指南

組件構建指南

用戶：“我如何構建一個訂單輸入組件？”

AI 使用 get_component_guide 工具，組件類型為 “order-entry”
→ 返回完整的實現指南

📚 詳細文檔

可用工具

1. search_orderly_docs

在 Orderly 文檔中搜索特定主題、概念或問題。

參數：

• query（字符串，必需）：關於 Orderly 的搜索查詢詞。
• limit（數字，可選）：最大結果數（默認值：5）。

示例查詢：

• "金庫系統如何工作"
• "交易費用"
• "訂單類型"
• "槓桿計算"

2. get_sdk_pattern

獲取 Orderly SDK v2 鉤子和完整 DEX 組件的代碼示例和使用模式。

參數：

• pattern（字符串，必需）：鉤子或模式名稱（例如，'useOrderEntry'、'wallet-connection'、'LightweightChart'）。
• includeExample（布爾值，可選）：是否包含完整代碼示例（默認值：true）。

可用模式：

• 賬戶：useAccount、useWalletConnector
• 訂單：useOrderEntry、useOrderStream
• 倉位：usePositionStream、useCollateral
• 市場數據：useOrderbookStream、useMarkPrice、useTickerStream
• 鏈：useChains
• 資產：useDeposit
• 圖表：LightweightChart、TradingViewWidgetSetup、Real-timeKlineDataviaWebSocket
• 交易組件：CreateOrder、Orderbook、SymbolHeader、SymbolSelection
• 倉位組件：Positions、UpdatePosition、ClosePosition
• 錢包組件：ConnectWalletButton、WalletConnection、EvmDropdownMenu
• WebSocket 服務：websocket.service（即時 K 線數據）

3. get_contract_addresses

獲取 Orderly 在特定鏈上的智能合約地址。

參數：

• chain（字符串，必需）：鏈名（例如，'arbitrum'、'optimism'、'base'）。
• contractType（字符串，可選）：合約類型或 'all'（默認值：'all'）。
• network（字符串，可選）：'mainnet' 或 'testnet'（默認值：'mainnet'）。

支持的鏈：

• EVM：ethereum、arbitrum、optimism、base、mantle、solana
• Orderly L2：orderlyL2

4. explain_workflow

獲取常見開發工作流的逐步解釋。

參數：

• workflow（字符串，必需）：工作流名稱。

可用工作流：

• wallet-connection：連接錢包並創建 Orderly 密鑰。
• place-first-order：完成下第一筆交易的完整流程。
• deposit-funds：向 Orderly 存入 USDC/代幣。
• set-tp-sl：設置止盈和止損。
• subaccount-management：創建和管理子賬戶。

5. get_api_info

獲取關於 Orderly REST API 或 WebSocket 流的信息。

參數：

• type（字符串，必需）：'rest'、'websocket' 或 'auth'。
• endpoint（字符串，可選）：特定的端點或流名稱。

6. get_indexer_api_info

獲取關於 Orderly Indexer API 的信息，用於獲取交易指標、賬戶事件、交易量統計和排名。

參數：

• endpoint（字符串，可選）：特定的端點路徑或名稱（例如，'/events_v2'、'daily_volume'、'ranking/positions'）。
• category（字符串，可選）：按類別過濾（例如，'trading_metrics'、'events'、'ranking'）。

可用類別：

• 交易指標：每日交易量、費用、永續合約交易數據（/daily_volume、/daily_trading_fee、/daily_orderly_perp）。
• 事件：帶分頁的賬戶事件（/events_v2） - 交易、結算、清算、交易記錄。
• 交易量統計：賬戶和經紀商的交易量統計（/get_account_volume_statistic、/get_broker_volume_statistic）。
• 排名：倉位、盈虧、交易量、存款/提款（/ranking/positions、/ranking/realized_pnl、/ranking/trading_volume、/ranking/deposit、/ranking/withdraw）。

示例：

# 獲取所有索引器 API 端點
get_indexer_api_info

# 獲取特定端點的詳細信息
get_indexer_api_info endpoint="/events_v2"

# 獲取某個類別下的所有端點
get_indexer_api_info category="trading_metrics"

7. get_component_guide

獲取使用 Orderly SDK 構建 React UI 組件的指南。

參數：

• component（字符串，必需）：組件類型。
• complexity（字符串，可選）：'minimal'、'standard' 或 'advanced'（默認值：'standard'）。

可用組件：

• order-entry：訂單輸入表單。
• orderbook：市場深度顯示。
• positions：倉位管理表。
• wallet-connector：錢包連接 UI。

8. get_orderly_one_api_info

獲取關於 Orderly One API 的信息，用於 DEX 創建、升級和管理。

參數：

• endpoint（字符串，可選）：特定的端點路徑或名稱（例如，'/dex'、'verify-tx'、'/theme/modify'）。
• category（字符串，可選）：按類別過濾（例如，'auth'、'dex'、'graduation'、'theme'、'stats'、'leaderboard'、'admin'）。

可用類別：

• 認證：基於錢包簽名的認證（隨機數、驗證、確認）。
• DEX 管理：DEX 創建、更新、刪除、部署和管理交易所。
• 升級系統：從演示版升級到全功能經紀商並進行費用分成。
• 主題：基於 AI 的主題生成和 CSS 定製。
• 統計：平臺範圍的統計和分析。
• 排行榜：DEX 排名、性能指標和排行榜。
• 管理：平臺管理的管理操作。

示例：

# 獲取概述和認證流程
get_orderly_one_api_info

# 獲取某個類別下的所有端點
get_orderly_one_api_info category="dex"
get_orderly_one_api_info category="graduation"

# 獲取特定端點的詳細信息
get_orderly_one_api_info endpoint="verify-tx"
get_orderly_one_api_info endpoint="/theme/modify"

可用資源

通過資源 URI 訪問全面的文檔。所有資源都支持帶分頁的模糊搜索：

查詢參數：

• search（必需） - 模糊搜索查詢詞
• page（可選） - 頁碼（默認值：1）
• limit（可選） - 每頁結果數，最多 10 條（默認值：10）

資源：

• orderly://overview - 高級協議架構（無需搜索）
• orderly://sdk/hooks?search=orderEntry - 按名稱、描述或類別搜索 SDK 鉤子
• orderly://sdk/components?search=Checkbox - 按名稱或描述搜索組件
• orderly://contracts?search=arbitrum - 按鏈或名稱搜索合約
• orderly://workflows?search=wallet - 按名稱或步驟搜索工作流
• orderly://api/rest?search=position - 搜索 REST API 端點
• orderly://api/websocket?search=orderbook - 搜索 WebSocket 流
• orderly://api/indexer?search=events - 搜索索引器 API 端點

示例：

orderly://sdk/hooks?search=useOrderEntry&page=1&limit=5

🔧 技術細節

數據來源

此 MCP 服務器包含來自以下來源的嵌入式數據：

1. Orderly 文檔：架構、概念和指南。
2. SDK 使用模式：來自 @orderly.network/hooks 的 v2 鉤子示例和模式。
3. DEX 示例：來自 example-dex 倉庫的完整工作組件。
4. 合約地址：所有支持鏈上已部署的合約。
5. API 規範：REST 和 WebSocket 端點。
6. 索引器 API：交易指標、賬戶事件、交易量統計和排名。
7. Orderly One API：DEX 創建、升級和管理 API 文檔。
8. 工作流指南：常見開發任務的解釋。

項目結構

orderly-mcp/
├── src/
│   ├── index.ts                 # 主服務器入口（stdio 模式）
│   ├── http-server.ts           # HTTP 服務器入口（無狀態模式）
│   ├── server.ts                # 共享 MCP 服務器邏輯
│   ├── tools/
│   │   ├── searchDocs.ts        # 文檔搜索
│   │   ├── sdkPatterns.ts       # SDK 模式查找
│   │   ├── contracts.ts         # 合約地址查找
│   │   ├── workflows.ts         # 工作流解釋
│   │   ├── apiInfo.ts           # API 文檔
│   │   ├── indexerApi.ts        # 索引器 API 文檔
│   │   ├── componentGuides.ts   # 組件構建指南
│   │   └── orderlyOneApi.ts     # Orderly One API 文檔
│   ├── resources/
│   │   └── index.ts             # 資源處理程序
│   └── data/
│       ├── documentation.json   # 可搜索的文檔塊
│       ├── sdk-patterns.json    # SDK 模式和示例
│       ├── contracts.json       # 合約地址
│       ├── workflows.json       # 工作流解釋
│       ├── api.json             # API 規範
│       ├── indexer-api.json     # 索引器 API 文檔
│       ├── orderly-one-api.json # Orderly One API 文檔
│       ├── component-guides.json # 組件指南
│       └── resources/
│           └── overview.md      # 協議概述
├── .vscode/                     # VS Code 設置
│   ├── settings.json
│   └── extensions.json
├── package.json
├── tsconfig.json
├── eslint.config.mjs            # ESLint 配置
├── .prettierrc                  # Prettier 配置
├── .gitignore
├── .dockerignore                # Docker 忽略規則
├── Dockerfile                   # Docker 構建配置
└── README.md

更新數據

src/data/ 中的所有數據文件都是通過 scripts/ 文件夾中的腳本自動生成的。請勿手動編輯 JSON 文件 - 當再生腳本運行時，它們將被覆蓋。

前提條件

1. .env 文件中包含 NEAR AI API 密鑰：NEAR_AI_API_KEY=your_key
2. 在以下鏈接獲取 API 密鑰：https://cloud.near.ai/api-keys

完全再生（推薦）

從頭開始生成所有內容：

# 1. 下載最新的官方文檔
curl -o llms-full.txt https://orderly.network/docs/llms-full.txt

# 2. 拆分 Telegram 導出文件（如果有）
node scripts/split_telegram_chats.js

# 3. 分析 Telegram 聊天記錄 → tg_analysis.json
node scripts/analyze_chat_openai.js

# 4. 分析文檔 → docs_analysis.json
node scripts/analyze_llms_full.js

# 5. 從源代碼獲取 SDK 模式（免費 - 無需調用 AI）
node scripts/analyze_sdk.js

# 6. 從 example-dex 倉庫獲取 DEX 示例
# 選項 A：基本模式（免費 - 無需調用 AI）
git clone --depth 1 https://github.com/orderlynetwork/example-dex.git /tmp/example-dex
node scripts/analyze_example_dex.js
node scripts/enrich_sdk_patterns_with_examples.js

# 選項 B：AI 增強模式（約 $1 - 3，文檔質量更好）
# git clone --depth 1 https://github.com/orderlynetwork/example-dex.git /tmp/example-dex
# node scripts/analyze_example_dex.js
# USE_AI=true node scripts/enrich_sdk_patterns_with_examples.js

# 7. 生成文檔和工作流
node scripts/generate_mcp_data.js

# 8. 從 OpenAPI 規範生成 API 文檔
node scripts/generate_api_from_openapi.js

# 9. 從 OpenAPI 規範生成索引器 API 文檔
node scripts/generate_indexer_api.js

# 10. 生成合約地址
node scripts/generate_contracts.js

# 11. 構建並測試
yarn build && yarn test:run

僅更新文檔

如果你只想從官方文檔刷新數據，而不使用 Telegram 數據：

# 1. 下載最新的文檔
curl -o llms-full.txt https://orderly.network/docs/llms-full.txt

# 2. 僅分析文檔
node scripts/analyze_llms_full.js

# 3. 生成（如果存在，將使用現有的 tg_analysis.json）
node scripts/generate_mcp_data.js

# 4. 構建
yarn build

數據文件

🤝 貢獻

若要添加新內容，你需要更新源數據並重新生成：

1. 新文檔：更新 llms-full.txt 或 Telegram 導出文件，然後運行生成腳本。
2. 新 SDK 模式：SDK 會自動從 GitHub 解析 - 當 SDK 更新時，模式會自動出現。
3. 新 DEX 示例：克隆 example-dex 倉庫並運行分析腳本。
4. 新鏈：更新源文檔，然後重新生成。
5. 新工作流：添加到源文檔或 Telegram 聊天記錄中，然後重新生成。

📄 許可證

本項目採用 MIT 許可證。

🛠️ 支持

• Orderly 文檔：https://orderly.network/docs
• SDK 倉庫：https://github.com/OrderlyNetwork/js-sdk
• Orderly Discord：https://discord.gg/OrderlyNetwork