feat!: proxy Microsoft's almcp, narrow ALCops MCP to code fixes, require BC DevTools 18.0

[Arthurvdv]

Summary

Reuse Microsoft's almcp for everything it already does, and narrow ALCops MCP to the two things it doesn't do at all.

almcp has no code-fix capability — its LSP mode explicitly advertises CodeActionProvider = false, and it exposes no MCP tool for it — and no way to enumerate rules. Everything else (compiling, diagnostics, symbols, publishing, tests, translations, object IDs) it already does well. So our compile/diagnostics path, our bundled analyzers, and our four-strategy DevTools resolution chain were duplicated infrastructure maintained against a proprietary SDK that changes shape between majors.

This PR started as the proxy (dynamic tool registration, still the core), then finished the job — delete the duplication, bridge the project's own config into the child so both sides agree — and finally hardened the proxy after a review pass: one long-lived MCP session, non-blocking startup, and a clean stdio channel.

AI Client (Claude Code / Copilot / Codex / …)
└── ALCops MCP Server (single stdio entry point)
    ├── Native:  list_rules, get_fixes, apply_fix, apply_fix_all
    └── Proxied: al_compile, al_build, al_getdiagnostics, al_symbolsearch, al_publishapp, … (16 on 18.0.41)
        └── one McpClient ── streamable HTTP ──► almcp child (127.0.0.1:<free port>)

Breaking changes

• BC Development Tools 18.0 or later are required. The compile floor is 18.0.41.39415, the first stable release with a net10.0 payload (matching our own TFM); 17.x is dropped from the compatibility matrix.
• analyze is removed. Use the proxied al_compile. Note it defaults to onlyErrors: true while nearly every ALCops rule is a warning — callers must pass onlyErrors: false. Documented rather than patched, because ForwardAsync stays a generic passthrough with no per-tool argument rewriting.
• Analyzers are no longer bundled. They come solely from the project's al.codeAnalyzers (plus AL-Go rulesetFile and the custom.ruleset.json / app.ruleset.json conventions).
• New prerequisite. dotnet tool install -g Microsoft.Dynamics.BusinessCentral.Development.Tools, or the AL VS Code extension. Nothing is downloaded at runtime any more; the server fails fast with the install command instead of starting degraded.
• --almcp-path is gone, superseded by --devtools-path. almcp ships in the same directory as the DevTools DLLs, so a separate override would reintroduce exactly the version skew this change eliminates.

Closes #10 structurally

Bundling pinned ALCops.*Cop.dll beside whatever Nav.CodeAnalysis the user happened to install is what produced the AD0001 / MissingMethodException failures — it was the cause, not a mitigation. Cops and compiler now both come from the user's own toolchain, so we cannot mismatch them. The same co-location means our in-process CodeFixRunner loads the identical Nav.CodeAnalysis the child almcp uses.

What changed

Build — a plain PackageReference to the DevTools package is impossible: as of 17.0 it dropped the Dependency package type and the lib/ folder, and NuGet rejects referencing a DotnetTool package. PackageDownload restores it without referencing it, giving the three <Reference> items a stable HintPath into tools/<tfm>/any/. src uses Private=false so the proprietary DLLs never reach the package (the redistribution guard ExcludeBcDevToolsFromPublish used to provide); tests uses Private=true because the CI matrix hot-swaps them. CI stops hand-rolling curl + unzip and just passes -p:BcDevToolsVersion. The 18.x payload ships its own ModelContextProtocol.Core 1.0.0 beside the referenced DLLs, which MSBuild's dependency walk flags (MSB3277) against our 0.9.0-preview.2; suppressed with a why-comment, since we never reference the only consumer (Nav.Deployment) and our copy wins at runtime.

One locator — BcToolsLocator (~200 lines) replaces BcDevToolsBootstrap, DevToolsLocator, NuGetDevToolsDownloader, AlMcpLocator and AlExtensionLocator (~370). Probe order: --devtools-path → BCDEVELOPMENTTOOLSPATH → dotnet tool store → AL extension bin/ → hard error, each step logged.

Startup config bridge — almcp in MCP mode never reads .vscode/settings.json (its WorkspaceSettingsApplier is LSP-only) and has no per-call analyzer, ruleset or package-cache parameter. Without a bridge the child starts with zero analyzers and al_compile silently disagrees with our fix tools about what is suppressed. WorkspaceStartupResolver discovers projects exactly the way almcp's own LSP mode does, then passes --projects / --codeanalyzers / --rulesetpath / --packagecachepath at launch. --projects entries get the same treatment as the working directory (a workspace root expands to the projects beneath it; entries with none are ignored with a warning). User-supplied args always win. ProjectLoader reads the same al.packageCachePath for the in-process compilation, so a multi-app repo with one shared symbol cache works on both sides.

Proxy hardening (from the review pass):

• One MCP session per child. Every forwarded call used to build a fresh McpClient — initialize, initialized, tools/call, DELETE: four round-trips per call. The client is now created once after the child is ready and reused for discovery and every forward. almcp's HTTP transport evicts idle sessions (default 2 h) with a 404, which the server never dispatched, so that one case is retried once on a fresh session; any other transport failure drops the cached client and surfaces the error unchanged.
• Startup no longer blocks the stdio server. AlMcpProxyStartup awaited the child launch, the 30 s readiness poll and tool discovery inside IHostedService.StartAsync, ahead of the SDK's stdio hosted service — so a slow or broken almcp blocked even initialize. It now starts in the background; initialize answers in under a second. tools/list waits up to 10 s for the child so hosts that list once still get the full set; past that it answers with the native tools and arms a one-shot notifications/tools/list_changed (we already advertise listChanged). Early al_* calls wait for readiness instead of failing.
• Clean JSON-RPC channel. In HTTP mode almcp writes its banner, Port: N and project-load progress to stdout; the proxy redirected only stderr, so the child inherited ours and 17 non-JSON lines landed in the middle of the MCP stream. Both streams are now captured and logged at Debug.
• Port handling. FindFreePort has to release the port before almcp can bind it; if another process grabs it in between, the child exits and startup retries on a fresh port (up to three attempts). Connections go to 127.0.0.1 — the family the port was reserved on — instead of resolving localhost per connect.

Deleted — AnalyzeTool, DiagnosticsRunner, DiagnosticResult, AnalyzerRegistry, and the five resolution/locator services above.

Live bugs found while verifying

• The proxy had never actually connected. It posted to http://localhost:<port>/mcp/, but almcp calls MapMcp() with no pattern — its endpoint is the server root, and /mcp/ 404s. The readiness probe accepted any response including that 404, so startup reported success and the handshake failed afterwards. Endpoint corrected; readiness now rejects 404.
• Analyzer dependencies must travel with their analyzer. almcp resolves analyzer dependencies only among the paths it is handed and never probes the analyzer's own directory. Passing just the cop DLLs turned every rule into AD0001 FileNotFoundException — including Microsoft's own CodeCop, which needs its sibling Analyzers.Common.dll. Dependencies are now read from assembly metadata and included.
• almcp's stdout was our stdout (see above) — invisible to lenient clients, fatal to strict ones.

Also fixed: ParseProxyOptions shared one i + 1 < args.Length guard across every passthrough flag and unconditionally consumed the next arg, so --nolog / --noauth either vanished (when last) or swallowed the following flag as their value. Split into almcp's three real arities, in a testable ProxyOptions.Parse. Three tool descriptions still claimed "ALCops analyzers are always included"; removed.

Version resilience

Unchanged — dynamic registration means our code never references an MS tool name or schema.

MS Change	Code change needed?
New tool added	No — auto-discovered
Tool renamed / params changed	No — schema from ListToolsAsync()
Tool removed	No — disappears from list
almcp dropped entirely	No — native tools still work

CLI args

• --devtools-path <dir> — use this DevTools directory instead of probing
• --projects <dir>[;<dir>] — override project discovery; a non-project directory is scanned for projects beneath it
• --no-proxy — native tools only; retained deliberately, for when the agent already registers almcp itself and would otherwise see the al_* tools twice
• almcp's own args (--codeanalyzers, --rulesetpath, --packagecachepath, --noauth, --nolog, …) are forwarded and override anything discovered from the project

Test plan

• dotnet build — 0 errors, 0 warnings (confirms PackageDownload + HintPath resolves the tools/net10.0/any/ layout)
• dotnet test — 68/68 pass. The code-fix guard assertions genuinely fire rather than passing vacuously; AlMcpProxyTests / AlMcpProxyStartupTests run against the real almcp from the restored DevTools package (session reuse across calls, reconnect-and-retry after an out-of-band DELETE of the session, non-blocking start, early call waits, stop during boot, list_changed armed once) — they self-skip where almcp is not runnable
• grep for every removed symbol — no live references
• Resolution: works from the dotnet tool store (18.0.41.39415); an unusable path exits naming the install command
• --no-proxy — tools list is exactly list_rules, get_fixes, apply_fix, apply_fix_all; analyze absent
• With proxy — stderr shows discovered projects, the settings.json read, and every resolved analyzer/ruleset/package-cache path; the 16 al_* tools appear
• Raw stdio session (initialize → tools/list → tools/call): initialize answered at ~0.9 s while almcp was still booting; tools/list returned 4 native + 16 al_*; stdout carried JSON only (0 non-JSON lines, previously 17). With the list budget forced to 0: native-only list, then exactly one tools/list_changed, then the full list. With a stub almcp.exe that dies: initialize/tools/list still instant, al_* call returns "not available" in 18 ms
• End-to-end: al_compile { onlyErrors: false } returns LC0020 alongside CodeCop's AA0215/0218/0225/0247/0248 and zero AD0001 → get_fixes returns a fix → apply_fix modifies the file on disk → recompile and LC0020 is gone
• A ruleset setting LC0020 to None hides it from both al_compile and get_fixes, other rules unaffected — the specific guarantee the startup bridge exists to provide
• dotnet pack — no Microsoft.Dynamics.Nav.*.dll, no ALCops.*Cop.dll in the nupkg

Notes for review

• ALCops.Analyzers moves to the test project rather than being deleted outright. The fixtures test LC0020/AC0012; with nothing bundled they would find zero diagnostics and pass vacuously. Test-only keeps the package clean (verified above) and means the tests now exercise the real production path — spec → ExternalAnalyzerLoader → AnalyzerAssemblyLoadContext — which is better coverage than the built-in registry path it replaces.
• Microsoft.Dynamics.Nav.LanguageModelTools.AnalyzerReferenceResolver is public in the pinned floor version, but was rejected: it resolves through CompilerPathUtilities.GetPathToAnalyzerFolder() (the running process's base directory), so it cannot honour --devtools-path or our locator at all — and it would add a 4th version-drift surface to the three DLLs the CI matrix swaps. AnalyzerSpec.cs stays.
• The review flagged the removed <devtools>/<tfm> entry in packageCachePaths as a loss of system symbols. It was not: no .app ships in the DevTools package or the AL extension, and the fixtures compile and fix without any .alpackages. The real gap next to it — al.packageCachePath being ignored — is what got fixed.
• Agent instructions moved from .github/copilot-instructions.md to AGENTS.md (imported by CLAUDE.md), so Copilot and Claude Code read the same file.

Known, out of scope

• After apply_fix, an al_compile in the same session still reports the fixed diagnostic — the child almcp serves its cached compilation (Recompilation of all app for every Analyze call #4). A fresh session is clean.
• The DevTools nupkg ships no Linux/macOS almcp launcher (only almcp.exe + almcp.dll, and DotnetToolSettings.xml declares only al), so off Windows the proxy is unavailable from the dotnet tool store until BcToolsLocator learns to fall back to dotnet almcp.dll. This is also why the almcp-backed tests skip on the Ubuntu CI runner.
• ModelContextProtocol 0.9.0-preview.2 → 1.0.0 (the version almcp 18.0 itself ships) would drop the MSB3277 suppression. Separate PR.

🤖 Generated with Claude Code