CPQ-BML VS Code Extension

A professional, feature-rich Visual Studio Code extension for Oracle CPQ BigMachines Language (BML). This extension serves as the ultimate development environment for CPQ professionals, providing IntelliSense, syntax highlighting, robust diagnostics/linting, workspace-wide formatting, remote REST integration, and MCP-powered AI assistance.

📖 Table of Contents

• Features at a Glance

• Key Capabilities

  • 1. Language Support & IntelliSense

  • 2. Workspace Formatter & Beautifier

  • 3. BML Linter & Real-time Diagnostics

  • 4. Better Comments & Documentation Headers

  • 5. Interactive Settings Dashboard WebView

  • 6. Remote REST Integration & Synchronization

  • 7. Model Context Protocol (MCP) Server for AI Integration

  • 8. AI Agent Skills Integration (AgentSkills.io)

  • 9. BML Color Themes

• ⌨ Commands Reference

• ⚙ Configuration Settings

• 🔧 Formatter Settings (.bmlbeautifyrc)

• 📂 Project Structure

• 🚀 Installation & Setup

• 💻 Local Development

• 📄 License & Changelog

Related MCP server: MCP Workspace Server

✨ Features at a Glance

• 🎨 BML Color Themes: Four tailored editor themes offering deep semantic token coloring.

• 💡 IntelliSense: Context-aware auto-completion, signature help, and parameter tooltips.

• 🔍 Linter & Diagnostics: 70+ real-time checks for security (SQL injection, hardcoded secrets), guaranteed compile/runtime failures verified against Oracle's own BML docs, deprecated APIs, and logical errors.

• 📖 Offline Help Viewer: Docusaurus-style rendered documentation (with :::note/:::warning callouts) opens instantly from any hover tooltip - no internet connection required.

• 🛠 Workspace-Wide Formatting: Recursively beautify directories or targeted folders.

• ☁ REST Integration: Synchronize, compile, validate, debug, and deploy BML functions directly on remote CPQ instances.

• 🤖 AI-Agent Connectivity (MCP): Build or debug via AI using the secure local Model Context Protocol (MCP) server.

• 🧠 AI Agent Skills (AgentSkills.io): Ships with 8 pre-compiled semantic skills to inject profound CPQ and BML domain knowledge into AI assistants like Claude Code.

• 📝 Better Comments: Distinct visual styling for tasks, tags, directives, and function headers.

🔍 Key Capabilities

1. Language Support & IntelliSense

• Rich Syntax Highlighting: Full grammar support for BML methods, control flow statements (if, elif, else, for), database queries (bmql), operators, and literals.

• Snippets Library: Instant, context-aware code skeletons for looping constructs, common string operations, JSON manipulations, and system functions.

• Autocomplete & Tooltips: Signatures, return types, and parameter checklists populate as you type, matching Oracle CPQ specifications.

• Offline Help Viewer: Every hover tooltip for a built-in function includes a 📖 Read Offline Help link that opens a fast, self-contained documentation panel - no internet connection needed. It renders Docusaurus-style :::note/:::tip/:::warning callouts as proper colored boxes (not raw markdown text), theme-matched to your editor, and reuses a single panel across opens so repeated lookups are instant rather than re-launching a preview each time.

• Spell Checker Integration: Preconfigured with cspell.json definitions to automatically support CPQ-specific functions (strtojavadate, jsonarrayrefid, bmql, etc.) without triggering spelling errors.

2. Workspace Formatter & Beautifier

• Recursive Formatting: Run CPQ-BML: Beautify / Format All BML Files in Workspace (cpqBml.beautifyWorkspace) to format BML files recursively.

• Folder Targeting UI: A multi-select quick-pick picker displays workspace root paths and folders, letting you target specific modules.

• CPQ Conventions: Standardizes indentation, spacing, brace layouts, and enforces uppercase rules like auto-replacing the keyword not with the compiler-mandated NOT.

• Flexible Configuration: Formatter behavior can be overridden for specific directories using local .bmlbeautifyrc JSON files.

3. BML Linter & Real-time Diagnostics

The extension includes a custom BML-native static analyzer to capture defects, anti-patterns, and vulnerabilities before you upload to CPQ:

Inline Suppressions

You can bypass specific linter rules on a granular basis using comments. Directives are case-insensitive and work inside both line comments and block comments:

// bml-lint-disable-file               ← suppress everything in this file
// bml-lint-disable                    ← start of suppressed block
// bml-lint-enable                     ← end of suppressed block
x = 10 / 0; // bml-lint-disable-line  ← suppress diagnostics on this line
/* bml-lint-disable-next-line */       ← suppress all diagnostics on the next line
// bml-lint-disable-next-line bml-operator-fix, bml-spelling-error
x = 10 / 0;                            ← only those two codes are suppressed

Supported directive styles:

4. Better Comments & Documentation Headers

Enhance code readability by styling comments into categorized tasks, statuses, or visual callouts.

Custom Tag Styling

Directives & Block Headers

• Lint & Formatting Directives: Comments like // bml-lint-disable-line or /* beautify ignore:start */ are styled with a distinctive purple border to keep control tags visible yet out of the way.

• Standard Doc Headers: Function doc blocks starting with Function Name:, Description:, Inputs:, or Returns: are automatically grouped and colorized in light blue italicized fonts.

5. Interactive Settings Dashboard WebView

Configure connections and features via a custom graphical dashboard using CPQ-BML: Open Settings (cpqBml.settings.open):

• Connection Tab: Input your server's site URL, authentication scheme, and active API credentials.

• Environments Tab: Store multiple sandboxes (e.g. Dev, Test, UAT, Production) to switch active targets.

• Features Tab: Toggle linting rules, Better Comments styling, and general extension assistants in a clean UI.

• Secure Storage integration: Connects directly with the VS Code Secret Storage API. Credentials, passwords, and tokens are saved on your OS keychain, never written in plaintext configuration files.

• Test Connection: A one-click check verifies remote credentials and site connectivity immediately before applying settings.

6. Remote REST Integration & Synchronization

Perform CPQ development workflows entirely inside your local editor:

• Pull Code: Fetch Utility Library functions and Commerce Process functions (cpqBml.rest.pullLibraryFunctions, cpqBml.rest.pullCommerceFunctions) from the remote server along with their metadata.

• Remote Validation & Compilation: Run CPQ-BML: Validate Current File Against CPQ to trigger Oracle's server-side compiler on the active document and surface syntax diagnostics locally.

• Sandbox Debugger: Press CPQ-BML: Debug Current Function on CPQ to launch a parameter picker dialog, send test values to the sandbox runtime, and review standard outputs in the terminal.

• Deployment Controls: Deploy modified code instantly using individual file saves, utility library batch deployments, or full commerce process configurations.

7. Model Context Protocol (MCP) Server for AI Integration

The extension runs a built-in, secure Model Context Protocol (MCP) server, allowing AI coding assistants (such as Claude Code) to securely inspect, debug, and deploy code in your workspace.

graph TD
    subgraph External Environment
        AI[AI Client / Claude Code]
    end
    subgraph VS Code Host
        MCP[MCP Server <br> 127.0.0.1:47821]
        Ext[CPQ-BML Extension]
        Sec[OS Keychain / Secret Storage]
    end
    subgraph Cloud Service
        CPQ[Oracle CPQ Sandbox / Instance]
    end

    AI -- "MCP JSON-RPC Protocol" --> MCP
    MCP -- "Internal Bridge (No Auth Shared)" --> Ext
    Ext -- "Retrieves Credentials" --> Sec
    Ext -- "REST API Requests" --> CPQ

Security Model

Credentials, cookies, and secret tokens are kept within the extension's secure context. The MCP server does not expose these values to the AI client. It only acts as an executor, routing requests through the local extension instance.

AI Work Isolation

When an AI agent requests a file modification or download via MCP, the extension creates an isolated [variableName]-AI.bml working copy. This prevents the agent from overwriting your local scripts and ensures you can review changes via a diff tool before committing.

Exposed MCP Tools

• list_util_functions: Enumerate all remote utility library functions.

• list_commerce_functions: List all commerce scripts on the CPQ instance.

• pull_function: Fetch standard BML and save locally as .bml and -meta.json files.

• save_function: Apply updates to the CPQ environment.

• validate_function: Query the CPQ server compiler to validate changes.

• debug_function: Execute the function remotely with test parameters.

• deploy_function / mass_deploy_util_functions: Deploy individual or batched functions.

• deploy_commerce_process: Publish the entire process configuration.

• create_util_function: Scaffold and publish a brand new utility function.

• create_override: Create an editable override of a standard (system) function - required before it can be validated, saved, or deployed.

• remove_override: Revert an overridden standard function back to CPQ's system version (destructive; requires confirm:true).

8. AI Agent Skills Integration (AgentSkills.io)

CPQ-BML ships with a pre-compiled set of "Agent Skills" designed around the AgentSkills.io specification. This injects deep domain knowledge into AI Coding Assistants (like Claude Code or Cursor) that natively parse these skills when interacting with your workspace.

Zero-Configuration Setup: When you enable the MCP server in the extension settings, CPQ-BML automatically registers these skills into your workspace. There is no manual setup command to run! To keep the extension package tiny and your workspace clean:

• The massive semantic knowledge base is compressed into a highly optimized .br archive at build time.

• At runtime, the extension transparently decompresses this knowledge into your secure VS Code Global Storage directory.

• It automatically provisions pointer files (e.g., .agents/skills.json, CLAUDE.md, .cursorrules) in your workspace that route your AI assistant to the global storage location.

Instead of your AI blindly trying to edit BML using standard Javascript assumptions, the extension provides context-aware directives on:

• BML's unique syntax limitations (e.g. no var or let, == over ===, NOT instead of !).

• Direct Database Access vs BMQL syntax.

• Best practices regarding dictionary, JSON, and string manipulation in CPQ.

• How to correctly utilize the CPQ-BML MCP tools (like pull_function, save_function, validate_function) as part of an end-to-end AI development workflow.

The AI dynamically fetches these contextual rules in real-time, bridging the gap between standard LLM code generation and Oracle CPQ's proprietary runtime.

9. BML Color Themes

Four specialized themes are bundled with the extension:

• BML Dark

• BML Dark Default

• BML Light

• BML Light Default

Color Details

• Categorized Functions: Distinct colors are assigned to built-in function categories (e.g., string, math, date, DB/BMQL, array, URL, dictionary, JSON, XML).

• Attribute Access: CPQ member variables (such as line.attribute and transaction.attribute) are highlighted differently from general variables.

• Operators: Math, logical, and assignment operators are styled distinctly, helping you catch syntax typos like writing = instead of ==.

⌨ Commands Reference

Use the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) to trigger these actions:

⚙ Configuration Settings

Configure these options in VS Code's settings.json or through the Settings Editor UI:

{
  "cpqBml.connection.enabled": true,
  "cpqBml.connection.siteUrl": "example.bigmachines.com",
  "cpqBml.connection.authMethod": "basic",
  "cpqBml.connection.username": "api_developer",
  "cpqBml.connection.environments": [
    {
      "name": "Dev Sandbox",
      "siteUrl": "dev.bigmachines.com",
      "username": "api_developer",
      "authMethod": "basic"
    }
  ],
  "cpqBml.rest.restVersion": "v18",
  "cpqBml.rest.commerceProcess": "oraclecpqo",
  "cpqBml.rest.commerceDocument": "transaction",
  "cpqBml.rest.pullFolder": "library",
  "cpqBml.features.lint": true,
  "cpqBml.features.comments": true,
  "cpqBml.mcp.enable": false,
  "cpqBml.mcp.port": 47821,
  "cpqBml.mcp.logToTerminal": false,
  "cpqBml.debug.logRestDetails": false,
  "cpqBml.debug.logOutputToFile": false
}

🔧 Formatter Settings (.bmlbeautifyrc)

Place a .bmlbeautifyrc configuration file in any directory to customize the BML formatter rules. The options are modeled after JS-beautify structures:

{
  "indent_size": 2,
  "brace_style": "collapse",
  "preserve_newlines": true,
  "max_preserve_newlines": 1,
  "space_before_conditional": true
}

📂 Project Structure

The project has a modular design structure with clean segregation of BML editor services, REST networking, testing utilities, and AI integration:

├── app/                              # Extension Core Source Code
│   └── lang/                         # Language Intelligence & Tooling
│       ├── beautify/                 # Code Formatter & Beautification Engine
│       │   ├── commandWorkspace.js   # Workspace-wide mass formatter
│       │   ├── docHeader.js          # Auto-insert /// doc block comment completion
│       │   └── index.js              # Formatting core config/integration
│       ├── comments/                 # Better Comments parser (tags, directives, headers)
│       ├── intellisense/             # IntelliSense (autocompletions, hovers, signatures)
│       │   ├── index.js              # Go to definition, References, Rename registrations
│       │   ├── workspaceIndex.js     # Codebase scanner indexing util.* & commerce.*
│       │   ├── helpViewer.js         # Fast offline docs webview (Docusaurus-style ::: admonitions)
│       │   └── custom-snippets.json  # Smart snippet database
│       ├── lint/                     # Real-time Native Static Diagnostics
│       │   ├── lint.js               # Central rule runner pipeline
│       │   ├── nullSafety.js         # Checks nullable results of bmql() / get()
│       │   ├── infiniteLoop.js       # Identifies empty or non-populating loops
│       │   └── best-practices/       # BMQL safety, security, doc-verified guaranteed failures, etc.
│       ├── mcp/                      # Model Context Protocol AI Tool Integration
│       │   ├── server.js             # Local MCP server implementation
│       │   └── tools/                # Declarative AI helper tools
│       ├── metrics/                  # Code quality analysis WebView Dashboard
│       │   ├── complexity.js         # Cyclomatic complexity & nesting depth calculations
│       │   ├── report.js             # Metrics accumulator logic
│       │   └── reportWebview.js      # WebView layout rendering
│       ├── rest/                     # Oracle CPQ REST Client Integration
│       ├── settings-panel/           # Extension settings GUI dashboard WebView
│       ├── testing/                  # Safe sandboxed local execution & unit testing
│       │   ├── runner.js             # Sidecar *.bmltest.json executor
│       │   └── snapshot.js           # Regression snapshot comparisons
│       └── xslt/                     # XSLT preview, formatting, & linking features
│
├── test/                             # Automated Test Suites
│   ├── linter/                       # Tests for suppressions & core linter behaviors
│   ├── mcp/                          # Tests for local MCP tool server
│   └── rest/                         # Offline mocked testing for CPQ REST sync
│
├── extension.js                      # Extension Activation/Deactivation Entry-point
├── package.json                      # VS Code Extension manifest & command declarations
└── README.md                         # Project documentation

🚀 Installation & Setup

1. Install from Marketplace: Search for "CPQ-BML" in the VS Code Extensions panel (Ctrl+Shift+X / Cmd+Shift+X) and click Install.

2. Initial Onboarding: On first load, the Settings Dashboard will launch automatically.

3. Set Up Environments: Insert your site details, choose your authentication method, and verify connection.

4. Secure Credentials: Use the commands CPQ-BML: Set CPQ Password or CPQ-BML: Set CPQ Auth Token to securely store your passwords or keys.

💻 Local Development

If you wish to run, customize, or contribute to this extension:

Prerequisites

• Node.js (v22 or newer recommended)

• Visual Studio Code

Steps

1. Clone the Repository:

   git clone https://github.com/vikram-vn/cpq-bml.git
   cd cpq-bml

2. Install Dependencies:

   npm install

3. Compile the Project:

   npm run compile

4. Run Extension Host: Open the root workspace in VS Code and press F5 (or navigate to Run and Debug -> Launch Extension). This opens an Extension Development Host window where you can test BML support immediately.

📄 License & Changelog

• License: This project is licensed under the MIT License.

• Changelog: Detailed version history, additions, and updates are available in CHANGELOG.md.

• Disclaimer: This extension is an independent community project and is not affiliated with, sponsored by, endorsed by, or otherwise associated with Oracle Corporation or BigMachines.