@habitusnet/bc365 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [2.0.0] — Unreleased
+
+### Added
+- `bc365 onboard` CLI: auto-discovers tenant, environments, companies via Entra ID device code flow, writes `.mcp.json`
+- `bc365 switch <profile>` for multi-tenant profile management
+- `bc365 profiles` command to list saved profiles
+- `bc365 check` command to check latest npm versions of bc365 packages
+- Entra ID multi-tenant app (`bc365 CLI`) with device code flow authentication
+- Token caching via OS keychain (`keytar`)
+- Vendored mirror repos with daily upstream-watch and security scanning:
+  - `habitusnet/d365bc-admin-mcp`
+  - `habitusnet/mcp-business-central`
+- npm package published as `@habitusnet/bc365`
+- CI: Jest tests, npm audit, CodeQL on every PR
+
+### Changed
+- Package name changed to `@habitusnet/bc365` for scoped npm distribution
+- Minimum Node.js version: 20
+
+---
+

package/README.md

@@ -0,0 +1,48 @@
+# bc365 — MCP Config Manager for Business Central
+
+`@habitusnet/bc365` is a CLI that auto-discovers your Microsoft Dynamics 365 Business Central environments and writes `.mcp.json` for use with Claude / MCP-compatible AI tools.
+
+## v2 — Smart Onboarding
+
+Instead of manually editing `.mcp.json`, use the CLI:
+
+```bash
+npx @habitusnet/bc365 onboard
+```
+
+Sign in with your Microsoft account. The CLI discovers your tenant, environments, and companies automatically, checks your BC permissions, and writes `.mcp.json`.
+
+**Prerequisites:**
+- Microsoft 365 / Azure AD account with access to Business Central
+- Business Central environment with `D365 BUS FULL ACCESS` permission set
+
+---
+
+## Installation
+
+```bash
+npm install -g @habitusnet/bc365
+```
+
+Or use without installing:
+
+```bash
+npx @habitusnet/bc365 onboard
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `bc365 onboard` | Auto-discover tenant, environments, companies; write `.mcp.json` |
+| `bc365 profiles` | List saved profiles |
+| `bc365 switch <profile>` | Switch to a saved profile |
+| `bc365 check` | Check latest npm versions of bc365 packages |
+
+## Multi-Tenant Usage
+
+For agencies managing multiple clients, see [SETUP.md](SETUP.md#multi-tenant-usage-agencies).
+
+## License
+
+MIT

package/bin/bc365.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { program } from '../lib/cli.js';
+program.parse();

package/lib/auth.js

@@ -0,0 +1,52 @@
+import { PublicClientApplication } from '@azure/msal-node';
+import keytar from 'keytar';
+
+const SERVICE = 'bc365';
+const ACCOUNT = 'token';
+const CLIENT_ID = process.env.BC365_CLIENT_ID ?? 'e9dd228a-569c-4ab2-8e0a-cda6b01555d9';
+const AUTHORITY = 'https://login.microsoftonline.com/organizations';
+const SCOPES = [
+  'https://api.businesscentral.dynamics.com/user_impersonation',
+  'User.Read',
+];
+
+// Lazy PCA creation so tests can control the mock per-call via
+// PublicClientApplication.mockImplementation() before invoking getToken().
+function createPca() {
+  return new PublicClientApplication({
+    auth: { clientId: CLIENT_ID, authority: AUTHORITY },
+  });
+}
+
+export async function getToken() {
+  const cached = await keytar.getPassword(SERVICE, ACCOUNT);
+  if (cached) {
+    try {
+      const parsed = JSON.parse(cached);
+      if (parsed.expiresOn > Date.now() + 60_000) return parsed;
+    } catch {
+      // Corrupt cache — fall through to re-authenticate
+    }
+  }
+
+  const pca = createPca();
+  const response = await pca.acquireTokenByDeviceCode({
+    scopes: SCOPES,
+    deviceCodeCallback: (info) => {
+      console.log(info.message);
+    },
+  });
+
+  const token = {
+    accessToken: response.accessToken,
+    expiresOn: response.expiresOn instanceof Date
+      ? response.expiresOn.getTime()
+      : response.expiresOn,
+  };
+  await keytar.setPassword(SERVICE, ACCOUNT, JSON.stringify(token));
+  return token;
+}
+
+export async function clearToken() {
+  await keytar.deletePassword(SERVICE, ACCOUNT);
+}

package/lib/cli.js

@@ -0,0 +1,77 @@
+import { createRequire } from 'node:module';
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { onboard } from './onboard.js';
+import { listProfiles, loadProfile } from './profiles.js';
+import { checkVersions } from './versions.js';
+
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+
+export const program = new Command();
+
+program
+  .name('bc365')
+  .description('Business Central MCP onboarding and management CLI')
+  .version(version);
+
+program
+  .command('onboard')
+  .description('Auto-discover tenant/environment/company and write .mcp.json')
+  .option('-t, --tenant-id <id>', 'Azure AD tenant ID (skip Graph lookup)')
+  .option('-o, --output <path>', 'Output path for .mcp.json', '.mcp.json')
+  .option('-p, --profile <name>', 'Profile name to save (default: tenantId/envName)')
+  .action(async (opts) => {
+    try {
+      await onboard({ tenantId: opts.tenantId, output: opts.output, profileName: opts.profile });
+    } catch (err) {
+      console.error(chalk.red(`✗ ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('switch <profile>')
+  .description('Switch active profile (writes .mcp.json from saved profile)')
+  .option('-o, --output <path>', 'Output path', '.mcp.json')
+  .action(async (profileName, opts) => {
+    try {
+      const profile = await loadProfile(profileName);
+      if (!profile) {
+        console.error(chalk.red(`✗ Profile '${profileName}' not found. Run 'bc365 onboard' first.`));
+        process.exit(1);
+      }
+      const { writeFile } = await import('node:fs/promises');
+      const { buildMcpConfig } = await import('./onboard.js');
+      const config = buildMcpConfig(profile);
+      await writeFile(opts.output, JSON.stringify(config, null, 2), 'utf8');
+      console.log(chalk.green(`✓ Switched to profile '${profileName}'`));
+    } catch (err) {
+      console.error(chalk.red(`✗ ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('profiles')
+  .description('List saved tenant profiles')
+  .action(async () => {
+    const profiles = await listProfiles();
+    if (profiles.length === 0) {
+      console.log('No profiles saved yet. Run bc365 onboard to create one.');
+      return;
+    }
+    profiles.forEach((p) => console.log(`  ${p.name}  (${p.tenantId})`));
+  });
+
+program
+  .command('check')
+  .description('Check latest versions of bc365 packages from npm registry')
+  .action(async () => {
+    console.log('Checking npm registry...');
+    const results = await checkVersions();
+    results.forEach((r) => {
+      const status = r.latest ? chalk.green(r.latest) : chalk.yellow('unknown');
+      console.log(`  ${r.package}  latest: ${status}`);
+    });
+  });

package/lib/discovery.js

@@ -0,0 +1,38 @@
+const BC_ADMIN_BASE = 'https://api.businesscentral.dynamics.com/admin/v2.21';
+const BC_API_BASE = 'https://api.businesscentral.dynamics.com/v2.0';
+const REQUIRED_PERMISSIONS = ['D365 BUS FULL ACCESS'];
+
+async function bcFetch(url, token) {
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${token.accessToken}` },
+  });
+  if (!res.ok) throw new Error(`BC API error ${res.status}: ${url}`);
+  return res.json();
+}
+
+export async function getEnvironments(token, opts = {}) {
+  const { tenantId, type } = opts;
+  const url = tenantId
+    ? `${BC_ADMIN_BASE}/applications/BusinessCentral/environments?aadTenantId=${tenantId}`
+    : `${BC_ADMIN_BASE}/applications/BusinessCentral/environments`;
+  const data = await bcFetch(url, token);
+  const envs = data.value ?? [];
+  return type ? envs.filter((e) => e.type === type) : envs;
+}
+
+export async function getCompanies(env, token) {
+  const url = `${BC_API_BASE}/${encodeURIComponent(env.aadTenantId)}/${encodeURIComponent(env.name)}/api/v2.0/companies`;
+  const data = await bcFetch(url, token);
+  return data.value ?? [];
+}
+
+export async function getPermissions(env, token, opts = {}) {
+  const { companyId } = opts;
+  const url = `${BC_API_BASE}/${encodeURIComponent(env.aadTenantId)}/${encodeURIComponent(env.name)}/api/v2.0/companies(${encodeURIComponent(companyId)})/userPermissions`;
+  const data = await bcFetch(url, token);
+  const grantedRoles = (data.value ?? []).map((p) => p.roleId);
+  return {
+    present: REQUIRED_PERMISSIONS.filter((r) => grantedRoles.includes(r)),
+    missing: REQUIRED_PERMISSIONS.filter((r) => !grantedRoles.includes(r)),
+  };
+}

package/lib/index.js

@@ -0,0 +1,2 @@
+export { onboard } from './onboard.js';
+export { getToken } from './auth.js';

package/lib/onboard.js

@@ -0,0 +1,74 @@
+import { writeFile } from 'node:fs/promises';
+import inquirer from 'inquirer';
+import { getToken } from './auth.js';
+import { getEnvironments, getCompanies, getPermissions } from './discovery.js';
+import { saveProfile } from './profiles.js';
+
+const BC_API_BASE = 'https://api.businesscentral.dynamics.com/v2.0';
+
+export function buildMcpConfig(ctx) {
+  const { tenantId, envName, companyId } = ctx;
+  return {
+    mcpServers: {
+      'bc-admin': {
+        type: 'stdio',
+        command: 'd365bc-admin-mcp',
+        env: { BC_TENANT_ID: tenantId },
+      },
+      'bc-data': {
+        type: 'stdio',
+        command: 'npx',
+        args: ['-y', '@habitusnet/mcp-business-central'],
+        env: {
+          BC_URL_SERVER: `${BC_API_BASE}/${tenantId}/${envName}/api/v2.0`,
+          BC_COMPANY: companyId,
+          BC_AUTH_TYPE: 'azure_cli',
+        },
+      },
+    },
+  };
+}
+
+export async function onboard(options = {}) {
+  const { tenantId, output = '.mcp.json', profileName } = options;
+  const token = await getToken();
+
+  const environments = await getEnvironments(token, { tenantId, type: 'Production' });
+  if (environments.length === 0) throw new Error('No Production environments found.');
+
+  const { envName } = environments.length === 1
+    ? { envName: environments[0].name }
+    : await inquirer.prompt([{
+        type: 'list',
+        name: 'envName',
+        message: 'Select environment:',
+        choices: environments.map((e) => e.name),
+      }]);
+
+  const selectedEnv = environments.find((e) => e.name === envName);
+  const companies = await getCompanies(selectedEnv, token);
+  if (companies.length === 0) throw new Error('No companies found in this environment.');
+
+  const { companyId } = companies.length === 1
+    ? { companyId: companies[0].id }
+    : await inquirer.prompt([{
+        type: 'list',
+        name: 'companyId',
+        message: 'Select company:',
+        choices: companies.map((c) => ({ name: c.name, value: c.id })),
+      }]);
+
+  const perms = await getPermissions(selectedEnv, token, { companyId });
+  if (perms.missing.length > 0) {
+    console.warn(`⚠️  Missing permissions: ${perms.missing.join(', ')}`);
+  }
+
+  const ctx = { tenantId: selectedEnv.aadTenantId, envName, companyId };
+  const config = buildMcpConfig(ctx);
+  await writeFile(output, JSON.stringify(config, null, 2), 'utf8');
+  console.log(`✓ Wrote ${output}`);
+
+  const name = profileName ?? `${selectedEnv.aadTenantId}/${envName}`;
+  await saveProfile(name, ctx);
+  console.log(`✓ Saved profile '${name}'`);
+}

package/lib/profiles.js

@@ -0,0 +1,46 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// PROFILE_PATH exported for external reference (computed at import time using real homedir)
+export const PROFILE_PATH = join(homedir(), '.bc365', 'profiles.json');
+
+// Lazy path helpers — always call homedir() at runtime so mocks work in tests
+function getProfileDir() {
+  return join(homedir(), '.bc365');
+}
+
+function getProfilePath() {
+  return join(homedir(), '.bc365', 'profiles.json');
+}
+
+async function readProfiles() {
+  try {
+    const data = await readFile(getProfilePath(), 'utf8');
+    return JSON.parse(data);
+  } catch {
+    return {};
+  }
+}
+
+async function writeProfiles(profiles) {
+  const dir = getProfileDir();
+  await mkdir(dir, { recursive: true });
+  await writeFile(getProfilePath(), JSON.stringify(profiles, null, 2), 'utf8');
+}
+
+export async function saveProfile(name, config) {
+  const profiles = await readProfiles();
+  profiles[name] = { ...config, savedAt: new Date().toISOString() };
+  await writeProfiles(profiles);
+}
+
+export async function listProfiles() {
+  const profiles = await readProfiles();
+  return Object.entries(profiles).map(([name, cfg]) => ({ name, ...cfg }));
+}
+
+export async function loadProfile(name) {
+  const profiles = await readProfiles();
+  return profiles[name] ?? null;
+}

package/lib/versions.js

@@ -0,0 +1,27 @@
+const NPM_REGISTRY = 'https://registry.npmjs.org';
+
+const PACKAGES = [
+  '@habitusnet/bc365',
+  '@habitusnet/d365bc-admin-mcp',
+  '@habitusnet/mcp-business-central',
+];
+
+export async function getLatestVersion(pkg) {
+  try {
+    const res = await fetch(`${NPM_REGISTRY}/${encodeURIComponent(pkg)}`);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data['dist-tags']?.latest ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export async function checkVersions() {
+  return Promise.all(
+    PACKAGES.map(async (pkg) => ({
+      package: pkg,
+      latest: await getLatestVersion(pkg),
+    }))
+  );
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@habitusnet/bc365",
+  "version": "2.0.0",
+  "description": "Smart onboarding CLI and MCP config manager for Business Central",
+  "type": "module",
+  "bin": {
+    "bc365": "./bin/bc365.js"
+  },
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "commands/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/habitusnet/mcp-d365-BC"
+  },
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --coverage",
+    "lint": "eslint lib/ bin/"
+  },
+  "dependencies": {
+    "@azure/msal-node": "^2.15.0",
+    "@microsoft/microsoft-graph-client": "^3.0.7",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "inquirer": "^10.1.5",
+    "keytar": "^7.9.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}