bcdocker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksandr (Ciellos)
+
+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

@@ -0,0 +1,165 @@
+# bcd — BC Docker MCP Server & CLI
+
+An MCP (Model Context Protocol) server and CLI for managing Business Central Docker containers. Lets AI assistants in Cursor, VS Code, or Claude Desktop directly manage your BC dev environments.
+
+## Prerequisites
+
+- **Node.js 18+**
+- **Windows PowerShell 5.1** (BC management cmdlets require it)
+- **Docker Desktop** in Windows containers mode
+- **BCDocker PowerShell module** (the `PartnerScript/` sibling folder)
+
+## Setup
+
+```bash
+cd bcd
+npm install
+npm run build
+```
+
+## Usage: MCP Server
+
+### Cursor
+
+Add to your Cursor MCP settings (`.cursor/mcp.json` or workspace settings):
+
+```json
+{
+  "mcpServers": {
+    "bcd": {
+      "command": "node",
+      "args": ["C:/myspace/work/Mine/DockerUtils/bcd/dist/server.js"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "bcd": {
+      "command": "node",
+      "args": ["C:/myspace/work/Mine/DockerUtils/bcd/dist/server.js"]
+    }
+  }
+}
+```
+
+### VS Code (Copilot)
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "bcd": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["C:/myspace/work/Mine/DockerUtils/bcd/dist/server.js"]
+    }
+  }
+}
+```
+
+After configuring, your AI assistant can:
+
+- "List my BC containers"
+- "Create a new BC sandbox container with version 26.0"
+- "Show me the apps in bcsandbox"
+- "Run tests in my container"
+- "Compile and publish my AL project to bcsandbox"
+- "Stop the bcsandbox container"
+
+## Usage: CLI
+
+```bash
+# List containers
+node dist/cli.js list
+
+# Container details
+node dist/cli.js info bcsandbox
+
+# Create container
+node dist/cli.js create --name bcsandbox --version 26.0 --country w1 --bypass-cdn
+
+# Start / Stop / Restart
+node dist/cli.js start bcsandbox
+node dist/cli.js stop bcsandbox
+node dist/cli.js restart bcsandbox
+
+# Remove container
+node dist/cli.js remove bcsandbox
+
+# Open web client
+node dist/cli.js open bcsandbox
+
+# List apps
+node dist/cli.js apps bcsandbox
+node dist/cli.js apps bcsandbox --publisher Microsoft
+
+# Install .app file
+node dist/cli.js install bcsandbox "C:\apps\MyApp.app"
+
+# Compile and publish AL project
+node dist/cli.js publish bcsandbox "C:\Projects\MyApp"
+
+# Run tests
+node dist/cli.js test bcsandbox
+node dist/cli.js test bcsandbox --codeunit 50100
+node dist/cli.js test bcsandbox --app "C:\Projects\MyApp.Test"
+
+# Import test toolkit
+node dist/cli.js toolkit bcsandbox
+node dist/cli.js toolkit bcsandbox --full
+
+# Import license
+node dist/cli.js license bcsandbox "C:\license.bclicense"
+```
+
+### Global install (optional)
+
+```bash
+npm link
+# Now use 'bcd' directly:
+bcd list
+bcd create --name mybc --version 26.0
+bcd apps mybc
+```
+
+## MCP Tools Reference
+
+| Tool | Description |
+|---|---|
+| `list-containers` | List all BC containers with status |
+| `container-info` | Get version, status, and endpoints |
+| `create-container` | Create a new BC container (5-30 min) |
+| `remove-container` | Remove a container |
+| `start-container` | Start a stopped container |
+| `stop-container` | Stop a running container |
+| `restart-container` | Restart a container |
+| `list-apps` | List apps in a container |
+| `install-app` | Install a .app file |
+| `publish-project` | Compile and publish an AL project |
+| `import-test-toolkit` | Import test toolkit |
+| `import-license` | Import a license file |
+| `run-tests` | Run AL tests |
+
+## Architecture
+
+```
+bcd/
+├── src/
+│   ├── server.ts       # MCP server — exposes tools over stdio
+│   ├── cli.ts          # CLI — same operations via command line
+│   └── executor.ts     # PowerShell 5.1 execution layer
+├── dist/               # Compiled JS (after npm run build)
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+The MCP server and CLI both call through `executor.ts`, which spawns `powershell.exe` (5.1, not pwsh 7.x) and imports the `BCDocker.psm1` module from the sibling `PartnerScript/` folder. This ensures all the BcContainerHelper cmdlets work correctly, including on BC 28+.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runPowerShell, runRawPowerShell } from "./executor.js";
+const program = new Command();
+program
+    .name("bcd")
+    .description("CLI for Business Central Docker container management")
+    .version("1.0.0");
+// ── Containers ───────────────────────────────────────────
+program
+    .command("list")
+    .alias("ls")
+    .description("List all BC containers with status")
+    .action(async () => {
+    const { stdout } = await runRawPowerShell(`
+      Import-Module BcContainerHelper -DisableNameChecking -ErrorAction Stop
+      $containers = Get-BcContainers
+      if ($containers.Count -eq 0) { Write-Output "No BC containers found." }
+      else {
+        foreach ($name in $containers) {
+          $status = docker inspect $name --format '{{.State.Status}}' 2>$null
+          Write-Output "$($name.PadRight(25)) $status"
+        }
+      }
+    `);
+    console.log(stdout);
+});
+program
+    .command("info <container>")
+    .description("Show container details: version, status, endpoints")
+    .action(async (container) => {
+    const { stdout } = await runRawPowerShell(`
+      Import-Module BcContainerHelper -DisableNameChecking -ErrorAction Stop
+      $v = Get-BcContainerNavVersion -containerNameOrId '${container}'
+      $u = Get-BcContainerUrl -containerName '${container}' -useHttps:$false
+      $s = docker inspect '${container}' --format '{{.State.Status}}' 2>$null
+      Write-Output "Container  : ${container}"
+      Write-Output "Status     : $s"
+      Write-Output "BC Version : $v"
+      Write-Output "Web Client : $u"
+      Write-Output "OData/API  : http://${container}:7048/BC/api"
+      Write-Output "Dev Service: http://${container}:7049/BC"
+    `);
+    console.log(stdout);
+});
+program
+    .command("create")
+    .description("Create a new BC container")
+    .option("-n, --name <name>", "Container name", "bcsandbox")
+    .option("-v, --version <version>", "BC version (sandbox, onprem, 26.0)", "sandbox")
+    .option("-c, --country <code>", "Country code (us, w1, gb, nl)", "us")
+    .option("-u, --user <username>", "Admin username", "admin")
+    .option("-p, --password <password>", "Admin password", "P@ssw0rd!")
+    .option("-m, --memory <limit>", "Memory limit", "8G")
+    .option("-i, --isolation <mode>", "Isolation: hyperv or process", "hyperv")
+    .option("-t, --toolkit <mode>", "Test toolkit: none, libraries, full", "libraries")
+    .option("--bypass-cdn", "Skip Azure CDN, use blob storage")
+    .option("-l, --license <file>", "Path or URL to .bclicense / .flf license file")
+    .action(async (opts) => {
+    const includeToolkit = opts.toolkit !== "none" ? "$true" : "$false";
+    const libOnly = opts.toolkit === "libraries" ? "$true" : "$false";
+    const cdn = opts.bypassCdn ? "-BypassCDN" : "";
+    const lic = opts.license ? `-LicenseFile '${opts.license}'` : "";
+    console.log(`Creating container '${opts.name}'...`);
+    console.log(`  Version: ${opts.version}, Country: ${opts.country}, Toolkit: ${opts.toolkit}`);
+    console.log(`  This may take 5-30 minutes.\n`);
+    const { stdout, stderr } = await runPowerShell(`
+      New-BCDContainer \`
+        -ContainerName '${opts.name}' \`
+        -Version '${opts.version}' \`
+        -Country '${opts.country}' \`
+        -UserName '${opts.user}' \`
+        -Password '${opts.password}' \`
+        -MemoryLimit '${opts.memory}' \`
+        -Isolation '${opts.isolation}' \`
+        -IncludeTestToolkit ${includeToolkit} \`
+        -TestLibrariesOnly ${libOnly} \`
+        ${cdn} ${lic}
+    `, 1_800_000);
+    if (stdout)
+        console.log(stdout);
+    if (stderr)
+        console.error(stderr);
+});
+program
+    .command("remove <container>")
+    .alias("rm")
+    .description("Remove a BC container")
+    .action(async (container) => {
+    const { stdout } = await runPowerShell(`Remove-BCDContainer -ContainerName '${container}'`);
+    console.log(stdout || `Container '${container}' removed.`);
+});
+program
+    .command("start <container>")
+    .description("Start a stopped container")
+    .action(async (container) => {
+    const { stdout } = await runPowerShell(`Start-BCDContainer -ContainerName '${container}'`);
+    console.log(stdout || `Container '${container}' started.`);
+});
+program
+    .command("stop <container>")
+    .description("Stop a running container")
+    .action(async (container) => {
+    const { stdout } = await runPowerShell(`Stop-BCDContainer -ContainerName '${container}'`);
+    console.log(stdout || `Container '${container}' stopped.`);
+});
+program
+    .command("restart <container>")
+    .description("Restart a container")
+    .action(async (container) => {
+    const { stdout } = await runPowerShell(`Restart-BCDContainer -ContainerName '${container}'`);
+    console.log(stdout || `Container '${container}' restarted.`);
+});
+program
+    .command("open <container>")
+    .description("Open the BC Web Client in your browser")
+    .action(async (container) => {
+    const { stdout } = await runPowerShell(`Open-BCDWebClient -ContainerName '${container}'`);
+    console.log(stdout || "Opening web client...");
+});
+// ── Apps ─────────────────────────────────────────────────
+program
+    .command("apps <container>")
+    .description("List apps in a container")
+    .option("--publisher <name>", "Filter by publisher")
+    .action(async (container, opts) => {
+    const filter = opts.publisher
+        ? `| Where-Object { $_.Publisher -eq '${opts.publisher}' }`
+        : "";
+    const { stdout } = await runRawPowerShell(`
+      Import-Module BcContainerHelper -DisableNameChecking -ErrorAction Stop
+      Get-BcContainerAppInfo -containerName '${container}' -tenant default -tenantSpecificProperties ${filter} |
+        Select-Object Name, Publisher, Version, IsInstalled, Scope |
+        Sort-Object Publisher, Name |
+        Format-Table -AutoSize | Out-String -Width 200
+    `);
+    console.log(stdout || "No apps found.");
+});
+program
+    .command("install <container> <appFile>")
+    .description("Install a .app file into a container")
+    .option("-u, --user <username>", "Admin username", "admin")
+    .option("-p, --password <password>", "Admin password", "P@ssw0rd!")
+    .action(async (container, appFile, opts) => {
+    const { stdout } = await runPowerShell(`
+      $cred = Get-BCCredential -UserName '${opts.user}' -Password '${opts.password}'
+      Install-BCDApp -ContainerName '${container}' -AppFile '${appFile}' -Credential $cred
+    `);
+    console.log(stdout || "App installed.");
+});
+program
+    .command("uninstall <container> <appName> <publisher>")
+    .description("Uninstall an app by name and publisher")
+    .action(async (container, appName, publisher) => {
+    const { stdout } = await runRawPowerShell(`
+      Import-Module BcContainerHelper -DisableNameChecking -ErrorAction Stop
+      $sorted = Get-BcContainerAppInfo -containerName '${container}' -tenant default -tenantSpecificProperties -sort DependenciesLast
+      $target = $sorted | Where-Object { $_.Name -eq '${appName}' -and $_.Publisher -eq '${publisher}' -and $_.IsInstalled }
+      if (-not $target) { Write-Output "App '${appName}' by '${publisher}' not found or not installed."; exit }
+      foreach ($app in $target) {
+        UnInstall-BcContainerApp -name $app.Name -containerName '${container}' -publisher $app.Publisher -version $app.Version -force
+        Write-Output "Uninstalled: $($app.Name) v$($app.Version)"
+      }
+    `);
+    console.log(stdout);
+});
+program
+    .command("publish <container> <projectFolder>")
+    .description("Compile and publish an AL project into a container")
+    .option("-u, --user <username>", "Admin username", "admin")
+    .option("-p, --password <password>", "Admin password", "P@ssw0rd!")
+    .action(async (container, folder, opts) => {
+    const { stdout } = await runPowerShell(`
+      $cred = Get-BCCredential -UserName '${opts.user}' -Password '${opts.password}'
+      Publish-BCDProject -ContainerName '${container}' -ProjectFolder '${folder}' -Credential $cred
+    `, 300_000);
+    console.log(stdout || "Project compiled and published.");
+});
+// ── Tests & License ──────────────────────────────────────
+program
+    .command("test [container]")
+    .description("Run AL tests in a container")
+    .option("-c, --codeunit <id>", "Test codeunit ID")
+    .option("-f, --function <name>", "Test function name")
+    .option("-a, --app <folder>", "AL test project folder to compile/publish/run")
+    .option("-u, --user <username>", "Admin username", "admin")
+    .option("-p, --password <password>", "Admin password", "P@ssw0rd!")
+    .action(async (container = "bcsandbox", opts) => {
+    const params = [`-ContainerName '${container}'`];
+    params.push(`-Credential (Get-BCCredential -UserName '${opts.user}' -Password '${opts.password}')`);
+    if (opts.codeunit)
+        params.push(`-TestCodeunitId ${opts.codeunit}`);
+    if (opts.function)
+        params.push(`-TestFunctionName '${opts.function}'`);
+    if (opts.app)
+        params.push(`-AppProjectFolder '${opts.app}'`);
+    const { stdout } = await runPowerShell(`Invoke-BCDTests ${params.join(" ")}`, 600_000);
+    console.log(stdout || "Test run complete.");
+});
+program
+    .command("toolkit <container>")
+    .description("Import BC Test Toolkit into a container")
+    .option("--full", "Import full test framework (default: libraries only)")
+    .option("-u, --user <username>", "Admin username", "admin")
+    .option("-p, --password <password>", "Admin password", "P@ssw0rd!")
+    .action(async (container, opts) => {
+    const libOnly = opts.full ? "$false" : "$true";
+    const { stdout } = await runPowerShell(`
+      $cred = Get-BCCredential -UserName '${opts.user}' -Password '${opts.password}'
+      Import-BCDTestToolkit -ContainerName '${container}' -Credential $cred -LibrariesOnly ${libOnly}
+    `, 300_000);
+    console.log(stdout || "Test toolkit imported.");
+});
+program
+    .command("license <container> <file>")
+    .description("Import a license file into a container")
+    .action(async (container, file) => {
+    const { stdout } = await runPowerShell(`Import-BCDLicense -ContainerName '${container}' -LicenseFile '${file}'`);
+    console.log(stdout || "License imported.");
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error("Error:", err.message);
+    process.exit(1);
+});

package/dist/executor.d.ts

@@ -0,0 +1,7 @@
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export declare function runPowerShell(script: string, timeoutMs?: number): Promise<ExecResult>;
+export declare function runRawPowerShell(script: string, timeoutMs?: number): Promise<ExecResult>;

package/dist/executor.js

@@ -0,0 +1,72 @@
+import { execFile } from "node:child_process";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function resolveModulePath() {
+    // 1. Environment variable override
+    if (process.env.BCD_MODULE_PATH)
+        return process.env.BCD_MODULE_PATH;
+    // 2. Bundled inside npm package (dist/../ps/BCDocker.psm1)
+    const bundled = resolve(__dirname, "../ps/BCDocker.psm1");
+    if (existsSync(bundled))
+        return bundled;
+    // 3. Development layout (dist/../../PartnerScript/BCDocker.psm1)
+    const dev = resolve(__dirname, "../../PartnerScript/BCDocker.psm1");
+    if (existsSync(dev))
+        return dev;
+    throw new Error("BCDocker.psm1 not found. Set BCD_MODULE_PATH or ensure the ps/ folder exists.");
+}
+const MODULE_PATH = resolveModulePath();
+// BC management cmdlets require Windows PowerShell 5.1, not pwsh 7.x
+const PS_EXE = "powershell.exe";
+export function runPowerShell(script, timeoutMs = 600_000) {
+    const wrappedScript = `
+    $ErrorActionPreference = 'Stop'
+    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+    Import-Module '${MODULE_PATH.replace(/\\/g, "\\\\")}' -DisableNameChecking -Force
+    ${script}
+  `;
+    return new Promise((resolve, reject) => {
+        const child = execFile(PS_EXE, [
+            "-NoProfile",
+            "-NonInteractive",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-Command",
+            wrappedScript,
+        ], { timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+            if (error && !stdout) {
+                reject(new Error(stderr || error.message));
+                return;
+            }
+            resolve({
+                stdout: stdout.trim(),
+                stderr: stderr.trim(),
+                exitCode: error ? 1 : 0,
+            });
+        });
+    });
+}
+export function runRawPowerShell(script, timeoutMs = 600_000) {
+    return new Promise((resolve, reject) => {
+        execFile(PS_EXE, [
+            "-NoProfile",
+            "-NonInteractive",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-Command",
+            script,
+        ], { timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+            if (error && !stdout) {
+                reject(new Error(stderr || error.message));
+                return;
+            }
+            resolve({
+                stdout: stdout.trim(),
+                stderr: stderr.trim(),
+                exitCode: error ? 1 : 0,
+            });
+        });
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1 @@
+export {};