# alrm-mcp

MCP server for [AL ID Range Manager](https://github.com/artex-is/ALRM-VSCode).

Lets an AI coding agent reserve AL object IDs the same way the ALRM VS Code extension does. When the agent is about to create a new AL object, it calls `new_object`, and the shared ALRM database in Business Central validates the name and hands back the next free object ID — so IDs stay unique across everyone working on the same extension.

## Tools

### `new_object`

Reserves the next free ID for a new AL object and validates its name.

| Parameter    | Type               | Description                                                                  |
| ------------ | ------------------ | ---------------------------------------------------------------------------- |
| `appId`      | UUID               | The `id` from your extension's `app.json`                                    |
| `objectType` | enum, see below    | AL object type, lowercase, as written in the declaration                     |
| `objectName` | string, ≤ 30 chars | Name as it will appear in the declaration, unquoted, e.g. `ART CU Demo Data` |

Returns the reserved declaration as text, e.g. `codeunit 50061 "ART CU Demo Data"`, so an agent making several calls at once can't mismatch an ID with the name it belongs to.

Calling it again with the same name in the same app returns the same ID rather than allocating a new one, which makes it safe to retry.

Object types that have no ID in AL — `interface`, `controladdin`, `profile`, `entitlement`, `pagecustomization` — come back as `<NO-ID>` instead.

`objectType` accepts:

`codeunit`, `page`, `pageextension`, `pagecustomization`, `table`, `tableextension`, `query`, `report`, `reportextension`, `xmlport`, `enum`, `enumextension`, `permissionset`, `permissionsetextension`, `entitlement`, `profile`, `interface`, `controladdin`

### `new_object_line`

Reserves the next free ID for one new field in a table extension, or one new value in an enum extension.

| Parameter    | Type                                | Description                                                       |
| ------------ | ----------------------------------- | ----------------------------------------------------------------- |
| `appId`      | UUID                                | The `id` from your extension's `app.json`                         |
| `objectType` | `tableextension` \| `enumextension` | Type of the extension object the field or value is being added to |
| `objectId`   | integer                             | ID of the extension object itself, as returned by `new_object`    |

Returns the field or value ID as text, e.g. `50004`.

One call reserves one ID — there is no batch mode, so five new fields means five calls. Unlike `new_object` there is no name to key on, so **every call allocates a new ID**: don't call twice for the same field, and don't retry a call that may already have succeeded.

When two tables are linked by `TransferFields`, register the field only in the main table and reuse that ID in the other.

## Requirements

- Node.js 20 or newer
- A Business Central environment with the ALRM extension installed
- Permission to sign in to that environment (see [Authentication](#authentication))

## Configuration

```json
{
  "mcpServers": {
    "alrm-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "alrm-mcp@latest"],
      "env": {
        "BC_TENANT": "{tenant}",
        "BC_ENVIRONMENT": "{environment}",
        "BC_COMPANY": "{company}"
      }
    }
  }
}
```

For Claude Code you can add it in one command:

```sh
claude mcp add alrm-mcp \
  --env BC_TENANT=contoso.com \
  --env BC_ENVIRONMENT=Production \
  --env BC_COMPANY=00000000-0000-0000-0000-000000000000 \
  -- npx -y alrm-mcp@latest
```

### Environment variables

All three are required — the server exits immediately with a message naming whichever is missing.

| Variable         | Description                                                                                                                                                      |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BC_TENANT`      | Your Microsoft Entra tenant — either the domain (`contoso.com`) or the tenant GUID.                                                                              |
| `BC_ENVIRONMENT` | The Business Central environment name as shown in the BC admin center, e.g. `Production` or `Sandbox`.                                                           |
| `BC_COMPANY`     | The company **id** (a GUID, not the display name). List them at `https://api.businesscentral.dynamics.com/v2.0/{BC_TENANT}/{BC_ENVIRONMENT}/api/v2.0/companies`. |

These are read only from the MCP client's `env` block — there is no `.env` file support, since the server is normally launched by the client rather than from a shell.

Two optional variables let you point the server at your own Entra app registration instead of the default public client:

| Variable         | Default  | Description                                                                         |
| ---------------- | -------- | ----------------------------------------------------------------------------------- |
| `ALRM_CLIENT_ID` | built-in | Application (client) ID of a public client app registration.                        |
| `ALRM_TENANT`    | `common` | Authority tenant used for sign-in. Set this to restrict sign-in to a single tenant. |

## Authentication

The first tool call signs you in using the OAuth 2.0 device code flow:

1. A browser tab opens at <https://microsoft.com/devicelogin>.
2. The device code is copied to your clipboard, and also printed to the server's stderr in case the clipboard or browser isn't available.
3. Paste the code, complete sign-in, and the tool call proceeds.

Afterwards the token cache is stored in your operating system's credential store — Keychain on macOS, DPAPI on Windows, Secret Service/libsecret on Linux — with a small index file at `.alrm-cache.json` in your home directory. Later sessions reuse it silently, including across restarts of the server and of your editor, so you should not see the browser again until the refresh token expires (roughly 90 days of inactivity).

To sign out, delete `.alrm-cache.json` and remove the `alrm-mcp` entry from your credential store. On macOS:

```sh
rm ~/.alrm-cache.json
security delete-generic-password -s alrm-mcp -a alrm-mcp
```

There is no `logout` command yet.

### Platform notes

On Linux the server refuses to fall back to storing tokens in plaintext. On a headless machine with no Secret Service available, sign-in will fail rather than silently write an unencrypted token cache.

## Troubleshooting

**The server won't start / the client reports `CONNECTION_CLOSED`.** Almost always a missing or misspelled environment variable. Run it directly to see the actual error, which the MCP client swallows:

```sh
BC_TENANT=contoso.com BC_ENVIRONMENT=Production BC_COMPANY=... npx -y alrm-mcp@latest
```

A healthy server prints `MCP server running on stdio` and waits.

**`Extension {id} not found!`** The `appId` from your `app.json` has not been registered in the ALRM database for this company. Register the extension first, using the VS Code extension or directly in Business Central.

**A browser opened unexpectedly.** That's the sign-in described above. It should happen once, not on every call — if it repeats, the token cache isn't being persisted; check the stderr output for a message about reusing the stored sign-in.

## Development

```sh
git clone https://github.com/hiimnit/alrm-mcp.git
cd alrm-mcp
npm install
npm run build
```

Then point your MCP client at the local build instead of the published package:

```json
{
  "mcpServers": {
    "alrm-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/alrm-mcp/dist/index.js"],
      "env": {
        "BC_TENANT": "...",
        "BC_ENVIRONMENT": "...",
        "BC_COMPANY": "..."
      }
    }
  }
}
```