aveva-pisystem-mcp-server

# AVEVA PI 系统 MCP 服务器 一个无状态、零信任的模型上下文协议（MCP）服务器，用于 AVEVA PI 系统。该服务器作为中间方，使 AI 代理和 LLM 客户端能够使用标准工具调用安全地查询和写入时间序列存档、AF 资产数据库、元素、属性和摘要。 --- ## 1. 架构概述 该服务器使用 **干净架构** 原则构建，以隔离核心 PI 系统模型与传输层问题： ``` [MCP 客户端] <--- 标准输入/输出 或 HTTP ---> [协议层（边缘身份验证/速率限制）] | [控制器层] | [PI Web API 客户端网关] | [PI Web API] ``` - **协议层：** 处理标准输入/输出或 HTTP 传输上的 JSON-RPC 消息帧。执行入站令牌验证（JWKS）和客户端相互 TLS 验证在网络边缘。 - **控制器层：** 将命名空间工具输入（例如 `pi.data.get_value`）映射到域操作。 - **PI Web API 网关：** 处理基于 undici 的 HTTP 连接池、重试策略、自适应限流和批处理。 - **域层：** 包含纯值（例如 `TagPath`、`TimeRange`、`Paging`）以控制格式化和验证不变量。 --- ## 2. 外发身份模型（承载负载） > [!IMPORTANT] > 服务器在 **单个固定服务身份模型** 下运行。它作为单个配置的服务帐户（使用 Kerberos、基本身份验证或 OAuth/Bearer 凭证在启动时配置）向上游 PI Web API 进行身份验证。 > - 服务器 **不** 委托入站 MCP 调用者的身份（不进行代理委托）。 > - 所有缓存层（WebID 和元数据）都根据资源路径全局键控。如果将来引入身份委托，则所有缓存必须重新键控以防止权限提升。 --- ## 3. 快速入门和安装 **强烈建议：让 LLM 代理为您安装。** 设置涉及选择四种身份验证模式之一（Kerberos、基本身份验证、Bearer/OIDC 或匿名），为私有/内部 OT 证书颁发机构配置 TLS 信任，编写 `.env` 文件，并使用您的 MCP 客户端注册服务器 - 人们经常在此过程中出错。LLM 代理会读取完整指南并为您完成每个步骤。 将此提示粘贴到 Claude Code、Claude Desktop、Cursor、AmpCode 或任何编码代理中： ``` 按照以下说明安装和配置 AVEVA PI 系统 MCP 服务器： https://raw.githubusercontent.com/Digital-Enginks/aveva-pisystem-mcp-server/refs/heads/main/README.md 询问我公司使用哪种 PI Web API 身份验证模式（Kerberos、基本身份验证、Bearer/OIDC 或匿名）以及 PI Web API 服务器是否使用私有/内部证书颁发机构，然后为我完成所有步骤： 安装依赖项，从匹配的模板创建 `.env` 文件，并配置 MCP 客户端注册块。 ``` 如果您更喜欢手动操作？请继续执行以下手动步骤。 ### 先决条件 - **Node.js：** 必须安装版本 **`22.14.0`** （LTS）。 - **网络访问：** 您必须具有通过 HTTPS（通常为 443 端口）访问公司 PI Web API 服务器的网络权限。 - **Kerberos（如果使用 Windows 帐户）：** 如果您配置服务器使用 Windows Active Directory 帐户（Kerberos），请确保您的操作系统上已安装 Kerberos 客户端标头（或标准 Active Directory 域访问权限）。 ### 安装 克隆此存储库到您的计算机，打开终端（Windows 上的 PowerShell 或命令提示符），并运行以下命令以下载和安装所需的依赖项： ```bash npm ci ``` --- ## 4. 配置 要配置服务器，您需要在该项目的根文件夹中创建一个名为 `.env` 的文件。 由于不同公司使用不同的方式登录其 PI 系统，我们创建了 **4 个预制的配置文件模板**，您可以复制。请选择与您的公司设置匹配的模板： ### A. 复制与您的设置匹配的模板 - **Windows / Active Directory 登录（Kerberos）：** 复制 [templates/kerberos.env](templates/kerberos.env) 到 `.env`。这是工业 OT 和企业控制系统中最常见的设置。 - **用户名和密码登录（基本身份验证）：** 复制 [templates/basic.env](templates/basic.env) 到 `.env`。如果您有具有固定用户名和密码的专用服务帐户，请使用此选项。 - **AVEVA 身份管理器登录（Bearer OIDC）：** 复制 [templates/bearer.env](templates/bearer.env) 到 `.env`。如果您的公司使用现代 Web 单点登录（SSO）令牌，请使用此选项。 - **匿名登录（无身份验证）：** 复制 [templates/anonymous.env](templates/anonymous.env) 到 `.env`。仅在开发或测试沙盒中使用。 ### B. 用白话理解设置 - `PIWEBAPI_BASE_URL`：您的 PI Web API 服务的 Web 地址（例如 `https://pi-server.company.com/piwebapi`）。请始终向您的 PI 管理员或 IT 支持团队询问确切的地址。 - `PIWEBAPI_AUTH_MODE`：告诉服务器如何登录。必须是 `kerberos`、`basic`、`bearer` 或 `anonymous`。 - `PIWEBAPI_TLS_CA_FILE`：如果您的公司使用私有安全证书（在隔离的 OT 网络中非常常见），当访问 PI Web API 页面时，您的浏览器可能会显示证书警告。请保存公司的根证书文件（以 `.pem` 格式）并将其完整路径放在此处（例如 `C:\certs\company-ca.pem`）。 - `MCP_TRANSPORT`：如果您在本地计算机上运行服务器并使用诸如 Claude Desktop 之类的客户端，请将其保留为 `stdio`。 - `MCP_WRITE_TOOLS_ENABLED`：仅在您希望允许 AI 助手向 PI 系统写入数据时设置为 `true`。为了安全，请将其设置为 `false` 以启用只读访问。**注意：** 启用写入还要求 `MCP_READ_ONLY=false` - 服务器默认是只读的，如果 `MCP_WRITE_TOOLS_ENABLED=true` 而 `MCP_READ_ONLY` 仍然为 `true`，则服务器拒绝启动。 ### C. 使用 Claude Desktop 注册 要将此服务器连接到您的 Claude Desktop 应用程序，请打开您的 Claude 配置文件（位于 Windows 上的 `%APPDATA%\Claude\claude_desktop_config.json`）并在 `mcpServers` 列表中添加此服务器。 选择与您公司身份验证策略匹配的以下配置块： #### 选项 1：Windows / Active Directory（Kerberos） ```json { "mcpServers": { "aveva-pi-system": { "command": "node", "args": ["c:/development/aveva-pisystem-mcp-server/src/main.js"], "env": { "PIWEBAPI_BASE_URL": "https://pi-web-api-server.company.com/piwebapi", "PIWEBAPI_AUTH_MODE": "kerberos", "PIWEBAPI_KERBEROS_SPN": "HTTP/pi-web-api-server.company.com", "PIWEBAPI_TLS_CA_FILE": "C:/certs/company-root-ca.pem", "MCP_TRANSPORT": "stdio", "MCP_WRITE_TOOLS_ENABLED": "false" } } } } ``` #### 选项 2：用户名和密码登录（基本身份验证） ```json { "mcpServers": { "aveva-pi-system": { "command": "node", "args": ["c:/development/aveva-pisystem-mcp-server/src/main.js"], "env": { "PIWEBAPI_BASE_URL": "https://pi-web-api-server.company.com/piwebapi", "PIWEBAPI_AUTH_MODE": "basic", "PIWEBAPI_BASIC_USER": "company_domain\\service-username", "PIWEBAPI_BASIC_PASSWORD": "your-secret-password-here", "PIWEBAPI_TLS_CA_FILE": "C:/certs/company-root-ca.pem", "MCP_TRANSPORT": "stdio", "MCP_WRITE_TOOLS_ENABLED": "false" } } } } ``` #### 选项 3：AVEVA 身份管理器 / OIDC（Bearer 令牌） ```json { "mcpServers": { "aveva-pi-system": { "command": "node", "args": ["c:/development/aveva-pisystem-mcp-server/src/main.js"], "env": { "PIWEBAPI_BASE_URL": "https://pi-web-api-server.company.com/piwebapi", "PIWEBAPI_AUTH_MODE": "bearer", "PIWEBAPI_BEARER_ISSUER": "https://aim-server.company.com/identitymanager/", "PIWEBAPI_BEARER_CLIENT_ID": "mcp-client-application-id", "PIWEBAPI_BEARER_CLIENT_SECRET": "your-aim-client-secret-key", "PIWEBAPI_BEARER_AUDIENCE": "https://pi-web-api-server.company.com/piwebapi", "PIWEBAPI_TLS_CA_FILE": "C:/certs/company-root-ca.pem", "MCP_TRANSPORT": "stdio", "MCP_WRITE_TOOLS_ENABLED": "false" } } } } ``` #### 选项 4：匿名访问（无登录） ```json { "mcpServers": { "aveva-pi-system": { "command": "node", "args": ["c:/development/aveva-pisystem-mcp-server/src/main.js"], "env": { "PIWEBAPI_BASE_URL": "https://pi-web-api-server.company.com/piwebapi", "PIWEBAPI_AUTH_MODE": "anonymous", "PIWEBAPI_ALLOW_ANONYMOUS": "true", "PIWEBAPI_TLS_CA_FILE": "C:/certs/company-root-ca.pem", "MCP_TRANSPORT": "stdio", "MCP_WRITE_TOOLS_ENABLED": "false" } } } } ``` > [!IMPORTANT] > **连接设置需要帮助吗？** > 如果您不知道 PI Web API 服务器的地址、客户端密钥或证书路径，或者在登录/身份验证过程中遇到错误，**请联系您的公司 PI 系统管理员或 IT 支持团队**。这些值特定于您的公司网络，只能由您的 IT 部门提供。 --- ## 5. 安全概览 - **在需要的地方强制执行 TLS 验证：** `NODE_TLS_REJECT_UNAUTHORIZED=0` 始终拒绝启动。`PIWEBAPI_TLS_VERIFY=false` 仅作为非生产调试逃生门 - 它在 `NODE_ENV=production`、HTTP 传输或与证书固定结合时被拒绝。 - **自定义信任锚点：** 对于使用私有或内部 CA 的 PI Web API 服务器，请通过 `PIWEBAPI_TLS_CA_FILE` 提供 PEM CA 文件。服务器信任该文件和系统公共根的并集（因此公共 CA（如 AIM）仍然有效）。 - **默认发送 CSRF 头部：** `X-Requested-With` 头部附加到每个写入请求（POST/PUT/PATCH/DELETE）；`PIWEBAPI_SEND_CSRF_HEADER=false` 仅为拒绝该头部的上游部署禁用它。 - **写入默认拒绝：** 写入工具在未设置 `MCP_READ_ONLY=false` 和 `MCP_WRITE_TOOLS_ENABLED=true` 的情况下关闭；在 HTTP 传输中，它们还需要边缘身份验证 (`MCP_EDGE_AUTH_MODE`) 和与 `MCP_EDGE_WRITE_ROLES` 匹配的调用者角色。 - **强化入站 HTTP 传输：** 在边缘强制执行 bearer 令牌或 mTLS (`MCP_EDGE_AUTH_MODE`)，默认情况下 `MCP_HTTP_BIND` 不会通配符绑定。 请参阅 [安全建议](docs/security/recommendations.md)、[威胁模型](docs/security/threat-model.md) 和 [入站传输指南](docs/security/inbound-transport.md)，了解完整的安全姿态。 --- ## 6. 参考文档 - **兼容性矩阵：** 请参阅 [COMPATIBILITY.md](COMPATIBILITY.md) 以获取支持的 PI Web API 和 Node 版本。 - **配置指南：** 请参阅 [docs/configuration.md](docs/configuration.md) 以获取所有配置变量的描述。 - **身份验证设置：** [基本身份验证](docs/auth/basic.md) · [Kerberos](docs/auth/kerberos.md) · [Bearer / OIDC（AIM）](docs/auth/bearer.md)。 - **威胁模型：** 请参阅 [docs/security/threat-model.md](docs/security/threat-model.md) 以获取 STRIDE 威胁分析。 - **故障排除：** 请参阅 [docs/troubleshooting.md](docs/troubleshooting.md) 以获取调试指南和常见错误解决方案。 - **工具目录：** 请参阅 [docs/tools.md](docs/tools.md) 以获取命名空间工具和 JSON 模式的详细信息。 --- ## 7. 来源和 SBOM 已发布的版本从 GitHub Actions 使用 **npm 来源** (`npm publish --provenance`) 构建和发布。要验证下载的包是否从此源构建： ```bash npm audit signatures ``` CycloneDX **SBOM** 附加到每个 GitHub 版本中，用于下游漏洞和许可证扫描。请参阅 [SECURITY.md](SECURITY.md) 以获取验证详细信息和披露政策。 --- ## 8. 许可证和贡献 - **许可证：** 根据 Apache License, Version 2.0（请参阅 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)）授权。 - **贡献：** 贡献者指南和 DCO 签署在 [CONTRIBUTING.md](CONTRIBUTING.md) 中。 - **漏洞披露：** 安全策略和报告渠道在 [SECURITY.md](SECURITY.md) 中定义。 - **联系和支持：** 由 **Oscar Ortiz** ([@oscarinom](https://github.com/oscarinom)) 维护。如需支持或自定义 OT 集成，请发送电子邮件：`oscar.ortiz@denginks.com`。