Alloy Navigator

Alloy Navigator MCP 服务

适用于 Alloy Navigator REST API 的 MCP 服务，为 AI 助手和 WYRE Conduit 网关提供 IT 资产管理、ITSM 和网络库存数据（事件、工单、资产、软件目录、耗材等）。

身份验证

Alloy Navigator 使用 OAuth2 client_credentials 授权类型对第三方应用进行身份验证。在 Alloy Navigator Settings App 的 Services > API > Applications 下注册应用账户后，系统会签发 client ID 和 client secret。此连接器通过向 <base URL>/api/token 发送 POST 请求，交换这些凭据以获取 bearer 访问令牌；之后的每个请求都会发送 Authorization: Bearer <token>。根据 Alloy Navigator 自身的文档，访问令牌有效期为 8 小时；此连接器会按凭据组缓存令牌，并在令牌即将过期时自动重新进行身份验证（参见 src/auth.ts）。

Alloy Navigator 没有固定的托管 API 端点——每个实例（无论是本地部署，还是客户自己的可自托管云租户）都部署在各自的基础 URL 上，因此此连接器需要提供全部三项信息：基础 URL、client ID 和 client secret。在网关模式下，这三项信息会通过 X-Alloy-Base-Url、X-Alloy-Client-Id 和 X-Alloy-Client-Secret 请求头按请求传入；在本地/stdio 模式下，则从 ALLOY_BASE_URL、ALLOY_CLIENT_ID 和 ALLOY_CLIENT_SECRET 中读取一次。

Alloy Navigator 的 API 模块（具体而言，此连接器使用的应用账户授权类型）要求目标实例已安装并启用 API Module。如果 client_credentials 请求返回连接错误或 404 错误，而非身份验证错误，请参阅 Alloy Navigator 自带的《Installation Guide》中的“Installing and Configuring the API Module”。

凭据范围

此信息来自供应商文档，尚未通过实时账户独立验证（原因见下文“验证”）：Alloy Navigator 的《API User's Guide》将应用账户描述为供“没有已登录用户在场时运行的第三方应用”使用的账户，并将其与常规技术人员（用户名/密码）账户区分开来；但文档没有说明如何将应用账户的读取权限限制在 Alloy Navigator 自身安全/角色配置中该账户有权查看的对象类别和字段范围以内。实际上，这意味着实际的只读保证由此连接器提供的工具界面（仅 GET，不执行工作流操作）来实现，而非凭据本身——Alloy Navigator 自身的工作流操作模型意味着，即使是技术上属于“读取”的 API 调用，也会通过同一个账户执行，而该账户的角色原则上也可能在其他地方被授予写入/工作流操作权限。客户应为此连接器创建一个权限最小化的专用应用账户，这与本工具集合中其他供应商（例如 PRTG）的建议做法一致，因为这些供应商的 API 密钥会继承创建账户的完整权限集。

验证

此连接器直接依据 Alloy Navigator 官方《API User's Guide》构建（docs.alloysoftware.com/alloynavigator/docs/api-userguide/），而非依据二手文档或命名惯例——以下每个工具都对应一个实际且有文档说明的 GET 操作，其查询参数和响应格式均根据指南中的示例逐一核实（所依据的示例来源见 src/client.ts 中每个工具的 JSDoc）。但此连接器并未通过实时 Alloy Navigator 实例进行独立验证：Alloy Navigator 未提供可公开自行申请的试用版或沙盒实例，而申请开通需要与销售/许可团队实际对接，本构建环境无法完成。这是构建环境的限制，并非供应商对已有许可证客户设置的审批门槛。

配置

环境变量	描述
ALLOY_BASE_URL	Alloy Navigator 服务的基础 URL，例如 https://alloy.example.com。
ALLOY_CLIENT_ID	应用账户客户端 ID，由 Settings App > Services > API > Applications 中签发。
ALLOY_CLIENT_SECRET	应用账户客户端密钥，与客户端 ID 一同签发。
MCP_TRANSPORT	stdio（默认）或 http。
AUTH_MODE	env（默认，读取上述变量）或 gateway（凭据通过 Conduit 网关注入的 X-Alloy-Base-Url / X-Alloy-Client-Id / X-Alloy-Client-Secret 标头按请求传入）。Docker 镜像和 Compose 文件默认使用 gateway。在网关模式下，缺少任何一个上述标头时，/mcp 都会返回 401，且不会回退到 ALLOY_*。
CONDUIT_S2S_SECRET	使用 HTTP 时必需。服务间密钥。当该值为空或为已知占位值（changeme、secret、placeholder、your-s2s-secret、replace-with-a-real-secret，以及 src/http.ts 中相同的列表）时，HTTP 服务会记录错误并以非零状态码退出。未设置时，Compose 不会启动。切勿提交真实值。进程绝不会记录该值。
MCP_ALLOW_INSECURE_DEV	仅在本地开发时，将其设为恰好 1，即可在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告、跳过 X-Gateway-S2S，并且只监听 127.0.0.1。更宽泛的 MCP_HTTP_HOST 设置会被覆盖。已知占位密钥仍会被拒绝。
MCP_HTTP_HOST	当 MCP_TRANSPORT=http 时的绑定地址。默认为 127.0.0.1。设置了 CONDUIT_S2S_SECRET 时，此值会生效，包括 0.0.0.0。容器镜像将其设为 0.0.0.0。没有密钥时，监听地址仅为 127.0.0.1。
MCP_HTTP_PORT	HTTP 端口。默认为 8080。
LOG_LEVEL	debug | info（默认）| warn | error。

/health 无需身份验证，且不会读取凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

HTTP 身份验证

设置了 CONDUIT_S2S_SECRET 且 MCP_TRANSPORT=http 时，每个 /mcp 请求都必须包含 X-Gateway-S2S。缺少或无效的标头会在读取任何供应商凭据前返回 401。

该标头是 HMAC 证明，而不是密钥的副本：

t=<unix seconds>,v1=<hex hmac-sha256>

<hex hmac-sha256> 是对 ASCII 字符串 t=<unix seconds>（使用相同的 t= 前缀和相同的十进制时间戳）计算得出的 HMAC-SHA256，以 CONDUIT_S2S_SECRET 为密钥，并编码为小写十六进制。时间戳必须在服务器时钟的 300 秒范围内。

import { createHmac } from 'node:crypto';

const secret = process.env.CONDUIT_S2S_SECRET;
const t = Math.floor(Date.now() / 1000);
const v1 = createHmac('sha256', secret).update(`t=${t}`).digest('hex');
const xGatewayS2s = `t=${t},v1=${v1}`;

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-Alloy-Base-Url、X-Alloy-Client-Id 和 X-Alloy-Client-Secret。这些标头是该请求唯一的凭据来源。

await fetch('http://127.0.0.1:8080/mcp', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    accept: 'application/json, text/event-stream',
    'x-gateway-s2s': xGatewayS2s,
    'x-alloy-base-url': 'https://alloy.example.com',
    'x-alloy-client-id': 'application-client-id',
    'x-alloy-client-secret': 'application-client-secret',
  },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
});

工具

Alloy Navigator 的 API 按类通用，而不是为每种对象类型提供一个固定的 REST 路径（例如 PRTG 的 /devices、/sensors 等）——只需一个对象类参数（Incidents、Computers、Work Orders、Consumables、SoftwareCatalog、Purchase Order Items 等）即可选择要查询的内容。此连接器的 4 个工具如实沿用这一结构，而不是虚构 Alloy Navigator 自身 API 并不具备的逐类工具。

对象

• alloy_list_objects - 列出/搜索指定对象类的对象，支持字段选择、排序、分页、全文搜索和按字段筛选。
• alloy_get_object - 通过 OID（工单编号）或数据库记录 GUID 获取单个对象的所有字段。

活动记录

• alloy_get_object_activities - 获取针对单个对象记录的活动/历史日志条目（状态变更、分配变更、系统备注）。

字典

• alloy_get_dictionary - 获取对象类中某个字段允许使用的引用/分类值（例如有效的 Status 或 Types 值）。

范围

这是一个刻意收窄、只读的 v1 接口面：4 个 GET 操作，恰好涵盖 Alloy Navigator 的通用对象查询、单个对象读取、活动/历史记录读取和引用值查找——除此之外没有其他内容。 Alloy Navigator 的 API 用户指南记录了一个规模大得多的接口面，围绕工作流操作构建（Alloy Navigator 不会直接创建或更新对象；每次变更都会作为针对某个对象的具名工作流操作执行）。本连接器按设计排除了所有这类操作，并非疏忽：

硬性排除（对象创建和变更——Alloy Navigator 的 API 模型中，所有变更都通过工作流操作执行）——从未实现： POST /object/<oid>/action/<actionId>——执行工作流操作（这是 Alloy Navigator 自己的“创建对象”文档中描述的机制，用于创建新事件、工单、资产及任何其他对象）按定义属于写入操作，因此一律排除，包括客户实例可能标记为听起来无害的任何工作流操作（例如“Acknowledge”或“Close”操作）——本连接器无法区分仅读取的操作和真正会改变状态的操作，因此不会公开任何此类操作。

硬性排除（冗余的基于 POST 的检索）——从未实现： Alloy Navigator 指南记录了对象列表和对象活动 GET 端点的 POST 变体（POST /<objectClass>、POST /Activities/<oid>），其目的是在调用方手动构造原始 URL 时绕过 URL 查询长度限制。本连接器会根据结构化工具参数在服务端构造每个请求，而非使用手动输入的 URL，因此此处无需绕过 POST 变体所针对的长度限制——实现该功能会增加一个行为相同且自身没有读写区分的第二条代码路径，因此排除它是因为冗余，而非因为范围限制。

硬性排除（用户/会话/应用管理——身份和凭据管理，不属于 ITSM/资产数据）——从未实现： 技术人员（用户名/密码）身份验证授权方式（使用 grant_type=password 的 POST /api/token）——本连接器仅使用应用账户的 client_credentials 授权方式，这是为无人值守服务集成设计的方式——以及任何用于管理应用账户、技术人员账户或会话本身的端点。

硬性排除（超出 ITSM/资产数据范围）——从未实现： GET /api/v2/GetAppConfig——用于已注册移动扫描器应用的配置（Settings App > Services > Mobile Applications），与 IT 资产/ITSM 记录数据无关，并且还要求客户事先注册移动应用。

如有需求，可在经过审慎的范围决策后作为后续功能添加——不会默认加入。

开发

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

Docker

镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。将端口发布到回环地址，并传入 S2S 密钥。在网关模式下，每个请求都会通过 X-Alloy-* 标头传入 Alloy Navigator 凭据；镜像不会从环境变量读取这些凭据。

docker build -t alloy-navigator-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  alloy-navigator-mcp

如果未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动；它会设置 AUTH_MODE=gateway，发布 127.0.0.1:8080:8080，且不会传入任何 ALLOY_* 变量：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，随后使用 ALLOY_BASE_URL、ALLOY_CLIENT_ID 和 ALLOY_CLIENT_SECRET：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e ALLOY_BASE_URL=https://alloy.example.com \
  -e ALLOY_CLIENT_ID=your-client-id \
  -e ALLOY_CLIENT_SECRET=your-client-secret \
  -p 127.0.0.1:8080:8080 \
  alloy-navigator-mcp

不带密钥的本地 HTTP 仅用于开发。它会绑定到 127.0.0.1 并记录警告。若 MCP_HTTP_HOST 设置为非回环地址，则会被覆盖为 127.0.0.1：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http