entrapulse-polyarchy

EntraPulse Polyarchy

以 MCP App 形式提供的 Microsoft Entra ID 身份关系交互式可视化工具。

2003 年，Microsoft 演示了 PolyArchy Server——一种将身份数据可视化的网页，展示相互交织的关系层级；点击某个数据点，整个视图就会切换到该上下文。它最终未能发布。如今，它终于成为现实：一个实时 D3 力导向图，展示你的 Entra ID 租户，并在你的 MCP 客户端中呈现（Claude Desktop、VS Code Copilot、M365 Copilot、ChatGPT、Cursor、Goose、Postman——以及任何支持 MCP Apps 扩展的客户端）。

向助手询问 “显示 Rebecca 周围的身份多层关系图”，然后开始探索：

• 组织 — 汇报关系链和直接下属
• 组 — 成员身份，以及组到成员的展开关系
• 属性 — 连接所有共享某个值对象的枢纽：可从常用默认项（部门、办公室、城市……）中选择，也可在完整的 Graph 属性目录中输入搜索，包括 onPremisesExtensionAttributes/extensionAttribute9 等嵌套路径
• 访问权限 — 目录角色和应用分配

相比图形，你更喜欢数据？polyarchy-report 会以结构化 JSON 返回相同的关系——汇报关系链、包含类型以及已分配/动态状态的组成员关系、角色和应用分配——供助手分析，无需 UI。

探索

• 单击节点可打开其个人资料面板（照片、属性、汇报关系链链接）。
• 双击任意节点，或使用面板中的 设为焦点 按钮，即可将整个上下文切换到该节点：跳数距离会重新锚定，视图平滑移至中心，并加载该节点的关系。这就是 PolyArchy 最初的交互方式。
• 重置（工具栏）会清空画布，方便重新探索关系链，且不会丢失任何内容：本次会话中获取的所有数据都会保留在缓存中，因此重新探索相同的人、组或群体时，可立即重建视图，无需额外调用 Graph。状态栏会显示邻域数据是否来自缓存。
• 展开 / 最小化（工具栏）可在全屏视图和内嵌卡片之间切换应用。只有打开多层关系图时才会自动请求全屏，因此在宿主中最小化后，可通过此功能返回完整画布。不支持全屏的宿主中会隐藏此选项。
• 图例复选框可就地筛选关系类型和对象类型。

图表会跨维度累积：形成一张相互交织的多层关系图，而非四张独立图表。人员根据与焦点的分离度着色（蓝色渐变）；组、角色、应用和属性枢纽则采用连接它们的关系颜色——与对应边的颜色一致——并随距离增加而淡化，以保留跳数提示。浅色和深色主题会跟随你的 MCP 客户端。

安装（Claude Desktop 示例）

{
  "mcpServers": {
    "entrapulse-polyarchy": {
      "command": "npx",
      "args": ["-y", "entrapulse-polyarchy"]
    }
  }
}

对于大多数租户来说，到这里就可以了——无需注册应用。请注意，这意味着：在未配置的情况下，服务会通过 Microsoft 的第一方“Microsoft Graph Command Line Tools”公共客户端（客户端 ID 14d82eec-204b-4c2f-b7e8-296a70dab67e）为你登录——这也是 Graph PowerShell/CLI 工具使用的那个知名应用。每个租户中都存在此应用，而且许多租户已经授予它广泛的委派同意。强化安全的环境通常会阻止或限制此应用（条件访问、同意策略或应用管理限制）——如果你的租户属于这种情况，请改用自己的应用注册；其他功能的工作方式完全相同。

首次调用工具时会进行登录——之后不再需要：

• 令牌会保存在你的 OS 密钥链（DPAPI/Keychain/libsecret）中。
• 已登录的帐户会记录在 ~/.entrapulse-polyarchy/auth-record.json 中，因此新启动的服务进程可以静默登录——MCP 客户端可以自由重启 stdio 服务，而这些进程启动时都不会再次提示登录。
• 令牌获取会在进程内合并为单个请求并缓存：切换焦点会触发十多个并发 Graph 调用（扩展 + 照片），它们会共享一个令牌请求，而不会争抢 MSAL 缓存。
• 每个身份验证事件都会连同耗时记录到 ~/.entrapulse-polyarchy/auth.log 中（静默获取只需几毫秒；任何交互式操作都很明显）——如果你遇到意料之外的提示，这是首先要查看的地方。

身份验证模式

模式	配置	说明
交互式（默认）	无需配置——或设置 TENANT_ID + CLIENT_ID 以使用自己的应用	通过系统浏览器登录（随机环回端口——注册时使用不带端口的 http://localhost）；委派权限；默认焦点为 /me
设备代码	USE_DEVICE_CODE=true	无头环境/SSH——代码会打印到服务日志中
仅应用	TENANT_ID + CLIENT_ID + CLIENT_SECRET	应用程序权限；不支持 /me，因此始终需要向 visualize-identity / polyarchy-report 传入人员
客户端提供令牌	USE_CLIENT_TOKEN=true（+ 可选的 ACCESS_TOKEN）	MCP 客户端通过 set-access-token 工具提供/刷新 Graph bearer 令牌——对于已持有令牌的 EntraPulse 等主机，可实现无缝 SSO

其他环境变量：POLYARCHY_DISABLE_TOKEN_CACHE=true 会禁用 OS 密钥链令牌持久化；POLYARCHY_AUTH_RECORD=<path> 会更改持久化登录记录的位置（删除该文件可强制重新登录）。

权限（委派）

范围	用途
User.Read.All	组织层级、搜索、属性交叉查询
Group.Read.All	组成员身份和成员
RoleManagement.Read.Directory	目录角色
Application.Read.All	应用分配

默认的第一方客户端通常已经获得广泛的委派同意。缺少同意时，会显示清晰的 403 消息并指出所需范围——请让助手运行 get-auth-status，查看令牌中具体包含的应用注册、范围和帐户。

范围和目录角色是相互独立的门槛：令牌必须始终包含上述范围（管理员角色不能替代这些范围）；而在用户端，普通成员的默认权限足以涵盖此应用读取的所有内容——无需管理员角色。只有限制默认用户读取权限的租户（或来宾用户）才需要具备目录读取权限的角色，其中权限最低的合适角色是 Directory Readers。

高度保护的租户：使用自己的应用注册

如果 Graph Command Line Tools 应用被阻止、未获得同意，或者你只是想使用自己控制的应用（自行设置条件访问目标、自行保留同意记录），可以让服务指向自己的应用注册——交互模式和设备代码模式均支持：

1. Entra 管理中心 → 应用注册 → 新注册——单租户即可。
2. 身份验证 → 添加平台 → 移动和桌面应用程序——添加重定向 URI http://localhost（不带端口！）；如果要使用设备代码登录，请启用 允许公共客户端流。端口很重要：每次交互式登录都会监听一个随机环回端口（例如 http://localhost:51106），而 Entra 只有在注册的重定向 URI 是不带端口的 http://localhost 时才会忽略端口。注册固定端口（例如 :3000），或重复使用只有 Web 重定向 URI 的应用（例如 Graph Explorer），都会因回复 URL 不匹配而失败。
3. API 权限 → Microsoft Graph → 委派的权限——添加上表中的四个范围，然后授予管理员同意。
4. 使用你的 ID 配置服务：

{
  "mcpServers": {
    "entrapulse-polyarchy": {
      "command": "npx",
      "args": ["-y", "entrapulse-polyarchy"],
      "env": {
        "TENANT_ID": "<your-tenant-guid>",
        "CLIENT_ID": "<your-app-registration-client-id>"
      }
    }
  }
}

单独设置 TENANT_ID（不设置 CLIENT_ID）也很有用：它会将登录固定到你的租户，而不是 common 终结点。无论使用哪个客户端应用，多租户用户和来宾帐户通常都会希望这样做。

属性维度

“属性”视图会根据共享属性值对人员进行分组。工具栏选择器提供常用维度（Department、Job title、Company、Office、City、State、Employee type），以及 其他属性…，后者会打开一个可对完整 Graph 用户属性目录进行即时搜索的选择器——包括全部十五个 onPremisesExtensionAttributes、employeeOrgData/costCenter、onPremisesSamAccountName、employeeId 等约 50 个属性。匹配方式较为宽松（输入 ext9 可找到 extensionAttribute9），对于目录中未列出的属性也接受自由文本；你选择的属性会在本次会话剩余时间内加入下拉列表。嵌套路径由服务端解析：按需对所需属性使用 $select，并使用 Graph 高级查询进行群组筛选；属性路径会在进入 OData 筛选器之前通过验证。

工具

工具	用途
visualize-identity	打开以你为中心的 polyarchy，或使用 {search: "name"} / {userId}。名称有歧义时不会猜测：工具会返回候选项（含对象 ID），以便助手询问你指的是哪一个，然后使用 userId 再次调用。作为 search 传入的 GUID 会直接视为对象 ID
polyarchy-expand	返回单个节点的关系，作为节点/边增量（组织/群组/访问权限/属性；群组/角色成员；属性群组——attr 支持嵌套路径）。完整增量——每个节点都带有对象 ID，群组还包含群组类型和分配型或动态型标记——会返回给调用方；它不会重绘已打开的画布（UI 会在交互时自行获取数据）
polyarchy-search	按姓名/UPN 查找人员——返回每个匹配项的 UPN、职务/部门和对象 ID
polyarchy-report	以结构化 JSON 格式报告用户关系，无需 UI：完整的经理链和直接下属、群组成员身份（含群组类型及分配型/动态型标记）、目录角色、应用分配、核心属性——可选择 dimensions 或获取 all
set-access-token / get-auth-status	令牌透传 + 身份验证诊断

（get-photo、get-app-logo 和 get-manager 也存在，但仅对应用 UI 可见，模型不可见。它们会为用户和 Microsoft 365 群组节点提供照片，并为应用节点提供徽标。）

开发

npm install
npm run build        # tsc (server → build/server) + vite single-file (UI → build/ui/mcp-app.html)
npm start            # run the server on stdio

使用 MCPJam 检查器 或任何支持 MCP Apps 的宿主进行交互式测试，并将其指向 node build/server/index.js。UI 是一个自包含的 HTML 文件（内联 D3），符合 MCP Apps 默认 CSP 的要求——iframe 不会发起任何网络请求；所有 Graph 流量都通过服务经由 tools/call 传输。

发布

npm version patch    # bumps package.json + server.json (synced automatically) and tags
git push --follow-tags

此标签会触发 .github/workflows/release.yml，先发布到 npm（可信发布 — OIDC，已附带来源证明，无需令牌），然后发布到 MCP 注册表（mcp-publisher login github-oidc）。仓库和 Actions 中均不存储机密。

起源

Microsoft 在 TechEd 2003 上演示了 PolyArchy Server，但从未正式发布。2017 年，Darren 用 MIM + Power BI + Journey Chart 对其进行了近似实现 （博客文章）。 2026 年，MCP Apps 让真正实现这一构想成为可能——一个身份多头治理系统，存在于你已在使用的任意 AI 客户端中，也是 EntraPulse 系列的一员。

采用 MIT 许可。