Inforcer

Inforcer MCP Server

一个 Model Context Protocol (MCP) 服务，为 AI 助手提供对 Inforcer Microsoft 365 基线治理数据的结构化、基本只读访问，包括租户、基线、对齐/偏差、策略、安全评分、身份、审计日志和报告生成；此外，还提供两个写入操作，用于触发评估运行或排队生成报告。

注意： 本项目由 Wyre Technology 维护。

⚠ 社区整理的 API

截至撰写本文时，Inforcer 尚未发布官方 REST API 规范。本服务封装了 @wyre-technology/node-inforcer SDK，其 API 接口由社区根据 royklo/InforcerCommunity 整理。端点、字段结构和行为可能随时发生变化，恕不另行通知。请谨慎对待返回结果，并通过 Inforcer 门户核实任何关键内容。

只读范围

本服务中的所有工具均为只读，但以下两个工具除外：

• inforcer_assessments_run — 为租户触发一次评估运行。
• inforcer_reports_run — 为一个或多个租户排队生成一份或多份报告。

这两个操作均属高影响操作（但不具破坏性）：它们会在 Inforcer 中启动实际任务，且操作人员可以看到。两者都带有相应标注，并会在运行前请求确认。调用前请先征得用户确认。

本服务不包含用于创建、更新或删除策略、租户或基线的工具——社区 API 未提供这些操作，且本服务有意不予支持。

快速开始

Claude Code（CLI）：

claude mcp add inforcer-mcp \
  -e INFORCER_REGION=us \
  -e INFORCER_API_KEY=your-api-key \
  -- npx -y github:WYRE-AI/inforcer-mcp

Docker 和从源代码安装方式请参阅安装。

功能

• 🔌 MCP 协议兼容性：全面支持 MCP 工具和提示词
• 🛡️ 治理覆盖范围（只读）：租户、基线、对齐/偏差、策略、Microsoft Secure Score、Entra ID 身份和审计日志
• 🔍 决策树导航：从 inforcer_navigate 开始探索各个领域，然后调用相应领域的工具
• 🧭 灵活的租户解析：大多数工具接受 tenant，其值可以是数字形式的 Client Tenant ID、租户 DNS 名称、Azure AD GUID 或易记名称；系统会自动解析
• 🔒 安全认证：使用 Inf-Api-Key 请求头认证，并限定区域
• 🌐 双传输方式：stdio（本地）和 HTTP Streamable（网关/Docker）
• 🐳 支持 Docker：容器化部署，支持 HTTP 传输和健康检查
• 📊 结构化日志：日志级别可配置，绝不记录凭据

目录

• 安装
• 配置
• 租户标识符
• 领域和工具
• 网关连接
• Docker 部署
• 开发
• 测试
• 贡献
• 许可证

安装

选项 1：Claude Code（CLI）

claude mcp add inforcer-mcp \
  -e INFORCER_REGION=us \
  -e INFORCER_API_KEY=your-api-key \
  -- npx -y github:WYRE-AI/inforcer-mcp

选项 2：Docker

镜像在容器内监听 0.0.0.0，并默认使用 AUTH_MODE=gateway。请将端口发布到环回地址，并传入真实的 S2S 密钥。在网关模式下，Inforcer 区域和 API 密钥会通过请求头传入，不会从环境变量中读取。

docker build -t inforcer-mcp .
docker run \
  -e CONDUIT_S2S_SECRET \
  -p 127.0.0.1:8080:8080 \
  inforcer-mcp

也可以拉取预构建镜像：

docker run -d \
  -e CONDUIT_S2S_SECRET \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/inforcer-mcp:latest

Compose 会从项目的 .env 文件读取 CONDUIT_S2S_SECRET，如果该值未设置，则拒绝启动。请勿在命令行中设置该变量：空的 shell 值会覆盖 .env 中的值。

docker compose up

选项 3：从源代码安装

git clone https://github.com/WYRE-AI/inforcer-mcp.git
cd inforcer-mcp
export NODE_AUTH_TOKEN=$(gh auth token)   # to install @wyre-ai/* from GitHub Packages
npm ci
npm run build

配置

变量	必需	描述
INFORCER_REGION	stdio 和 AUTH_MODE=env 必需	Inforcer API 区域，可选值为 anz、eu、uk、us。没有默认值。Compose 网关服务不会加载此变量。
INFORCER_API_KEY	stdio 和 AUTH_MODE=env 必需	Inforcer API 密钥，通过 Inf-Api-Key 标头发送。Compose 网关服务不会加载此变量。
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose 的默认值）或 env。网关模式要求每个 /mcp 请求都包含 X-Inforcer-Region 和 X-Inforcer-API-Key，且绝不会回退到 INFORCER_*。env 仅在 S2S 身份验证成功后使用这些变量。
CONDUIT_S2S_SECRET	HTTP 必需	服务到服务密钥。使用 openssl rand -hex 32 生成。如果该值为空或为已知占位值（changeme、your-s2s-secret、secret、placeholder 以及类似的公开示例），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。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。
LOG_LEVEL	否	日志级别（debug、info、warn、error）。默认为 info。

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

在 stdio 和 AUTH_MODE=env 模式下，任何 API 调用都必须设置 INFORCER_REGION 和 INFORCER_API_KEY。工具发现（tools/list）无需这些变量；如果缺少其中任意一个，首次实际调用时会报错。

HTTP 身份验证

当 MCP_TRANSPORT=http 且已设置 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含 X-Gateway-S2S。检查逻辑位于 src/s2s-verify.ts 的 verifyS2sHeader 中：标头值格式为 t=<unix seconds>,v1=<hex>，其中十六进制值是以 CONDUIT_S2S_SECRET 为密钥、对字面字符串 t=<unix seconds> 计算得出的 HMAC-SHA256（64 个小写十六进制字符）。时间戳与服务器时钟的偏差必须在 300 秒以内。若标头缺失或无效，会在读取供应商凭据前返回 HTTP 401。

CONDUIT_S2S_SECRET 必须预先设置在环境中。示例会在进程内部读取该变量，不会将密钥作为命令参数传递。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | node -e 'const {createHmac}=require("node:crypto"); const chunks=[]; process.stdin.on("data",(c)=>chunks.push(c)); process.stdin.on("end",()=>{ const secret=process.env.CONDUIT_S2S_SECRET; if(!secret){ console.error("CONDUIT_S2S_SECRET is not set"); process.exit(1); } process.stdout.write(createHmac("sha256", secret).update(Buffer.concat(chunks)).digest("hex")); });')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H 'X-Inforcer-Region: us' \
  -H "X-Inforcer-API-Key: $INFORCER_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-Inforcer-Region 和 X-Inforcer-API-Key。这些标头是此请求唯一的凭据来源。在 AUTH_MODE=env 模式下，已签名请求会使用环境中的 INFORCER_REGION 和 INFORCER_API_KEY。

租户标识符

Inforcer 的租户范围路由使用整数 Client Tenant ID，它与 Azure AD 租户 GUID（msTenantId）并不相同。为方便使用工具，tenant 参数接受以下任意一种：

• 数字形式的 Client Tenant ID（例如 42），
• 租户 DNS 名称（例如 contoso.onmicrosoft.com），
• Azure AD 租户 GUID（msTenantId），或
• 易记名称（例如 Contoso）。

每次调用租户范围的接口前，SDK 都会通过 resolveTenantId 将名称、DNS 名称或 GUID 解析为数字形式的 Client Tenant ID。如果名称匹配多个租户，调用会失败并显示清晰的“ambiguous”（有歧义）错误；请改用数字形式的 Client Tenant ID。使用 inforcer_tenants_resolve 可查看输入具体对应哪个 Client Tenant ID。

域和工具

服务器使用决策树导航。使用 inforcer_navigate 选择一个域，或直接调用任何工具。除 inforcer_assessments_run 和 inforcer_reports_run 外，所有工具均为只读。

域	工具	只读
navigation	inforcer_navigate、inforcer_status（实时 baselines.list() 连通性检查）	✅
tenants	inforcer_tenants_list、inforcer_tenants_get、inforcer_tenants_resolve	✅
baselines	inforcer_baselines_list	✅
alignment	inforcer_alignment_scores、inforcer_alignment_details（按租户查看偏差）	✅
policies	inforcer_policies_list（按租户）	✅
secure-scores	inforcer_secure_scores_get（按租户）	✅
identity	inforcer_users_list、inforcer_users_get、inforcer_groups_list、inforcer_groups_get、inforcer_roles_list	✅
audit	inforcer_audit_event_types、inforcer_audit_search	✅
assessments	inforcer_assessments_list（✅）、inforcer_assessments_run（⚠ 高影响，非只读）	混合
reports	inforcer_reports_types_list、inforcer_reports_runs_list、inforcer_reports_run_status、inforcer_reports_download_output（✅）、inforcer_reports_run（⚠ 高影响，非只读）	混合

inforcer_reports_run 会异步排队执行 — 使用 inforcer_reports_run_status 轮询运行状态，直到 isTerminal: true，然后使用 inforcer_reports_download_output 获取每个输出（返回经过 base64 编码的文件内容）。

网关连接

在 WYRE MCP Gateway 后托管时，设置 AUTH_MODE=gateway 和 MCP_TRANSPORT=http。在此模式下，服务器为无状态（每个请求都会创建新的 MCP 服务和传输），并从网关注入的每个请求的 HTTP 标头中读取凭据。缺少任一标头的请求会收到 HTTP 401，且不会回退使用 INFORCER_REGION 或 INFORCER_API_KEY。

标头	映射到
X-Gateway-S2S	HTTP authentication 中所述的 HMAC 证明。当设置了 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含此标头。
X-Inforcer-Region	INFORCER_REGION
X-Inforcer-API-Key	INFORCER_API_KEY

容器镜像默认使用 MCP_TRANSPORT=http 和 AUTH_MODE=gateway。/health 始终返回 200，无需身份验证，也不会读取供应商凭据。

Docker 部署

参见 docker-compose.yml。仓库中提交的 Compose 服务为网关模式。它发布 127.0.0.1:8080:8080，要求设置 CONDUIT_S2S_SECRET，且不设置 INFORCER_REGION、INFORCER_API_KEY 或 env_file。

cp .env.example .env
# Set CONDUIT_S2S_SECRET in .env (openssl rand -hex 32). Leave INFORCER_* empty
# for the gateway service; those credentials arrive as request headers.
# Compose loads .env itself. Do not prefix the command with a shell assignment.
docker compose up -d

单租户 HTTP（AUTH_MODE=env）仍要求设置 S2S 密钥，然后使用 INFORCER_REGION 和 INFORCER_API_KEY。它与网关 Compose 服务相互独立：

docker run \
  -e CONDUIT_S2S_SECRET \
  -e AUTH_MODE=env \
  -e INFORCER_REGION=us \
  -e INFORCER_API_KEY=your-key \
  -p 127.0.0.1:8080:8080 \
  inforcer-mcp

不使用密钥的本地 HTTP 仅限开发环境。它只绑定到 127.0.0.1，并会记录警告。非环回地址的 MCP_HTTP_HOST 会被忽略，并记录此覆盖情况：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

开发

export NODE_AUTH_TOKEN=$(gh auth token)
npm ci
npm run build       # Build the project
npm run dev         # Watch mode
npm run test        # Run tests
npm run lint        # Type-check
npm run clean       # Remove dist/

# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 npm run start:http

测试

npm test            # Run test suite
npm run test:watch  # Watch mode

贡献

参见 CONTRIBUTING.md 了解指南。

许可证

Apache 2.0 — 版权所有 WYRE Technology