ojo-plugin

VS Code extension for Ojo integration.

Commands

• Ojo: Open Project (ojo-plugin.openWeb)
  • Click from status bar $(globe) Ojo or activity bar Ojo icon.
  • Shows a project picker (loaded via ojo project list --json --page-size 100).
  • Selecting a project opens /p/{projectId} in IDE built-in browser.
  • If project list fetch fails or returns empty, falls back to manual Project ID input.
  • Reads CLI auth state from ~/.nexight/session.json (same as CLI).
  • If auth state is valid, requests /api/account/api/auth/v1/create_ide_handoff and opens /login/ide?ticket=... for browser confirmation.
  • If auth state is missing/invalid or handoff fails, opens the target web URL directly.
  • Launch URL includes IDE context query params: ide_in_app, ide_client, ide_local_server, ide_sync_token.

Cursor MCP

• When the extension activates in Cursor, it attempts to register a session-scoped Ojo MCP server through vscode.cursor.mcp.registerServer().
• The extension also persists ojo into Cursor MCP config for durability:
  • global: ~/.cursor/mcp.json
  • workspace: .cursor/mcp.json
• Registration merges mcpServers.ojo and does not overwrite unrelated MCP server entries.
• The MCP server is the bundled dist/mcpServer.js, launched via node over stdio.
• In plain VS Code, MCP registration is skipped without surfacing an error.

IDE MCP Usage Notes

• On first use, agents should call ojo_llm_guide before invoking other Ojo MCP tools.
• The MCP surface is intentionally limited to: ojo_llm_guide, ojo_login, ojo_logout, ojo_project_list, ojo_project_url, ojo_open_editor, ojo_chat, ojo_workspace_sync, and ojo_query.
• Most project tools expect either an initialized local workspace that contains .ojo/project.json, or an explicit projectId when the tool supports it.
• Login-required tools rely on the same local auth state used by the CLI.
• Long-running chat flows should be checked with ojo_query instead of sending duplicate requests.
• ojo_chat only supports two shapes: { message } to create a new project and thread automatically, or { projectId, threadId, message } to continue an existing thread.
• ojo_query requires explicit { projectId, runId }.

IDE MCP Tool Reference

Auth

• ojo_login

  • Purpose: sign in to Ojo from the IDE MCP server.
  • Parameters: mode? (web | device | pat), pat?, noOpen?.
  • Returns: plain text, not JSON.
  • Return fields explanation: the text may include a login URL, verification URL, device code, expiration window, or next-step guidance depending on the chosen login mode.
  • Notes: ask the user which login mode they want before invoking it; returns plain-text guidance because login may need URLs, device codes, or browser steps.

• ojo_logout

  • Purpose: clear the current local Ojo session.
  • Parameters: none.
  • Returns: JSON with success: true.
  • Return fields explanation: success means the local auth state was cleared successfully.
  • Notes: returns JSON with success: true.

Guide

• ojo_llm_guide
  • Purpose: read the full Ojo LLM/Agent guide used by the IDE integration.
  • Parameters: none.
  • Returns: plain text, not JSON.
  • Return fields explanation: the body is the authoritative guide content and should be read as-is before using other Ojo tools.
  • Notes: read-only; agents should call this first.

Project

• ojo_project_list

  • Purpose: list Ojo projects visible to the current account.
  • Parameters: pageSize?, pageToken?, favorite?.
  • Returns: paginated JSON project list.
  • Return fields explanation: projects is the current page, next_page_token is the next-page cursor, total is the total matched count. Each projects[] item may include project_id, name, created_at, updated_at, creator_uid, cover_res_id, status, and is_favorite.
  • Notes: requires login; use before open/sync/chat flows when the project needs to be discovered first.

• ojo_project_url

  • Purpose: return the canonical Ojo project editor URL for an explicit projectId without opening a browser.
  • Parameters: projectId (required).
  • Returns: JSON project target info.
  • Return fields explanation: projectId is the normalized target project, targetPath is the web path like /p/<projectId>, and url is the final editor URL.
  • Notes: read-only; no workspace context or login is required.

• ojo_open_editor

  • Purpose: open the current workspace project in the Ojo web editor.
  • Parameters: cwd?, projectId?.
  • Returns: JSON describing the open result.
  • Return fields explanation: projectId is the resolved project, targetPath is the web path like /p/<projectId>, url is the final browser URL, openedVia tells whether the builtin bridge or external browser opened it, and handoff explains why that URL was chosen.
  • Notes: side-effectful; resolves the nearest .ojo/project.json; if local auth is valid, it attempts IDE handoff through /api/account/api/auth/v1/create_ide_handoff and /login/ide?ticket=..., otherwise it falls back to opening the target page directly.

Chat And Query

• ojo_chat

  • Purpose: send one message to Ojo for a target project.
  • Parameters: message (required), projectId?, threadId?, debug?.
  • Returns: final JSON chat result.
  • Return fields explanation: projectId is the target project, projectUrl is the project page link, threadId is the resolved thread, runId is the created run, status is completed or waiting_input, text is the final assistant text, inspireQuestions contains suggested follow-up prompts when available, and interrupt is present only when the run pauses for more user input.
  • Notes: requires login; send only message to auto-create a new project and thread, or send projectId + threadId + message to continue an existing thread. Partial context is rejected.

• ojo_query

  • Purpose: inspect the status of a previously started run.
  • Parameters: projectId (required), runId (required).
  • Returns: JSON run status payload.
  • Return fields explanation: projectId is the queried project, projectUrl is the project page link, runId is the inspected run, and status is one of running, success, or fail. When status is running, statusText contains the current short progress copy. When status is fail, failure contains the structured reason.
  • Notes: use this after long-running ojo_chat calls instead of retrying the original message; callers must provide an explicit runId.

Workspace And Workflow

• ojo_workspace_sync
  • Purpose: sync workspace files from Ojo into the local filesystem.
  • Parameters: cwd?, path?.
  • Returns: JSON workspace sync result.
  • Return fields explanation: project_id is the synced project, thread_id is the locally bound thread when available, path is the local output directory, and workspace_hash identifies the synced snapshot version.
  • Notes: requires login and initialized project context; this is workspace-bound and not a replacement for ojo_project_list or ojo_open_editor.

CLI Auth State Contract

Primary file path (same as CLI):

• ~/.nexight/session.json

Supported JSON (CLI default):

• sessionId (string, required)
• updatedAt (number, optional)

Backward-compatible legacy format:

• ~/.ojo/session.json
• session_id, user_id, created_at_ms, expires_at_ms, source

Invalid JSON or missing session id means "no auth state" and no ticket injection.

内置浏览器与链接打开

扩展默认会将所有 ojo.art 页面（包含子域名）配置为在 Cursor/IDE 内置浏览器中打开；如需调整范围，可通过 productUriGlobs 自定义匹配规则。该能力包括：

• 终端：终端中的匹配链接点击后在内置浏览器打开
• 右侧面板（Chat/Composer）：使用 registerExternalUriOpener（proposed API）拦截链接，在内置浏览器打开

右侧面板支持需要启用 proposed API。调试时在 .vscode/launch.json 中已配置 --enable-proposed-api。在 Cursor 中若需此功能，可添加启动参数：

--enable-proposed-api=ojo.ojo-plugin

Settings

• ojoPlugin.accountApiBaseUrl: account API base URL for create_ide_handoff.
• ojoPlugin.webBaseUrl: web app base URL.
• ojoPlugin.productUriGlobs: URI 模式列表，匹配的链接在内置浏览器中打开，默认覆盖 ojo.art 及其子域名页面。
• ojoPlugin.webTargetPath: fallback target path to open.
• ojoPlugin.loginBridgePath: IDE 登录确认入口路径（默认 /login/ide，ticket 在浏览器确认后消费）。