diff --git a/README.md b/README.md index 332f62ef..728ffb95 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ pip install longbridge { "mcpServers": { "longbridge": { - "url": "https://openapi.longbridge.com/mcp" + "url": "https://mcp.longbridge.com" } } } diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 693d36ca..0f52e23d 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -15,7 +15,7 @@ import yaml from 'js-yaml' const __dirname = dirname(fileURLToPath(import.meta.url)) const docsRoot = resolve(__dirname, '..') -const MCP_TOOLS_URL = 'https://openapi.longbridge.com/mcp/tools.json' +const MCP_TOOLS_URL = 'https://mcp.longbridge.com/mcp/tools.json' const MCP_TOOLS_DATA_PATH = resolve(__dirname, 'data/mcp-tools.json') const regionCfg = getRegionConfig() const regionSrcExclude = computeSrcExclude(docsRoot) diff --git a/docs/.vitepress/theme/components/AppNav.vue b/docs/.vitepress/theme/components/AppNav.vue index 35fe20ea..f26304f9 100644 --- a/docs/.vitepress/theme/components/AppNav.vue +++ b/docs/.vitepress/theme/components/AppNav.vue @@ -97,6 +97,7 @@ const avatarCloseTimer = ref | null>(null) const avatarMenuItems = computed(() => [ { title: 'Dashboard', href: '/dashboard' }, + { title: 'Connect AI', href: '/connect' }, { title: 'Log out', href: '/log-out' }, ]) diff --git a/docs/.vitepress/theme/components/NewHomePage/ProductMCP.vue b/docs/.vitepress/theme/components/NewHomePage/ProductMCP.vue index eba0f8e1..8f4e56fa 100644 --- a/docs/.vitepress/theme/components/NewHomePage/ProductMCP.vue +++ b/docs/.vitepress/theme/components/NewHomePage/ProductMCP.vue @@ -50,7 +50,7 @@ const clients = [ name: 'Claude Code', logo: 'https://assets.lbctrl.com/uploads/6932dfac-0f9c-4577-bdd8-fc3d22d4223a/claude.svg', type: 'shell' as const, - cmd: 'claude mcp add --transport http longbridge https://openapi.longbridge.com/mcp', + cmd: 'claude mcp add --transport http longbridge https://mcp.longbridge.com', }, { id: 'codex', @@ -58,7 +58,7 @@ const clients = [ logo: 'https://assets.lbctrl.com/uploads/88eb58fe-b3bb-4875-90c7-c97e6d8fcc9e/openai.svg', type: 'ui' as const, steps: ['Settings', 'MCP Servers', 'Add Server'], - fields: { Name: 'longbridge', Type: 'Streamable HTTP', URL: 'https://openapi.longbridge.com/mcp' }, + fields: { Name: 'longbridge', Type: 'Streamable HTTP', URL: 'https://mcp.longbridge.com' }, }, { id: 'cursor', @@ -66,14 +66,14 @@ const clients = [ logo: 'https://assets.lbctrl.com/uploads/f694478e-201b-4e74-a7b6-023639a27805/cursor.svg', type: 'ui' as const, steps: ['Settings', 'MCP Servers', 'Add Remote MCP Server'], - fields: { URL: 'https://openapi.longbridge.com/mcp' }, + fields: { URL: 'https://mcp.longbridge.com' }, }, { id: 'zed', name: 'Zed', logo: 'https://assets.lbctrl.com/uploads/3418077a-9766-4514-bc8e-eef076309689/zed.svg', type: 'json' as const, - json: { mcpServers: { longbridge: { url: 'https://openapi.longbridge.com/mcp' } } }, + json: { mcpServers: { longbridge: { url: 'https://mcp.longbridge.com' } } }, }, { id: 'cherry', @@ -81,7 +81,7 @@ const clients = [ logo: 'https://assets.lbctrl.com/uploads/df8f9467-91a5-4bdb-8dde-5127441f0b04/cherrystudio.svg', type: 'ui' as const, steps: ['Settings', 'MCP Servers', 'Add'], - fields: { URL: 'https://openapi.longbridge.com/mcp' }, + fields: { URL: 'https://mcp.longbridge.com' }, }, ] diff --git a/docs/.vitepress/theme/components/NewHomePage/index.vue b/docs/.vitepress/theme/components/NewHomePage/index.vue index f8515458..78e1c5f0 100644 --- a/docs/.vitepress/theme/components/NewHomePage/index.vue +++ b/docs/.vitepress/theme/components/NewHomePage/index.vue @@ -1773,7 +1773,7 @@ const GETSTARTED = [ + + + + + +
@@ -2154,8 +2226,8 @@ function triggerRipple(event: MouseEvent, el: HTMLElement) { gap: 12px; } .skill-hero-install-label { - font-size: 12px; - color: var(--lb-fg-3); + font-size: 13px; + color: var(--lb-fg-2); font-weight: 500; } .skill-hero-install-cmd { @@ -2178,6 +2250,73 @@ function triggerRipple(event: MouseEvent, el: HTMLElement) { flex: 1; text-align: left; } +.skill-hero-connect-card { + display: flex; + flex-direction: column; + gap: 12px; + background: var(--lb-bg-2); + border: 1px solid var(--app-card-stroke); + border-radius: 10px; + padding: 16px; + max-width: 480px; + width: 100%; +} +.skill-hero-connect-step { + display: flex; + align-items: flex-start; + gap: 10px; + font-size: 13px; + color: var(--lb-fg-2); + text-align: left; + line-height: 1.5; +} +.skill-hero-connect-step-num { + flex: none; + width: 18px; + height: 18px; + border-radius: 50%; + background: color-mix(in srgb, var(--lb-brand) 14%, transparent); + color: var(--lb-brand); + font-size: 11px; + font-weight: 700; + display: inline-flex; + align-items: center; + justify-content: center; + margin-top: 1px; +} +.skill-hero-connect-card .btn { + margin-top: 4px; + align-self: center; +} +.skill-hero-seg { + display: inline-flex; + align-items: center; + gap: 2px; + padding: 3px; + border-radius: 999px; + background: var(--lb-bg-2); + border: 1px solid var(--app-card-stroke); +} +.skill-hero-seg-btn { + padding: 6px 18px; + border-radius: 999px; + font-size: 13px; + font-weight: 600; + color: var(--lb-fg-3); + background: transparent; + border: none; + cursor: pointer; + transition: + color 0.15s, + background 0.15s; +} +.skill-hero-seg-btn:hover { + color: var(--lb-fg-1); +} +.skill-hero-seg-btn.is-active { + color: #fff; + background: var(--lb-brand); +} .skill-hero-install-link { font-size: 13px; color: var(--lb-brand); @@ -2937,6 +3076,14 @@ function triggerRipple(event: MouseEvent, el: HTMLElement) { background: var(--lb-brand); color: #fff; } +.btn-dark { + background: #111; + color: #fff; +} +.dark .btn-dark { + background: #fff; + color: #111; +} /* ─── Skills Catalog ──────────────────────────────────────────────────────── */ .sc-header { diff --git a/docs/en/docs/agent-auth.md b/docs/en/docs/agent-auth.md new file mode 100644 index 00000000..6ca1cbce --- /dev/null +++ b/docs/en/docs/agent-auth.md @@ -0,0 +1,95 @@ +--- +title: 'Agent Auth Code' +id: agent-auth +slug: /agent-auth +sidebar_position: 2.5 +sidebar_icon: sparkles +--- + +# Agent Auth Code + +Agent Auth Code lets you authorize an AI agent to use Longbridge market data and account capabilities by pasting a short, one-time code into the agent — no long URLs and no waiting browser. + +You generate the code on the Longbridge authorization page, pick the permissions you want to grant, and hand the code to your AI assistant. The agent redeems it in one step through the CLI or the hosted MCP service. + +:::tip Generate a code +Open [https://open.longbridge.com/connect](https://open.longbridge.com/connect), sign in, select the scopes you need, and click generate. +::: + +## When to use it + +Browser-based OAuth is still the default for most desktop clients. Reach for an Agent Auth Code instead when the standard flow does not work well: + +- **The client does not render the authorization link** — some chat and agent apps show the long OAuth URL as plain text, so it cannot be clicked. +- **No browser is available** — on mobile, in a remote shell, or in a sandboxed agent environment that cannot launch a browser. +- **The agent does not stay running** — Device Flow requires the CLI to keep polling while you authorize, but many agents do not hold a process open. A one-time code avoids any polling. + +For a desktop client that fully supports the browser OAuth flow, the standard [MCP authorization flow](/mcp) is simpler and you do not need a code. + +## Steps + +1. **Open the authorization page** — go to [https://open.longbridge.com/connect](https://open.longbridge.com/connect). +2. **Sign in** with your Longbridge account. +3. **Select permissions** — choose the scopes (market data, account, trading, etc.) you want to grant. The generated code can only ever carry the scopes you pick here. +4. **Generate the code** — the page produces a short auth code and a ready-to-paste instruction text. +5. **Paste it to your AI agent** — copy the instruction text and send it to your assistant. The agent redeems the code using one of the methods below. + +The code is valid for **5 minutes** and can be used **once**. + +## Redeem via CLI + +Pass the code to `auth login` with the `--auth-code` flag. Replace the example code with your real one: + + +# Redeem an auth code generated from the connect page +longbridge auth login --auth-code 6vYzXq3WbKp9TmHd + + +On success the token is saved to `~/.longbridge/openapi/tokens/` and reused automatically by all subsequent commands — exactly like the browser login. See [Installation](/docs/cli/install) for the full `auth` command reference. + +## Redeem via MCP + +Auth-code redemption runs against a dedicated endpoint, **`https://mcp.longbridge.com/agent`**. This endpoint allows unauthorized connections, and while a session is unauthorized it exposes only the `authenticate` tool. The main endpoint `https://mcp.longbridge.com` is standard OAuth 2.1 only and does not offer `authenticate` — clients that fully support OAuth should use the main endpoint, and `/agent` is the fallback channel for when OAuth is not available. + +**Flow:** + +1. **Configure the `/agent` endpoint** — point your client at `https://mcp.longbridge.com/agent`. The unauthorized session shows just the `authenticate` tool. +2. **Call `authenticate` with the auth code** — tell your assistant something like: "Authenticate the Longbridge MCP session with auth code 1234567890." The agent invokes `authenticate` with that code. +3. **Configure the returned token as a Bearer header** — on success, the tool result returns a token. Follow the instructions in the result to have the client send it as `Authorization: Bearer ` on subsequent requests. The remaining Longbridge MCP tools then become available — no browser redirect required. + +For Claude Code, re-add the server with the token as a header: + +```bash +claude mcp add --transport http longbridge https://mcp.longbridge.com --header "Authorization: Bearer " +``` + +Replace `` with the token returned by `authenticate`. Note this points at the main endpoint `https://mcp.longbridge.com` — once you hold a Bearer token, you connect there directly. + +## Security + +- **Scope is pre-selected on the web** — the code can only grant the permissions you chose on the authorization page; an agent cannot request more than the code carries. +- **5-minute TTL** — the code expires 5 minutes after it is generated. +- **One-time use** — the code is consumed on first successful redemption and cannot be reused. +- **Revocable anytime** — go to your Longbridge account security settings and revoke the **AI Agent** authorization to end access. + +Follow least privilege: grant only the scopes the current task needs. For any trading-related grant, instruct the agent to confirm with you before placing orders. + +## FAQ + +### The code has expired + +Auth codes are valid for 5 minutes. Return to [https://open.longbridge.com/connect](https://open.longbridge.com/connect) and generate a new one, then redeem it promptly. + +### The code was already used + +Each code works only once. If redemption already succeeded earlier, you are authorized — there is no need to redeem again. If you need a fresh session, generate a new code. + +### The granted permissions are not enough + +The code only carries the scopes selected on the authorization page. Generate a new code and select the additional scopes you need, then redeem it again to refresh the session's permissions. + +### Connection still fails after redeeming + +- Confirm your Longbridge account is in good standing and identity verification is complete. +- Confirm the scopes you selected cover the action you are attempting (for example, trading requires trading scopes). +- For MCP, verify the agent connects to `https://mcp.longbridge.com/agent` to call `authenticate`, then reconnects to `https://mcp.longbridge.com` with the returned `Authorization: Bearer` token. diff --git a/docs/en/docs/cli/install.md b/docs/en/docs/cli/install.md index 3af54acc..7b3e1e90 100644 --- a/docs/en/docs/cli/install.md +++ b/docs/en/docs/cli/install.md @@ -61,6 +61,13 @@ Running `auth login` prints a URL and a short code. Open the URL in any browser, and authorize. The token is saved to `~/.longbridge/openapi/tokens/` and reused automatically by all subsequent commands. +If no browser is available, generate an [Agent Auth Code](/agent-auth) at +[https://open.longbridge.com/connect](https://open.longbridge.com/connect) and redeem it directly: + +```bash +longbridge auth login --auth-code 6vYzXq3WbKp9TmHd +``` + ### auth logout Clears the stored OAuth token. The next command or TUI launch will trigger re-authentication. diff --git a/docs/en/docs/mcp.md b/docs/en/docs/mcp.md index df40d2ea..90c9e5cb 100644 --- a/docs/en/docs/mcp.md +++ b/docs/en/docs/mcp.md @@ -12,8 +12,8 @@ next: false Longbridge provides a hosted HTTP 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. :::tip MCP endpoint -- Global: `https://openapi.longbridge.com/mcp` -- Mainland China: `https://openapi.longbridge.cn/mcp` (faster access) +- Global: `https://mcp.longbridge.com` +- Mainland China: `https://mcp.longbridge.cn` (faster access) ::: ## Available capabilities @@ -49,7 +49,7 @@ Actual tool availability depends on your region, account level, and granted OAut Run the following command in your terminal: ```bash -claude mcp add --transport http longbridge https://openapi.longbridge.com/mcp +claude mcp add --transport http longbridge https://mcp.longbridge.com ``` Then open the `claude` terminal interface, type `/mcp`, select `longbridge`, and choose **Authenticate** to complete the OAuth authorization flow. @@ -60,7 +60,7 @@ Then open the `claude` terminal interface, type `/mcp`, select `longbridge`, and 2. In the "Connect to a custom MCP" screen, fill in: - Name: `longbridge` - Type: **Streamable HTTP** - - URL: `https://openapi.longbridge.com/mcp` + - URL: `https://mcp.longbridge.com` - Leave all other fields empty 3. Click **Save** 4. Back in the MCP Servers list, click **Authenticate** on the `longbridge` entry to complete OAuth authorization @@ -77,7 +77,7 @@ Add the following to your `settings.json` under the `context_servers` key (key n { "mcpServers": { "longbridge": { - "url": "https://openapi.longbridge.com/mcp" + "url": "https://mcp.longbridge.com" } } } @@ -118,6 +118,10 @@ Known issue: early versions of Cherry Studio do not support the full OAuth flow. If another client fails to connect, check its version and MCP support documentation. +:::tip Client can't open the browser? +If your client has incomplete OAuth support or cannot launch a browser, use an [Agent Auth Code](/agent-auth) instead: generate a one-time code at [https://open.longbridge.com/connect](https://open.longbridge.com/connect), connect to the dedicated endpoint `https://mcp.longbridge.com/agent`, and have the agent redeem it via the `authenticate` tool. +::: + ## Security recommendations - **Least privilege**: Only approve the scopes required for your current task; avoid over-granting diff --git a/docs/en/skill/install/index.md b/docs/en/skill/install/index.md index 83059871..0281d1a5 100644 --- a/docs/en/skill/install/index.md +++ b/docs/en/skill/install/index.md @@ -7,7 +7,7 @@ description: Install Longbridge Skill for OpenClaw, Claude Code, Cursor, Codex, @@ -71,6 +71,12 @@ iwr https://open.longbridge.com/longbridge/longbridge-terminal/install.ps1 | iex longbridge auth login ``` +Already have a one-time authorization code from [open.longbridge.com/connect](https://open.longbridge.com/connect)? Redeem it directly — no browser needed: + +```bash +longbridge auth login --auth-code 1234567890 +``` + That's it. The AI can now call `longbridge` commands on your behalf. **Claude Code users:** The first time Claude runs a `longbridge` command, it will ask for permission. To allow all Longbridge commands without repeated prompts, add this to `.claude/settings.json` in your project (create the file if it doesn't exist): @@ -92,7 +98,7 @@ Works with Claude Desktop, Cursor, Zed, Gemini CLI, Warp, and any tool that supp Add the following as a remote MCP server in your AI tool: ``` -https://openapi.longbridge.com/mcp +https://mcp.longbridge.com ``` For clients that use a JSON config file (Claude Desktop, Cursor, Zed, Gemini CLI, etc.), add this to your MCP config: @@ -101,13 +107,13 @@ For clients that use a JSON config file (Claude Desktop, Cursor, Zed, Gemini CLI { "mcpServers": { "longbridge": { - "url": "https://openapi.longbridge.com/mcp" + "url": "https://mcp.longbridge.com" } } } ``` -> Users in mainland China can use the accelerated endpoint: `https://openapi.longbridge.cn/mcp` +> Users in mainland China can use the accelerated endpoint: `https://mcp.longbridge.cn` Where to find the MCP configuration in each client: diff --git a/docs/zh-CN/docs/agent-auth.md b/docs/zh-CN/docs/agent-auth.md new file mode 100644 index 00000000..ac86891c --- /dev/null +++ b/docs/zh-CN/docs/agent-auth.md @@ -0,0 +1,95 @@ +--- +title: '授权码授权' +id: agent-auth +slug: /agent-auth +sidebar_position: 2.5 +sidebar_icon: sparkles +--- + +# 授权码授权 + +授权码授权让你只需把一个简短的一次性授权码粘贴给 AI Agent，即可授权它使用 Longbridge 行情数据与账户能力——无需冗长的 URL，也无需等待浏览器。 + +你在 Longbridge 授权页生成授权码、勾选要授予的权限，然后把授权码交给 AI 助手。Agent 通过 CLI 或托管 MCP 服务一步完成兑换。 + +:::tip 生成授权码 +打开 [https://open.longbridge.com/connect](https://open.longbridge.com/connect)，登录，选择所需的权限范围，点击生成。 +::: + +## 适用场景 + +大多数桌面客户端仍以浏览器 OAuth 为默认方式。当标准流程不便时，改用授权码： + +- **客户端不渲染授权链接** — 部分聊天和 Agent 应用把冗长的 OAuth URL 显示为纯文本，无法点击。 +- **没有可用的浏览器** — 在手机端、远程 shell，或无法拉起浏览器的沙箱 Agent 环境中。 +- **Agent 不会持续挂起** — Device Flow 需要 CLI 在你授权期间持续轮询，而许多 Agent 不会保持进程运行。一次性授权码无需任何轮询。 + +如果桌面客户端完整支持浏览器 OAuth 流程，使用标准的 [MCP 授权流程](/zh-CN/docs/mcp) 更简单，无需授权码。 + +## 步骤 + +1. **打开授权页** — 访问 [https://open.longbridge.com/connect](https://open.longbridge.com/connect)。 +2. **登录** Longbridge 账户。 +3. **选择权限** — 勾选要授予的权限范围（行情、账户、交易等）。生成的授权码所携带的权限上限就是你在此处选择的范围。 +4. **生成授权码** — 页面会生成一个简短的授权码和一段可直接粘贴的指令文本。 +5. **粘贴给 AI Agent** — 复制指令文本发送给助手，Agent 用下面任一方式兑换授权码。 + +授权码有效期 **5 分钟**，且**仅可使用一次**。 + +## 通过 CLI 兑换 + +用 `--auth-code` 参数把授权码传给 `auth login`，将示例授权码替换为你的真实授权码： + + +# 兑换从 connect 页面生成的授权码 +longbridge auth login --auth-code 6vYzXq3WbKp9TmHd + + +兑换成功后，Token 保存至 `~/.longbridge/openapi/tokens/`，后续所有命令自动复用——与浏览器登录效果一致。完整的 `auth` 命令参考见 [安装](/zh-CN/docs/cli/install)。 + +## 通过 MCP 兑换 + +授权码兑换走专用端点 **`https://mcp.longbridge.com/agent`**。该端点允许未授权连接，会话在未授权时仅暴露 `authenticate` 这一个工具。主端点 `https://mcp.longbridge.com` 仅支持标准 OAuth 2.1，不提供 `authenticate`——完整支持 OAuth 的客户端应直接用主端点，`/agent` 是 OAuth 不可用时的备用通道。 + +**流程：** + +1. **配置 `/agent` 端点** — 将客户端指向 `https://mcp.longbridge.com/agent`，未授权会话只显示 `authenticate` 工具。 +2. **调用 `authenticate` 传入授权码** — 你可以这样告诉助手：「用授权码 1234567890 为 Longbridge MCP 会话完成授权。」Agent 即会带该授权码调用 `authenticate`。 +3. **将返回的 Token 配置为 Bearer header** — 兑换成功后，工具结果会返回一个 Token。按结果中的指引让客户端在后续请求中以 `Authorization: Bearer ` 携带它，其余 Longbridge MCP 工具随即可用——无需浏览器跳转。 + +以 Claude Code 为例，用该 Token 作为 header 重新添加服务： + +```bash +claude mcp add --transport http longbridge https://mcp.longbridge.com --header "Authorization: Bearer " +``` + +将 `` 替换为 `authenticate` 返回的 Token。注意此处指向的是主端点 `https://mcp.longbridge.com`——拿到 Bearer Token 后即可直接连接主端点。 + +## 安全说明 + +- **权限在网页端预选** — 授权码只能授予你在授权页勾选的权限，Agent 无法请求超出授权码携带范围的权限。 +- **5 分钟有效期** — 授权码在生成 5 分钟后过期。 +- **一次性使用** — 授权码在首次成功兑换后即失效，不可重复使用。 +- **随时可撤销** — 前往 Longbridge 账户安全设置，撤销 **AI Agent** 授权即可终止访问。 + +遵循最小权限原则：只授予当前任务所需的权限范围。涉及交易的授权，务必要求 Agent 在下单前与你确认。 + +## 常见问题 + +### 授权码已过期 + +授权码有效期为 5 分钟。回到 [https://open.longbridge.com/connect](https://open.longbridge.com/connect) 重新生成一个，并尽快兑换。 + +### 授权码已被使用 + +每个授权码仅可使用一次。若此前已兑换成功，则你已完成授权，无需再次兑换。如需新的会话，请重新生成授权码。 + +### 授予的权限不够 + +授权码只携带在授权页勾选的权限范围。重新生成一个授权码并勾选所需的额外权限，再次兑换即可刷新会话权限。 + +### 兑换后仍无法连接 + +- 确认 Longbridge 账户状态正常且已完成身份认证。 +- 确认所选权限范围覆盖你尝试执行的操作（例如交易需要交易权限）。 +- 对于 MCP，确认 Agent 连接 `https://mcp.longbridge.com/agent` 调用 `authenticate`，再用返回的 `Authorization: Bearer` Token 连接 `https://mcp.longbridge.com`。 diff --git a/docs/zh-CN/docs/cli/install.md b/docs/zh-CN/docs/cli/install.md index b2e70208..13dfc71d 100644 --- a/docs/zh-CN/docs/cli/install.md +++ b/docs/zh-CN/docs/cli/install.md @@ -58,6 +58,12 @@ longbridge auth login 运行 `auth login` 后会打印一个 URL 和短码。在任意浏览器中打开该 URL，输入短码并授权。Token 保存至 `~/.longbridge/openapi/tokens/`，后续所有命令自动复用。 +如无可用浏览器，可在 [https://open.longbridge.com/connect](https://open.longbridge.com/connect) 生成[授权码](/zh-CN/docs/agent-auth)并直接兑换： + +```bash +longbridge auth login --auth-code 6vYzXq3WbKp9TmHd +``` + ### auth logout 清除已存储的 OAuth Token。下次执行命令或启动 TUI 时将重新触发鉴权。 diff --git a/docs/zh-CN/docs/mcp.md b/docs/zh-CN/docs/mcp.md index 93f90a75..cd3a02af 100644 --- a/docs/zh-CN/docs/mcp.md +++ b/docs/zh-CN/docs/mcp.md @@ -12,8 +12,8 @@ next: false Longbridge 提供托管的 HTTP MCP（Model Context Protocol）服务，让你在 AI 编程助手或对话工具中直接使用 Longbridge 的行情与账户能力，无需手动管理 API 密钥。 :::tip MCP 服务地址 -- 全球：`https://openapi.longbridge.com/mcp` -- 中国大陆：`https://openapi.longbridge.cn/mcp`（访问更快） +- 全球：`https://mcp.longbridge.com` +- 中国大陆：`https://mcp.longbridge.cn`（访问更快） ::: ## 可用能力 @@ -49,7 +49,7 @@ Longbridge MCP 暴露 100+ 工具，覆盖六大能力域，客户端连接后 在终端运行以下命令： ```bash -claude mcp add --transport http longbridge https://openapi.longbridge.com/mcp +claude mcp add --transport http longbridge https://mcp.longbridge.com ``` 然后进入 `claude` 终端界面，输入 `/mcp`，选择 `longbridge`，再选择 **Authenticate** 跟随流程完成 OAuth 授权。 @@ -60,7 +60,7 @@ claude mcp add --transport http longbridge https://openapi.longbridge.com/mcp 2. 在 "Connect to a custom MCP" 界面填写： - Name：`longbridge` - 类型：**Streamable HTTP** - - URL：`https://openapi.longbridge.com/mcp` + - URL：`https://mcp.longbridge.com` - 其他字段留空 3. 点击 **Save** 4. 回到 MCP Servers 列表，点击 `longbridge` 条目上的 **Authenticate** 完成 OAuth 授权 @@ -77,7 +77,7 @@ Settings → MCP Servers → 添加 Remote MCP Server，填入上方地址即可 { "mcpServers": { "longbridge": { - "url": "https://openapi.longbridge.com/mcp" + "url": "https://mcp.longbridge.com" } } } @@ -118,6 +118,10 @@ Longbridge MCP 依赖 **MCP OAuth 2.1** 标准。若客户端未完整实现该 如遇其他客户端连接失败，请确认客户端版本并查阅其 MCP 支持文档。 +:::tip 客户端无法打开浏览器？ +若客户端的 OAuth 实现不完整或无法拉起浏览器，可改用[授权码授权](/zh-CN/docs/agent-auth)：在 [https://open.longbridge.com/connect](https://open.longbridge.com/connect) 生成一次性授权码，连接专用端点 `https://mcp.longbridge.com/agent`，让 Agent 通过 `authenticate` 工具兑换。 +::: + ## 安全建议 - **最小权限**：授权时仅同意当前任务所需的 scope，避免过度授权 diff --git a/docs/zh-CN/skill/install/index.md b/docs/zh-CN/skill/install/index.md index 267221e0..f473e724 100644 --- a/docs/zh-CN/skill/install/index.md +++ b/docs/zh-CN/skill/install/index.md @@ -7,7 +7,7 @@ description: 在 OpenClaw、Claude Code、Cursor、Codex 等 AI 工具中安装 @@ -69,6 +69,12 @@ iwr https://open.longbridge.com/longbridge/longbridge-terminal/install.ps1 | iex longbridge auth login ``` +已有来自 [open.longbridge.com/connect](https://open.longbridge.com/connect) 的一次性授权码？直接兑换，无需浏览器： + +```bash +longbridge auth login --auth-code 1234567890 +``` + 完成后，AI 即可代你调用 `longbridge` 命令。 **Claude Code 用户：** Claude 首次运行 `longbridge` 命令时会弹出权限确认提示。若要避免每次都被询问，可在项目的 `.claude/settings.json` 中添加以下配置（文件不存在时新建）： @@ -90,7 +96,7 @@ longbridge auth login 在 AI 工具的 MCP 配置中添加以下服务器地址： ``` -https://openapi.longbridge.com/mcp +https://mcp.longbridge.com ``` 对于使用 JSON 配置文件的客户端（Claude Desktop、Cursor、Zed、Gemini CLI 等），将以下内容添加到 MCP 配置中： @@ -99,13 +105,13 @@ https://openapi.longbridge.com/mcp { "mcpServers": { "longbridge": { - "url": "https://openapi.longbridge.com/mcp" + "url": "https://mcp.longbridge.com" } } } ``` -> 中国大陆用户可使用加速地址：`https://openapi.longbridge.cn/mcp` +> 中国大陆用户可使用加速地址：`https://mcp.longbridge.cn` 各工具配置入口： diff --git a/docs/zh-HK/docs/agent-auth.md b/docs/zh-HK/docs/agent-auth.md new file mode 100644 index 00000000..c405f3d1 --- /dev/null +++ b/docs/zh-HK/docs/agent-auth.md @@ -0,0 +1,95 @@ +--- +title: '授權碼授權' +id: agent-auth +slug: /agent-auth +sidebar_position: 2.5 +sidebar_icon: sparkles +--- + +# 授權碼授權 + +授權碼授權讓你只需把一個簡短的一次性授權碼貼給 AI Agent，即可授權它使用 Longbridge 行情資料與帳戶能力——無需冗長的 URL，也無需等待瀏覽器。 + +你在 Longbridge 授權頁產生授權碼、勾選要授予的權限，然後把授權碼交給 AI 助手。Agent 透過 CLI 或託管 MCP 服務一步完成兌換。 + +:::tip 產生授權碼 +開啟 [https://open.longbridge.com/connect](https://open.longbridge.com/connect)，登入，選擇所需的權限範圍，點擊產生。 +::: + +## 適用場景 + +大多數桌面客戶端仍以瀏覽器 OAuth 為預設方式。當標準流程不便時，改用授權碼： + +- **客戶端不渲染授權連結** — 部分聊天和 Agent 應用把冗長的 OAuth URL 顯示為純文字，無法點擊。 +- **沒有可用的瀏覽器** — 在手機端、遠端 shell，或無法拉起瀏覽器的沙箱 Agent 環境中。 +- **Agent 不會持續掛起** — Device Flow 需要 CLI 在你授權期間持續輪詢，而許多 Agent 不會保持行程執行。一次性授權碼無需任何輪詢。 + +如果桌面客戶端完整支援瀏覽器 OAuth 流程，使用標準的 [MCP 授權流程](/zh-HK/docs/mcp) 更簡單，無需授權碼。 + +## 步驟 + +1. **開啟授權頁** — 造訪 [https://open.longbridge.com/connect](https://open.longbridge.com/connect)。 +2. **登入** Longbridge 帳戶。 +3. **選擇權限** — 勾選要授予的權限範圍（行情、帳戶、交易等）。產生的授權碼所攜帶的權限上限就是你在此處選擇的範圍。 +4. **產生授權碼** — 頁面會產生一個簡短的授權碼和一段可直接貼上的指令文字。 +5. **貼給 AI Agent** — 複製指令文字傳送給助手，Agent 用下面任一方式兌換授權碼。 + +授權碼有效期 **5 分鐘**，且**僅可使用一次**。 + +## 透過 CLI 兌換 + +用 `--auth-code` 參數把授權碼傳給 `auth login`，將範例授權碼替換為你的真實授權碼： + + +# 兌換從 connect 頁面產生的授權碼 +longbridge auth login --auth-code 6vYzXq3WbKp9TmHd + + +兌換成功後，Token 儲存至 `~/.longbridge/openapi/tokens/`，後續所有命令自動複用——與瀏覽器登入效果一致。完整的 `auth` 命令參考見 [安裝](/zh-HK/docs/cli/install)。 + +## 透過 MCP 兌換 + +授權碼兌換走專用端點 **`https://mcp.longbridge.com/agent`**。該端點允許未授權連接，工作階段在未授權時僅暴露 `authenticate` 這一個工具。主端點 `https://mcp.longbridge.com` 僅支援標準 OAuth 2.1，不提供 `authenticate`——完整支援 OAuth 的客戶端應直接用主端點，`/agent` 是 OAuth 不可用時的備用通道。 + +**流程：** + +1. **設定 `/agent` 端點** — 將客戶端指向 `https://mcp.longbridge.com/agent`，未授權工作階段只顯示 `authenticate` 工具。 +2. **呼叫 `authenticate` 傳入授權碼** — 你可以這樣告訴助手：「用授權碼 1234567890 為 Longbridge MCP 工作階段完成授權。」Agent 即會帶該授權碼呼叫 `authenticate`。 +3. **將回傳的 Token 設定為 Bearer header** — 兌換成功後，工具結果會回傳一個 Token。按結果中的指引讓客戶端在後續請求中以 `Authorization: Bearer ` 攜帶它，其餘 Longbridge MCP 工具隨即可用——無需瀏覽器跳轉。 + +以 Claude Code 為例，用該 Token 作為 header 重新新增服務： + +```bash +claude mcp add --transport http longbridge https://mcp.longbridge.com --header "Authorization: Bearer " +``` + +將 `` 替換為 `authenticate` 回傳的 Token。注意此處指向的是主端點 `https://mcp.longbridge.com`——拿到 Bearer Token 後即可直接連接主端點。 + +## 安全說明 + +- **權限在網頁端預選** — 授權碼只能授予你在授權頁勾選的權限，Agent 無法請求超出授權碼攜帶範圍的權限。 +- **5 分鐘有效期** — 授權碼在產生 5 分鐘後過期。 +- **一次性使用** — 授權碼在首次成功兌換後即失效，不可重複使用。 +- **隨時可撤銷** — 前往 Longbridge 帳戶安全設定，撤銷 **AI Agent** 授權即可終止存取。 + +遵循最小權限原則：只授予當前任務所需的權限範圍。涉及交易的授權，務必要求 Agent 在下單前與你確認。 + +## 常見問題 + +### 授權碼已過期 + +授權碼有效期為 5 分鐘。回到 [https://open.longbridge.com/connect](https://open.longbridge.com/connect) 重新產生一個，並盡快兌換。 + +### 授權碼已被使用 + +每個授權碼僅可使用一次。若此前已兌換成功，則你已完成授權，無需再次兌換。如需新的工作階段，請重新產生授權碼。 + +### 授予的權限不夠 + +授權碼只攜帶在授權頁勾選的權限範圍。重新產生一個授權碼並勾選所需的額外權限，再次兌換即可重新整理工作階段權限。 + +### 兌換後仍無法連線 + +- 確認 Longbridge 帳戶狀態正常且已完成身分認證。 +- 確認所選權限範圍涵蓋你嘗試執行的操作（例如交易需要交易權限）。 +- 對於 MCP，確認 Agent 連接 `https://mcp.longbridge.com/agent` 呼叫 `authenticate`，再用回傳的 `Authorization: Bearer` Token 連接 `https://mcp.longbridge.com`。 diff --git a/docs/zh-HK/docs/cli/install.md b/docs/zh-HK/docs/cli/install.md index dcd9ac6e..918681ef 100644 --- a/docs/zh-HK/docs/cli/install.md +++ b/docs/zh-HK/docs/cli/install.md @@ -58,6 +58,12 @@ longbridge auth login 執行 `auth login` 後會印出一個 URL 和短碼。在任意瀏覽器中開啟該 URL，輸入短碼並授權。Token 儲存至 `~/.longbridge/openapi/tokens/`，後續所有命令自動複用。 +如無可用瀏覽器，可在 [https://open.longbridge.com/connect](https://open.longbridge.com/connect) 產生[授權碼](/zh-HK/docs/agent-auth)並直接兌換： + +```bash +longbridge auth login --auth-code 6vYzXq3WbKp9TmHd +``` + ### auth logout 清除已儲存的 OAuth Token。下次執行命令或啟動 TUI 時將重新觸發鑑權。 diff --git a/docs/zh-HK/docs/mcp.md b/docs/zh-HK/docs/mcp.md index 87be40a5..eb6de257 100644 --- a/docs/zh-HK/docs/mcp.md +++ b/docs/zh-HK/docs/mcp.md @@ -12,8 +12,8 @@ next: false Longbridge 提供托管的 HTTP MCP（Model Context Protocol）服務，讓你在 AI 編程助手或對話工具中直接使用 Longbridge 的行情與帳戶能力，無需手動管理 API 金鑰。 :::tip MCP 服務地址 -- 全球：`https://openapi.longbridge.com/mcp` -- 中國大陸：`https://openapi.longbridge.cn/mcp`（訪問更快） +- 全球：`https://mcp.longbridge.com` +- 中國大陸：`https://mcp.longbridge.cn`（訪問更快） ::: ## 可用能力 @@ -49,7 +49,7 @@ Longbridge MCP 暴露 100+ 工具，覆蓋六大能力域，客戶端連接後 在終端執行以下命令： ```bash -claude mcp add --transport http longbridge https://openapi.longbridge.com/mcp +claude mcp add --transport http longbridge https://mcp.longbridge.com ``` 然後進入 `claude` 終端介面，輸入 `/mcp`，選擇 `longbridge`，再選擇 **Authenticate** 跟隨流程完成 OAuth 授權。 @@ -60,7 +60,7 @@ claude mcp add --transport http longbridge https://openapi.longbridge.com/mcp 2. 在 "Connect to a custom MCP" 介面填寫： - Name：`longbridge` - 類型：**Streamable HTTP** - - URL：`https://openapi.longbridge.com/mcp` + - URL：`https://mcp.longbridge.com` - 其他欄位留空 3. 點擊 **Save** 4. 回到 MCP Servers 列表，點擊 `longbridge` 條目上的 **Authenticate** 完成 OAuth 授權 @@ -77,7 +77,7 @@ Settings → MCP Servers → 添加 Remote MCP Server，填入上方地址即可 { "mcpServers": { "longbridge": { - "url": "https://openapi.longbridge.com/mcp" + "url": "https://mcp.longbridge.com" } } } @@ -118,6 +118,10 @@ Longbridge MCP 依賴 **MCP OAuth 2.1** 標準。若客戶端未完整實作該 如遇其他客戶端連線失敗，請確認客戶端版本並查閱其 MCP 支援文件。 +:::tip 客戶端無法開啟瀏覽器？ +若客戶端的 OAuth 實作不完整或無法拉起瀏覽器，可改用[授權碼授權](/zh-HK/docs/agent-auth)：在 [https://open.longbridge.com/connect](https://open.longbridge.com/connect) 產生一次性授權碼，連接專用端點 `https://mcp.longbridge.com/agent`，讓 Agent 透過 `authenticate` 工具兌換。 +::: + ## 安全建議 - **最小權限**：授權時僅同意當前任務所需的 scope，避免過度授權 diff --git a/docs/zh-HK/skill/install/index.md b/docs/zh-HK/skill/install/index.md index 80b43323..f270cb76 100644 --- a/docs/zh-HK/skill/install/index.md +++ b/docs/zh-HK/skill/install/index.md @@ -7,7 +7,7 @@ description: 在 OpenClaw、Claude Code、Cursor、Codex 等 AI 工具中安裝 @@ -69,6 +69,12 @@ iwr https://open.longbridge.com/longbridge/longbridge-terminal/install.ps1 | iex longbridge auth login ``` +已有來自 [open.longbridge.com/connect](https://open.longbridge.com/connect) 的一次性授權碼？直接兌換，無需瀏覽器： + +```bash +longbridge auth login --auth-code 1234567890 +``` + 完成後，AI 即可代你調用 `longbridge` 命令。 **Claude Code 用戶：** Claude 首次執行 `longbridge` 指令時會彈出權限確認提示。若要避免每次都被詢問，可在專案的 `.claude/settings.json` 中新增以下配置（文件不存在時新建）： @@ -90,7 +96,7 @@ longbridge auth login 在 AI 工具的 MCP 配置中新增以下伺服器地址： ``` -https://openapi.longbridge.com/mcp +https://mcp.longbridge.com ``` 對於使用 JSON 配置文件的客戶端（Claude Desktop、Cursor、Zed、Gemini CLI 等），將以下內容添加到 MCP 配置中： @@ -99,13 +105,13 @@ https://openapi.longbridge.com/mcp { "mcpServers": { "longbridge": { - "url": "https://openapi.longbridge.com/mcp" + "url": "https://mcp.longbridge.com" } } } ``` -> 中國大陸用戶可使用加速地址：`https://openapi.longbridge.cn/mcp` +> 中國大陸用戶可使用加速地址：`https://mcp.longbridge.cn` 各工具配置入口： diff --git a/region.config.ts b/region.config.ts index d3b3136d..646c299f 100644 --- a/region.config.ts +++ b/region.config.ts @@ -42,6 +42,9 @@ export const regionConfig: Record = { // MCP '**/docs/mcp.md', + // Agent Auth Code + '**/docs/agent-auth.md', + // AI Skills '**/skill/**', ], diff --git a/skills/longbridge/references/mcp.md b/skills/longbridge/references/mcp.md index 6059e52f..22ec8b1b 100644 --- a/skills/longbridge/references/mcp.md +++ b/skills/longbridge/references/mcp.md @@ -4,7 +4,7 @@ Longbridge provides MCP (Model Context Protocol) support in two modes: a hosted ## Hosted MCP Service -**Endpoint:** `https://openapi.longbridge.com/mcp` +**Endpoint:** `https://mcp.longbridge.com` No API keys needed — uses OAuth 2.1. The AI client handles the browser authorization flow automatically. @@ -16,7 +16,7 @@ Add to MCP config in any compatible client: { "mcpServers": { "longbridge": { - "url": "https://openapi.longbridge.com/mcp" + "url": "https://mcp.longbridge.com" } } } @@ -25,7 +25,7 @@ Add to MCP config in any compatible client: **Per-client setup:** - **Cursor**: Settings → MCP Servers → Add Remote MCP Server -- **Claude Code**: `claude mcp add longbridge https://openapi.longbridge.com/mcp` +- **Claude Code**: `claude mcp add longbridge https://mcp.longbridge.com` - **ChatGPT**: Settings → Connectors - **Zed**: `context_servers` in `settings.json` - **Cherry Studio**: Settings → MCP Servers → Add (requires latest version for OAuth support) @@ -38,6 +38,16 @@ Add to MCP config in any compatible client: 4. Credentials are stored by the client; tokens refresh automatically 5. To revoke: Longbridge account → Security Settings +**No browser? Use an auth code.** If the client can't open a browser or has +incomplete OAuth support, have the user generate a one-time auth code at +https://open.longbridge.com/connect, then connect to the dedicated +**authorization endpoint** `https://mcp.longbridge.com/agent` — an auth-only +channel, NOT the MCP service address (it allows unauthorized connections and +exposes only the `authenticate` tool) — and call `authenticate` with that code +from the unauthorized session. The tool returns a token; configure the client to +send it as `Authorization: Bearer ` against `https://mcp.longbridge.com` +(e.g. `claude mcp add --transport http longbridge https://mcp.longbridge.com --header "Authorization: Bearer "`). + ### Security Recommendations - Only approve scopes required for the task (least privilege) diff --git a/skills/longbridge/references/setup.md b/skills/longbridge/references/setup.md index 64f09a53..add5b94c 100644 --- a/skills/longbridge/references/setup.md +++ b/skills/longbridge/references/setup.md @@ -26,6 +26,19 @@ Authenticate: longbridge auth login ``` +If the browser OAuth flow is unavailable (no browser, headless, or a client that +can't open links), have the user generate a one-time auth code at +https://open.longbridge.com/connect, then redeem it: + +```bash +longbridge auth login --auth-code +``` + +For MCP clients, redeem the code against the dedicated authorization endpoint +`https://mcp.longbridge.com/agent` via the `authenticate` tool (auth-only +channel — the MCP service address remains `https://mcp.longbridge.com`) — see +[references/mcp.md](references/mcp.md). + ## CLI Update ```bash @@ -40,7 +53,7 @@ curl -sSL https://open.longbridge.com/longbridge/longbridge-terminal/install | s ```bash # Claude Code -claude mcp add longbridge https://openapi.longbridge.com/mcp +claude mcp add longbridge https://mcp.longbridge.com ``` First tool call triggers an OAuth browser flow. See [references/mcp.md](references/mcp.md) for Cursor, ChatGPT, Zed.