aras-plm-mcp

Ein MCP-Server für Aras Innovator PLM, der das Schema kennt, statt es zu erraten.

71 Tools über OData und AML. Getestet gegen eine Live-Instanz von Aras Innovator 2025 (14.35.0): 260 Assertions über zehn Suiten, plus ein 39-Schritte-Demoskript, das Ende-zu-Ende ausgeführt wurde. Jedes der 71 Tools wird von mindestens einer Suite abgedeckt, und jedes Schreibwerkzeug wird mit einem echten Schreibvorgang getestet.

Das Problem

Die OData-API von Aras Innovator ist dynamisch. Das Dienstdokument antwortet mit 501 Not Implemented, und eine Standardinstanz legt 484 ItemTypes offen, deren Namen und Eigenschaften davon abhängen, wie der Administrator das Datenmodell konfiguriert hat. Es gibt keinen statischen Katalog zum Nachlesen.

Ein dünner HTTP-Wrapper — get_items(itemtype, filter) — schiebt das Problem auf das Modell. Er muss raten, dass der Typ Part und nicht Parts heißt, dass die Stückliste Part BOM und nicht BOM heißt, dass das Mengenfeld quantity und nicht qty heißt. Jede falsche Vermutung ist ein Roundtrip und ein undurchsichtiger Fehler.

Dieser Server untersucht das Schema und gibt es zurück.

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

Related MCP server: kicad-mcp

Was OData allein nicht sehen kann

Drei Dinge in Aras sind für OData unsichtbar, und jedes davon ist eine Frage, die Leute tatsächlich stellen. Dieser Server erreicht sie über AML:

Letzteres brauchte ein Serverprotokoll, um es zu finden. Aras antwortet mit An internal error has occured; das Protokoll sagt Workflow: EvaluateActivity: Complete value not found.

Tools

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_read_file, aras_get_history, aras_get_revisions, aras_get_my_identities, aras_get_identity_members, aras_export_aml

aras_get_bom (rekursive Auflösung mit kumulativen Mengen und Zykluserkennung pro Zweig), 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

Lebenszyklus-Maps und -Zustände mit der Rolle, die jeder Übergang erfordert; Benutzer, Gruppen, Mitgliedschaften und Berechtigungen; Erstellen von ItemTypes mit funktionierenden Instanzen; Dashboards, Metriken, Berichte, gespeicherte Abfragen, Sequenzen, Methoden; Serverprotokolle aus sowohl den Serilog-Dateien als auch dem ItemType SystemEventLog.

Führen Sie zuerst aras_ping aus — es sagt Ihnen, womit Sie verbunden sind.

Vor dem Versuch konsultieren

aras_how_to beantwortet „Wie mache ich X von einem externen Client aus“ und „Warum dieser Fehler“, bevor das Modell zu raten beginnt.

Es indiziert bewusst nicht die offizielle Dokumentation von Aras. Dieses Korpus beschreibt clientseitiges JavaScript und serverseitiges C# — genau die Wege, die von außen nicht funktionieren — und würde daher selbstbewusst auf Sackgassen verweisen. Die Antwort des Programmer's Guide auf das Anhängen einer Datei ist aras.vault.selectFile, das nur innerhalb des Aras-Clients existiert.

Es stützt sich auf zwei Quellen, die tatsächlich zuverlässig sind:

1. Wissen, das gegen eine Live-Instanz verifiziert wurde, mit der genauen Meldung, die Aras zurückgibt. <Complete>1</Complete>, <ApplyItem>, das nur das erste Element eines Stapels anwendet, abhängige ItemTypes, die innerhalb der Beziehung erstellt werden müssen — nichts davon steht in einem Handbuch.

2. Die Instanz selbst — ihr UserMessage-Katalog und installierte Methoden. Das ist die Wahrheit dieser Installation und nicht einer generischen.

Und es sagt es, wenn es es nicht weiß, anstatt die nächstbeste Übereinstimmung zurückzugeben. Ein Werkzeug, das auf alles antwortet, ist so nutzlos wie eines, das auf nichts antwortet.

Wissenswerte Designentscheidungen

Standardmäßig schreibgeschützt. Schreibvorgänge in ein PLM werden versioniert und geprüft, daher sind sie absichtlich aktiviert: ARAS_READONLY=false. Jedes der 21 Schreibwerkzeuge verweigert höflich, solange es true ist.

dryRun ist für Massenvorgänge standardmäßig aktiv. aras_replace_component und aras_bulk_update zeigen Ihnen die betroffenen Zeilen und ändern nichts, bis Sie es verlangen.

Das Löschen wird geplant, bevor es ausgeführt wird. aras_plan_delete meldet, was das Element referenziert, und verweigert, wenn etwas darauf verweist. Wo es eine Beziehung nicht verifizieren konnte, gibt es -1 zurück, anstatt so zu tun, als wäre die Beziehung leer — eine ehrliche Prüfung schlägt eine, die Sie umsonst beruhigt.

Berechtigungsverweigerungen werden dekodiert. Aras gibt ein generisches HTTP 500 für eine verweigerte Berechtigung zurück, kein 403. aras_get_type_permissions sagt Ihnen, welche Identität fehlt; aras_lookup_error schlägt die Meldung im UserMessage-Katalog nach.

Elementreferenzen kommen nur als Annotationen und nur mit $select. Die Abfrage von Part BOM mit $select ergibt related_id@aras.id und related_id@aras.keyed_name; ohne kommt nichts zurück und die Zeilen sehen wie undurchsichtige Metadaten aus. Dies ist einmal in readItemRef() (src/aras/odata.ts) kodiert, sodass kein Aufrufer sich das merken muss. Es ist auch der einfachste Weg, einen BOM-Explorer zu bauen, der stillschweigend einen leeren Baum zurückgibt.

Installation

npm install
npm run build

Kopieren Sie .env.example in .env und füllen Sie es aus. Für Claude Code fügen Sie zu .mcp.json hinzu:

{
  "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"
      }
    }
  }
}

Die Authentifizierung erfolgt über OAuth 2.0 Resource Owner Password Credentials gegen den IOMApp-Client, Bereich Innovator.

Erfordert Node 20+ und eine Aras-Innovator-Instanz, mit der Sie sprechen dürfen.

Testen

Jede Suite läuft gegen eine Live-Instanz, schreibt nur in Elemente mit dem Präfix ZZ- und entfernt sie danach. Der letzte Ablauf stellt sicher, dass Produktionsdaten unangetastet blieben.

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 ist das Interessante. Es testet keine Tools — es testet Fragen, so wie sie jemand in einem Unternehmen stellen würde:

„Ein Konstrukteur hat angefangen: Erstellen Sie sein Konto und ordnen Sie es der richtigen Abteilung zu.“ „Codieren Sie eine neue Komponente, führen Sie sie durch die Freigabe und geben Sie sie frei.“ „Ersetzen Sie eine Komponente überall, aber sagen Sie mir zuerst, wo sie landen würde.“ „Versuchen Sie, eine Komponente zu löschen, die in einer Stückliste verwendet wird: Sie muss sich weigern.“

Was nicht funktioniert und warum

Vier Dinge sind von einem externen Client aus nicht erreichbar. Das ist kein Versehen, und jedes betroffene Tool sagt das und verweist auf die Alternative, anstatt undurchsichtig zu scheitern.

Das Lesen hingegen funktioniert und ist verifiziert. aras_read_file lädt den Inhalt über die OData-Medienressource (File('<id>')/$value) herunter, mit Fallback auf den Vault-Endpunkt, und gibt etwas Lesbares zurück: Text für Textformate, extrahierten Text für PDFs, die solchen enthalten, und das Bild selbst für PNG/JPEG/GIF/WebP, damit man es tatsächlich ansehen kann. Ein gescanntes Dokument sagt, dass es OCR bräuchte, anstatt einen leeren String zurückzugeben.

docs/field-notes.md ist das Feldprotokoll: jeder Fehler, den die Live-Tests aufgedeckt haben, und der genaue Fehler, der jede Grenze beweist.

Dokumentation

docs/it/ enthält das ursprüngliche italienische Material: ein 39-Blöcke-Demoskript und das rohe Testprotokoll.

Mitwirken

Instanzen, die nicht unsere sind, sind das, was dies am meisten braucht — verschiedene Versionen, verschiedene Vorlagen, verschiedene Datenmodelle. Siehe CONTRIBUTING.md.

Sicherheitsprobleme: SECURITY.md, privat.

Lizenz

MIT — siehe LICENSE.