@habitusnet/bc365 2.2.5 → 2.2.7

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.2.7] — 2026-02-20
+
+### Added
+- `bc365 onboard --target claude-desktop` writes MCP servers directly into `claude_desktop_config.json`, merging with any existing config and preserving other keys
+- `bc365 switch <profile> --target claude-desktop` does the same from a saved profile
+- Both commands print "Restart Claude Desktop to apply changes." when using the claude-desktop target
+
+## [2.2.6] — 2026-02-20
+
+### Changed
+- README rewritten: two-command quick start, scope table, skills section, multi-tenant workflow, troubleshooting
+- SETUP.md updated: removed stale v1/`--output` references, updated multi-tenant section for `bc365 switch`
+
 ## [2.2.5] — 2026-02-20
 
 ### Changed

package/README.md

@@ -1,103 +1,149 @@
-# bc365 — MCP Config Manager for Business Central
+# bc365
 
-`@habitusnet/bc365` is a CLI that connects Claude Code to Microsoft Dynamics 365 Business Central — auto-discovering your environments, registering MCP servers, and installing BC-aware Claude skills.
-
-## Quick Start
+> Connect Claude Code to Microsoft Dynamics 365 Business Central in two commands.
 
 ```bash
 npx @habitusnet/bc365 onboard
+claude plugin install habitusnet/bc365-skills
 ```
 
-Sign in with your Microsoft account. The CLI discovers your tenant, environments, and companies automatically, checks your BC permissions, and registers both MCP servers with Claude Code.
+---
 
-Then install the Claude Code skill bundle:
+## What It Does
 
-```bash
-claude plugin install habitusnet/bc365-skills
-```
+`bc365 onboard` signs you in with Microsoft, discovers your BC environments and companies, and registers two MCP servers directly with Claude Code:
+
+| MCP Server | Purpose |
+|------------|---------|
+| `bc-data` | Read and write BC data — customers, items, orders, G/L entries via OData |
+| `bc-admin` | Manage environments, apps, feature flags, and user sessions |
+
+`claude plugin install habitusnet/bc365-skills` adds three Claude skills that tell Claude how to use those servers effectively.
+
+---
+
+## Prerequisites
 
-**Prerequisites:**
-- Claude Code installed (`npm install -g @anthropic-ai/claude-code`)
-- Microsoft 365 / Azure AD account with access to Business Central
-- Business Central environment with `D365 BUS FULL ACCESS` permission set
+- [Claude Code](https://docs.anthropic.com/claude-code) installed
+- Node.js ≥ 20
+- Microsoft 365 account with access to Business Central
+- `D365 BUS FULL ACCESS` permission set in BC
 
 ---
 
 ## Installation
 
+### Global install (recommended)
+
 ```bash
 npm install -g @habitusnet/bc365
+bc365 onboard
 ```
 
-Or use without installing:
+### One-off (no install)
 
 ```bash
 npx @habitusnet/bc365 onboard
 ```
 
-## What `bc365 onboard` Does
+---
+
+## Onboarding
+
+```bash
+bc365 onboard
+```
 
-1. Opens a Microsoft device code login in your browser
-2. Discovers your BC environments and companies
-3. Checks your permission sets
-4. Registers two MCP servers with Claude Code (`claude mcp add-json -s local`):
-   - **`bc-data`** — query and update BC data via OData (customers, items, orders, G/L entries)
-   - **`bc-admin`** — manage environments, apps, feature flags, and sessions
+1. A device code URL is printed — open it in your browser and sign in with your Microsoft account
+2. The CLI discovers your tenant, environments, and companies
+3. Checks your BC permission sets and warns if anything is missing
+4. Registers `bc-data` and `bc-admin` with Claude Code
 
-Servers are registered at local scope (`.claude/settings.local.json`, gitignored and per-user). Pass `--scope` to override:
+Servers are registered at **local scope** by default — stored in `.claude/settings.local.json`, gitignored, per-user. Use `--scope` to change this:
 
 | Scope | Stored in | Use when |
 |-------|-----------|----------|
-| `local` (default) | `.claude/settings.local.json` | Per-user, gitignored — recommended |
+| `local` *(default)* | `.claude/settings.local.json` | Per-user, gitignored — recommended |
 | `user` | `~/.claude.json` | All projects for this user |
 | `project` | `.mcp.json` | Shared team config, committed to git |
 
 ```bash
-bc365 onboard                        # local scope (default)
-bc365 onboard --scope project        # writes .mcp.json
-bc365 switch habitusnet-prod         # re-register saved profile at local scope
-bc365 switch habitusnet-prod --scope user  # re-register at user scope
+bc365 onboard                   # local scope (default)
+bc365 onboard --scope project   # writes .mcp.json for the whole team
 ```
 
-## Claude Code Skills
-
-After onboarding, install the companion skill bundle:
+After onboarding, install the skill bundle:
 
 ```bash
 claude plugin install habitusnet/bc365-skills
 ```
 
-This gives Claude three skills:
+---
+
+## Claude Skills
 
-| Skill | Description |
-|-------|-------------|
-| `bc-query` | Query and update BC data — OData filters, expand for line items, pagination |
-| `bc-admin` | Manage environments, apps, feature flags, sessions |
-| `bc-diagnose` | Interpret BC HTTP/OData errors and suggest fixes |
+The [`habitusnet/bc365-skills`](https://github.com/habitusnet/bc365-skills) plugin teaches Claude how to use the MCP servers:
 
-Skills are also bundled in this package under `skills/` for offline use.
+| Skill | What it covers |
+|-------|----------------|
+| `bc-query` | OData filters, `$expand` for line items, pagination, write operations |
+| `bc-admin` | Environment inspection, app update workflow, feature flags, session management |
+| `bc-diagnose` | HTTP/OData error interpretation, permission set reference, diagnostic workflow |
 
-## Commands
+Skills are also bundled in this package under `skills/` for offline access.
+
+---
+
+## Multi-Tenant Usage (Agencies)
+
+Each `bc365 onboard` run saves a profile. Switch between clients without re-authenticating:
+
+```bash
+# Onboard client A (saves profile automatically)
+bc365 onboard
+
+# Later: switch to client B
+bc365 switch client-b-profile
+
+# List all saved profiles
+bc365 profiles
+```
+
+`bc365 switch` accepts the same `--scope` flag as `onboard`.
+
+---
+
+## All Commands
 
 | Command | Description |
 |---------|-------------|
-| `bc365 onboard [-s local\|user\|project]` | Discover and register MCP servers |
+| `bc365 onboard [-s local\|user\|project]` | Discover tenant/env/company and register MCP servers |
 | `bc365 switch <profile> [-s local\|user\|project]` | Re-register servers from a saved profile |
 | `bc365 profiles` | List saved profiles |
 | `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).
+---
 
 ## MCP Servers
 
-| Server | Package | Purpose |
-|--------|---------|---------|
-| `bc-data` | [`@habitusnet/mcp-business-central`](https://github.com/habitusnet/mcp-business-central) | OData read/write on BC entities |
-| `bc-admin` | [`habitusnet/d365bc-admin-mcp`](https://github.com/habitusnet/d365bc-admin-mcp) | BC Admin Center API |
+Both servers are vendored mirrors with daily upstream sync and security scanning:
+
+| Server | Upstream | npm command |
+|--------|----------|-------------|
+| `bc-admin` | [`habitusnet/d365bc-admin-mcp`](https://github.com/habitusnet/d365bc-admin-mcp) | `d365bc-admin-mcp` |
+| `bc-data` | [`habitusnet/mcp-business-central`](https://github.com/habitusnet/mcp-business-central) | `npx @habitusnet/mcp-business-central` |
+
+---
+
+## Troubleshooting
+
+**Auth errors (`401`)** — run `az login` to refresh Azure CLI credentials, or re-run `bc365 onboard`.
+
+**Missing permissions warning** — ask your BC admin to assign `D365 BUS FULL ACCESS` in Settings → Users → Permission Sets.
 
-Both are vendored mirrors with daily upstream sync and security scanning.
+**`claude: command not found`** — Claude Code must be installed and on your PATH before running `bc365 onboard`.
+
+---
 
 ## License
 

package/lib/cli.js

@@ -17,13 +17,14 @@ program
 
 program
   .command('onboard')
-  .description('Auto-discover tenant/environment/company and register MCP servers with Claude Code')
+  .description('Auto-discover tenant/environment/company and register MCP servers')
   .option('-t, --tenant-id <id>', 'Azure AD tenant ID (skip Graph lookup)')
-  .option('-s, --scope <scope>', 'Configuration scope: local, user, or project (default: local)', 'local')
+  .option('-s, --scope <scope>', 'Claude Code scope: local, user, or project (default: local)', 'local')
+  .option('--target <target>', 'Target: claude-code or claude-desktop (default: claude-code)', 'claude-code')
   .option('-p, --profile <name>', 'Profile name to save (default: tenantId/envName)')
   .action(async (opts) => {
     try {
-      await onboard({ tenantId: opts.tenantId, scope: opts.scope, profileName: opts.profile });
+      await onboard({ tenantId: opts.tenantId, scope: opts.scope, target: opts.target, profileName: opts.profile });
     } catch (err) {
       console.error(chalk.red(`✗ ${err.message}`));
       process.exit(1);
@@ -33,7 +34,8 @@ program
 program
   .command('switch <profile>')
   .description('Switch active profile (re-registers MCP servers from saved profile)')
-  .option('-s, --scope <scope>', 'Configuration scope: local, user, or project (default: local)', 'local')
+  .option('-s, --scope <scope>', 'Claude Code scope: local, user, or project (default: local)', 'local')
+  .option('--target <target>', 'Target: claude-code or claude-desktop (default: claude-code)', 'claude-code')
   .action(async (profileName, opts) => {
     try {
       const profile = await loadProfile(profileName);
@@ -41,15 +43,21 @@ program
         console.error(chalk.red(`✗ Profile '${profileName}' not found. Run 'bc365 onboard' first.`));
         process.exit(1);
       }
-      const { execFile: _execFile } = await import('node:child_process');
-      const { promisify } = await import('node:util');
-      const execFile = promisify(_execFile);
-      const { buildMcpConfig } = await import('./onboard.js');
+      const { buildMcpConfig, registerWithClaudeDesktop } = await import('./onboard.js');
       const config = buildMcpConfig(profile);
-      for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
-        await execFile('claude', ['mcp', 'add-json', '-s', opts.scope, name, JSON.stringify(serverConfig)]);
+      if (opts.target === 'claude-desktop') {
+        const configPath = await registerWithClaudeDesktop(config);
+        console.log(chalk.green(`✓ Switched to profile '${profileName}' → ${configPath}`));
+        console.log('Restart Claude Desktop to apply changes.');
+      } else {
+        const { execFile: _execFile } = await import('node:child_process');
+        const { promisify } = await import('node:util');
+        const execFile = promisify(_execFile);
+        for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+          await execFile('claude', ['mcp', 'add-json', '-s', opts.scope, name, JSON.stringify(serverConfig)]);
+        }
+        console.log(chalk.green(`✓ Switched to profile '${profileName}' (scope: ${opts.scope})`));
       }
-      console.log(chalk.green(`✓ Switched to profile '${profileName}' (scope: ${opts.scope})`));
     } catch (err) {
       console.error(chalk.red(`✗ ${err.message}`));
       process.exit(1);

package/lib/onboard.js

@@ -1,4 +1,7 @@
 import { execFile as _execFile } from 'node:child_process';
+import { readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { promisify } from 'node:util';
 import inquirer from 'inquirer';
 import { getToken } from './auth.js';
@@ -8,6 +11,13 @@ import { saveProfile } from './profiles.js';
 const execFile = promisify(_execFile);
 const BC_API_BASE = 'https://api.businesscentral.dynamics.com/v2.0';
 
+export function claudeDesktopConfigPath() {
+  if (process.platform === 'win32') {
+    return join(process.env.APPDATA, 'Claude', 'claude_desktop_config.json');
+  }
+  return join(homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+}
+
 export function buildMcpConfig(ctx) {
   const { tenantId, envName, companyId } = ctx;
   return {
@@ -31,8 +41,24 @@ export function buildMcpConfig(ctx) {
   };
 }
 
+export async function registerWithClaudeDesktop(config) {
+  const configPath = claudeDesktopConfigPath();
+  let existing = {};
+  try {
+    existing = JSON.parse(await readFile(configPath, 'utf8'));
+  } catch {
+    // file doesn't exist yet — start fresh
+  }
+  const merged = {
+    ...existing,
+    mcpServers: { ...(existing.mcpServers ?? {}), ...config.mcpServers },
+  };
+  await writeFile(configPath, JSON.stringify(merged, null, 2), 'utf8');
+  return configPath;
+}
+
 export async function onboard(options = {}) {
-  const { tenantId, scope = 'local', profileName } = options;
+  const { tenantId, scope = 'local', target = 'claude-code', profileName } = options;
   const token = await getToken();
 
   const environments = await getEnvironments(token, { tenantId, type: 'Production' });
@@ -68,10 +94,16 @@ export async function onboard(options = {}) {
   const ctx = { tenantId: selectedEnv.aadTenantId, envName, companyId };
   const config = buildMcpConfig(ctx);
 
-  for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
-    await execFile('claude', ['mcp', 'add-json', '-s', scope, name, JSON.stringify(serverConfig)]);
+  if (target === 'claude-desktop') {
+    const configPath = await registerWithClaudeDesktop(config);
+    console.log(`✓ Wrote MCP servers to ${configPath}`);
+    console.log('Restart Claude Desktop to apply changes.');
+  } else {
+    for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+      await execFile('claude', ['mcp', 'add-json', '-s', scope, name, JSON.stringify(serverConfig)]);
+    }
+    console.log(`✓ Registered MCP servers (scope: ${scope})`);
   }
-  console.log(`✓ Registered MCP servers (scope: ${scope})`);
 
   const name = profileName ?? `${selectedEnv.aadTenantId}/${envName}`;
   await saveProfile(name, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@habitusnet/bc365",
-  "version": "2.2.5",
+  "version": "2.2.7",
   "description": "Smart onboarding CLI and MCP config manager for Business Central",
   "type": "module",
   "bin": {