aras-plm-mcp

Aras Innovator PLM용 MCP 서버로, 스키마를 추측하는 대신 실제로 알고 있습니다.

OData 및 AML을 통한 69개의 도구. 실제 Aras Innovator 2025(14.35.0) 인스턴스에서 테스트 완료: 10개 스위트에 걸친 244개의 어서션, 그리고 39단계 데모 스크립트를 처음부터 끝까지 실행.

문제

Aras Innovator의 OData API는 동적입니다. 서비스 문서는 501 Not Implemented로 응답하며, 기본 인스턴스는 관리자가 데이터 모델을 어떻게 구성했는지에 따라 이름과 속성이 달라지는 484개의 ItemType을 노출합니다. 읽을 수 있는 정적 카탈로그가 없습니다.

얇은 HTTP 래퍼 — get_items(itemtype, filter) — 는 그 문제를 모델에 떠넘깁니다. 타입이 Parts가 아니라 Part인지, BOM(자재 명세서)이 BOM이 아니라 Part BOM인지, 수량 필드가 qty가 아니라 quantity인지 추측해야 합니다. 잘못된 추측 하나하나가 왕복 요청과 불투명한 오류가 됩니다.

이 서버는 스키마를 내부적으로 조사하여 그대로 돌려줍니다.

aras_describe_item_type  itemType: "Part"
  → 41 typed properties, real mandatory flags, outgoing relationships

Related MCP server: kicad-mcp

OData만으로는 볼 수 없는 것

Aras에는 OData로는 보이지 않는 세 가지가 있으며, 각각은 사람들이 실제로 묻는 질문입니다. 이 서버는 AML을 통해 이에 답합니다:

마지막 항목은 서버 로그를 봐야 찾을 수 있었습니다. Aras는 An internal error has occured라고 응답합니다. 로그에는 Workflow: EvaluateActivity: Complete value not found라고 표시됩니다.

도구

aras_query_items, aras_get_item, aras_get_relationships, aras_get_bom, aras_where_used, aras_get_documents, aras_get_aml, aras_get_files, aras_get_history, aras_get_revisions, aras_get_my_identities, aras_get_identity_members, aras_export_aml

aras_get_bom (누적 수량과 분기별 사이클 감지를 포함한 재귀적 전개), aras_manage_bom_line, aras_replace_component, aras_copy_part, aras_add_manufacturer_part, aras_check_release_readiness, aras_check_effectivity

aras_create_change, aras_add_affected_item, aras_get_change_impact, aras_get_workflow, aras_advance_change, aras_vote_activity, aras_delegate_activity

각 전환에 필요한 역할과 함께 라이프사이클 맵 및 상태; 사용자, 그룹, 멤버십 및 권한; 작동하는 인스턴스를 가진 ItemType 생성; 대시보드, 메트릭, 보고서, 저장된 쿼리, 시퀀스, 메서드; Serilog 파일과 SystemEventLog ItemType 양쪽의 서버 로그.

먼저 aras_ping을 실행하세요 — 연결된 대상이 무엇인지 알려줍니다.

알아 둘 만한 설계 결정

기본적으로 읽기 전용. PLM에 대한 쓰기는 버전 관리되고 감사되므로, 의도적으로 활성화됩니다: ARAS_READONLY=false. 21개의 쓰기 도구 모두 true인 동안에는 정중하게 거부합니다.

dryRun은 일괄 작업에서 기본적으로 켜져 있습니다. aras_replace_component와 aras_bulk_update는 영향을 받는 행을 보여주고 요청하기 전까지는 아무것도 변경하지 않습니다.

삭제는 실행 전에 계획됩니다. aras_plan_delete는 항목을 참조하는 대상을 보고하고, 참조하는 것이 있으면 거부합니다. 관계를 확인할 수 없는 경우 관계가 비어 있다고 가장하는 대신 -1을 반환합니다 — 공짜로 안심시키는 검사보다 정직한 검사가 낫습니다.

권한 거부는 해독됩니다. Aras는 권한 거부에 대해 403이 아닌 일반적인 HTTP 500을 반환합니다. aras_get_type_permissions는 어떤 ID에 권한이 없는지 알려주고, aras_lookup_error는 UserMessage 카탈로그에서 메시지를 조회합니다.

항목 참조는 주석으로만, 그리고 $select와 함께만 도착합니다. Part BOM을 $select 포함으로 쿼리하면 related_id@aras.id와 related_id@aras.keyed_name이 반환됩니다. 없이 쿼리하면 아무것도 반환되지 않고 행이 불투명한 메타데이터처럼 보입니다. 이것은 readItemRef()(src/aras/odata.ts)에 한 번만 인코딩되어 있어 호출자가 기억할 필요가 없습니다. 또한 조용히 빈 트리를 반환하는 BOM 탐색기를 만드는 가장 쉬운 방법이기도 합니다.

설치

npm install
npm run build

.env.example을 .env로 복사하고 작성하세요. Claude Code의 경우 .mcp.json에 추가하세요:

{
  "mcpServers": {
    "aras-plm": {
      "command": "node",
      "args": ["/path/to/aras-plm-mcp/dist/index.js"],
      "env": {
        "ARAS_URL": "http://localhost/InnovatorServer",
        "ARAS_DATABASE": "InnovatorSolutions",
        "ARAS_USER": "admin",
        "ARAS_PASSWORD": "…",
        "ARAS_CLIENT_ID": "IOMApp",
        "ARAS_READONLY": "true"
      }
    }
  }
}

인증은 IOMApp 클라이언트, 범위 Innovator에 대한 OAuth 2.0 리소스 소유자 비밀번호 자격 증명입니다.

Node 20+와 통신이 허용된 Aras Innovator 인스턴스가 필요합니다.

테스트

모든 스위트는 실제 인스턴스에 대해 실행되며, ZZ- 접두사가 붙은 항목에만 쓰고 이후에 제거합니다. 마지막 흐름은 프로덕션 데이터가 손상되지 않았음을 어서션합니다.

node test-flussi.mjs      # ten whole business flows, request to conclusion
node test-demo.mjs        # the 39 blocks of the demo script, one by one
node test-full.mjs        # connection, discovery, reading, navigation
node test-product.mjs     # BOM, where-used, AML, documents, revisions
node test-lifecycle.mjs   # lifecycle, transitions, roles
node test-schema.mjs      # custom ItemTypes and properties
node test-admin.mjs       # identities and permissions
node test-analytics.mjs   # dashboards, metrics, effectivity
node test-reports.mjs     # reports, saved queries, sequences, methods
node test-write.mjs       # read-only refusals
node test-writepath.mjs   # real writes, created and removed

test-flussi.mjs가 흥미로운 파일입니다. 도구를 테스트하지 않고 — 질문을 테스트합니다. 회사에서 누군가가 묻는 방식 그대로입니다:

"디자이너가 새로 합류했습니다: 계정을 만들고 올바른 부서에 배치하세요." "새 구성 요소를 코딩하고, 승인을 거쳐 릴리스하세요." "구성 요소를 모든 곳에서 교체하되, 먼저 어디에 적용될지 알려주세요." "BOM에서 사용되는 구성 요소를 삭제하려고 하면: 거부해야 합니다."

작동하지 않는 것과 그 이유

외부 클라이언트에서 접근할 수 없는 네 가지가 있습니다. 이것은 실수가 아닙니다, 영향을 받는 각 도구는 그렇게 말하고 불투명하게 실패하는 대신 대안을 안내합니다.

볼트 파일 읽기 및 다운로드는 작동합니다. 업로드만 되지 않습니다.

docs/field-notes.md는 현장 기록입니다: 실제 테스트에서 발견된 모든 결함과 각 제한을 증명하는 정확한 오류입니다.

문서

docs/it/에는 원본 이탈리아어 자료가 있습니다: 39블록 데모 스크립트 및 원시 테스트 로그.

기여

우리의 것이 아닌 인스턴스가 가장 필요합니다 — 다른 버전, 다른 템플릿, 다른 데이터 모델. CONTRIBUTING.md를 참조하세요.

보안 문제: SECURITY.md, 비공개로.

라이선스

MIT — LICENSE 참조.