OVB3 Bridge
OVB3 Bridge is an MCP server/CLI/Claude Code plugin for reading, editing, building, auditing, and syncing Oracle VBCS/VB Studio projects and managing related CI/VBCS data.
Diagnose install, workspace, credentials, and build prerequisites (
doctor).List repos/apps/artifacts; read and safely write artifact files.
Find artifacts by glob and search file contents (text or regex).
Audit cross-app REST service calls and parameter-key consistency.
Run git status, commit, pull, push, and clone non-interactively.
Install build tools and run Oracle
grunt-vb-build/grunt-vb-audit.Trigger VB Studio CI builds, check status, and inspect job parameters.
For standalone VBCS: list/lock/unlock apps and export/import business-object data.
Provides tools for interacting with local Git repositories of Oracle Visual Builder Studio projects: listing repos, checking git status, committing, pulling, and pushing changes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OVB3 Bridge List VBCS apps in the sales repo"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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@ovb3Claude 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 | Notes |
Diagnose |
| Checks Node, git, workspace, credentials, build tools; never prints secrets |
Browse & edit |
|
|
Search |
| Grep file content (text or regex) across a repo |
Cross-app audit |
| Finds every |
Git |
| Non-interactive: authenticates with your token and fails fast instead of hanging |
Build & audit |
| Oracle's |
VB Studio CI |
| Oracle's documented Builds REST API; the base URL is derived from your repo's git remote |
Standalone VBCS |
| 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/getOrdersreports, 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 |
|
|
|
VB Studio CI jobs |
|
Standalone VBCS |
|
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:
Run
setup_build_toolsonce per checkout. VB Studio projects pin Oracle'sgrunt-vb-build/grunt-vb-audittarballs in their ownpackage.json, so no extra registry setup is needed. (Ifnpm installfails, check access tostatic.oracle.comandregistry.npmjs.org; if only non-Oracle packages fail, suspect a stale token in your global.npmrc.)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(orVB_BUILD_CE_ACCESS_TOKEN).run_auditalso needs network access to a live Visual Builder backend (it fetchesvb.services.catalog.json). On a machine that can't reach one you'll seeETIMEDOUT; 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_buildon 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_datamakes you chooseappendorreplaceexplicitly.
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 doctorEvery 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:vbcsshows ✗ in/mcpright after install: the first launch downloads the package vianpx, which can exceed Claude Code's 30s connect limit on a slow or restricted network. Select the server in/mcpand choose reconnect (it starts fast once the cache is warm), or runnpx -y ovb3-bridgeonce in a terminal first and pressCtrl+Cafter the startup line.doctorin a plain terminal says everything is unset: plugin config is only injected when Claude Code launches the server. Run/ovb3:vbs-doctorinside 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 … ETIMEDOUTfromrun_audit: this machine can't reach a Visual Builder backend (VPN/proxy).VBCS login fails:
VBCS_BASE_URLmust 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 toolsaudit_service_callsARead-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.
doctorARead-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_statusBRead-onlyIdempotent
Show git status for a repo checkout.
Inputs: repo.
list_appsBRead-onlyIdempotent
List VBCS web app names (webApps/) present in a repo checkout.
Inputs: repo.
list_artifactsARead-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_reposARead-onlyIdempotent
List local VB Studio project repo checkouts discoverable under VBS_WORKSPACE_DIR.
Inputs: no named parameters.
read_artifactBRead-onlyIdempotent
Read a VBCS artifact file (page/flow/chain/service JSON, etc) by repo-relative path.
Inputs: path (required), repo.
run_auditARead-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_artifactsARead-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_dataARead-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_dataADestructive
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_applicationsARead-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_applicationAIdempotent
Lock a live application on a standalone VBCS instance (do this before exporting/importing its data).
Inputs: branchId (required).
vbcs_unlock_applicationCIdempotent
Unlock a locked live application on a standalone VBCS instance.
Inputs: branchId (required).
vbstudio_build_statusBRead-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_paramsARead-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_artifactBDestructiveIdempotent
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
Scored across 24 tools
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.
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.
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.
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
Related MCP Connectors
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn 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 npm5MIT
- FlicenseNot gradedqualityCmaintenanceA 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.-
- AlicenseBqualityDmaintenanceMCP server for integrating coding agents (Claude Code CLI, etc.) with the GIMS Automation system. Enables development of automation scripts, data source types, activator types, and Git synchronization.61MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that connects Claude Desktop to an Oracle Fusion Cloud instance. It exposes suppliers, purchase orders, invoices, and project costs as callable tools.-