diff --git a/docs/en/docs/mcp.md b/docs/en/docs/mcp.md index 4bd98c12..dbfe9f58 100644 --- a/docs/en/docs/mcp.md +++ b/docs/en/docs/mcp.md @@ -6,167 +6,113 @@ sidebarCollapsed: true id: mcp --- -# MCP +# Longbridge MCP Service -Longbridge provides an online MCP service so AI tools can securely access market and account capabilities through the Model Context Protocol. +Longbridge provides a hosted MCP (Model Context Protocol) service that lets you use Longbridge market data and account capabilities directly from AI coding assistants and chat tools — without managing API keys manually. -- MCP endpoint: `https://openapi.longportapp.com/mcp` -- OAuth discovery: `https://openapi.longportapp.com/.well-known/oauth-authorization-server` +**MCP endpoint:** `https://openapi.longportapp.com/mcp` -> This page describes the **hosted Longbridge MCP service** and its **OAuth authentication flow**. +## Prerequisites -## What the Longbridge MCP service can do +- An active Longbridge account with onboarding completed +- An AI client that supports MCP OAuth 2.1 (see compatibility note below) -After authorization, MCP clients can use Longbridge capabilities such as: +## Available capabilities -- Market quotes and snapshots -- Candlesticks and historical data queries -- Account overview and position queries -- Trading actions (subject to account permissions and product rules) +Once connected, MCP clients can call the following tools: -Actual tool availability may vary by region, account level, and permission scope. +| Category | Description | +| --- | --- | +| Market data | Real-time quotes, candlesticks, historical data queries | +| Account information | Account overview, assets, and position queries | +| Trading actions | Place, modify, and cancel orders (subject to account permissions and regional restrictions) | -## OAuth authentication flow - -Longbridge MCP uses OAuth so users can authorize clients without sharing raw API secrets. - -### 1) Start MCP connection from your client - -In your MCP-capable client (for example Cursor, Claude Desktop, or Cherry Studio), choose to connect to the Longbridge MCP server. - -### 2) Redirect to Longbridge authorization page - -The client opens a browser page for Longbridge sign-in and consent. - -### 3) Sign in and grant permissions - -Review requested scopes and approve access. - -### 4) Receive authorization and establish session - -After approval, the client receives OAuth credentials and the MCP session becomes available. - -### 5) Refresh and revoke - -- Access may expire and be refreshed according to OAuth policy. -- You can revoke access from your Longbridge security/authorization settings at any time. - -## Client compatibility note - -Some clients that do not fully implement the MCP OAuth 2.1 flow may fail to connect to Longbridge MCP. - -For example, older versions of certain clients (such as early Cherry Studio releases) may not complete OAuth correctly. Please upgrade to the latest version of your client. - -## Security notes - -- OAuth credentials are sensitive and should be stored securely by your client. -- Use least-privilege scopes whenever possible. -- For trading-related prompts, always require human confirmation before order placement. +Actual tool availability varies by region, account level, and granted scopes. ## Client setup -> Note: Client MCP configuration format may change by version. Prefer the client official MCP docs/UI as source of truth, and use the Longbridge MCP server URL below. - -### ChatGPT +> Configuration format may vary across client versions. Treat your client's official MCP documentation as the source of truth. The core parameter you need is the server URL below. -In ChatGPT, open **Settings → Connectors / MCP** (or the MCP entry in your workspace settings), then add a remote MCP server: +In any MCP-capable client, add Longbridge as a remote MCP server: ```json { "mcpServers": { "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" + "url": "https://openapi.longportapp.com/mcp" } } } ``` -Then complete OAuth sign-in and grant scopes. +Where to find the MCP configuration entry in each client: -### Claude Code +- **Cursor**: Settings → MCP Servers → Add Remote MCP Server +- **Claude Code**: MCP config file or the `claude mcp add` command +- **ChatGPT**: Settings → Connectors (or the workspace MCP configuration entry) +- **Zed**: `context_servers` key in `settings.json` (key name is customizable) +- **Cherry Studio**: Settings → MCP Servers → Add -In Claude Code MCP settings, add a remote MCP server: - -```json -{ - "mcpServers": { - "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" - } - } -} -``` +After saving the configuration, the client will guide you through the OAuth authorization flow automatically. -Finish OAuth in browser, then return to Claude Code to start using tools. +## OAuth authorization flow -### Cursor +Longbridge MCP uses standard OAuth 2.1. You never need to paste API keys or tokens into the client. -Open **Cursor Settings → MCP Servers**, add a remote MCP server endpoint: - -```json -{ - "mcpServers": { - "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" - } - } -} +``` +AI client Browser Longbridge + | | | + |--- initiate MCP ------->| | + | |--- redirect to auth ------>| + | |<-- show login & consent ---| + | |--- sign in & approve ------>| + |<-- return credentials --| | + |--- call tools with credentials ----------------------->| ``` -Complete OAuth authorization and verify tools are listed. +**Steps:** -### Zed +1. **Initiate connection** — Adding the Longbridge MCP config and calling a tool for the first time triggers the authorization flow +2. **Browser redirect** — The client opens a browser tab with the Longbridge login and consent page +3. **Sign in and approve** — Log in with your Longbridge account and review and accept the requested permission scopes +4. **Session established** — After approval, the client receives credentials and MCP tools become available +5. **Credential maintenance** — Credentials are refreshed automatically per OAuth policy; to revoke access, visit Longbridge account security settings -Open `settings.json`, add: +## Client compatibility -```json -{ - "context_servers": { - "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" - } - } -} -``` +Longbridge MCP requires clients that fully implement **MCP OAuth 2.1**. Clients with incomplete support will fail during the authorization flow. -Then authorize via OAuth and return to Zed for usage. +Known issue: early versions of Cherry Studio do not support the full OAuth flow. Please upgrade to the latest release. -### OpenClaw +If another client fails to connect, check its version and MCP support documentation. -In OpenClaw MCP/tool integration settings, add Longbridge remote MCP endpoint: - -```json -{ - "mcpServers": { - "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" - } - } -} -``` +## Security recommendations -Complete OAuth and confirm the MCP tools are available in your session. +- **Least privilege**: Only approve the scopes required for your current task; avoid over-granting +- **Trading confirmation**: For any order placement prompt, explicitly instruct the AI to ask for human confirmation before executing +- **Credential handling**: OAuth credentials are managed by your client; avoid copying them into untrusted environments +- **Regular review**: Periodically check and revoke unused authorizations in your Longbridge account security settings ## Recommended usage pattern -1. Start with read-only tasks (quote/account/position). -2. Add trading actions only after confirming permission scopes and risk controls. -3. Set guardrails in prompts (max amount, symbol allowlist, confirmation required). +1. **Start with read-only tools**: Begin with market data, account overview, and position queries to learn tool behavior at low risk +2. **Gradually enable trading**: Enable order placement only after verifying scope configuration and your own risk controls +3. **Add guardrails in prompts**: For example, "keep each trade under X", "always confirm with me before placing an order" ## Troubleshooting ### OAuth sign-in failed -- Confirm your Longbridge account is in good standing. -- Retry authorization from the MCP client. -- Check whether the requested scopes are supported for your account. +- Confirm your Longbridge account is in good standing and identity verification is complete +- Remove the existing MCP configuration from the client and re-add it to trigger a fresh authorization +- Check whether the requested scopes are supported for your account type ### Connected but some tools are missing -- Your account/region may not have those permissions. -- Re-authorize if scope has changed. +- Account or regional restrictions: certain markets or features may be limited by account level or region +- Scope changes: if tool capabilities have been updated, re-authorize to receive the new scopes ### Permission denied on trading actions -- Verify trading permissions and market eligibility on your account. -- Ensure the MCP session has the required OAuth scopes. +- Verify trading permissions and market eligibility on your account +- Confirm that the current MCP session's OAuth scopes include trading-related permissions diff --git a/docs/zh-CN/docs/getting-started.md b/docs/zh-CN/docs/getting-started.md index 47d4d767..9eeb5b75 100644 --- a/docs/zh-CN/docs/getting-started.md +++ b/docs/zh-CN/docs/getting-started.md @@ -163,7 +163,7 @@ oauth = OAuth2Session(client_id, redirect_uri=redirect_uri) authorization_url, state = oauth.authorization_url( 'https://openapi.longportapp.com/oauth2/authorize' ) -print(f'请访问此 URL 进行授权: {authorization_url}') +print(f'请访问此 URL 进行授权：{authorization_url}') # 授权后获取回调 URL authorization_response = input('请输入完整的回调 URL: ') @@ -201,7 +201,7 @@ const authorizationUri = client.authorizeURL({ redirect_uri: 'http://localhost:60355/callback', }); -console.log('请访问此 URL 进行授权:', authorizationUri); +console.log('请访问此 URL 进行授权：', authorizationUri); // 授权后使用 code 获取 token const tokenParams = { diff --git a/docs/zh-CN/docs/mcp.md b/docs/zh-CN/docs/mcp.md index 370093b7..2cfd2bb5 100644 --- a/docs/zh-CN/docs/mcp.md +++ b/docs/zh-CN/docs/mcp.md @@ -6,167 +6,113 @@ sidebarCollapsed: true id: mcp --- -# MCP +# Longbridge MCP 服务 -Longbridge 提供在线 MCP 服务，支持 AI 工具通过 Model Context Protocol 安全访问行情与账户能力。 +Longbridge 提供托管的 MCP（Model Context Protocol）服务，让你在 AI 编程助手或对话工具中直接使用 Longbridge 的行情与账户能力，无需手动管理 API 密钥。 -- MCP 服务地址：`https://openapi.longportapp.com/mcp` -- OAuth 发现地址：`https://openapi.longportapp.com/.well-known/oauth-authorization-server` +**MCP 服务地址：** `https://openapi.longportapp.com/mcp` -> 本文只介绍 **Longbridge MCP 在线服务** 及其 **OAuth 认证流程**。 +## 前置条件 -## Longbridge MCP 在线服务能力 +- 已拥有 Longbridge 账户并完成开户 +- 使用支持 MCP OAuth 2.1 的 AI 客户端（见下方兼容性说明） -在完成授权后，MCP 客户端可以使用 Longbridge 的能力，例如： +## 可用能力 -- 行情快照与实时查询 -- K 线与历史数据查询 -- 账户概览与持仓查询 -- 交易相关操作（取决于账户权限与产品规则） +接入后，MCP 客户端可调用以下能力： -实际可用能力会因地区、账户等级和授权范围而有所不同。 +| 能力类别 | 说明 | +| --- | --- | +| 行情数据 | 实时快照、K 线、历史行情查询 | +| 账户信息 | 账户概览、资产、持仓查询 | +| 交易操作 | 下单、改单、撤单（受账户权限与地区限制） | -## OAuth 认证流程 +实际可用能力因地区、账户等级和授权范围而有所不同。 -Longbridge MCP 使用 OAuth，用户无需向客户端暴露原始 API 密钥。 +## 客户端接入 -### 1）在客户端发起 MCP 连接 +> 各客户端的 MCP 配置格式可能随版本变更，以客户端官方文档为准。以下提供核心配置参数。 -在支持 MCP 的客户端（如 Cursor、Claude Desktop、Cherry Studio）中，发起连接 Longbridge MCP 服务。 - -### 2）跳转 Longbridge 授权页面 - -客户端会打开浏览器，进入 Longbridge 登录与授权页面。 - -### 3）登录并确认授权 - -查看请求权限（scope），确认后授权。 - -### 4）回调完成并建立会话 - -授权成功后，客户端获得 OAuth 凭证，MCP 会话可用。 - -### 5）刷新与撤销 - -- 凭证会按 OAuth 策略过期并刷新。 -- 你可以随时在 Longbridge 安全/授权设置中撤销访问。 - -## 客户端兼容性说明 - -部分未完整实现 MCP OAuth 2.1 流程的客户端，可能无法接入 Longbridge MCP。 - -例如，部分较早版本的客户端（如早期 Cherry Studio）可能无法完整完成 OAuth 流程。建议升级到客户端最新版本。 - -## 安全建议 - -- OAuth 凭证属于敏感信息，客户端应安全存储。 -- 遵循最小权限原则，仅授予必要 scope。 -- 涉及交易操作时，建议始终加入人工确认。 - -## 客户端接入方式 -> 说明：各客户端 MCP 配置格式可能随版本变化，请以客户端官方文档/界面为准，本文仅提供接入要点与服务地址。 - - -### ChatGPT - -在 ChatGPT 的 **Settings → Connectors / MCP**（或工作区 MCP 配置入口）中新增远程 MCP 服务： +在支持 MCP 的客户端中，以 Remote MCP Server 方式添加如下配置： ```json { "mcpServers": { "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" + "url": "https://openapi.longportapp.com/mcp" } } } ``` -然后按页面指引完成 OAuth 授权。 +各主流客户端的配置入口： -### Claude Code +- **Cursor**：Settings → MCP Servers → 添加 Remote MCP Server +- **Claude Code**：MCP 配置文件或 `claude mcp add` 命令 +- **ChatGPT**：Settings → Connectors（或工作区 MCP 配置入口） +- **Zed**：`settings.json` 中的 `context_servers` 字段（key 名称可自定义） +- **Cherry Studio**：设置 → MCP 服务器 → 添加 -在 Claude Code 的 MCP 配置中新增远程 MCP 服务： - -```json -{ - "mcpServers": { - "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" - } - } -} -``` +配置完成后，客户端会自动引导你完成 OAuth 授权流程。 -浏览器完成 OAuth 后，回到 Claude Code 即可调用工具。 +## OAuth 授权流程 -### Cursor +Longbridge MCP 使用标准 OAuth 2.1 授权，你无需向客户端提供 API 密钥或 Token。 -打开 **Cursor Settings → MCP Servers**，新增远程 MCP 服务： - -```json -{ - "mcpServers": { - "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" - } - } -} +``` +AI 客户端 浏览器 Longbridge + | | | + |--- 发起 MCP 连接 ------>| | + | |-- 跳转授权页 ------------>| + | |<- 展示登录 & 权限确认 ----| + | |-- 登录并同意 ------------>| + |<-- 返回授权凭证 --------| | + |--- 携带凭证访问工具 ----------------------------------->| ``` -完成 OAuth 后，确认工具列表已出现。 - -### Zed +**步骤说明：** -打开 `settings.json`，增加： +1. **发起连接** — 在客户端添加 Longbridge MCP 配置后，首次调用会触发授权 +2. **浏览器跳转** — 客户端自动打开浏览器，进入 Longbridge 登录与权限确认页 +3. **登录并授权** — 使用 Longbridge 账户登录，查看并同意所请求的权限范围（scope） +4. **建立会话** — 授权完成后，客户端获得凭证，MCP 工具即可使用 +5. **凭证维护** — 凭证按 OAuth 策略自动刷新；如需撤销，前往 Longbridge 账户安全设置 -```json -{ - "context_servers": { - "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" - } - } -} -``` +## 客户端兼容性 -然后完成 OAuth 授权即可使用。 +Longbridge MCP 依赖 **MCP OAuth 2.1** 标准。若客户端未完整实现该协议，将无法完成授权。 -### OpenClaw +已知问题：Cherry Studio 早期版本不支持完整 OAuth 流程，请升级至最新版本。 -在 OpenClaw 的 MCP/工具集成配置中添加 Longbridge 远程 MCP： +如遇其他客户端连接失败，请确认客户端版本并查阅其 MCP 支持文档。 -```json -{ - "mcpServers": { - "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" - } - } -} -``` +## 安全建议 -完成 OAuth 后，在会话中确认工具可用。 +- **最小权限**：授权时仅同意当前任务所需的 scope，避免过度授权 +- **交易确认**：涉及下单等交易操作时，在 AI 提示词中明确要求执行前人工确认 +- **凭证安全**：OAuth 凭证由客户端管理，避免将其复制到不受信任的环境 +- **定期审查**：定期在 Longbridge 账户安全设置中检查并撤销不再使用的授权 ## 推荐使用方式 -1. 先从只读能力开始（行情/账户/持仓）。 -2. 确认权限范围和风控后，再开启交易相关能力。 -3. 在提示词中增加约束（金额上限、标的白名单、下单前确认）。 +1. **从只读能力开始**：优先使用行情查询、持仓查看等低风险功能，熟悉工具行为 +2. **逐步开放交易能力**：确认权限范围和风控逻辑后，再使用下单相关工具 +3. **在提示词中加入约束**：例如"每笔交易金额不超过 X"、"执行前向我确认"等明确限制 ## 常见问题 ### OAuth 登录失败 -- 确认 Longbridge 账户状态正常。 -- 在客户端重新发起授权。 -- 检查当前账户是否支持所请求的 scope。 +- 确认 Longbridge 账户状态正常，已完成必要的身份验证 +- 在客户端删除现有配置后重新添加并发起授权 +- 检查当前账户是否支持所请求的 scope ### 已连接但部分工具不可用 -- 可能是账户/地区权限限制。 -- 如 scope 有变更，请重新授权。 +- 账户或地区限制：特定市场或功能可能受账户等级或地区限制 +- scope 变更：如工具能力有更新，可能需要重新授权以获得新 scope ### 交易操作提示权限不足 -- 检查账户交易权限与市场可交易资格。 -- 确认当前 MCP 会话已获得对应 OAuth scope。 +- 检查账户的交易权限和市场可交易资格 +- 确认当前 MCP 会话的 OAuth scope 包含交易相关权限 diff --git a/docs/zh-HK/docs/getting-started.md b/docs/zh-HK/docs/getting-started.md index 81fcdfcd..a7cb4f0c 100644 --- a/docs/zh-HK/docs/getting-started.md +++ b/docs/zh-HK/docs/getting-started.md @@ -162,7 +162,7 @@ oauth = OAuth2Session(client_id, redirect_uri=redirect_uri) authorization_url, state = oauth.authorization_url( 'https://openapi.longportapp.com/oauth2/authorize' ) -print(f'請造訪此 URL 進行授權: {authorization_url}') +print(f'請造訪此 URL 進行授權：{authorization_url}') # 授權後取得回呼 URL authorization_response = input('請輸入完整的回呼 URL: ') @@ -200,7 +200,7 @@ const authorizationUri = client.authorizeURL({ redirect_uri: 'http://localhost:60355/callback', }); -console.log('請造訪此 URL 進行授權:', authorizationUri); +console.log('請造訪此 URL 進行授權：', authorizationUri); // 授權後使用 code 取得 token const tokenParams = { diff --git a/docs/zh-HK/docs/mcp.md b/docs/zh-HK/docs/mcp.md index 4699dba0..007e5e6a 100644 --- a/docs/zh-HK/docs/mcp.md +++ b/docs/zh-HK/docs/mcp.md @@ -6,167 +6,113 @@ sidebarCollapsed: true id: mcp --- -# MCP +# Longbridge MCP 服務 -Longbridge 提供線上 MCP 服務，讓 AI 工具可透過 Model Context Protocol 安全存取行情與帳戶能力。 +Longbridge 提供托管的 MCP（Model Context Protocol）服務，讓你在 AI 編程助手或對話工具中直接使用 Longbridge 的行情與帳戶能力，無需手動管理 API 金鑰。 -- MCP 服務地址：`https://openapi.longportapp.com/mcp` -- OAuth 發現地址：`https://openapi.longportapp.com/.well-known/oauth-authorization-server` +**MCP 服務地址：** `https://openapi.longportapp.com/mcp` -> 本頁僅說明 **Longbridge MCP 線上服務** 與其 **OAuth 驗證流程**。 +## 前置條件 -## Longbridge MCP 線上服務能力 +- 已擁有 Longbridge 帳戶並完成開戶 +- 使用支援 MCP OAuth 2.1 的 AI 客戶端（見下方相容性說明） -完成授權後，MCP 客戶端可使用 Longbridge 能力，例如： +## 可用能力 -- 行情快照與即時查詢 -- K 線與歷史資料查詢 -- 帳戶總覽與持倉查詢 -- 交易相關操作（取決於帳戶權限與產品規則） +接入後，MCP 客戶端可調用以下能力： -實際可用能力會因地區、帳戶等級與授權範圍而有所不同。 +| 能力類別 | 說明 | +| --- | --- | +| 行情資料 | 即時快照、K 線、歷史行情查詢 | +| 帳戶資訊 | 帳戶總覽、資產、持倉查詢 | +| 交易操作 | 下單、改單、撤單（受帳戶權限與地區限制） | -## OAuth 驗證流程 +實際可用能力因地區、帳戶等級和授權範圍而有所不同。 -Longbridge MCP 採用 OAuth，使用者無需向客戶端提供原始 API 密鑰。 +## 客戶端接入 -### 1）在客戶端發起 MCP 連線 +> 各客戶端的 MCP 配置格式可能隨版本變更，以客戶端官方文件為準。以下提供核心配置參數。 -於支援 MCP 的客戶端（例如 Cursor、Claude Desktop、Cherry Studio）中發起連線 Longbridge MCP。 - -### 2）跳轉至 Longbridge 授權頁面 - -客戶端會開啟瀏覽器，進入 Longbridge 登入與授權頁。 - -### 3）登入並同意授權 - -檢視請求權限（scope）後完成授權。 - -### 4）授權回調並建立會話 - -授權成功後，客戶端取得 OAuth 憑證，MCP 會話即可使用。 - -### 5）刷新與撤銷 - -- 憑證會依 OAuth 策略過期並刷新。 -- 你可隨時在 Longbridge 安全/授權設定中撤銷存取。 - -## 客戶端相容性說明 - -部分未完整實作 MCP OAuth 2.1 流程的客戶端，可能無法接入 Longbridge MCP。 - -例如，部分較早版本的客戶端（如早期 Cherry Studio）可能無法完整完成 OAuth 流程。建議升級至最新版本。 - -## 安全建議 - -- OAuth 憑證屬敏感資訊，客戶端應妥善保存。 -- 採用最小權限原則，只授與必要 scope。 -- 涉及交易操作時，建議一律加入人工確認。 - -## 客戶端接入方式 -> 說明：各客戶端 MCP 配置格式可能隨版本變化，請以客戶端官方文件/介面為準，本文僅提供接入要點與服務地址。 - - -### ChatGPT - -在 ChatGPT 的 **Settings → Connectors / MCP**（或工作區 MCP 設定入口）新增遠端 MCP 服務： +在支援 MCP 的客戶端中，以 Remote MCP Server 方式加入如下配置： ```json { "mcpServers": { "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" + "url": "https://openapi.longportapp.com/mcp" } } } ``` -其後依指示完成 OAuth 授權。 +各主流客戶端的配置入口： -### Claude Code +- **Cursor**：Settings → MCP Servers → 添加 Remote MCP Server +- **Claude Code**：MCP 配置文件或 `claude mcp add` 命令 +- **ChatGPT**：Settings → Connectors（或工作區 MCP 配置入口） +- **Zed**：`settings.json` 中的 `context_servers` 欄位（key 名稱可自訂） +- **Cherry Studio**：設定 → MCP 伺服器 → 添加 -在 Claude Code 的 MCP 設定中新增遠端 MCP 服務： - -```json -{ - "mcpServers": { - "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" - } - } -} -``` +配置完成後，客戶端會自動引導你完成 OAuth 授權流程。 -於瀏覽器完成 OAuth 後，回到 Claude Code 即可使用工具。 +## OAuth 授權流程 -### Cursor +Longbridge MCP 使用標準 OAuth 2.1 授權，你無需向客戶端提供 API 金鑰或 Token。 -打開 **Cursor Settings → MCP Servers**，新增遠端 MCP 服務： - -```json -{ - "mcpServers": { - "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" - } - } -} +``` +AI 客戶端 瀏覽器 Longbridge + | | | + |--- 發起 MCP 連線 ------>| | + | |-- 跳轉授權頁 ------------>| + | |<- 展示登入 & 權限確認 ----| + | |-- 登入並同意 ------------>| + |<-- 返回授權憑證 --------| | + |--- 攜帶憑證存取工具 ----------------------------------->| ``` -完成 OAuth 後，確認工具列表已出現。 - -### Zed +**步驟說明：** -打開 `settings.json`，增加： +1. **發起連線** — 在客戶端添加 Longbridge MCP 配置後，首次調用會觸發授權 +2. **瀏覽器跳轉** — 客戶端自動開啟瀏覽器，進入 Longbridge 登入與權限確認頁 +3. **登入並授權** — 使用 Longbridge 帳戶登入，查看並同意所請求的權限範圍（scope） +4. **建立會話** — 授權完成後，客戶端取得憑證，MCP 工具即可使用 +5. **憑證維護** — 憑證依 OAuth 策略自動刷新；如需撤銷，前往 Longbridge 帳戶安全設定 -```json -{ - "context_servers": { - "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" - } - } -} -``` +## 客戶端相容性 -然後完成 OAuth 授權即可使用。 +Longbridge MCP 依賴 **MCP OAuth 2.1** 標準。若客戶端未完整實作該協議，將無法完成授權。 -### OpenClaw +已知問題：Cherry Studio 早期版本不支援完整 OAuth 流程，請升級至最新版本。 -在 OpenClaw 的 MCP/工具整合設定中加入 Longbridge 遠端 MCP： +如遇其他客戶端連線失敗，請確認客戶端版本並查閱其 MCP 支援文件。 -```json -{ - "mcpServers": { - "longbridge": { - "url": "https://openapi.longportapp.cn/mcp" - } - } -} -``` +## 安全建議 -完成 OAuth 後，於會話中確認工具可用。 +- **最小權限**：授權時僅同意當前任務所需的 scope，避免過度授權 +- **交易確認**：涉及下單等交易操作時，在 AI 提示詞中明確要求執行前人工確認 +- **憑證安全**：OAuth 憑證由客戶端管理，避免將其複製至不受信任的環境 +- **定期審查**：定期在 Longbridge 帳戶安全設定中檢查並撤銷不再使用的授權 -## 建議使用方式 +## 推薦使用方式 -1. 先從唯讀能力開始（行情/帳戶/持倉）。 -2. 確認權限範圍與風控後，再開啟交易能力。 -3. 在提示詞加入限制（金額上限、標的白名單、下單前確認）。 +1. **從唯讀能力開始**：優先使用行情查詢、持倉查看等低風險功能，熟悉工具行為 +2. **逐步開放交易能力**：確認權限範圍和風控邏輯後，再使用下單相關工具 +3. **在提示詞中加入限制**：例如「每筆交易金額不超過 X」、「執行前向我確認」等明確限制 ## 常見問題 ### OAuth 登入失敗 -- 確認 Longbridge 帳戶狀態正常。 -- 在客戶端重新發起授權。 -- 檢查帳戶是否支援所請求的 scope。 +- 確認 Longbridge 帳戶狀態正常，已完成必要的身份驗證 +- 在客戶端刪除現有配置後重新添加並發起授權 +- 檢查當前帳戶是否支援所請求的 scope ### 已連線但部分工具不可用 -- 可能受帳戶/地區權限限制。 -- 若 scope 有變更，請重新授權。 +- 帳戶或地區限制：特定市場或功能可能受帳戶等級或地區限制 +- scope 變更：如工具能力有更新，可能需要重新授權以取得新 scope ### 交易操作提示權限不足 -- 檢查帳戶交易權限與市場可交易資格。 -- 確認目前 MCP 會話已取得對應 OAuth scope。 +- 檢查帳戶的交易權限和市場可交易資格 +- 確認當前 MCP 會話的 OAuth scope 包含交易相關權限