@ovigroup/oap-devkit

Thin npm client cho OAP Meta MCP. Package này không phải nơi chứa implementation MCP chính.

Source of truth

• Thin client / transport proxy: packages/oap-devkit
• MCP backend implementation: oap-meta/backend/src/mcp

Vai trò của package này

Package packages/oap-devkit/src/index.js và packages/oap-devkit/bin/oap-devkit.js chịu trách nhiệm:

• stdio ↔ SSE/HTTP proxy cho AI IDE
• profile / token management
• reconnect / session bootstrap
• local cache cho tools/resources
• optional runtimeBaseUrl persistence cho browser preview / runtime verification flow

Không sửa package này khi

Nếu yêu cầu thuộc các nhóm sau, ưu tiên sửa backend MCP ở oap-meta/backend/src/mcp:

• thêm MCP tool mới
• sửa auth / execution context của MCP
• sửa metadata resources
• sửa tool registry / JSON schema exposure
• sửa page/report/plugin/admin MCP behavior

Browser preview config

Tool add_server hỗ trợ thêm runtimeBaseUrl optional để lưu runtime URL riêng cho browser verification.

Ví dụ local profile trong .oap-devkit.json:

{
  "url": "http://localhost:3001",
  "token": "<jwt>",
  "runtimeBaseUrl": "http://localhost:5173"
}

Backend tool get_page_preview sẽ ưu tiên:

1. runtimeBaseUrl truyền trực tiếp vào tool
2. runtimeBaseUrl đã lưu trong profile/devkit config
3. runtime URL derive từ meta URL hoặc fallback localhost

Split trách nhiệm cho get_page_preview

• Backend oap-meta/backend/src/mcp/tools/allTools.ts trả previewUrl, browserVerification.checks, và fallback guidance.
• Thin client packages/oap-devkit/src/index.js tự resolve runtimeBaseUrl từ active profile trước khi gọi backend.
• Backend trả auth bootstrap additive:
  • baseUrl
  • runtimeUrl
  • injectScript
  • verificationChecks
  • authBootstrap

injectScript không còn nhét DEVKIT token trực tiếp vào browser. Thay vào đó backend sinh preview ticket một lần và script sẽ exchange ticket này qua /api/v1/auth/preview/exchange để lấy runtime session/token thật, rồi mới set sessionStorage['token'] và cookie auth_token.

Điểm vào chính

• CLI bootstrap: packages/oap-devkit/bin/oap-devkit.js
• Proxy runtime: packages/oap-devkit/src/index.js
• Profile/config helpers: packages/oap-devkit/src/profiles.js
• Backend MCP plugin: oap-meta/backend/src/mcp/McpPlugin.ts

Rule of thumb

Khi ai hỏi "oap-devkit đang được code ở đâu?":

1. Nếu hỏi về npm client / transport proxy → trả lời packages/oap-devkit
2. Nếu hỏi về implementation MCP chính / source of truth → trả lời oap-meta/backend/src/mcp