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