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. BML Color Themes
• ⌨ Commands Reference
• ⚙ Configuration Settings
• 🔧 Formatter Settings (.bmlbeautifyrc)
• 🚀 Installation & Setup
• 💻 Local Development
• 📄 License & Changelog

✨ 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: Real-time analysis for security (SQL Injection), deprecated APIs, and logical errors.
• 🛠 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.
• 📝 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.
• 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:

• // bml-lint-disable (entire file)
• // bml-lint-disable-line (current line)
• // bml-lint-disable-next-line (subsequent line)
• // bml-lint-disable-file (entire file)

[!TIP] Lightbulb Quick Fixes (Ctrl+. or Cmd+.) are available for many diagnostics, allowing you to auto-resolve semicolon styling, variable typos, formatting errors, or deprecated APIs instantly.

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.

8. BML Color Themes

Four specialized themes are bundled with the extension:

• BML Dark
• BML Dark Default
• BML Light
• BML Light Default

[!NOTE] Syntax coloring is theme-driven. The extension does not force overrides onto external themes. Select one of the BML themes (Ctrl+K Ctrl+T / Cmd+K Cmd+T) to view CPQ-specific token colors.

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
}

🚀 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.