@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
• file-based preprocessing cho page và plugin authoring (v1.0.9+)
• auto-clear cache khi npm version thay đổi (v1.0.11+)

File-Based Preprocessing

Client tự động xử lý local file paths và convert sang inline content cho server:

Page Tools

| Tool | File Parameters | Processing | |------|-----------------|------------| | update_page | metadataFile, translationsFile, eventsFile, pageTourFile, pageTourTranslationsFile, approvalFile | Read JSON → parse → inline → delete path |

Workflow:

// 1. Download page to local
inspect_page({ workspaceCode, appCode, pageCode });
// → Files written to: oap-devkit/page-builder/{ws}/{app}/{pageCode}/

// 2. Edit local files (metadata.json, translations.json, etc.)

// 3. Update page with file path
update_page({ 
  workspaceCode, appCode, pageCode,
  metadataFile: 'D:/DEV/oap-platform/oap-devkit/page-builder/OVI_SUITE/hcm/MY_PAGE/metadata.json'
});
// → Client reads file, inlines content, sends to server

Plugin Tools

| Tool | File Parameters | Processing | |------|-----------------|------------| | deploy_plugin | sourcePath (folder) | Read folder structure → map to filesContent → inline → delete path |

Expected Plugin Structure:

plugin-folder/
├── plugin.json              # Top-level metadata (exact match)
├── Component.tsx            # Main component (exact match)
├── Component.css            # Styles (exact match)
├── index.tsx                # Entry point (exact match)
├── sources/                 # SQL resources (flat - NOT recursive)
│   ├── *.sql               # Query type
│   ├── *.plsql             # PL/SQL type
│   └── *.dml               # DML type
├── hooks/                   # Custom hooks (RECURSIVE)
│   └── *.ts, *.tsx, *.js, *.jsx, *.css
├── components/              # Nested components (RECURSIVE)
│   └── *.ts, *.tsx, *.js, *.jsx, *.css
└── utils/                   # Utilities (RECURSIVE)
    └── *.ts, *.tsx, *.js, *.jsx, *.css

Ignored: .backup/, backup/, build/, node_modules/, .git/

Workflow:

// 1. Download plugin to local
inspect_plugin({ workspaceCode, pluginCode });
// → Files written to: oap-devkit/plugin-builder/{ws}/{app}/{code}/

// 2. Edit local files (Component.tsx, sources/*.sql, etc.)

// 3. Deploy with folder path
deploy_plugin({
  workspaceCode, 
  appCode,
  pluginCode,
  sourcePath: 'D:/DEV/oap-platform/oap-devkit/plugin-builder/demo/DEMO/my-plugin'
});
// → Client reads entire folder structure recursively
// → Converts to filesContent map with relative paths
// → Sends inline to server
// → Server runs esbuild and deploys

Report Tools

| Tool | File Parameters | Processing | |------|-----------------|------------| | manage_report, manage_report_template | filePath | Read binary/template file → base64 → inline before forwarding | | report_render response hints | _fileHint._inlineContent | Decode base64 and write binary output under current workspace oap-devkit/reporting-builder/... |

Cross-Platform Path Handling

Client tự động xử lý path normalization cho:

• ✅ Windows (Git Bash / MINGW64) - giữ forward slashes
• ✅ Windows (PowerShell / cmd) - convert to backslashes
• ✅ Linux / macOS

Logic: buildPathCandidates() thử cả forward và backslash variants, không normalize absolute paths.

Version Management

Client tự động clear tools cache khi detect npm version mismatch:

// ~/.oap-devkit/version.txt tracks installed version
// On boot: if version.txt != package.json version → clear tools-cache.json
checkVersionAndClearCache();

Benefit: Không cần manual cache clear sau npm update.

Version History

| Version | Changes | |---------|---------| | v1.0.7 | Path normalization fix (Git Bash compat) | | v1.0.9 | File preprocessing: delete metadataFile after load | | v1.0.10 | File preprocessing: bundlePath & report filePath | | v1.0.11 | Auto-clear cache on version mismatch | | v1.0.12 | deploy_plugin folder preprocessing (basic) | | v1.0.13 | Recursive folder reading with SQL support | | v1.0.14 | Full backend structure match (sources/, hooks/, components/, utils/) | | v1.0.15 | Report tool consolidation, current-workspace auto-download, binary base64 file writes |

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