d365fo-mcp 1.4.0 → 1.5.1

package/README.md

@@ -10,7 +10,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg)](https://www.typescriptlang.org/)
 [![Tests](https://img.shields.io/badge/tests-1400%2B-brightgreen.svg)](docs/TESTING.md)
 <!-- coverage-badge:start -->
-[![Core coverage](https://img.shields.io/badge/core_coverage-100%25-brightgreen.svg)](eval/COVERAGE.md) [![Total coverage](https://img.shields.io/badge/total_coverage-64.9%25-lightgrey.svg)](eval/COVERAGE.md)
+[![Core coverage](https://img.shields.io/badge/core_coverage-100%25-brightgreen.svg)](eval/COVERAGE.md) [![Total coverage](https://img.shields.io/badge/total_coverage-72.7%25-lightgrey.svg)](eval/COVERAGE.md)
 <!-- coverage-badge:end -->
 
 *Grounded AI development for Dynamics 365 Finance & Operations — works with GitHub Copilot and Claude Code*
@@ -74,6 +74,8 @@ Structural violations (wrong order, missing container, disallowed control) **blo
 
 ## Quick Start
 
+> **From D365FO platform update 10.0.49 (PU74), Visual Studio 2026 is the supported IDE for X++ development** — Microsoft no longer supports VS 2022. Earlier platform versions still use VS 2022 ≥ 17.14. [Details](https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/fin-ops/get-started/whats-new-platform-updates-10-0-49)
+
 **Installing on your own D365FO VM** — the usual case. One line in PowerShell installs Node.js if it is missing, installs the server from npm, and runs the setup wizard, which asks where the index should live and builds the C# bridge for you:
 
 ```powershell
@@ -105,7 +107,7 @@ One shared instance for the whole team — the metadata index lives in Blob Stor
 
 [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fdynamics365ninja%2Fd365fo-mcp-server%2Frefs%2Fheads%2Fmain%2Finfrastructure%2Fazuredeploy.json)
 
-Deployment guide: [docs/SETUP_AZURE.md](docs/SETUP_AZURE.md) · CI/CD automation: [docs/PIPELINES.md](docs/PIPELINES.md)
+Deployment guide: [docs/SETUP_AZURE.md](docs/SETUP_AZURE.md) — includes CI/CD pipeline automation
 
 ---
 
@@ -114,11 +116,10 @@ Deployment guide: [docs/SETUP_AZURE.md](docs/SETUP_AZURE.md) · CI/CD automation
 | Getting started | Reference | Operations |
 |-----------------|-----------|------------|
 | [Quick Start](docs/QUICK_START.md) — connect or install | [All 26 tools](docs/MCP_TOOLS.md) | [Azure deployment](docs/SETUP_AZURE.md) |
-| [Setup scenarios A–F](docs/SETUP.md) | [`.mcp.json` reference](docs/MCP_CONFIG.md) | [DevOps pipelines](docs/PIPELINES.md) |
-| [Claude Code setup](docs/CLAUDE_CODE_SETUP.md) | [Architecture](docs/ARCHITECTURE.md) | [Testing](docs/TESTING.md) |
-| [Usage examples](docs/USAGE_EXAMPLES.md) — real tool chains | [C# Bridge](docs/BRIDGE.md) | [Custom / ISV models](docs/CUSTOM_EXTENSIONS.md) |
-| | [Workspace detection](docs/WORKSPACE_DETECTION.md) | [SQLite vs Bridge](docs/SQLITE_DEPENDENCY.md) |
-| | [Backlog](docs/BACKLOG.md) — deferred work & ideas | [Coverage](eval/COVERAGE.md) — what the badge counts |
+| [Setup scenarios A–F](docs/SETUP.md) | [`.mcp.json` reference](docs/MCP_CONFIG.md) | [DevOps pipelines](docs/SETUP_AZURE.md#azure-devops-pipelines) |
+| [Claude Code setup](docs/SETUP.md#claude-code-cli) | [Configuration](docs/CONFIGURATION.md) | [Testing](docs/TESTING.md) |
+| [Usage examples](docs/USAGE_EXAMPLES.md) — real tool chains | [Architecture](docs/ARCHITECTURE.md) | [Custom / ISV models](docs/CUSTOM_EXTENSIONS.md) |
+| | | [Coverage](eval/COVERAGE.md) — what the badge counts |
 
 ## License
 

package/bridge/D365MetadataBridge/NuGet.config

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  D365FO dev VMs frequently ship a machine-wide NuGet.config that only lists
+  offline/VS package sources (e.g. "C:\Program Files\dotnet\library-packs" and
+  "Microsoft Visual Studio Offline Packages") — nuget.org isn't in it, so
+  restoring System.Text.Json / Microsoft.NETFramework.ReferenceAssemblies.net48
+  fails with NU1101 even though the machine has internet access.
+
+  This file has no <clear/>, so NuGet MERGES it with whatever the machine/user
+  config already defines — it only adds nuget.org, it never removes the
+  offline sources the D365FO tooling relies on. See docs/SETUP.md
+  "Restrictive NuGet feed".
+-->
+<configuration>
+  <packageSources>
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+  </packageSources>
+</configuration>

package/dist/cli/commands/connect.js

@@ -104,7 +104,7 @@ function serverEntry(url, apiKey, alwaysLoad) {
         url,
         ...(apiKey ? { headers: { 'X-Api-Key': apiKey } } : {}),
         // Without it Claude Code defers the tools and may answer X++ questions from
-        // built-in search instead (docs/CLAUDE_CODE_SETUP.md).
+        // built-in search instead (docs/SETUP.md § Claude Code CLI).
         ...(alwaysLoad ? { alwaysLoad: true } : {}),
     };
 }

package/dist/cli/commands/setup.js

@@ -153,7 +153,7 @@ function openRootStore() {
 }
 /** D365FO environment: type, then the paths/models that type needs. */
 async function configureEnvironment(store, scenario) {
-    p.log.step('D365FO environment — where the X++ packages live');
+    p.log.step('D365FO environment');
     let envType;
     if (scenario === 'ude') {
         envType = 'ude';
@@ -193,29 +193,90 @@ async function configureEnvironment(store, scenario) {
 }
 /** Model/paths the write tools target. Auto-detection covers what is left empty. */
 async function configureWorkspace(store, scenario) {
-    p.log.step('Workspace — which model the server writes to (leave empty to auto-detect from the IDE)');
+    p.log.step('Workspace target');
     await askSetting(store, setting('workspace.modelName'));
     await askSetting(store, setting('workspace.path'), { required: scenario === 'hybrid' || scenario === 'ude' });
     await askSetting(store, setting('workspace.solutionsPath'));
 }
 async function configureNaming(store) {
-    p.log.step('Naming convention — applied to every generated object');
+    p.log.step('Naming');
     await askSettings(store, settingsInSection('naming', 'basic'));
 }
 async function configureIndex(store) {
-    p.log.step('Metadata index — what gets extracted and how long the build takes');
+    p.log.step('Metadata index');
     await askSetting(store, setting('index.extractMode'));
     const includeLabels = await askSetting(store, setting('index.includeLabels'));
     if (includeLabels)
         await askSetting(store, setting('index.labelLanguages'));
 }
 async function maybeBuildIndex() {
-    if (!await askConfirm('Build the metadata index now? (custom models: minutes; full index: 1–2 h)')) {
+    if (!await askConfirm('Build the metadata index now? (custom: minutes, full: 1-2 h)')) {
         p.log.warn('Skipped — run `d365fo-mcp index` before first use.');
         return true;
     }
     return rebuildIndex(rootTarget());
 }
+function writeCopilotSetupReadme(stageDir, includeLocalMcpCopy) {
+    const readmePath = resolve(stageDir, 'README.md');
+    const lines = [
+        '# VS setup quick guide',
+        '',
+        'This folder is generated by `d365fo-mcp setup` to simplify Visual Studio onboarding.',
+        '',
+        '1. Copy .mcp.json',
+        '   - Recommended (all solutions): %USERPROFILE%\\.mcp.json',
+        '   - Per solution: place .mcp.json next to your .sln file',
+        includeLocalMcpCopy
+            ? '   - Local copy prepared here: .mcp.json'
+            : `   - Local copy path: ${paths.mcpSuggestion}`,
+        '',
+        '2. Copy .github/copilot-instructions.md',
+        '   - Destination: a parent folder of your solution directories',
+        '   - Why: provides mandatory D365FO tool-routing and safety rules for Copilot',
+        '',
+        '3. Restart Visual Studio after copying files.',
+    ];
+    fs.writeFileSync(readmePath, lines.join('\n') + '\n', 'utf8');
+}
+async function maybePrepareCopilotInstructions(store) {
+    const source = resolve(repoRoot, '.github', 'copilot-instructions.md');
+    if (!fs.existsSync(source)) {
+        p.log.warn('Cannot find .github\\copilot-instructions.md in the package; skipping copy helper.');
+        return {};
+    }
+    const wantsDirectCopy = await askConfirm('Create/copy .github/copilot-instructions.md into the solutions folder now?', true);
+    const solutionsPath = String(readSetting(store, setting('workspace.solutionsPath')) ?? '').trim();
+    if (wantsDirectCopy && solutionsPath) {
+        const targetDir = resolve(solutionsPath, '.github');
+        fs.mkdirSync(targetDir, { recursive: true });
+        fs.copyFileSync(source, resolve(targetDir, 'copilot-instructions.md'));
+        p.log.success(`Prepared: ${resolve(targetDir, 'copilot-instructions.md')}`);
+        return {};
+    }
+    const stageDir = resolve(dataRoot(), 'copilot-setup');
+    const stageGitHubDir = resolve(stageDir, '.github');
+    fs.mkdirSync(stageGitHubDir, { recursive: true });
+    fs.copyFileSync(source, resolve(stageGitHubDir, 'copilot-instructions.md'));
+    writeCopilotSetupReadme(stageDir, false);
+    if (wantsDirectCopy && !solutionsPath) {
+        p.log.warn('Solutions folder is empty, so files were prepared in the local staging folder instead.');
+    }
+    else {
+        p.log.info('Copy was skipped; files were prepared in a local staging folder for later use.');
+    }
+    p.log.info(`Staging folder: ${stageDir}`);
+    return { stagingDir: stageDir };
+}
+function finalizeStagedCopilotFiles(plan) {
+    if (!plan.stagingDir)
+        return;
+    const localMcp = paths.mcpSuggestion;
+    if (fs.existsSync(localMcp)) {
+        fs.copyFileSync(localMcp, resolve(plan.stagingDir, '.mcp.json'));
+        writeCopilotSetupReadme(plan.stagingDir, true);
+        p.log.success(`Prepared: ${resolve(plan.stagingDir, '.mcp.json')}`);
+    }
+}
 export function savedNote(store) {
     const rel = relative(dataRoot(), store.configPath) || store.configPath;
     const lines = [`Settings written to ${rel}`];
@@ -237,12 +298,12 @@ export async function setupCommand() {
         p.log.warn(`This is d365fo-mcp ${release.current}; ${release.latest} is published.\n` +
             `   Updating first avoids rebuilding the index twice: ${installMode === 'npm' ? 'npm install -g d365fo-mcp@latest' : 'd365fo-mcp update'}`);
     }
-    const scenario = await askSelect('How will this developer machine use the MCP server? (docs/SETUP.md)', [
-        { value: 'local-stdio', label: 'E — Local stdio ★', hint: 'single developer on a D365FO VM; VS launches the server' },
-        { value: 'hybrid', label: 'B — Hybrid ★', hint: 'Azure serves the shared index; local companion handles writes' },
-        { value: 'local-http', label: 'C — Local HTTP', hint: 'several clients on this machine share one server on a port' },
-        { value: 'ude', label: 'D — UDE', hint: 'Unified Developer Experience / Power Platform Tools' },
-        { value: 'multi', label: 'F — Multi-instance', hint: 'several D365FO clients on one machine, one instance each' },
+    const scenario = await askSelect('How will this machine use MCP? (docs/SETUP.md)', [
+        { value: 'local-stdio', label: 'E — Local stdio ★', hint: 'Single developer VM. Visual Studio launches MCP.' },
+        { value: 'hybrid', label: 'B — Hybrid ★', hint: 'Azure serves search. Local companion handles writes.' },
+        { value: 'local-http', label: 'C — Local HTTP', hint: 'Multiple local clients share one MCP HTTP port.' },
+        { value: 'ude', label: 'D — UDE', hint: 'Unified Developer Experience setup.' },
+        { value: 'multi', label: 'F — Multi-instance', hint: 'One machine, multiple isolated D365FO instances.' },
     ]);
     // Before anything is written: every path below hangs off the data directory.
     await configureDataRoot();
@@ -271,6 +332,7 @@ export async function setupCommand() {
         const url = await askText({ message: 'Azure server URL', placeholder: 'https://your-server.azurewebsites.net/mcp/', required: true });
         await configureEnvironment(store, scenario);
         await configureWorkspace(store, scenario);
+        const copilotPlan = await maybePrepareCopilotInstructions(store);
         await configureNaming(store);
         await askSecrets(store, ['behavior']);
         await askAdvanced(store, ['environment', 'workspace', 'naming', 'bridge', 'behavior', 'server']);
@@ -280,6 +342,7 @@ export async function setupCommand() {
             'd365fo-azure': { url },
             'd365fo-local': stdioServer(store),
         });
+        finalizeStagedCopilotFiles(copilotPlan);
         placementNote();
         p.outro('Hybrid setup complete — no local index needed (Azure serves the search).');
         return;
@@ -288,6 +351,7 @@ export async function setupCommand() {
     writeSetting(store, setting('server.mode'), 'full');
     await configureEnvironment(store, scenario);
     await configureWorkspace(store, scenario);
+    const copilotPlan = await maybePrepareCopilotInstructions(store);
     await configureNaming(store);
     await configureIndex(store);
     let port = Number(readSetting(store, setting('server.port')) ?? 8080);
@@ -305,6 +369,7 @@ export async function setupCommand() {
     }
     if (scenario === 'local-http') {
         mcpJsonNote({ 'd365fo-mcp-tools': { url: `http://localhost:${port}/mcp/` } });
+        finalizeStagedCopilotFiles(copilotPlan);
         placementNote();
         p.outro('Done. Start the server with: d365fo-mcp start');
         return;
@@ -312,6 +377,7 @@ export async function setupCommand() {
     // D / E — the IDE spawns dist/index.js itself and is pointed at the config
     // file; every other setting comes from there.
     mcpJsonNote({ 'd365fo-mcp-tools': stdioServer(store) });
+    finalizeStagedCopilotFiles(copilotPlan);
     placementNote();
     p.outro('Done. VS spawns the server automatically — no manual start needed.');
 }

package/dist/cli/context.d.ts

@@ -60,7 +60,7 @@ export declare const paths: {
     readonly instancesDir: string;
     readonly defaultDb: string;
     readonly defaultLabelsDb: string;
-    /** Where the wizard drops the ready-to-paste .mcp.json block. */
+    /** Where setup writes the ready-to-copy .mcp.json file. */
     readonly mcpSuggestion: string;
     /**
      * Where `dotnet build` puts the bridge.

package/dist/cli/context.js

@@ -120,8 +120,8 @@ export const paths = {
     get instancesDir() { return resolve(currentDataRoot, 'instances'); },
     get defaultDb() { return resolve(currentDataRoot, 'data', 'xpp-metadata.db'); },
     get defaultLabelsDb() { return resolve(currentDataRoot, 'data', 'xpp-metadata-labels.db'); },
-    /** Where the wizard drops the ready-to-paste .mcp.json block. */
-    get mcpSuggestion() { return resolve(currentDataRoot, 'mcp-config-suggestion.json'); },
+    /** Where setup writes the ready-to-copy .mcp.json file. */
+    get mcpSuggestion() { return resolve(currentDataRoot, '.mcp.json'); },
     /**
      * Where `dotnet build` puts the bridge.
      *

package/dist/cli/mcpJson.js

@@ -28,20 +28,20 @@ export function stdioServer(store, extraEnv) {
 export function mcpJsonNote(servers, title = '.mcp.json') {
     const json = JSON.stringify({ servers }, null, 2);
     p.note(json, title);
-    // Also write the raw JSON to a file so it can be copied without terminal box
-    // characters. It goes to the data directory, not the package: an npm install
-    // replaces the package on every update, and may not even be writable.
+    // Also write the JSON to a file so it can be copied as-is into VS.
+    // It goes to the data directory, not the package: npm updates replace the
+    // package directory and may not be writable.
     const outPath = paths.mcpSuggestion;
     fs.mkdirSync(dirname(outPath), { recursive: true });
     fs.writeFileSync(outPath, json + '\n', 'utf8');
-    p.log.info(`Raw JSON written to: ${outPath}`);
+    p.log.info(`.mcp.json prepared at: ${outPath}`);
 }
 export function placementNote() {
-    p.note('Place the block above in:\n' +
+    p.note('Copy the generated .mcp.json to one of these locations:\n' +
         '  %USERPROFILE%\\.mcp.json          — all solutions (recommended)\n' +
         '  next to the .sln                 — that solution only\n\n' +
-        'Also copy .github\\copilot-instructions.md into a parent of your\n' +
-        'solution folders (mandatory for Copilot — see docs/SETUP.md).\n' +
-        'Restart Visual Studio after editing .mcp.json.', 'Where it goes');
+        'Make sure .github\\copilot-instructions.md exists in a parent folder\n' +
+        'of your solutions (mandatory for Copilot — see docs/SETUP.md).\n' +
+        'Restart Visual Studio after copying .mcp.json.', 'Where it goes');
 }
 //# sourceMappingURL=mcpJson.js.map

package/dist/cli/settingsPrompt.js

@@ -14,7 +14,19 @@ import { askConfirm, askSelect, askText, ensure, p } from './ui.js';
 /** "Label\n  description" — the uniform question layout. */
 function message(setting, suffix) {
     const head = suffix ? `${setting.label} ${suffix}` : setting.label;
-    return `${head}\n${c.dim(wrapText(setting.description, 76, '  '))}`;
+    if (setting.path === 'environment.type')
+        return head;
+    return `${head}\n${c.dim(compactDescription(setting.description))}`;
+}
+function compactDescription(text) {
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    const primary = normalized.split(/(?<=[.!?])\s+/)[0] ?? normalized;
+    const wrapped = wrapText(primary, 76, '  ').split('\n');
+    if (wrapped.length <= 2)
+        return wrapped.join('\n');
+    const lines = wrapped.slice(0, 2);
+    lines[1] = `${lines[1].replace(/\.*\s*$/, '')}...`;
+    return lines.join('\n');
 }
 function wrapText(text, width, indent) {
     const words = text.split(/\s+/);

package/dist/config/settings.js

@@ -80,7 +80,7 @@ export const SETTINGS = [
         tier: 'basic',
         type: 'path',
         label: 'Packages root (PackagesLocalDirectory)',
-        description: 'Root folder of all D365FO packages — the read-only reference the index is built from. ' +
+        description: 'AOT packages folder (PackagesLocalDirectory) used as the read-only source for indexing. ' +
             'Machine-wide on a traditional VM; UDE resolves it from the XPP config instead.',
         placeholder: 'C:\\AOSService\\PackagesLocalDirectory',
     },

package/dist/metadata/xmlParser.d.ts

@@ -48,8 +48,8 @@ export interface XppClassExtensionRecord extends XppExtensionMembers {
  */
 export declare function buildClassExtensionRecord(classInfo: XppClassInfo, model: string): XppClassExtensionRecord | null;
 export declare class XppMetadataParser {
-    private parser;
     private enhancedParser;
+    private get parser();
     constructor();
     /**
      * Parse an X++ class file (AxClass XML)

package/dist/metadata/xmlParser.js

@@ -57,14 +57,15 @@ export function buildClassExtensionRecord(classInfo, model) {
     };
 }
 export class XppMetadataParser {
-    parser;
     enhancedParser;
-    constructor() {
-        this.parser = new Parser({
+    get parser() {
+        return new Parser({
             explicitArray: false,
             mergeAttrs: true,
             trim: true,
         });
+    }
+    constructor() {
         this.enhancedParser = new EnhancedXppParser();
     }
     /**

package/dist/scripts/build-database.js

@@ -31,7 +31,7 @@ var SETTINGS = [
     tier: "basic",
     type: "path",
     label: "Packages root (PackagesLocalDirectory)",
-    description: "Root folder of all D365FO packages \u2014 the read-only reference the index is built from. Machine-wide on a traditional VM; UDE resolves it from the XPP config instead.",
+    description: "AOT packages folder (PackagesLocalDirectory) used as the read-only source for indexing. Machine-wide on a traditional VM; UDE resolves it from the XPP config instead.",
     placeholder: "C:\\AOSService\\PackagesLocalDirectory"
   },
   {

package/dist/scripts/build-fts.js

@@ -31,7 +31,7 @@ var SETTINGS = [
     tier: "basic",
     type: "path",
     label: "Packages root (PackagesLocalDirectory)",
-    description: "Root folder of all D365FO packages \u2014 the read-only reference the index is built from. Machine-wide on a traditional VM; UDE resolves it from the XPP config instead.",
+    description: "AOT packages folder (PackagesLocalDirectory) used as the read-only source for indexing. Machine-wide on a traditional VM; UDE resolves it from the XPP config instead.",
     placeholder: "C:\\AOSService\\PackagesLocalDirectory"
   },
   {