d365fo-mcp 1.5.0 → 1.5.2

package/.github/copilot-instructions.md

@@ -0,0 +1,86 @@
+# D365 Finance & Operations X++ Development
+
+<!-- Thin pointer — full rules are delivered via the MCP `xpp_system_instructions` prompt.
+     This file provides only the minimum static context needed when the MCP server
+     is not yet connected or the prompt hasn't been loaded.
+     Serves Claude Code too: copy it to a parent of your solution folders as
+     CLAUDE.md (docs/SETUP.md § Claude Code CLI, Step 3). -->
+
+## Tool Priority
+
+This workspace contains a D365FO MCP server. **Always use the specialized MCP tools** for D365FO objects (`.xml`, `.xpp`, `.rnrproj`, `.label.txt`). Built-in file/search tools are fine for `.cs`, `.json`, `.yml`, `.md`, `.config` files.
+
+## Mandatory First Check
+
+Call `get_workspace_info()` before doing anything with D365FO objects.
+
+| Response | Action |
+|----------|--------|
+| Call fails | STOP. MCP server not connected. Ask user to start it. |
+| `⛔ CONFIGURATION PROBLEM` | STOP. Relay message. Wait for user. |
+| `✅ Configuration looks valid` | Note model name. Proceed. |
+
+## Terminal Prohibition
+
+PowerShell / any terminal command **WILL HANG** in VS 2022 / VS 2026 MCP integration. Never use `run_in_terminal` or generate scripts as a fallback when an MCP tool fails — STOP and report the error verbatim.
+
+## Core Tool Mapping
+
+| Action | Tool |
+|--------|------|
+| Plan an extension before changing code | `prepare(mode="change", goal, objectName, methodName?)` — returns signature, existing CoC wrappers, strategy + `groundingToken` |
+| Plan a new object before creating it | `prepare(mode="create", goal, objectName, objectType)` — returns collision check, naming, EDT/label hints + `groundingToken` |
+| Create a D365FO object | `d365fo_file(action="create")` (never `create_file`) |
+| Edit an existing object | `d365fo_file(action="modify")` (applies immediately — confirm in chat first) |
+| Revert the last write | `undo_last_modification` |
+| Search objects | `search` — multiple via `search(queries[])`, custom-only via `search(scope="extensions")` |
+| Read any object's metadata | `get_object_info(objectType, name, options?)` — objectType ∈ class/table/form/query/view/enum/edt/report/data-entity/menu-item/service/map/config-key/security-policy/macro. 2+ known names: `batch_get_info(objects[])` |
+| Method signature for CoC | `get_method(include="signature")` (already returned by `prepare(mode="change")`) |
+| Validate X++ before write | `validate_code(mode="syntax", code)` — offline BP check, <50 ms |
+| X++ rules & patterns | `get_knowledge(kind="knowledge", topic)` — select grammar, CoC, BP rules, SysOperation, workflow, … |
+| Create a NEW form | `object_patterns(domain="form", action="analyze", recommend={...})` → `object_patterns(domain="form", action="spec", pattern)` → `generate_object(mode="scaffold", objectType="form", cloneFrom=referenceForm, tableMapping={...})` → `object_patterns(domain="form", action="validate", xml)` |
+| Validate form XML against its pattern | `object_patterns(domain="form", action="validate", xml \| formName \| filePath)` — structural errors block form writes (FORM_PATTERN_ENFORCE) |
+| Resolve label / EDT / class refs | `validate_code(mode="references", code)` |
+| Build / BP / Sync | `build_d365fo_project` / `run_bp_check` / `trigger_db_sync` |
+| Error diagnosis | `get_knowledge(kind="error", errorText)` |
+
+## Key Rules
+
+### Workspace & model targeting
+
+1. **The target model comes from `.mcp.json`** — never infer it from search results or object names. The symbol database contains objects from all models (Microsoft + ISV + custom); the model on a search/`get_*_info` result is the source model, not where new files belong.
+
+### Writes & file editing
+
+2. **`d365fo_file` (action=create/modify) applies immediately** (no dry-run / preview). Describe the change in chat and wait for explicit user confirmation ("apply", "ok", "yes") before calling. Revert with `undo_last_modification` (or pass `createBackup=true` to keep a `.bak`).
+3. **Never** use `replace_string_in_file`, `edit_file`, `apply_patch`, or any built-in file-write tool on `.xml` or `.xpp` files — **not even as a fallback** when `d365fo_file(action="modify")` fails. These bypass `IMetadataProvider` and corrupt VS 2022's in-memory model. If `d365fo_file(action="modify")` errors, STOP and report the error verbatim.
+
+### Build automation
+
+4. Never run `build_d365fo_project()` automatically — only on explicit user request ("build", "compile", "check errors").
+
+### X++ correctness (BP-clean code)
+
+5. Never copy default parameter values into CoC wrapper signatures.
+6. Never use `today()` — use `DateTimeUtil::getToday(DateTimeUtil::getUserPreferredTimeZone())`.
+7. Never use hardcoded strings in `Info()` / `warning()` / `error()` — use `@Model:Label` references.
+8. Call `labels(action="search")` before `labels(action="create")` — reuse existing labels.
+
+### Extension naming
+
+9. Extension naming follows `EXTENSION_NAMING_STYLE` (see `get_workspace_info`):
+   - `prefix` (default) → class `{Target}{Prefix}_Extension`, element `{Target}.{Prefix}Extension`
+   - `model-name` → class `{Target}_{ModelName}_Extension`, element `{Target}.{ModelName}`
+
+   Pass the BASE object name to `d365fo_file(action="create")` and let the tool inject the token — don't hand-build the infix.
+
+### Reuse & diff safety
+
+10. **Reuse before creating** — `prepare(mode="change")` lists existing CoC wrappers and event handlers. If an extension or handler class in the custom model already owns the target, add the new method there. Never create a parallel feature-named class (`<Target>_<Feature>_Extension`, `<Form>_<Feature>_EH`) unless the user explicitly asks for a separate class. The suffix comes from `EXTENSION_NAMING_STYLE` / existing artifacts — never from feature, ticket, or customer names; if it cannot be derived, ask.
+11. **The post-write diff must be additive or narrowly targeted** — verify via `review_workspace_changes` (or re-read with `get_*_info`) that no unrelated XML nodes (`<DataSources>`, `<Controls>`, methods, pattern metadata) disappeared. If they did, the edit failed: `undo_last_modification`.
+12. **An example form named by the user is a pattern contract** — keep its pattern family and required scaffolding (datasources, ActionPane/Tab/grid/QuickFilter); missing pattern elements are a failed generation even if the XML is well-formed.
+
+## Full Instructions
+
+The complete X++ rules, query grammar, CoC authoring rules, and workflow details are delivered via the MCP prompt `xpp_system_instructions`. If that prompt is not loaded, request it or consult [src/prompts/systemInstructions.ts](../src/prompts/systemInstructions.ts) directly.
+

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/instance.js

@@ -8,6 +8,7 @@ import * as fs from 'node:fs';
 import { resolve } from 'node:path';
 import { settingByPath, settingsInSection } from '../../config/settings.js';
 import { pinBridgeExe } from '../bridgePath.js';
+import { finalizeStagedCopilotFiles, maybePrepareCopilotInstructions } from '../copilotFiles.js';
 import { createInstance, getInstance, listInstances, normalizeInstanceLayout, suggestPort } from '../instances.js';
 import { mcpJsonNote, placementNote, stdioServer } from '../mcpJson.js';
 import { selectXppConfig } from './config.js';
@@ -98,17 +99,23 @@ export async function instanceAddCommand(name, portArg) {
     p.log.step('Workspace and naming');
     await askSetting(store, settingByPath('workspace.modelName'));
     await askSetting(store, settingByPath('workspace.path'));
+    await askSetting(store, settingByPath('workspace.solutionsPath'));
     await askSettings(store, settingsInSection('naming', 'basic'));
     p.log.step('Metadata index');
     await askSettings(store, settingsInSection('index', 'basic'));
     await askAdvanced(store, ['environment', 'workspace', 'index', 'server', 'bridge', 'behavior']);
     saveStore(store);
+    // Copilot needs the instructions file just as much as it needs .mcp.json,
+    // and an instance is somebody's only setup run — asking here is the only
+    // chance scenario F gets.
+    const copilotPlan = await maybePrepareCopilotInstructions(String(readSetting(store, settingByPath('workspace.solutionsPath')) ?? ''));
     // Both ways to reach this instance: the IDE spawning it over stdio with its
     // own config, or an HTTP client on the port it was given.
     mcpJsonNote({
         [`d365fo-${instanceName}`]: stdioServer(store),
         [`d365fo-${instanceName}-http`]: { url: `http://localhost:${port}/mcp/` },
     }, `.mcp.json — keep the stdio entry OR the http one, not both`);
+    finalizeStagedCopilotFiles(copilotPlan);
     placementNote();
     p.note(`Config: ${store.configPath}\n\n` +
         `1. Build the index:  d365fo-mcp instance rebuild ${instanceName}\n` +

package/dist/cli/commands/setup.js

@@ -15,6 +15,7 @@ import { DOTNET_MISSING, dataRoot, installMode, isWindows, paths, repoRoot, setD
 import { settingByPath, settingsInSection } from '../../config/settings.js';
 import { commandExists, runExe, runShell } from '../exec.js';
 import { pinBridgeExe } from '../bridgePath.js';
+import { finalizeStagedCopilotFiles, maybePrepareCopilotInstructions } from '../copilotFiles.js';
 import { mcpJsonNote, placementNote, stdioServer } from '../mcpJson.js';
 import { checkRelease } from '../npmRegistry.js';
 import { askAdvanced, askSecrets, askSetting, askSettings } from '../settingsPrompt.js';
@@ -198,6 +199,10 @@ async function configureWorkspace(store, scenario) {
     await askSetting(store, setting('workspace.path'), { required: scenario === 'hybrid' || scenario === 'ude' });
     await askSetting(store, setting('workspace.solutionsPath'));
 }
+/** Where the user keeps the .sln folders — the copy target for the client files. */
+function solutionsPath(store) {
+    return String(readSetting(store, setting('workspace.solutionsPath')) ?? '');
+}
 async function configureNaming(store) {
     p.log.step('Naming');
     await askSettings(store, settingsInSection('naming', 'basic'));
@@ -216,67 +221,6 @@ async function maybeBuildIndex() {
     }
     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}`];
@@ -332,7 +276,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);
+        const copilotPlan = await maybePrepareCopilotInstructions(solutionsPath(store));
         await configureNaming(store);
         await askSecrets(store, ['behavior']);
         await askAdvanced(store, ['environment', 'workspace', 'naming', 'bridge', 'behavior', 'server']);
@@ -351,7 +295,7 @@ export async function setupCommand() {
     writeSetting(store, setting('server.mode'), 'full');
     await configureEnvironment(store, scenario);
     await configureWorkspace(store, scenario);
-    const copilotPlan = await maybePrepareCopilotInstructions(store);
+    const copilotPlan = await maybePrepareCopilotInstructions(solutionsPath(store));
     await configureNaming(store);
     await configureIndex(store);
     let port = Number(readSetting(store, setting('server.port')) ?? 8080);

package/dist/cli/copilotFiles.d.ts

@@ -0,0 +1,15 @@
+export type CopilotFilePlan = {
+    stagingDir?: string;
+};
+/**
+ * Offer to place copilot-instructions.md, falling back to a staging folder.
+ *
+ * `solutionsPath` is what the user gave for workspace.solutionsPath; when it
+ * is empty there is nowhere to copy to, so the files are staged instead and
+ * the returned plan tells {@link finalizeStagedCopilotFiles} to complete it
+ * once the .mcp.json exists.
+ */
+export declare function maybePrepareCopilotInstructions(solutionsPath: string): Promise<CopilotFilePlan>;
+/** Add the generated .mcp.json to the staging folder — call after mcpJsonNote(). */
+export declare function finalizeStagedCopilotFiles(plan: CopilotFilePlan): void;
+//# sourceMappingURL=copilotFiles.d.ts.map

package/dist/cli/copilotFiles.js

@@ -0,0 +1,96 @@
+/**
+ * The `.github\copilot-instructions.md` half of client setup.
+ *
+ * `.mcp.json` only tells the IDE how to *start* the server; without the
+ * instructions file in a parent of the solution folder Copilot keeps using its
+ * built-in file tools and edits X++ behind the metadata provider's back. Both
+ * files therefore have to be placed for a working install, so the wizards
+ * offer to put this one down as well — either straight into the solutions
+ * folder, or, when that is unknown, into a staging folder next to the
+ * generated .mcp.json with a README naming the two destinations.
+ *
+ * Shared by `setup` (scenarios B–E) and `instance add` (scenario F), which
+ * both end on the same two-file placement step.
+ */
+import * as fs from 'node:fs';
+import { resolve } from 'node:path';
+import { dataRoot, paths, repoRoot } from './context.js';
+import { askConfirm, p } from './ui.js';
+/** The copy shipped with this installation — package root in both install modes. */
+const copilotSource = () => resolve(repoRoot, '.github', 'copilot-instructions.md');
+function writeCopilotSetupReadme(targetDir, opts) {
+    const readmePath = resolve(targetDir, 'README.md');
+    const lines = [
+        '# VS setup quick guide',
+        '',
+        'This file 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',
+        opts.includeLocalMcpCopy
+            ? '   - Local copy prepared here: .mcp.json'
+            : `   - Local copy path: ${paths.mcpSuggestion}`,
+        '',
+        '2. Copy .github/copilot-instructions.md',
+        opts.copilotAlreadyPlaced
+            ? '   - Already placed here: .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');
+}
+/**
+ * Offer to place copilot-instructions.md, falling back to a staging folder.
+ *
+ * `solutionsPath` is what the user gave for workspace.solutionsPath; when it
+ * is empty there is nowhere to copy to, so the files are staged instead and
+ * the returned plan tells {@link finalizeStagedCopilotFiles} to complete it
+ * once the .mcp.json exists.
+ */
+export async function maybePrepareCopilotInstructions(solutionsPath) {
+    const source = copilotSource();
+    if (!fs.existsSync(source)) {
+        p.log.warn('Cannot find copilot-instructions.md in this installation; skipping copy helper.\n' +
+            `   Looked for: ${source}`);
+        return {};
+    }
+    const wantsDirectCopy = await askConfirm('Create/copy .github/copilot-instructions.md into the solutions folder now?', true);
+    const target = solutionsPath.trim();
+    if (wantsDirectCopy && target) {
+        const targetDir = resolve(target, '.github');
+        fs.mkdirSync(targetDir, { recursive: true });
+        fs.copyFileSync(source, resolve(targetDir, 'copilot-instructions.md'));
+        writeCopilotSetupReadme(target, { includeLocalMcpCopy: false, copilotAlreadyPlaced: true });
+        p.log.success(`Prepared: ${resolve(targetDir, 'copilot-instructions.md')}`);
+        p.log.success(`Prepared: ${resolve(target, 'README.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, { includeLocalMcpCopy: false, copilotAlreadyPlaced: false });
+    if (wantsDirectCopy && !target) {
+        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 };
+}
+/** Add the generated .mcp.json to the staging folder — call after mcpJsonNote(). */
+export 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, { includeLocalMcpCopy: true, copilotAlreadyPlaced: false });
+        p.log.success(`Prepared: ${resolve(plan.stagingDir, '.mcp.json')}`);
+    }
+}
+//# sourceMappingURL=copilotFiles.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "d365fo-mcp",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "MCP Server for X++ Code Completion in D365 Finance & Operations",
   "type": "module",
   "main": "dist/index.js",
@@ -11,6 +11,7 @@
     "dist",
     "!dist/**/*.map",
     "!dist/eval/**",
+    ".github/copilot-instructions.md",
     "bridge/D365MetadataBridge",
     "!bridge/D365MetadataBridge/bin/**",
     "!bridge/D365MetadataBridge/obj/**"