@habitusnet/bc365 2.0.0 → 2.1.0

package/lib/onboard.js

@@ -71,4 +71,5 @@ export async function onboard(options = {}) {
   const name = profileName ?? `${selectedEnv.aadTenantId}/${envName}`;
   await saveProfile(name, ctx);
   console.log(`✓ Saved profile '${name}'`);
+  console.log(`\nTo get BC-aware Claude skills, run:\n  claude plugin install habitusnet/bc365-skills`);
 }

package/package.json

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

package/skills/bc-admin/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: bc-admin
+description: Manage Microsoft Dynamics 365 Business Central environments, companies, installed apps, feature flags, and user sessions using the bc-admin MCP server. Use when the user asks about environment status, app updates, permissions, or wants to perform admin operations.
+allowed-tools: ["mcp__bc-admin__get_environment_informations", "mcp__bc-admin__get_environment_companies", "mcp__bc-admin__get_installed_apps", "mcp__bc-admin__get_available_app_updates", "mcp__bc-admin__update_app", "mcp__bc-admin__get_available_features", "mcp__bc-admin__activate_feature", "mcp__bc-admin__deactivate_feature", "mcp__bc-admin__get_active_sessions", "mcp__bc-admin__kill_active_sessions", "mcp__bc-admin__get_usage_storage_for_environment", "mcp__bc-admin__get_usage_storage_for_all_environments", "mcp__bc-admin__clear_cached_token", "mcp__bc-admin__get_token_cache_status", "mcp__bc-admin__get_extension_deployment_status", "mcp__bc-admin__get_app_operations"]
+---
+
+# BC Admin Skill
+
+Manage Business Central environments and tenant operations via the `bc-admin` MCP server.
+
+## Prerequisites
+
+The `bc-admin` MCP server must be configured in `.mcp.json` (run `bc365 onboard` if not). The `BC_TENANT_ID` environment variable must be set to the tenant's Entra ID GUID.
+
+## Tool Reference
+
+### Environment & Company
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__bc-admin__get_environment_informations()` | List all environments for the tenant |
+| `mcp__bc-admin__get_environment_companies(environment)` | List companies in an environment |
+| `mcp__bc-admin__get_usage_storage_for_environment(environment)` | Storage usage for one environment |
+| `mcp__bc-admin__get_usage_storage_for_all_environments()` | Storage usage across all environments |
+
+### Apps & Extensions
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__bc-admin__get_installed_apps(environment)` | List installed AL apps/extensions |
+| `mcp__bc-admin__get_available_app_updates(environment)` | List apps with pending updates |
+| `mcp__bc-admin__update_app(environment, appId, appVersion)` | Update an app to a specific version |
+| `mcp__bc-admin__get_extension_deployment_status(environment, operationId)` | Check app deployment status |
+| `mcp__bc-admin__get_app_operations(environment)` | List all app operations and their status |
+
+### Feature Flags
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__bc-admin__get_available_features(environment)` | List all BC feature flags and their state |
+| `mcp__bc-admin__activate_feature(environment, feature)` | Enable a feature flag |
+| `mcp__bc-admin__deactivate_feature(environment, feature)` | Disable a feature flag |
+
+### Sessions
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__bc-admin__get_active_sessions(environment)` | List currently active user sessions |
+| `mcp__bc-admin__kill_active_sessions(environment)` | Force-disconnect all sessions (e.g. before upgrade) |
+
+### Auth
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__bc-admin__get_token_cache_status()` | Check if cached token is valid |
+| `mcp__bc-admin__clear_cached_token()` | Clear stale auth token (then re-run `bc365 onboard`) |
+
+## Common Workflows
+
+### Inspect environments
+```
+mcp__bc-admin__get_environment_informations()
+# Returns: name, type (Production/Sandbox), applicationVersion, status
+```
+
+### List companies in Production
+```
+mcp__bc-admin__get_environment_companies(environment="Production")
+# Returns: id (GUID), name, displayName — use id as BC_COMPANY in .mcp.json
+```
+
+### Check for app updates
+```
+mcp__bc-admin__get_available_app_updates(environment="Production")
+# Returns: appId, name, currentVersion, latestVersion
+```
+
+### Update an app
+```
+# 1. Get current installed apps and their IDs
+mcp__bc-admin__get_installed_apps(environment="Production")
+
+# 2. Check for available updates
+mcp__bc-admin__get_available_app_updates(environment="Production")
+
+# 3. Update (always confirm with user first — this affects a live environment)
+mcp__bc-admin__update_app(environment="Production", appId="<guid>", appVersion="<latestVersion>")
+
+# 4. Monitor deployment
+mcp__bc-admin__get_extension_deployment_status(environment="Production", operationId="<operationId from step 3>")
+
+# 5. Or check all pending operations
+mcp__bc-admin__get_app_operations(environment="Production")
+```
+
+### Prepare for maintenance (force logout users)
+```
+# 1. Check who is logged in
+mcp__bc-admin__get_active_sessions(environment="Production")
+
+# 2. Confirm with user before disconnecting — this will interrupt active work
+mcp__bc-admin__kill_active_sessions(environment="Production")
+```
+
+### Check storage usage
+```
+mcp__bc-admin__get_usage_storage_for_all_environments()
+# Returns: environment name, database size, file size in GB
+```
+
+### Manage feature flags
+```
+# List available features and their current state
+mcp__bc-admin__get_available_features(environment="Production")
+
+# Enable a feature (confirm with user — some features cannot be disabled after activation)
+mcp__bc-admin__activate_feature(environment="Production", feature="<featureKey>")
+```
+
+## Auth Troubleshooting
+
+If bc-admin calls return 401 errors:
+```
+mcp__bc-admin__get_token_cache_status()
+# If expired or missing:
+mcp__bc-admin__clear_cached_token()
+# Then tell user: run `bc365 onboard` to re-authenticate
+```
+
+## Profile & Environment Context
+
+The active tenant is set by the `BC_TENANT_ID` env var in `.mcp.json`. To switch tenant/environment:
+```bash
+bc365 switch <profile-name>   # updates .mcp.json to a different profile
+bc365 profiles                # list saved profiles
+```

package/skills/bc-diagnose/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: bc-diagnose
+description: Interpret Microsoft Dynamics 365 Business Central error messages and API failures, and suggest specific fixes. Use when the user receives an HTTP error, OData error, permission error, or unexpected BC behaviour. Cross-references bc-admin skill for permission lookups.
+---
+
+# BC Diagnose Skill
+
+Interpret Business Central errors and guide the user to the correct fix.
+
+## HTTP Status Codes
+
+### 401 Unauthorized
+**Meaning:** The access token is expired, missing, or invalid.
+
+**Fix steps:**
+1. Check token health: `mcp__bc-admin__get_token_cache_status()`
+2. Clear the cached token: `mcp__bc-admin__clear_cached_token()`
+3. Tell the user: `bc365 logout && bc365 onboard` to re-authenticate
+
+If `bc365 onboard` also fails with 401, the Entra ID app registration may have expired or the user's device code session timed out. Ask the user to run `bc365 onboard` in a terminal with a TTY.
+
+### 403 Forbidden
+**Meaning:** Authenticated successfully, but the user lacks a required permission set.
+
+**Fix steps:**
+1. List companies via bc-admin to confirm the correct company: `mcp__bc-admin__get_environment_companies(environment="Production")`
+2. Common missing permission sets:
+   - `D365 BUS FULL ACCESS` — general read/write access
+   - `D365 BASIC` — minimum read access
+   - `D365 ACCOUNTANT` — finance/G/L access
+   - `D365 SALES` — sales access
+   - `D365 PURCHASING` — purchasing access
+   - `SUPER` — admin only
+3. A BC administrator must assign the missing permission in the BC UI (Settings → Users → select user → Permission Sets) — this cannot be done via MCP
+
+### 404 Not Found
+**Meaning:** The entity or endpoint does not exist. Most common causes:
+
+| Cause | Symptom | Fix |
+|-------|---------|-----|
+| Wrong company GUID | 404 on any data request | Run `bc365 profiles`, compare `BC_COMPANY` in `.mcp.json` with actual company ID from `mcp__bc-admin__get_environment_companies` |
+| Wrong API version | URL has `/v1.0/` instead of `/v2.0/` | Check `BC_URL_SERVER` in `.mcp.json` — should end in `/api/v2.0` |
+| Entity name wrong | 404 on specific entity | Use the exact camelCase entity name (e.g. `salesOrders` not `sales_orders`) — use `bc-query` skill for the full entity list |
+| Record deleted | 404 on specific ID | The record no longer exists — list the entity to confirm |
+
+### 429 Too Many Requests
+**Meaning:** BC's API rate limit was hit.
+
+**Fix steps:**
+1. Wait 30–60 seconds before retrying
+2. Reduce query size: add `top=50` to `list_items` calls
+3. Avoid broad queries with no filter on large entities (e.g. `generalLedgerEntries` without a date filter)
+4. If hitting limits repeatedly, schedule bulk operations during off-peak hours
+
+### 500 Internal Server Error
+**Meaning:** BC server-side error. Usually transient.
+
+**Fix steps:**
+1. Retry the same operation after 30 seconds
+2. If persistent, check BC service health at [aka.ms/bchealth](https://aka.ms/bchealth)
+3. Check environment status: `mcp__bc-admin__get_environment_informations()` — look for `status: Updating`
+
+### 503 Service Unavailable
+**Meaning:** BC environment is unavailable (often during scheduled maintenance or upgrade).
+
+**Fix steps:**
+1. `mcp__bc-admin__get_environment_informations()` — check `status` field
+2. If `status: Updating` — wait for upgrade to complete
+3. Monitor upgrade progress: `mcp__bc-admin__get_app_operations(environment="Production")`
+4. If unexpected downtime, report to Microsoft via BC Admin Center
+
+## OData Errors
+
+### Filter parse error
+**Symptom:** `BadRequest` or `An error occurred while reading from the store provider's data reader`
+
+**Cause:** OData `$filter` syntax error.
+
+**Common mistakes:**
+- String values must be in single quotes: `displayName eq 'Contoso'` (not double quotes)
+- Date values need full ISO format: `postingDate gt 2024-01-01T00:00:00Z`
+- Field names are camelCase: `displayName` not `Display Name`
+- Use `mcp__bc-data__get_schema(entity="...")` to verify correct field names
+
+### Unauthorized in OData response body
+**Cause:** bc-data server uses `azure_cli` auth — `az login` token has expired.
+
+**Fix:** Tell the user to run `az login` to refresh Azure CLI credentials.
+
+### ResourceNotFound in OData response
+**Cause:** Company GUID mismatch or entity not available in this BC version.
+
+**Fix:**
+1. Verify company: `mcp__bc-admin__get_environment_companies(environment="Production")`
+2. Compare with `BC_COMPANY` in `.mcp.json`
+3. If mismatch: `bc365 onboard` to regenerate config with the correct company
+
+## Permission Set Reference
+
+| Permission Set | Grants |
+|----------------|--------|
+| `D365 BUS FULL ACCESS` | Full read/write on business data |
+| `D365 BASIC` | Read-only on most business data |
+| `D365 ACCOUNTANT` | Full access to finance/G/L |
+| `D365 SALES` | Full access to sales |
+| `D365 PURCHASING` | Full access to purchasing |
+| `SUPER` | Full system access including user management (admin only) |
+
+## Diagnostic Workflow
+
+When a user reports an error, follow this sequence:
+
+1. **Identify the HTTP status code** — use the tables above
+2. **Check token health first** (most errors are auth-related):
+   ```
+   mcp__bc-admin__get_token_cache_status()
+   ```
+3. **Verify the environment is up**:
+   ```
+   mcp__bc-admin__get_environment_informations()
+   ```
+4. **Reproduce with a minimal query** — try this as a baseline:
+   ```
+   mcp__bc-data__list_items(entity="companies", top=1)
+   ```
+5. **Verify BC_COMPANY matches** — compare `mcp__bc-admin__get_environment_companies` output with the `BC_COMPANY` value in `.mcp.json`
+6. **Check field names** — if the error is filter-related, use `mcp__bc-data__get_schema` to confirm field names

package/skills/bc-query/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: bc-query
+description: Query and update Microsoft Dynamics 365 Business Central data using the bc-data MCP server. Use when the user asks to list customers, find items, check sales orders, query general ledger entries, or any other BC data operation.
+allowed-tools: ["mcp__bc-data__list_items", "mcp__bc-data__get_items_by_field", "mcp__bc-data__get_schema", "mcp__bc-data__create_item", "mcp__bc-data__update_item", "mcp__bc-data__delete_item"]
+---
+
+# BC Query Skill
+
+Query and update Business Central data via the `bc-data` MCP server.
+
+## Prerequisites
+
+The `bc-data` MCP server must be configured in `.mcp.json` (run `bc365 onboard` if not). The server uses Azure CLI credentials — run `az login` if you see auth errors.
+
+## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__bc-data__list_items` | List entities with optional OData filtering |
+| `mcp__bc-data__get_items_by_field` | Find records matching a specific field value |
+| `mcp__bc-data__get_schema` | Discover available fields for an entity |
+| `mcp__bc-data__create_item` | Create a new record |
+| `mcp__bc-data__update_item` | Update an existing record by ID |
+| `mcp__bc-data__delete_item` | Delete a record by ID |
+
+## Common Entity Names
+
+Use these exact strings as the `entity` parameter:
+
+| Entity | Description |
+|--------|-------------|
+| `customers` | Customer master records |
+| `vendors` | Vendor master records |
+| `items` | Item (product/service) master |
+| `salesOrders` | Sales order headers |
+| `salesInvoices` | Posted sales invoices |
+| `purchaseOrders` | Purchase order headers |
+| `purchaseInvoices` | Posted purchase invoices |
+| `generalLedgerEntries` | G/L ledger entries |
+| `accounts` | Chart of accounts |
+| `companies` | Companies in this environment |
+| `currencies` | Currency codes and exchange rates |
+| `paymentTerms` | Payment term codes |
+
+## Querying Patterns
+
+### List all records (with limit)
+```
+mcp__bc-data__list_items(entity="customers", top=50)
+```
+
+### Filter by field value
+```
+mcp__bc-data__list_items(entity="customers", filter="displayName eq 'Contoso'")
+mcp__bc-data__list_items(entity="items", filter="startswith(displayName, 'BIKE')")
+mcp__bc-data__list_items(entity="salesOrders", filter="sellToCustomerNumber eq '10000'")
+```
+
+### Select specific fields (reduces payload)
+```
+mcp__bc-data__list_items(entity="customers", select="number,displayName,email,phoneNumber", top=100)
+```
+
+### Find by known field value (simpler than filter)
+```
+mcp__bc-data__get_items_by_field(entity="customers", field="number", value="10000")
+mcp__bc-data__get_items_by_field(entity="items", field="number", value="ITEM-001")
+```
+
+### Discover available fields before querying
+```
+mcp__bc-data__get_schema(entity="salesOrders")
+```
+Always call `get_schema` first when the user asks about a field you haven't seen before.
+
+### Sort results
+```
+mcp__bc-data__list_items(entity="generalLedgerEntries", filter="postingDate gt 2024-01-01", orderby="postingDate desc", top=200)
+```
+
+### Paginate large result sets
+If the response contains `@odata.nextLink`, call `list_items` again with a `skip` offset:
+```
+mcp__bc-data__list_items(entity="generalLedgerEntries", top=200, skip=200)
+```
+
+## OData Filter Syntax
+
+BC uses OData v4. Supported operators:
+- Equality: `field eq 'value'` or `field eq 12345`
+- Comparison: `field gt value`, `field lt value`, `field ge value`, `field le value`
+- String: `startswith(field, 'prefix')`, `contains(field, 'substring')`
+- Date: `postingDate gt 2024-01-01T00:00:00Z`
+- Combine: `field1 eq 'x' and field2 gt 100`
+
+**Common mistake:** Field names are camelCase in the API (`displayName`, `sellToCustomerNumber`), NOT the BC UI names ("Name", "Sell-to Customer No."). Use `get_schema` to find the correct API field name.
+
+## Write Operations (use with care)
+
+Before creating or updating, always call `get_schema` to see required fields and field types.
+
+```
+# Create a new customer
+mcp__bc-data__create_item(entity="customers", data={"displayName": "New Corp", "currencyCode": "CHF"})
+
+# Update a customer's email
+mcp__bc-data__update_item(entity="customers", id="<guid>", data={"email": "new@example.com"})
+```
+
+Destructive operations (`delete_item`) require the record's GUID `id`, not its BC number. Always confirm with the user before deleting.