alrm-mcp

AL ID Range Manager용 MCP 서버입니다.

AI 코딩 에이전트가 ALRM VS Code 확장 프로그램과 동일한 방식으로 AL 개체 ID를 예약할 수 있게 해줍니다. 에이전트가 새 AL 개체를 만들려고 할 때 new_object를 호출하면, Business Central의 공유 ALRM 데이터베이스가 이름을 검증하고 다음 사용 가능한 개체 ID를 돌려줍니다. 따라서 동일한 확장 프로그램에서 작업하는 모든 사람 간에 ID가 고유하게 유지됩니다.

도구

new_object

새 AL 개체를 등록하고 할당된 ID를 반환합니다.

개체 ID를 텍스트로 반환합니다(예: 50061). 동일한 이름으로 다시 호출하면 새 ID를 할당하는 대신 동일한 ID를 반환합니다.

Related MCP server: Dynamics 365 Business Central Admin MCP Server

요구 사항

• Node.js 20 이상

• ALRM 확장 프로그램이 설치된 Business Central 환경

• 해당 환경에 로그인할 수 있는 권한(인증 참조)

구성

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

Claude Code의 경우 다음 한 줄의 명령으로 추가할 수 있습니다:

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

환경 변수

세 가지 모두 필수입니다. 누락된 변수가 있으면 서버는 해당 변수 이름을 알려주는 메시지와 함께 즉시 종료됩니다.

이 변수들은 MCP 클라이언트의 env 블록에서만 읽습니다. 서버는 일반적으로 셸이 아닌 클라이언트에 의해 실행되므로 .env 파일 지원은 없습니다.

두 개의 선택적 변수를 사용하면 기본 공용 클라이언트 대신 자체 Entra 앱 등록을 가리킬 수 있습니다:

인증

첫 번째 도구 호출 시 OAuth 2.0 디바이스 코드 흐름을 사용하여 로그인합니다:

1. 브라우저 탭이 https://microsoft.com/devicelogin에서 열립니다.

2. 디바이스 코드가 클립보드에 복사되며, 클립보드나 브라우저를 사용할 수 없는 경우를 대비해 서버의 stderr에도 출력됩니다.

3. 코드를 붙여넣고 로그인을 완료하면 도구 호출이 진행됩니다.

이후 토큰 캐시는 운영 체제의 자격 증명 저장소에 저장됩니다. macOS의 경우 Keychain, Windows의 경우 DPAPI, Linux의 경우 Secret Service/libsecret입니다. 홈 디렉터리에는 .alrm-cache.json이라는 작은 인덱스 파일이 생성됩니다. 이후 호출에서는 서버 및 편집기 재시작을 포함하여 저장된 로그인을 자동으로 재사용하므로, 새로 고침 토큰이 만료될 때까지(약 90일간 활동이 없을 때) 브라우저를 다시 볼 일이 없습니다.

로그아웃하려면 .alrm-cache.json을 삭제하고 자격 증명 저장소에서 alrm-mcp 항목을 제거하세요. macOS의 경우:

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

logout 명령은 아직 없습니다.

플랫폼별 참고 사항

Linux에서 서버는 토큰을 일반 텍스트로 저장하는 대체 방식을 거부합니다. Secret Service를 사용할 수 없는 헤드리스 머신에서는 암호화되지 않은 토큰 캐시를 조용히 기록하는 대신 로그인이 실패합니다.

문제 해결

서버가 시작되지 않거나 클라이언트에서 CONNECTION_CLOSED가 보고됩니다. 거의 항상 환경 변수가 누락되었거나 철자가 틀린 경우입니다. MCP 클라이언트가 삼켜버리는 실제 오류를 확인하려면 서버를 직접 실행하세요:

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

정상적인 서버는 MCP server running을 출력하고 대기합니다.

Extension {id} not found! app.json의 appId가 이 회사에 대한 ALRM 데이터베이스에 없습니다. ALRM 확장 프로그램을 사용하거나 Business Central에서 직접 확장 프로그램을 먼저 등록하세요.

로그인 브라우저가 반복적으로 열립니다. 위에서 설명한 로그인 화면이 표시되는 것입니다. 한 번만 표시되어야 합니다. 반복적으로 열린다면 토큰 캐시가 유지되지 않는 것입니다. 저장된 로그인 재사용에 관한 메시지가 서버 출력에 나타나는지 확인하세요.

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

그런 다음 MCP 클라이언트가 게시된 패키지 대신 로컬 복사본을 가리키도록 하세요:

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