Action1

Action1 MCP 服务

用于 Action1 的 MCP 服务——通过 Model Context Protocol 实现端点清单、补丁可见性和策略自动化。

v1 版本为只读。出于爆炸半径方面的考虑，部署／自动化功能有意留待后续版本推出（错误的策略推送可能导致整个端点群组无法使用）。

工具

工具	说明
action1_navigate	按领域发现可用工具（organizations / endpoints / policies / updates）
action1_list_organizations	列出配置的凭据可访问的 Action1 租户
action1_list_endpoints	列出组织中的受管设备
action1_get_endpoint	按 ID 获取单个端点
action1_list_missing_updates	列出所有端点缺少的 OS／应用程序补丁——这是 Action1 的核心价值主张
action1_list_policies	列出自动化／策略／修复规则

API 功能对应 PSAction1（Action1 采用 MIT 许可证的 PowerShell 模块）。待 v1 功能证明其价值后，v2 将在单独审核后加入写入工具（部署、重新查询、软件包上传）。

交互式设备卡片（MCP Apps）

在 MCP Apps 宿主（Claude Desktop/web）中，action1_get_endpoint 会呈现为交互式设备摘要卡片，一目了然地展示状态、OS、用户、IP、Agent 版本、是否需要重启以及缺少的更新数量；在其他宿主中，纯 JSON 行为保持不变。该卡片为只读（与 v1 工具功能相符），默认采用中性样式，也可通过注入 window.__BRAND__ 或设置 MCP_BRAND_* 环境变量（MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、MCP_BRAND_TEXT）进行品牌定制——无需重新构建。

用法

Claude Desktop（MCPB）

通过最新版本中的 MCPB 安装包进行安装。

所需凭据（在 Action1 → Settings → API Credentials 中创建，创建后无法恢复——请立即复制）：

• API Key（Client ID）
• Secret
• Region（默认为 NorthAmerica；也支持 NorthAmerica-2、Europe、Australia）
• 可选的默认组织 ID（用于单租户场景）

Stdio（直接运行）

ACTION1_API_KEY=... \
ACTION1_SECRET=... \
ACTION1_REGION=NorthAmerica \
ACTION1_DEFAULT_ORG_ID=org-... \
npx -y github:WYRE-AI/action1-mcp

HTTP

必须设置 CONDUIT_S2S_SECRET。如果该值为空或是已知占位符（如 changeme、replace-with-a-real-secret），HTTP 服务会记录错误并以非零状态码退出。服务绝不会打印该密钥。使用 openssl rand -hex 32 生成密钥。

未设置 MCP_HTTP_HOST 时，默认值为 127.0.0.1。仅当设置了 CONDUIT_S2S_SECRET 时，才应将其设为 0.0.0.0。容器镜像会这样设置，并将 AUTH_MODE=gateway。MCP_HTTP_PORT（或 PORT）用于选择端口，默认值为 8080。

设置 MCP_ALLOW_INSECURE_DEV=1 时，可在未设置 CONDUIT_S2S_SECRET 的情况下启动 HTTP 服务；服务会记录警告、跳过 X-Gateway-S2S，并且仅绑定到 127.0.0.1。如果 MCP_HTTP_HOST 不是环回地址（包括 0.0.0.0），服务将拒绝启动。占位符密钥仍会被拒绝。仅用于本地开发。

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

X-Gateway-S2S

配置密钥后，除 /health 外的每个 HTTP 请求都必须包含 X-Gateway-S2S。其值为 t=<unix seconds>,v1=<hex>，其中 hex 是以 CONDUIT_S2S_SECRET 为密钥，对字面字符串 t=<unix seconds> 计算出的 HMAC-SHA256（64 个小写十六进制字符）。时间戳与服务器时钟的偏差必须在 300 秒以内。缺少标头或标头无效时，将返回 HTTP 401，且此时尚未读取供应商凭据。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-Action1-API-Key: $ACTION1_API_KEY" \
  -H "X-Action1-Secret: $ACTION1_SECRET" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

网关模式（AUTH_MODE=gateway）

Docker 镜像和 Compose 文件默认使用网关模式。每个请求都必须包含：

• X-Action1-API-Key
• X-Action1-Secret
• X-Action1-Region（可选）
• X-Action1-Default-Org-Id（可选）

如果请求缺少 API 密钥或 Secret，将返回 401，且不会回退使用进程环境中的 ACTION1_API_KEY / ACTION1_SECRET。这些标头是该请求唯一的凭据来源。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/action1-mcp:latest

如果未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动；它会发布 127.0.0.1:8080:8080，且不会将静态 Action1 凭据传入容器：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）

请求仍须包含有效的 X-Gateway-S2S 标头。如果请求未携带相应标头，供应商凭据将从 ACTION1_API_KEY 和 ACTION1_SECRET 获取。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e ACTION1_API_KEY="$ACTION1_API_KEY" \
  -e ACTION1_SECRET="$ACTION1_SECRET" \
  -e ACTION1_REGION=NorthAmerica \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/action1-mcp:latest

不带 Secret 的本地 HTTP 仅用于开发环境。它绑定到 127.0.0.1，并会记录警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

架构

src/
├── index.ts                  # stdio + HTTP transports, tool dispatch, S2S startup
├── s2s-verify.ts             # X-Gateway-S2S HMAC-SHA256 check
├── card.builder.ts           # MCP Apps device-card normalization + brand injection
├── resources.ts              # resources/list + resources/read (ui:// device card)
├── generated/
│   └── device-card-html.ts   # committed vite single-file bundle (npm run build:ui)
├── sdk/
│   └── action1-client.ts     # embedded REST + OAuth client (factor-out candidate
│                             # if surface crosses ~20 tools / 2+ domains)
├── utils/
│   ├── client.ts             # credential resolution (env vs gateway headers)
│   └── types.ts              # DomainHandler interface
├── domains/                  # one file per resource type
│   ├── organizations.ts
│   ├── endpoints.ts
│   ├── policies.ts
│   └── updates.ts
└── __tests__/                # domain tests + MCP Apps contract tests
ui/                           # device-card source (index.html + device-card.ts)

通过 AsyncLocalStorage 隔离每个请求的凭据——在 HTTP 模式下，并发请求绝不会通过 process.env 共享凭据。

开发

npm install
npm run build
npm test
npm run dev      # tsc --watch
npm run lint     # eslint
npm run typecheck

许可证

Apache-2.0。参见 LICENSE。