d365fo-mcp 1.0.0 → 1.2.0

package/README.md

@@ -4,12 +4,13 @@
 
 **26 AI tools that know every X++ class, table, form, and EDT in your D365FO codebase**
 
+[![npm](https://img.shields.io/npm/v/d365fo-mcp.svg?logo=npm&color=cb3837)](https://www.npmjs.com/package/d365fo-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D24.0.0-brightgreen.svg)](https://nodejs.org/)
 [![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-79.1%25-yellow.svg)](eval/COVERAGE.md) [![Total coverage](https://img.shields.io/badge/total_coverage-48.1%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-59.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*
@@ -18,7 +19,7 @@
 [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_d365fo-24bfa5?style=flat-square&logo=githubcopilot&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=d365fo&quality=insiders&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22d365fo_server_url%22%2C%22description%22%3A%22D365FO%20MCP%20server%20URL%20(e.g.%20https%3A%2F%2Fyour-server.azurewebsites.net%2Fmcp%2F)%22%7D%5D&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22%24%7Binput%3Ad365fo_server_url%7D%22%7D)
 [![Add to Cursor](https://img.shields.io/badge/Cursor-Add_d365fo-000000?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=d365fo&config=eyJ1cmwiOiJodHRwczovL3lvdXItc2VydmVyLmF6dXJld2Vic2l0ZXMubmV0L21jcC8ifQ%3D%3D)
 
-*One-click install connects to an already-deployed server — VS Code asks for the URL, Cursor installs a placeholder to edit. Visual Studio & Claude Code: see [Quick Start](#quick-start).*
+*These connect an editor to a server that is already deployed — see [Quick Start](#quick-start) if you still need to set one up.*
 
 </div>
 
@@ -73,109 +74,28 @@ Structural violations (wrong order, missing container, disallowed control) **blo
 
 ## Quick Start
 
-Pick your path:
-
-| Path | Who | Install effort |
-|------|-----|---------------|
-| **A — Azure client** | Team member, server already deployed | `.mcp.json` only — 2 minutes |
-| **B — Hybrid** (recommended for teams) | Azure search + local writes on your VM | Clone + build, no indexing |
-| **C/E — Local** | Single developer, everything on the VM | Clone + build + index (~15 min) |
-
-Full walkthrough with all scenarios: **[docs/QUICK_START.md](docs/QUICK_START.md)**
-
-### One-line install (recommended)
-
-Paste into PowerShell on the D365FO VM — the installer checks (and installs, if missing) Node.js and Git, clones the repository, runs `npm install`, and starts the interactive setup wizard:
+**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
 irm https://raw.githubusercontent.com/dynamics365ninja/d365fo-mcp-server/main/install.ps1 | iex
 ```
 
-Safe to re-run — an existing installation is updated instead of re-cloned. Configure via env vars when needed: `$env:D365FO_MCP_DIR` (install directory), `$env:D365FO_MCP_YES = '1'` (non-interactive), `$env:D365FO_MCP_NO_WIZARD = '1'` (skip the wizard).
-
-### Interactive setup
-
-Already cloned, or prefer to run the steps yourself? After `npm install`, the management CLI walks you through everything else — scenario selection, C# bridge build, configuration, index build — and prints the `.mcp.json` block to paste. Every answer is explained as it is asked and stored in `config/d365fo-mcp.json`; there is no `.env` to fill in (see **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)** for the full setting reference):
-
-```powershell
-git clone https://github.com/dynamics365ninja/d365fo-mcp-server.git K:\d365fo-mcp-server
-cd K:\d365fo-mcp-server
-npm install
-npm run setup        # first-time setup wizard
-npm run doctor       # health check — verifies Node, build, index, bridge
-```
-
-Day-to-day management runs through the same CLI (`npx d365fo-mcp` or `npm run cli --`): `start`, `update`, `index`, `config` (change one area of the settings without re-running the wizard), and `instance add/list/run/rebuild/upgrade` for multi-instance setups. Every command works non-interactively with arguments, or asks with predefined choices when run bare.
-
-### Manual setup
+Already have Node.js 24+? Then the one-liner has nothing to bootstrap and you can skip it:
 
 ```powershell
-# Local / hybrid install (on the D365FO VM)
-git clone https://github.com/dynamics365ninja/d365fo-mcp-server.git K:\d365fo-mcp-server
-cd K:\d365fo-mcp-server
-npm install
-cd bridge\D365MetadataBridge; dotnet build -c Release; cd ..\..   # C# bridge — required for writes
-npm run build
-
-# Local only — build the metadata index (skip for hybrid)
-npm run setup                     # writes config/d365fo-mcp.json (packages path, models, prefix…)
-npm run extract-metadata
-npm run build-database
+npm install -g d365fo-mcp
+d365fo-mcp setup
 ```
 
-> Prefer to write the configuration yourself? `config/d365fo-mcp.json` is plain JSON — every key, default and
-> matching environment variable is listed in [docs/CONFIGURATION.md](docs/CONFIGURATION.md). A pre-existing
-> `.env` keeps working and is imported by the wizard.
-
-### Connect GitHub Copilot
-
-1. Enable *MCP servers in Copilot* at [github.com/settings/copilot/features](https://github.com/settings/copilot/features)
-2. Visual Studio → **Tools → Options → GitHub → Copilot** → *Enable MCP server integration in agent mode*
-3. Create `%USERPROFILE%\.mcp.json`:
-
-```json
-{
-  "servers": {
-    "d365fo-azure": { "url": "https://your-server.azurewebsites.net/mcp/" },
-    "d365fo-local": {
-      "command": "node",
-      "args": ["K:\\d365fo-mcp-server\\dist\\index.js"],
-      "env": {
-        "MCP_SERVER_MODE": "write-only",
-        "D365FO_SOLUTIONS_PATH": "K:\\repos\\MySolution\\projects",
-        "D365FO_WORKSPACE_PATH": "K:\\AosService\\PackagesLocalDirectory\\YourPackage\\YourModel"
-      }
-    }
-  }
-}
-```
+Re-running either is safe. An installation made before the npm package existed is a git checkout, and both are left exactly where they are and updated in place.
 
-4. Copy the instruction files into a parent folder of your solutions (one copy covers everything beneath it):
+**Your team already runs a shared server?** Then you install nothing — point your editor at it:
 
 ```powershell
-Copy-Item -Path ".github" -Destination "C:\source\repos\" -Recurse
-```
-
-All options: **[docs/MCP_CONFIG.md](docs/MCP_CONFIG.md)**
-
-### Connect Claude Code
-
-```powershell
-claude mcp add-json --scope user d365fo-mcp-tools '{"type":"http","url":"https://your-server.azurewebsites.net/mcp/","alwaysLoad":true}'
-Copy-Item "K:\d365fo-mcp-server\.github\copilot-instructions.md" "C:\source\repos\CLAUDE.md"
-```
-
-Stdio variant and troubleshooting: **[docs/CLAUDE_CODE_SETUP.md](docs/CLAUDE_CODE_SETUP.md)**
-
-### Verify
-
-Open the AI chat (Copilot Agent Mode / Claude Code) and ask:
-
-```
-I'm tracing a posting issue — find every table (standard + ISV extensions) that carries the CustAccount field, so I can see where the value could get overwritten.
+npx d365fo-mcp connect https://your-server.azurewebsites.net
 ```
 
-A `search` tool call returning results from **your** metadata — including your ISV models, which no model's training data has seen — means you're connected.
+Both paths in full — prerequisites, editor configuration for every scenario, the required instruction file, and how to verify grounding actually works: **[docs/QUICK_START.md](docs/QUICK_START.md)**
 
 ---
 
@@ -193,7 +113,7 @@ Deployment guide: [docs/SETUP_AZURE.md](docs/SETUP_AZURE.md) · CI/CD automation
 
 | Getting started | Reference | Operations |
 |-----------------|-----------|------------|
-| [Quick Start](docs/QUICK_START.md) — 5 steps to running | [All 26 tools](docs/MCP_TOOLS.md) | [Azure deployment](docs/SETUP_AZURE.md) |
+| [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) |

package/bridge/D365MetadataBridge/D365MetadataBridge.csproj

@@ -0,0 +1,116 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net48</TargetFramework>
+    <LangVersion>12.0</LangVersion>
+    <Nullable>enable</Nullable>
+    <RootNamespace>D365MetadataBridge</RootNamespace>
+    <AssemblyName>D365MetadataBridge</AssemblyName>
+    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
+    <!-- Resolve transitive assembly version conflicts in D365FO bin (e.g. SCDP 7.0.0 vs 7.0.4) -->
+    <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
+    <GenerateBindingRedirectsOutputType>true</GenerateBindingRedirectsOutputType>
+    <!-- MSB3277: version conflict between Microsoft-shipped SCDP.dll (7.0.0) and
+         SCDPBundling.dll (depends on 7.0.4) in PackagesLocalDirectory\bin.
+         We don't control these DLLs and the bridge doesn't use SCDP at all — safe to suppress.
+         MSB3106: some D365FO versions ship MetaModel.Core with a version suffix in the filename
+         (e.g. Microsoft.Dynamics.Framework.Tools.MetaModel.Core.17.0.dll); the wildcard glob
+         picks it up automatically, so the explicit name reference is gone and this warning should
+         no longer appear — kept here as a safety net for edge-case environments. -->
+    <MSBuildWarningsAsMessages>MSB3277;MSB3106</MSBuildWarningsAsMessages>
+  </PropertyGroup>
+
+  <!--
+    D365FO bin directory — contains all Microsoft.Dynamics.*.dll assemblies.
+    Every D365FO development desktop has this directory available.
+
+    Traditional VM:  K:\AosService\PackagesLocalDirectory\bin
+    Cloud-hosted:    C:\AosService\PackagesLocalDirectory\bin
+    UDE (Unified Developer Experience): path from .mcp.json microsoftPackagesPath/bin
+
+    Override per-machine via:
+      dotnet build -p:D365BinPath="C:\path\to\bin"
+    or in a local Directory.Build.props (not committed to source control).
+  -->
+  <PropertyGroup>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('K:\AosService\PackagesLocalDirectory\bin')">K:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('C:\AosService\PackagesLocalDirectory\bin')">C:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+  </PropertyGroup>
+
+  <!-- NuGet packages -->
+  <ItemGroup>
+    <PackageReference Include="System.Text.Json" Version="8.0.5" />
+    <PackageReference Include="Microsoft.NETFramework.ReferenceAssemblies.net48" Version="1.0.3">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
+    </PackageReference>
+  </ItemGroup>
+
+  <!--
+    D365FO assemblies: auto-referenced from $(D365BinPath) via glob.
+    At runtime, Program.cs dynamically loads them via AppDomain.AssemblyResolve
+    from the - -packages-path argument, so Private=false (don't copy to output).
+  -->
+  <ItemGroup>
+    <Reference Include="Microsoft.CSharp" />
+  </ItemGroup>
+  <ItemGroup Condition="'$(D365BinPath)' != ''">
+    <Reference Include="$(D365BinPath)\Microsoft.Dynamics.*.dll">
+      <Private>false</Private>
+    </Reference>
+  </ItemGroup>
+
+  <!--
+    Record WHICH metamodel build we compiled against, so the bridge can warn at
+    startup when it is pointed at an environment shipping a different one.
+
+    This matters because every platform build stamps the SAME assembly version
+    (7.0.0.0) and differs only in FileVersion (e.g. 7.0.7690.155 vs 7.0.7996.33).
+    The CLR binder therefore cannot tell them apart, and the AssemblyResolve →
+    LoadFrom path in Program.cs does not enforce identity — a mismatched DLL
+    loads silently and only blows up later as MissingMethodException /
+    TypeLoadException at JIT time, far from the cause.  See issue #703.
+  -->
+  <Target Name="CaptureMetamodelBuildVersion"
+          BeforeTargets="BeforeCompile"
+          Inputs="$(D365BinPath)\Microsoft.Dynamics.AX.Metadata.dll"
+          Outputs="$(IntermediateOutputPath)BuildInfo.g.cs">
+    <PropertyGroup>
+      <_MetamodelDll>$(D365BinPath)\Microsoft.Dynamics.AX.Metadata.dll</_MetamodelDll>
+    </PropertyGroup>
+    <GetFileVersion FilePath="$(_MetamodelDll)" Condition="Exists('$(_MetamodelDll)')">
+      <Output TaskParameter="Version" PropertyName="_MetamodelFileVersion" />
+    </GetFileVersion>
+    <Message Importance="high"
+             Text="Bridge compiles against metamodel $(_MetamodelFileVersion) from $(D365BinPath)"
+             Condition="'$(_MetamodelFileVersion)' != ''" />
+    <Warning Text="D365BinPath '$(D365BinPath)' has no Microsoft.Dynamics.AX.Metadata.dll — the runtime version check will be disabled."
+             Condition="'$(_MetamodelFileVersion)' == ''" />
+    <WriteLinesToFile File="$(IntermediateOutputPath)BuildInfo.g.cs" Overwrite="true" WriteOnlyWhenDifferent="true"
+                      Lines="// &lt;auto-generated /&gt; Produced by the CaptureMetamodelBuildVersion target.;namespace D365MetadataBridge;{;    internal static class BuildInfo;    {;        /// &lt;summary&gt;FileVersion of the Microsoft.Dynamics.AX.Metadata.dll this build compiled against, or &quot;&quot; if unknown.&lt;/summary&gt;;        internal const string MetamodelFileVersion = &quot;$(_MetamodelFileVersion)&quot;%3B;        /// &lt;summary&gt;bin directory those reference assemblies came from, or &quot;&quot; if unknown.&lt;/summary&gt;;        internal const string MetamodelBinPath = @&quot;$(D365BinPath)&quot;%3B;    };}" />
+    <ItemGroup>
+      <Compile Include="$(IntermediateOutputPath)BuildInfo.g.cs" />
+      <FileWrites Include="$(IntermediateOutputPath)BuildInfo.g.cs" />
+    </ItemGroup>
+  </Target>
+
+  <!--
+    MSBuild has no built-in task for reading a file's FileVersion (GetAssemblyIdentity
+    returns the assembly version — 7.0.0.0 for every platform build, which is exactly
+    the value that cannot distinguish them).
+  -->
+  <UsingTask TaskName="GetFileVersion" TaskFactory="RoslynCodeTaskFactory"
+             AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll">
+    <ParameterGroup>
+      <FilePath ParameterType="System.String" Required="true" />
+      <Version ParameterType="System.String" Output="true" />
+    </ParameterGroup>
+    <Task>
+      <Code Type="Fragment" Language="cs">
+        Version = System.Diagnostics.FileVersionInfo.GetVersionInfo(FilePath).FileVersion ?? "";
+      </Code>
+    </Task>
+  </UsingTask>
+
+</Project>