Skip to main content
Glama

OVB3: Oracle Visual Builder Bridge

OVB3 = Oracle Visual Builder + 3 (a nod to Thrishul: त्रिशूल, trident) + Bridge.

Work on Oracle Visual Builder Studio (VBS) / VBCS apps from Claude instead of the browser IDE. OVB3 is a Claude Code plugin, an MCP server and a CLI that let Claude read, search, edit, build, audit, commit and push the files a VB Studio project is made of. It can also manage data and CI jobs on your instance.

It deliberately works on the artifacts and git (the JSON/JS files and the repo behind a VB Studio project, plus Oracle's own grunt-vb-* tasks) rather than scripting the design-time browser UI, which has no public API and breaks whenever Oracle updates it. See docs/VBS-GUIDE.md for the confirmed repo layout and build behavior this is built against.

Unofficial community project. Not affiliated with, endorsed by, or supported by Oracle. "Oracle", "Visual Builder" and related names are trademarks of Oracle and are used only to say what this tool works with. It is early software: review what Claude changes before you push, and try it on a non-production project first.

Nothing is tied to one project: an instance hosts many VB Studio projects (git repos), each holding many apps under webApps/, and every tool takes the repo and app as arguments.

Quick start

1. Install (Claude Code):

/plugin marketplace add vanamthrishul/ovb3-bridge
/plugin install ovb3@ovb3

Claude Code asks for a workspace folder (any folder to hold your repo checkouts) and, optionally, git credentials and defaults. Secrets such as the git token are kept in your system keychain.

2. Link a project: run /ovb3:link and it walks you through cloning a repo (or pointing at one you already have).

3. Check it: run /ovb3:vbs-doctor. It tells you what works, what's missing, and the exact fix for each. This is the first thing to run whenever something doesn't work.

No Claude Code? The same tools ship as a CLI and a plain MCP server; see Other ways to run it.

Related MCP server: workday-studio-mcp

What you can do

Area

Tools (also ovb3 <command> in the CLI)

Notes

Diagnose

doctor

Checks Node, git, workspace, credentials, build tools; never prints secrets

Browse & edit

list_repos, list_apps, list_artifacts, read_artifact, write_artifact

write_artifact refuses invalid JSON and any path outside the repo

Search

search_artifacts

Grep file content (text or regex) across a repo

Cross-app audit

audit_service_calls

Finds every Actions.callRest call and flags parameter keys some apps send and others omit

Git

git_status, git_commit, git_pull, git_push, git_clone

Non-interactive: authenticates with your token and fails fast instead of hanging

Build & audit

setup_build_tools, run_build, run_audit

Oracle's grunt-vb-build / grunt-vb-audit; failures come with a plain-language hint

VB Studio CI

vbstudio_trigger_build, vbstudio_build_status, vbstudio_job_params

Oracle's documented Builds REST API; the base URL is derived from your repo's git remote

Standalone VBCS

vbcs_list_applications, vbcs_lock_application, vbcs_unlock_application, vbcs_export_bo_data, vbcs_import_bo_data

For VBCS apps with no VB Studio project; export/import business-object data as CSV/ZIP

Slash commands exist for each (/vbs-help and /vbcs-help list them; they're namespaced /ovb3:… when installed as a plugin). You can also just ask in plain language: "find every app that calls the Orders service without the region parameter" resolves to the same tools.

Example: check a shared service is called consistently

/vbs-audit-calls my-vbs-project Orders/getOrders

reports, per endpoint, which apps call it and any parameter key that some apps pass and others don't. It compares which keys are passed, not their values (values are arbitrary expressions).

Setting up credentials

Never paste credentials into a Claude conversation. Set them in plugin settings (/plugin → OVB3 → Configure, then /reload-plugins) or in a config file (see below).

You want

Set

Clone / pull / push over HTTPS

VBSTUDIO_GIT_USERNAME + VBSTUDIO_GIT_TOKEN (a VB Studio personal access token)

run_build / run_audit on apps with web components (most)

VB_BUILD_COMPONENT_EXCHANGE_URL: in VB Studio under Tenant Settings → Component Exchange; a private exchange looks like https://<vbs-host>/<org>/s/<org>_<project>/compcatalog/0.2.0

VB Studio CI jobs

VBSTUDIO_API_TOKEN (or leave it blank and your VBSTUDIO_GIT_TOKEN is reused as the bearer token)

Standalone VBCS

VBCS_BASE_URL (bare host, no /ic/builder), VBCS_IDCS_USERNAME, VBCS_IDCS_PASSWORD

Git credentials are sent as a scoped HTTP header, never put in URLs, logs or .git/config, and everything logged or returned in an error is redacted. Personal access tokens expire: if git starts failing with "Authentication failed" on something that used to work, generate a new one.

Outside the plugin, config is read from (highest priority first): real environment variables, ./.env, then the install's own file: <clone>/.env for a git clone, ~/.ovb3/.env for npm/npx installs (override with OVB3_ENV_FILE). .env.example documents every variable. ovb3 init creates and fills it interactively (non-secret fields only).

Build and audit: what to expect

run_build / run_audit run Oracle's tasks directly (no shell) inside your repo checkout:

  1. Run setup_build_tools once per checkout. VB Studio projects pin Oracle's grunt-vb-build / grunt-vb-audit tarballs in their own package.json, so no extra registry setup is needed. (If npm install fails, check access to static.oracle.com and registry.npmjs.org; if only non-Oracle packages fail, suspect a stale token in your global .npmrc.)

  2. Set the Component Exchange URL (above). Without it Oracle's own task stops with Missing mandatory component exchange URL. OVB3 detects that and tells you what to set. If your exchange needs a login, also set VB_BUILD_CE_USERNAME + VB_BUILD_CE_PASSWORD (or VB_BUILD_CE_ACCESS_TOKEN).

  3. run_audit also needs network access to a live Visual Builder backend (it fetches vb.services.catalog.json). On a machine that can't reach one you'll see ETIMEDOUT; that's a connectivity requirement, not a config flag.

Builds are stopped after 15 minutes by default (OVB3_BUILD_TIMEOUT_MS), and the whole process tree is killed, so nothing is left running.

Limits you should know about

These are properties of Oracle's APIs, not gaps waiting to be filled:

  • Standalone VBCS (no VB Studio project) has no page/flow editing. Oracle's published REST API for it has 14 endpoints: list/lock/unlock apps, a token endpoint, credential CRUD, and business-object data export/import. There is no whole-app export/import, version, build or deploy endpoint. If you want artifact editing, work from the app's VB Studio project.

  • VB Studio has no "deploy" API call: deploys are CI jobs or pipelines, so use vbstudio_trigger_build on the deploy job. Pipeline endpoints exist in Oracle's docs but their request shapes weren't published clearly enough to build against, so they're not included.

  • The service-call audit reads JavaScript action chains (Actions.callRest). It's a comment- and string-aware scanner, not a full JS parser; unusual dynamically built calls won't be seen.

  • Data import replaces by default in Oracle's API, so vbcs_import_bo_data makes you choose append or replace explicitly.

Other ways to run it

Plain MCP config (no plugin): add to any project's .mcp.json; runs via npx, nothing to clone:

{
  "mcpServers": {
    "vbcs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ovb3-bridge"],
      "env": { "VBS_WORKSPACE_DIR": "/absolute/path/to/a/workspace/folder" }
    }
  }
}

Copy commands/*.md into .claude/commands/ if you want the /vbs-* shortcuts.

CLI: npm install -g ovb3-bridge, then ovb3 init, ovb3 doctor, ovb3 list-repos, ovb3 search <repo> <text>, … (ovb3 --help lists them all). Run ovb3 init yourself in a terminal; when driving setup through an AI agent, use /link instead; the wizard is interactive and an agent can't type into it.

From source (contributing, or running an unreleased commit):

git clone https://github.com/vanamthrishul/ovb3-bridge.git
cd ovb3-bridge
npm install      # also compiles TypeScript into dist/ (via "prepare")
npm test
node dist/cli.js doctor

Every tool call is logged to stderr (what was touched, git operations, build/audit output as it streams), so nothing happens silently.

Troubleshooting

Run doctor first. Beyond that:

  • plugin:ovb3:vbcs shows ✗ in /mcp right after install: the first launch downloads the package via npx, which can exceed Claude Code's 30s connect limit on a slow or restricted network. Select the server in /mcp and choose reconnect (it starts fast once the cache is warm), or run npx -y ovb3-bridge once in a terminal first and press Ctrl+C after the startup line.

  • doctor in a plain terminal says everything is unset: plugin config is only injected when Claude Code launches the server. Run /ovb3:vbs-doctor inside Claude Code to see the real picture.

  • Git says "Authentication failed": your token is missing, wrong or expired (see credentials above). OVB3 never waits on a hidden prompt; it fails in seconds with this message.

  • Git stalls then times out: the host in the remote URL is unreachable. A stale host in an old URL (e.g. a retired test environment) is a common cause.

  • Missing mandatory component exchange URL: set the Component Exchange URL.

  • Backend fetch failed … ETIMEDOUT from run_audit: this machine can't reach a Visual Builder backend (VPN/proxy).

  • VBCS login fails: VBCS_BASE_URL must be the bare host. If you copied it from the browser and it's very long with ?state=… in it, that's a login redirect, not the instance URL.

Contributing

Issues and PRs welcome (all changes land through a reviewed pull request). Questions or feedback: open an issue, or email thrishulkrishna3@gmail.com. Please report security problems privately; see SECURITY.md. npm test must pass; CI runs it on Linux, macOS and Windows. A packaging test keeps the two command folders, the version numbers and .env.example in sync with the code.

MIT licensed.

Available Tools

24 tools
audit_service_callsA
Read-onlyIdempotent

Cross-app audit of REST service usage: finds every Actions.callRest call in the repo's action-chain JS, and for each service endpoint compares which parameter keys (uriParams/body/headers…) each app passes, flagging keys some apps send that others omit. Compares key sets, not values. Use it to check a shared service connection is mapped consistently across apps.

Inputs: apps, repo, endpoint, includeCalls.

doctorA
Read-onlyIdempotent

Diagnose this install: Node/git, workspace + repos, git credentials, build tools, Component Exchange URL, and optional services. Reports what's missing and the exact fix; never prints secrets. Run this first when something doesn't work. Set live=true to also test the standalone-VBCS login.

Inputs: live, repo.

git_cloneA

Clone a git remote into VBS_WORKSPACE_DIR so it's discoverable by list_repos. Used by /link's VBS setup flow. Do not embed credentials in remoteUrl - set VBSTUDIO_GIT_USERNAME/TOKEN instead.

Inputs: destName (required), remoteUrl (required).

git_commitB

Stage and commit changes in a repo checkout.

Inputs: message (required), repo, files.

git_pullB

Pull from the repo's remote. Authenticates with VBSTUDIO_GIT_USERNAME/TOKEN when set; never hangs on a hidden prompt.

Inputs: repo, branch, remote.

git_pushB

Push to the repo's remote. Authenticates with VBSTUDIO_GIT_USERNAME/TOKEN when set; never hangs on a hidden prompt.

Inputs: repo, branch, remote.

git_statusB
Read-onlyIdempotent

Show git status for a repo checkout.

Inputs: repo.

list_appsB
Read-onlyIdempotent

List VBCS web app names (webApps/) present in a repo checkout.

Inputs: repo.

list_artifactsA
Read-onlyIdempotent

List artifact files in a repo matching a glob pattern (file names only), e.g. 'webApps//flows/**/.json'. To search file CONTENT use search_artifacts.

Inputs: pattern (required), repo.

list_reposA
Read-onlyIdempotent

List local VB Studio project repo checkouts discoverable under VBS_WORKSPACE_DIR.

Inputs: no named parameters.

read_artifactB
Read-onlyIdempotent

Read a VBCS artifact file (page/flow/chain/service JSON, etc) by repo-relative path.

Inputs: path (required), repo.

run_auditA
Read-onlyIdempotent

Run grunt-vb-audit for a VBCS app. Streams output live to server logs. Needs the same setup as run_build, plus network access to a live Visual Builder backend; failures include a plain-language hint.

Inputs: repo, appName.

run_buildA

Run grunt-vb-build for a VBCS app. Streams output live to server logs. Needs setup_build_tools first, and VB_BUILD_COMPONENT_EXCHANGE_URL for apps using web components; failures include a plain-language hint.

Inputs: repo, appName.

search_artifactsA
Read-onlyIdempotent

Search artifact file CONTENT across a repo (grep). Substring by default, or a regex. Defaults to webApps/services/settings .js/.json/.html/.css/.md files; narrow with glob.

Inputs: query (required), glob, repo, regex, +2 more.

setup_build_toolsA

Install a repo's build dependencies (npm install) so run_build / run_audit work. VB Studio projects pin Oracle's grunt-vb-build/grunt-vb-audit in their own package.json, so no extra config is needed. Can take several minutes.

Inputs: repo.

vbcs_export_bo_dataA
Read-onlyIdempotent

Export business-object data from a standalone VBCS instance: one object as CSV (returned inline unless outputPath is given), or omit boName to export every object as a ZIP of CSVs (always saved to disk; path returned).

Inputs: appName (required), appVersion (required), boName, target, +1 more.

vbcs_import_bo_dataA
Destructive

Import business-object data into a standalone VBCS instance from a local .csv/.xls/.xlsx (one object; file name must equal the object id) or .zip (several). mode is required: 'append' adds rows, 'replace' OVERWRITES the object's existing data. Lock a live app first.

Inputs: mode (required), appName (required), filePath (required), appVersion (required), +2 more.

vbcs_list_applicationsA
Read-onlyIdempotent

List applications on a standalone VBCS instance via its REST API (VBCS_BASE_URL). For VBCS apps not backed by a VB Studio git repo.

Inputs: filter.

vbcs_lock_applicationA
Idempotent

Lock a live application on a standalone VBCS instance (do this before exporting/importing its data).

Inputs: branchId (required).

vbcs_unlock_applicationC
Idempotent

Unlock a locked live application on a standalone VBCS instance.

Inputs: branchId (required).

vbstudio_build_statusB
Read-onlyIdempotent

Get the status (e.g. SUCCESSFUL) of a VB Studio CI build from its job name and build number.

Inputs: jobName (required), buildNumber (required), repo.

vbstudio_job_paramsA
Read-onlyIdempotent

Get a parameterized VB Studio CI job's parameter definitions (YAML), to build the paramsYaml for vbstudio_trigger_build.

Inputs: jobName (required), repo.

vbstudio_trigger_buildA

Start a VB Studio CI job (also how you run a deploy job/pipeline step) via the documented Builds REST API. Returns the build number. The API base is derived from the repo's git remote. Credentials: VBSTUDIO_API_TOKEN, or VBSTUDIO_API_USERNAME/PASSWORD (falling back to the git credentials).

Inputs: jobName (required), repo, paramsYaml.

write_artifactB
DestructiveIdempotent

Write a VBCS artifact file by repo-relative path. Refuses invalid JSON for .json paths and any path outside the repo.

Inputs: path (required), content (required), repo.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 24 tools

    Disambiguation4/5

    Most tools target clearly distinct resources and actions, and descriptions are explicit about scope. The only near-collisions are name-level: list_apps (repo web apps) vs vbcs_list_applications (live standalone VBCS apps), and run_build (local grunt) vs vbstudio_trigger_build (CI job), but the descriptions disambiguate them well.

    Naming Consistency4/5

    All names are snake_case with functional prefixes (git_, vbcs_, vbstudio_) that map cleanly to subsystems, mostly following verb_noun. Minor deviations exist: 'doctor' is a bare noun and 'vbstudio_job_params' lacks a verb, but the pattern remains highly readable.

    Tool Count4/5

    24 tools is on the heavy side, but the server spans five distinct areas (git, artifacts, build, standalone VBCS, CI), each with roughly 3-6 well-differentiated tools. Each tool appears to earn its place; the count is justified by the broad bridge scope rather than padding.

    Completeness3/5

    Core workflows are covered (clone/commit/push, read/write/search artifacts, build+audit, live VBCS export/import, CI trigger/status). However, there are notable gaps: no delete_artifact, no git diff/log/branch operations, and no way to cancel or list CI builds/jobs, which will force agents into dead ends for cleanup and inspection tasks.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides comprehensive access to Salesforce Tooling API for metadata management, SOQL queries, code analysis, and debugging through Claude and other AI assistants.
      48 npm
      5
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      A local MCP server that gives Claude direct access to Workday Studio workspace. Enables reading, writing, planning, and validating integration assemblies without network calls or tenant credentials.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that connects Claude Desktop to an Oracle Fusion Cloud instance. It exposes suppliers, purchase orders, invoices, and project costs as callable tools.
      -