ev-ratio-mcp

An MCP (Model Context Protocol) server that builds, compiles and publishes Business Central AL apps using the alc.exe that ships inside the installed AL Language VS Code extension. It is the MCP half of EV Ratio, the Elbek & Vejrup agentic AL framework.

It replaces the bundled build.ps1 / publish.ps1 scripts with a self-contained Node package so the agent framework no longer has to ship and shell out to PowerShell. Consumers run it through npx; see the root README for setup.

Tools

All three tools accept a single path:

• App-folder path (contains app.json) → single-app mode. In-workspace dependencies are still resolved and built first.
• Workspace/solution root (contains several AL project folders) → whole-workspace mode. Every project is built in dependency order.

ev_ratio_build

Compiles with alc.exe and writes Publisher_Name_Version.app next to each app.json, then copies that .app into every dependent app's .alpackages. Builds the whole in-workspace dependency chain in order (e.g. app before test).

Returns a per-project verdict: CLEAN BUILD / BUILD FAILED / BLOCKED ON MISSING SYMBOLS.

| Parameter | Type | Default | Notes | |---|---|---|---| | path | string | — | App folder or workspace root | | includeWarnings | boolean | false | Also list warnings + info |

ev_ratio_compile

Same compile, but no .app is written next to app.json — it only returns errors, warnings and info. By default a dependency is only rebuilt when its symbol .app is missing from the dependent's .alpackages; set rebuildDependencies to force a fresh rebuild for current truth.

| Parameter | Type | Default | Notes | |---|---|---|---| | path | string | — | App folder or workspace root | | includeWarnings | boolean | true | List warnings + info | | rebuildDependencies | boolean | false | Force fresh dependency rebuild |

ev_ratio_publish

Builds the whole dependency chain (persisting each .app), then publishes every app to the running BC dev container via the /dev/apps endpoint, in dependency order (app before test). Connection details come from the project's .vscode/launch.json (UserPassword auth only).

| Parameter | Type | Default | Notes | |---|---|---|---| | path | string | — | App folder or workspace root | | tenant | string | from launch.json → default | | | port | number | 7049 | Dev endpoint port | | schemaUpdateMode | string | from launch.json → synchronize | | | dependencyPublishingOption | string | from launch.json → default | |

ev_ratio_git_branch

Creates and pushes a git branch named <ISSUE-KEY>-<slug-of-title> off the synced base branch. Fetches origin/<base>, guarantees a non-colliding name (appends -2/-3), carries the caller's uncommitted changes onto the new branch (via stash/pop), and pushes with upstream tracking. Non-destructive by design — it only fetches, stashes/pops, branches and pushes; it never force-pushes, resets, or deletes. Jira stays out of the MCP: the caller resolves the issue and passes issueKey + title in.

| Parameter | Type | Default | Notes | |---|---|---|---| | repoPath | string | — | Git repository working directory | | issueKey | string | — | Branch prefix, e.g. PROJ-123 | | title | string | — | Issue summary, slugified into the name | | baseBranch | string | origin default → main/master | Branch to fork from |

Reports EV GIT BRANCH: CREATED (with branch/base/WIP/push status + any warnings) or BLOCKED.

ev_ratio_github_pr

Opens a pull request for the current issue branch via the gh CLI (reuses your existing gh authentication, including GitHub Enterprise). Pushes the current branch and opens a PR with a fixed template so every PR looks the same: ## Summary (the caller's prose), ## Changes (generated from the real commits + diffstat), and a Resolves <key> line. Idempotent — an existing open PR for the branch is returned, not duplicated. The returned URL is read authoritatively from gh pr view --json. Non-destructive: it pushes and opens a PR, nothing else.

| Parameter | Type | Default | Notes | |---|---|---|---| | repoPath | string | — | Git repository working directory | | issueKey | string | — | Used in the title and the Resolves line | | title | string | — | Issue summary, used to build the PR title | | body | string | (none) | The ## Summary prose; the tool adds Changes + Resolves around it | | base | string | origin default | Base branch for the PR |

Reports EV GITHUB PR: CREATED / EXISTS (with PR URL, branch→base, push status) or BLOCKED. Requires gh installed and authenticated for the target host.

ev_ratio_git_changes

Returns the commits, changed files and a bounded unified diff between the base and the current branch — everything needed to write a PR summary — in one read-only call (so an agent can ground a prose PR description in the real diff without running, and getting approvals for, individual git commands).

| Parameter | Type | Default | Notes | |---|---|---|---| | repoPath | string | — | Git repository working directory | | base | string | origin default | Base branch to diff against |

The diff is capped (default 400 lines) to keep it context-friendly; truncation is flagged.

Prerequisites

• Node.js ≥ 18.17 (uses the built-in fetch / FormData).

• The AL Language extension installed in VS Code (the server finds the highest-version ms-dynamics-smb.al-* under ~/.vscode/extensions).

• Symbols already downloaded into each project's .alpackages (run AL: Download Symbols once). alc.exe compiles but does not download symbols; missing ones surface as AL1022 and are reported separately.

• For ev_ratio_publish: a running BC dev container, a valid .vscode/launch.json with authentication: UserPassword, and the credentials in environment variables BC_DEV_USER / BC_DEV_PASSWORD. Set them in the MCP server's env config:

  {
    "servers": {
      "ev-ratio": {
        "command": "node",
        "args": ["${workspaceFolder:agentic-dev-engine}/mcp-server/dist/index.js"],
        "env": { "BC_DEV_USER": "<user>", "BC_DEV_PASSWORD": "<password>" }
      }
    }
  }

  Credentials are read from the environment only and are never logged or echoed. Committing a plaintext password into mcp.json exposes it if the repo is shared — prefer gitignoring the file or supplying the values from your own environment.

Build & run locally

cd mcp-server
npm install
npm run build      # compiles src/ to dist/

The server is registered for the plugin in ev-ratio-mcp/mcp.json:

{
  "servers": {
    "ev-ratio": {
      "command": "node",
      "args": ["${workspaceFolder:agentic-dev-engine}/mcp-server/dist/index.js"]
    }
  }
}

Adjust the ${workspaceFolder:...} name if your workspace folder has a different basename, or point it at an absolute dist/index.js path.

Publishing

Consumers install nothing — their mcp.json runs npx -y ev-ratio-mcp, which pulls the current published version. To cut a release:

cd mcp-server
npm version patch     # or minor / major
npm publish           # prepublishOnly compiles first; only dist/ ships

Requires npm login once. dist/ is not committed — prepublishOnly builds it, so never publish from a tree where tsc fails.

Notes / current scope

• Windows-first (bin/win32/alc.exe), with a fallback to bin/linux/alc and bin/alc.exe.
• Publish is verified only against UserPassword auth on a single-tenant on-prem container; it refuses other authentication values rather than guessing the request shape.
• ev_ratio_build writes the .app into the working folder next to app.json by design (per spec). Consider adding *.app to that project's .gitignore if you do not want the artifact committed.