@ifx_zieglchr/oracle-sqlcl-mcp-wrapper 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christoph Ziegler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Oracle SQLcl MCP wrapper for VS Code (Windows)
+
+Unofficial, dependency-free stdio launcher for the MCP server bundled with
+Oracle SQL Developer for VS Code. It finds the locally installed extension and
+starts its MCP server without hardcoding your username or extension version.
+
+This package is not affiliated with or endorsed by Oracle. It does not contain,
+download or install Oracle binaries, Java, database credentials or connection
+files. Oracle software remains subject to its own licenses.
+
+## Requirements
+
+- Windows with Node.js 22 or later on PATH.
+- The official Oracle SQL Developer extension installed in the same user's
+  VS Code environment, including its `dbtools.exe` runtime.
+- The extension architecture must match the Node.js process architecture for
+  automatic discovery. macOS, Linux and remote extension hosts are unsupported.
+
+## Check your installation
+
+```powershell
+npx --yes @ifx_zieglchr/oracle-sqlcl-mcp-wrapper@0.1.0 --check
+```
+
+`--check` reports the resolved executable, arguments and extension version to
+stderr. It does not start Oracle or connect to a database. stdout is reserved
+for MCP traffic.
+
+## MCP client configuration
+
+For a client supporting local stdio servers, such as VS Code:
+
+```json
+{
+  "servers": {
+    "oracle-sqlcl-wrapper": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "--yes",
+        "@ifx_zieglchr/oracle-sqlcl-mcp-wrapper@0.1.0"
+      ]
+    }
+  }
+}
+```
+
+Use your client's stdio-server configuration mechanism. Enterprise clients may
+require separate approval of this exact server command and arguments.
+Installing this package does not grant database access or bypass client policy.
+Do not use `npm start` as the MCP command: npm lifecycle banners can interfere
+with the protocol.
+
+## Extension discovery
+
+The launcher searches `.vscode\extensions` in the current user's home directory.
+It ignores versions marked for removal in `.obsolete` and selects the numerically
+newest stable Windows Oracle extension matching the Node process architecture.
+It checks the extension manifest identity and the existence of `dbtools.exe`.
+These checks are not a cryptographic authenticity guarantee; installed
+extensions must be trusted.
+
+If the newest installation is incomplete, startup fails explicitly instead of
+silently switching to an older runtime. Discovery runs again on each server
+start; the wrapper does not update Oracle software.
+
+For custom extension directories, portable VS Code, Insiders or a pinned version,
+set `ORACLE_SQLDEV_EXTENSION_DIR` to the absolute extension directory, not the
+executable:
+
+```powershell
+$env:ORACLE_SQLDEV_EXTENSION_DIR = 'C:\path\to\oracle.sql-developer-26.3.0-win32-x64'
+npx --yes @ifx_zieglchr/oracle-sqlcl-mcp-wrapper@0.1.0 --check
+```
+
+For an MCP client, set the override through that client's server environment
+configuration. The default installation needs no override.
+
+## Runtime behavior and limitations
+
+The launcher runs the discovered `dbtools.exe` with:
+
+```text
+--jvm-option -Duser.language=en sql -mcp
+```
+
+The child inherits stdin, stdout, stderr and the calling environment. There is
+no shell, protocol translation, added stdout logging, or change to Oracle's tools
+and authorization. The wrapper does not load workspace `.env` files.
+Database connections and credentials are handled by Oracle's normal runtime;
+they are neither collected nor packaged by this launcher.
+
+Verified with Windows x64, Oracle extension 26.3.0 and Node.js 24:
+MCP initialization, listing ten tools without invoking database tools, and clean
+exit after closing stdin. Actual connection workflows, extension updates and
+client-driven forced termination of JVM subprocesses require testing in your
+environment. Windows ARM64 discovery is implemented but has not been validated
+with an actual ARM64 Oracle installation.
+
+## License
+
+MIT, copyright 2026 Christoph Ziegler. See [LICENSE](LICENSE).
+This license covers only this wrapper, not Oracle software.

package/bin/oracle-sqlcl-mcp-wrapper.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { resolveServer, startServer } from '../src/launcher.js';
+
+try {
+  const args = process.argv.slice(2);
+  if (args.length > 1 || (args.length === 1 && args[0] !== '--check')) {
+    throw new Error('Usage: oracle-sqlcl-mcp-wrapper [--check]');
+  }
+  const server = await resolveServer();
+  if (args[0] === '--check') {
+    process.stderr.write(`${JSON.stringify(server, null, 2)}\n`);
+  } else {
+    process.exitCode = await startServer(server);
+  }
+} catch (error) {
+  process.stderr.write(`[oracle-sqlcl-mcp-wrapper] ${error.message}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,32 @@
-{
-  "name": "@ifx_zieglchr/oracle-sqlcl-mcp-wrapper",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@ifx_zieglchr/oracle-sqlcl-mcp-wrapper",
+  "version": "0.1.0",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "description": "Windows stdio launcher for the locally installed Oracle SQL Developer VS Code extension",
+  "type": "module",
+  "bin": {
+    "oracle-sqlcl-mcp-wrapper": "bin/oracle-sqlcl-mcp-wrapper.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "os": [
+    "win32"
+  ],
+  "scripts": {
+    "check": "node bin/oracle-sqlcl-mcp-wrapper.js --check",
+    "probe": "node scripts/probe.js",
+    "start": "node bin/oracle-sqlcl-mcp-wrapper.js",
+    "test": "node --test"
+  }
+}

package/src/launcher.js

@@ -0,0 +1,101 @@
+import { spawn } from 'node:child_process';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+export const MCP_ARGS = ['--jvm-option', '-Duser.language=en', 'sql', '-mcp'];
+
+export async function resolveServer({
+  env = process.env,
+  home = homedir(),
+  platform = process.platform,
+  arch = process.arch,
+} = {}) {
+  if (platform !== 'win32') {
+    throw new Error('This prototype supports Windows only. Run it on the PC with the Oracle extension installed.');
+  }
+
+  let extensionDir = env.ORACLE_SQLDEV_EXTENSION_DIR;
+  if (extensionDir && !path.isAbsolute(extensionDir)) {
+    throw new Error('ORACLE_SQLDEV_EXTENSION_DIR must be an absolute extension directory path.');
+  }
+
+  if (!extensionDir) {
+    const root = path.join(home, '.vscode', 'extensions');
+    let entries;
+    try {
+      entries = await readdir(root, { withFileTypes: true });
+    } catch (error) {
+      throw new Error(`Cannot read VS Code extensions at ${root}. Install Oracle SQL Developer or set ORACLE_SQLDEV_EXTENSION_DIR.`, { cause: error });
+    }
+
+    let obsolete = {};
+    try {
+      obsolete = JSON.parse(await readFile(path.join(root, '.obsolete'), 'utf8'));
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw new Error(`Cannot read extension removal metadata at ${root}: ${error.message}`, { cause: error });
+      }
+    }
+    if (!obsolete || typeof obsolete !== 'object' || Array.isArray(obsolete)) {
+      throw new Error(`Invalid extension removal metadata at ${root}.`);
+    }
+
+    const candidates = entries.flatMap((entry) => {
+      const match = /^oracle\.sql-developer-(\d+)\.(\d+)\.(\d+)-win32-(x64|arm64)$/.exec(entry.name);
+      if (!entry.isDirectory() || !match || match[4] !== arch || obsolete[entry.name]) {
+        return [];
+      }
+      return [{ name: entry.name, version: match.slice(1, 4).map(Number) }];
+    });
+    candidates.sort((a, b) => {
+      for (let i = 0; i < 3; i += 1) {
+        if (a.version[i] !== b.version[i]) {
+          return b.version[i] - a.version[i];
+        }
+      }
+      return 0;
+    });
+    if (!candidates.length) {
+      throw new Error(`No active Windows ${arch} Oracle SQL Developer extension found in ${root}. Install it or set ORACLE_SQLDEV_EXTENSION_DIR.`);
+    }
+    extensionDir = path.join(root, candidates[0].name);
+  }
+
+  const manifest = JSON.parse(await readFile(path.join(extensionDir, 'package.json'), 'utf8'));
+  if (manifest.name !== 'sql-developer' || manifest.publisher?.toLowerCase() !== 'oracle') {
+    throw new Error(`Not an Oracle SQL Developer extension: ${extensionDir}`);
+  }
+  const command = path.join(extensionDir, 'dbtools', 'bin', 'dbtools.exe');
+  if (!(await stat(command)).isFile()) {
+    throw new Error(`Oracle MCP executable is not a file: ${command}`);
+  }
+  return { command, args: [...MCP_ARGS], extensionDir, extensionVersion: manifest.version };
+}
+
+export function startServer({ command, args }) {
+  const child = spawn(command, args, {
+    stdio: 'inherit',
+    shell: false,
+    windowsHide: true,
+  });
+  const onSignal = (signal) => child.kill(signal);
+  const onInterrupt = () => onSignal('SIGINT');
+  const onTerminate = () => onSignal('SIGTERM');
+  process.on('SIGINT', onInterrupt);
+  process.on('SIGTERM', onTerminate);
+
+  return new Promise((resolve, reject) => {
+    let spawnError;
+    child.once('error', (error) => { spawnError = error; });
+    child.once('close', (code, signal) => {
+      process.removeListener('SIGINT', onInterrupt);
+      process.removeListener('SIGTERM', onTerminate);
+      if (spawnError) {
+        reject(spawnError);
+      } else {
+        resolve(code ?? (signal === 'SIGINT' ? 130 : 143));
+      }
+    });
+  });
+}