aras-plm-mcp

一个用于 Aras Innovator PLM 的 MCP 服务器，它了解模式（schema）而不是靠猜测。

通过 OData 和 AML 提供 71 个工具。已针对真实运行的 Aras Innovator 2025（14.35.0）实例完成测试： 十个测试套件共 260 条断言，外加一个 39 步的演示脚本端到端执行。71 个工具中的每一个都至少被一个套件覆盖，每个写入工具都执行了真实的写入操作。

问题所在

Aras Innovator 的 OData API 是动态的。服务文档返回 501 Not Implemented，而一个标准实例暴露了 484 种 ItemType，其名称和属性取决于管理员如何配置数据模型。没有静态目录可读。

一个轻量级 HTTP 包装器——get_items(itemtype, filter)——把问题推给了模型。它必须猜测类型是 Part 而不是 Parts，物料清单是 Part BOM 而不是 BOM，数量字段是 quantity 而不是 qty。每次猜错都意味着一次往返请求和一个晦涩难懂的错误。

这个服务器会自省模式（schema）并将其返回。

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_read_file、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——它会告诉你连接到了什么。

尝试之前先咨询

aras_how_to 在模型开始猜测之前回答*"如何从外部客户端执行 X"和"为什么会出现这个错误"*。

它刻意不索引 Aras 的官方文档。那些文档描述的是客户端 JavaScript 和服务器端 C#——恰恰是从外部无法使用的路径——所以它会自信地指向死胡同。程序员指南中关于附加文件的答案是 aras.vault.selectFile，而它只存在于 Aras 客户端内部。

它依赖两个实际可靠的来源：

1. 针对真实实例验证过的知识，包含 Aras 返回的确切消息。<Complete>1</Complete>、<ApplyItem> 只应用批处理的第一个元素、依赖的 ItemType 必须在关系内部创建——这些在任何手册中都没有。

2. 实例本身——它的 UserMessage 目录和已安装的 Method。那是那个安装环境的真相，而不是泛泛而谈。

当它不知道时，它会明说，而不是返回最接近的匹配项。一个什么都能回答的工具和一个什么都回答不了的工具一样没用。

值得了解的设计决策

默认只读。 对 PLM 的写入是带版本和审计的，所以写入是有意启用的：ARAS_READONLY=false。当它为 true 时，21 个写入工具中的每一个都会礼貌地拒绝。

批量操作的 dryRun 默认为开启。 aras_replace_component 和 aras_bulk_update 会向你显示受影响的行，在你要求之前不会做任何更改。

删除在完成之前会先规划。 aras_plan_delete 会报告哪些内容引用了该项目，并在有引用时拒绝删除。在无法验证关系的情况下，它返回 -1，而不是假装关系为空——诚实的检查胜过免费的安慰。

权限拒绝会被解码。 Aras 对权限拒绝返回通用的 HTTP 500，而不是 403。aras_get_type_permissions 会告诉你缺少哪个身份；aras_lookup_error 会在 UserMessage 目录中查找消息。

项目引用只能作为注解获得，而且只能通过 $select。 使用 $select 查询 Part BOM 会得到 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 客户端的 OAuth 2.0 资源所有者密码凭据，作用域为 Innovator。

需要 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 中使用的组件：它必须拒绝。"

什么不可用，以及为什么

有四件事是外部客户端无法做到的。这并非疏忽，每个受影响的工具都会说明原因并指出替代方案，而不是以晦涩的方式失败。

另一方面，读取是有效的并且已经过验证。aras_read_file 通过 OData 媒体资源（File('<id>')/$value）下载内容，回退到保管库端点，并返回可读的内容：文本格式返回文本，包含文本的 PDF 返回提取的文本，PNG/JPEG/GIF/WebP 返回图像本身，以便实际查看。扫描的图纸会说明需要 OCR，而不是返回空字符串。

docs/field-notes.md 是现场日志：实时测试中暴露的每个缺陷，以及证明每个限制的确切错误。

文档

docs/it/ 保存了意大利语原文材料：一个 39 步的演示脚本和原始测试日志。

贡献

该项目最需要的是非我们自己的实例——不同版本、不同模板、不同数据模型。参见 CONTRIBUTING.md。

安全问题：SECURITY.md，请私下报告。

许可证

MIT — 参见 LICENSE。