iFacto Playbook VS Code Extension

Automated development environment setup for iFacto, Astena, O2Ti, and partner companies

Overview

The iFacto Playbook extension is designed for developers at iFactoBE, iFactoNL, iFactoFood, Astena, and O2Ti. It automates your complete development environment setup with company-specific configurations:

• Model Context Protocol (MCP) servers - Jira, Confluence, Azure DevOps, and more
• BC Code Intelligence - Company standards for Business Central development
• Prerequisites - Automatic Node.js, .NET SDK, and Azure CLI installation
• Authentication - Seamless Azure DevOps and Atlassian integration
• Company Profiles - One-click configuration for your organization

🚀 Getting Started<>

Step 1: Install the Extension

1. Open VS Code Extensions view (Ctrl+Shift+X)
2. Search for "iFacto Playbook"
3. Click Install

Or install from the VS Code Marketplace.

Step 2: Select Your Company Profile

Your company profile configures everything automatically - Azure DevOps organization, Atlassian sites, email domains, and which MCP servers to install.

1. Open Command Palette (Ctrl+Shift+P)
2. Run: iFacto: Select Company Profile
3. Choose your company:
   • iFactoBE - iFacto Belgium (@ifacto.be)
   • iFactoNL - iFacto Netherlands (@ifacto.nl)
   • iFactoFood - iFacto Food (@ifacto.be)
   • Astena - Astena (@astena.be)
   • O2Ti - O2Ti (@o2ti.be)

Why this matters: Each profile connects you to the right Jira/Confluence site, Azure DevOps organization, and issue tracker for your company.

Need to add a new company? See docs/PROFILE-QUICK-START.md for the 5-minute setup guide.

Step 3: Run the Setup Wizard

The setup wizard guides you through the complete installation process.

1. Open Command Palette (Ctrl+Shift+P)
2. Run: iFacto: Show Setup Wizard
3. Follow the prompts:

3a. Install Prerequisites

The wizard checks for and installs:

• Node.js 22.23.4+, 24.22.1+ or 26.12.1+ - Required for MCP servers (older versions miss the security fixes of October 2026)
• .NET SDK 8.0+ - Required for Business Central AL dependency analysis
• Azure CLI - Required for Azure DevOps authentication

Installation is automatic on Windows (winget), macOS (Homebrew), and Linux (package managers).

Troubleshooting:

• Permission errors: Run VS Code as Administrator (Windows) or use sudo
• Network issues: Check firewall and proxy settings
• Corporate restrictions: Contact IT for manual installation links

3b. Install MCP Servers

The wizard installs MCP servers based on your company profile and the install target you choose (VS Code / GitHub Copilot vs Claude Code CLI). Each profile defines two independent enable lists — mcpServers.vscode.enabled and mcpServers.claude.enabled — so the same profile can expose a different MCP set to each client.

Install commands (the team runs hybrid — some Copilot, some Claude — so the Setup Wizard offers a button for each):

• iFacto: Install MCP Servers (GitHub Copilot only) — registers only the mcpServers.vscode.enabled list into VS Code's mcp.json.
• iFacto: Install MCP Servers (Claude Code CLI only) — registers only the mcpServers.claude.enabled list with the local claude CLI (via claude mcp add).

Automatic MCP check on startup: when ifacto-token-tracker is enabled in your active profile's mcpServers.vscode.enabled, the extension automatically checks whether it is installed and up to date, installs it if missing, and updates it if configuration is outdated.

API Token Setup: For Jira, Confluence, and Mantis, the wizard will:

1. Open the API token generation page in your browser
2. Prompt you to enter the generated token
3. Configure the MCP server automatically

Microsoft AL MCP Server (almcp) — the AL MCP for Claude: installed as part of iFacto: Install MCP Servers (Claude Code CLI only), from any workspace. The extension resolves the AL launcher via AL tools detection (the bundled altool, or the al dotnet tool) and asks it once (launchmcpserver --help) whether it starts without project paths — true since AL 18.0, where projects became optional and can be loaded at runtime with the al_addproject MCP tool. On such a launcher it registers claude mcp add -s user almcp -- <altool> launchmcpserver (stdio, user scope, path-less): one registration that works wherever claude is started; the iFacto agents and skills load the workspace's AL project with al_addproject as part of their Required Toolset Gate. When the install runs from an AL workspace it additionally registers pre-loaded local-scoped entries (-s local ... launchmcpserver <App> <Test>) for the repo root and every workspace folder — local wins over user for the same name, so inside an AL workspace the project is already loaded (a local-scoped entry applies only to the exact directory claude is started from, and in a multi-root workspace VS Code's integrated terminal opens in a workspace folder, not in the folder holding the .code-workspace). On a pre-18.0 launcher (altool launchmcpserver exits with Error: No projects specified without a path) only the local-scoped entries are written, and the install is skipped with a warning when the workspace holds no AL project. The registered launcher path contains the AL extension version, so an AL Language update would break it: on activation in an AL workspace the extension checks the existing registrations (local roots and the user-scoped entry) and silently re-registers them against the current launcher — it only repairs a registration you already have, it never adds one on its own. Because it is standalone (no VS Code required), it is the single, leading AL MCP for Claude. If the AL Language Extension isn't installed, almcp is skipped without failing the rest of the Claude install.

BC Code Atlas (bc-code-atlas): a remote HTTP server (https://bc-code-atlas.stefanmaron.dev/mcp), registered like Microsoft Learn — claude mcp add --transport http at user scope for Claude, an http entry in the user mcp.json for Copilot. It is enabled in every profile for both targets and backs the iFacto.base-app-source skill ("what does the base app actually do / who subscribes to this event / show me the body"). It is one person's free server: the skill keeps agents to one or two calls per question and never requests a new version build without asking you. BC Observatory (bc-observatory): the knowledge-base MCP behind the atlas's "what is it, which id, which fields and events, where is it documented, what changed between versions" questions. Installed from the npm release (npx -y bc-observatory@latest, stdio) for both targets, enabled in every profile.

Already running the community bc-observatory Claude plugin? It bundles the same servers — bc-observatory, bc-code-atlas and, from plugin 0.3.0, Microsoft Learn (named microsoft-learn there). For each of them the Claude installer notices the plugin-provided server and skips its own registration, so no tool is loaded twice; the install log then says <server> is already provided by a Claude plugin, and the install picker, the custom selection and iFacto: Validate Environment show it as ✅ installed all the same.

AL MCP consolidation: for the Claude target, almcp replaces both the community al-mcp-server and the al-mcp-bridge — neither is installed for Claude anymore. The community al-mcp-server remains the AL MCP for the VS Code / GitHub Copilot target (unchanged). The al-mcp-bridge is retired from all default profiles. If you previously installed the bridge or the community server for Claude, they linger in ~/.claude.json until removed with iFacto: Remove iFacto Playbook MCP Servers (or claude mcp remove).

AL Development Tools detection: iFacto: Validate Environment reports whether the default AL tools are installed — the AL Language Extension (ms-dynamics-smb.al) and the platform-specific alc compiler it bundles under bin/<platform>/, together with the altool/almcp/aldoc companions. Detection is cross-platform: macOS (bin/darwin/alc), Windows (bin/win32/alc.exe), and Linux (bin/linux/alc, flagged as unofficial since Microsoft supports only Windows and macOS). If the extension is absent it also looks for a globally-installed Microsoft.Dynamics.BusinessCentral.Development.Tools dotnet tool. This section is informational and never fails the overall validation.

3c. Setup BC Code Intelligence (Business Central Only)

For Business Central developers, this step configures company-wide development standards:

What BC Code Intelligence Provides:

• Company Guidelines - iFacto coding standards and patterns
• AI Specialists - Company-specific development experts
• Automatic Updates - Company standards stay current (checks every 4 hours)
• Workspace Integration - Custom agents and prompts in .github folder

Prerequisites:

• Azure CLI authenticated (az login)
• Access to your company's Azure DevOps organization

What Happens:

1. User-level config created at ~/.bc-code-intel/config.json
2. Company guidelines synced from Azure DevOps (BCCompanyGuidelines)
3. Agents and prompts copied to workspace .github folder
4. MCP server added to VS Code configuration

Automatic Updates: Status bar shows "$(cloud-download) BC Code Intel Update" when updates are available. Click to update instantly.

Note: This step is skipped for profiles that use BCQuality instead (see below) — running it there redirects you to the BCQuality install command.

3c-2. Install BCQuality (iFacto Belgium & Astena only)

Some profiles use BCQuality — a git-based AL code-quality knowledge base — instead of BC Code Intelligence. The two are mutually exclusive per profile; a profile uses exactly one, never both. Currently: iFactoBE and Astena use BCQuality; iFactoNL, iFactoFood, and O2Ti stay on BC Code Intelligence.

BCQuality installs as a native plugin for both assistants:

• Claude Code: registered as a plugin marketplace (claude plugin marketplace add / claude plugin install) — kept fresh automatically (daily-throttled) once installed.
• GitHub Copilot (VS Code): a local clone of the fork (~/.ifacto-playbook/bcquality/<profile>) registered in VS Code's Preview "Agent Plugins" feature via chat.pluginLocations. This feature is still Preview, so on older VS Code builds the command reports it as unsupported instead of failing. (An earlier version of this registered the fork's URL in chat.plugins.marketplaces instead — that left Copilot with nothing to actually read until a manual "Chat: Manage Plugins" step was completed, which turned out to be an easy step to miss; the local-clone approach needs no manual finish.)

Run: iFacto: Install / Update BCQuality Knowledge Base (Copilot + Claude)

If bc-code-intel is still installed after a successful BCQuality install, you'll get a one-time offer to remove it — declining is remembered so you're not asked again.

You don't have to go looking for it: on iFactoBE/Astena profiles where BCQuality isn't installed yet, the extension shows a notification with an Install BCQuality button on every startup — it keeps appearing (no "don't show again") until you install it.

3d. Token Efficiency Dashboard

An in-editor dashboard that tracks how efficiently you use AI tools:

• Usage tracking — chat turns, inline completions, commands, file saves, active coding sessions
• Waste tracking — agents self-report inefficient patterns (vague prompts, long sessions, repetition, topic drift)
• LLM model breakdown — see which models you use and how much (agents report their model name)
• Scoring — daily efficiency score (0–100) balancing productive usage vs waste
• Trend chart — 7-day line chart with score, productive units, and waste events
• Coaching tips — actionable suggestions based on your top waste patterns

Open via: iFacto: Show Token Efficiency Dashboard

Data is stored locally (~/.ifacto/*.jsonl → VS Code globalState). 90-day retention, auto-refreshes every 5 minutes.

After Setup: You're ready to develop! The status bar and "iFacto Setup Status" view show your configuration health.

📋 Available Commands

⚙️ Configuration

🔐 Authentication

The extension uses Azure CLI for authentication (recommended):

az login

Alternative Methods:

• VS Code Azure Account extension (automatic)
• Personal Access Token (prompted if other methods fail)

Generate PAT at: https://dev.azure.com/iFactoAcademy/_usersSettings/tokens

🛠️ Troubleshooting

Prerequisites Won't Install

• Windows: Run VS Code as Administrator, or install manually from extension prompts
• macOS/Linux: Use sudo if package managers fail
• Corporate Networks: Contact IT if automatic installation is blocked

Authentication Fails

• Run az login in terminal
• Check Azure CLI is installed: az --version
• Verify you have access to your company's Azure DevOps organization

MCP Servers Not Working

• Check prerequisites: Node.js 22.23.4+ / 24.22.1+ / 26.12.1+, .NET SDK 8.0+, and Azure CLI must be installed
• Verify API tokens for Jira/Confluence/Mantis are correct
• Run iFacto: Validate Environment to diagnose issues

BC Code Intelligence Not Updating

• Ensure Azure CLI is authenticated: az login
• Check internet connection to Azure DevOps
• Manually trigger: iFacto: Check for BC Code Intel Updates

Need More Help? Check the "iFacto Setup Status" view in Explorer for detailed diagnostics.

🎉 What's New

v0.2.0 - January 2026

• Multi-company support with profiles for iFactoBE, iFactoNL, iFactoFood, Astena, O2Ti
• Region-specific configurations for Atlassian sites and email domains
• Streamlined setup wizard with guided installation

v0.1.0 - December 2025

• BC Code Intelligence - User-level MCP configuration for Business Central
• Automatic update detection with status bar notifications
• Prerequisites automation - One-click Node.js, .NET SDK, and Azure CLI installation
• Legacy migration from BCCopilotGuidance

See CHANGELOG.md for complete version history

🤝 Contributing

Want to add a new company profile or contribute to the extension?

See CONTRIBUTING.md for:

• Development setup and architecture
• How to add company profiles (5-minute guide)
• Coding guidelines and best practices
• Testing and release process

📄 License

Internal use only - iFacto Academy and partner companies

🔗 Related Projects

• BCCompanyGuidelines - Company-specific BC development standards
• bc-code-intel - Business Central Code Intelligence MCP server
• iFacto Playbook - Complete development environment documentation

Built with ❤️ by the DevLead team to make developer onboarding effortless!