{
  "markdown": "# EntraPulse Polyarchy\n\n**An interactive Microsoft Entra ID identity relationship visualization, served as an MCP App.**\n\n[![npm](https://img.shields.io/npm/v/entrapulse-polyarchy)](https://www.npmjs.com/package/entrapulse-polyarchy)\n[![npm downloads](https://img.shields.io/npm/dm/entrapulse-polyarchy)](https://www.npmjs.com/package/entrapulse-polyarchy)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n![EntraPulse Polyarchy — live identity relationship graph rendered inside an MCP client](https://raw.githubusercontent.com/darrenjrobinson/entrapulse-polyarchy/main/entrapulse-polyarchy-mcp.jpg)\n\nIn 2003 Microsoft demoed *PolyArchy Server* — a web visual over identity data showing\nintersecting relationship hierarchies, where clicking a datapoint flipped the whole view\nto that context. It never shipped. This is it, finally real: a live D3 force-graph over\nyour Entra ID tenant that renders **inside your MCP client** (Claude Desktop, VS Code\nCopilot, M365 Copilot, ChatGPT, Cursor, Goose, Postman — anything that supports the\n[MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) extension).\n\nAsk your assistant *\"show me the identity polyarchy around Rebecca\"* and explore:\n\n- **Org** — manager chains and direct reports\n- **Groups** — memberships, and group fan-out to members\n- **Attributes** — pivot hubs linking everyone who shares a value: pick from the\n  common defaults (department, office, city…) or type ahead into the full Graph\n  attribute catalog, including nested paths like\n  `onPremisesExtensionAttributes/extensionAttribute9`\n- **Access** — directory roles and app assignments\n\nPrefer data over pictures? `polyarchy-report` returns the same relationships as\nstructured JSON — manager chain, group memberships with type and assigned/dynamic,\nroles, app assignments — for the assistant to reason over, no UI required.\n\n## Exploring\n\n- **Click** a node to open its profile panel (photo, attributes, manager chain link).\n- **Double-click** any node — or use the panel's *Set as focus* button — to flip the\n  whole context to it: hop distances re-anchor, the view glides to center, and its\n  relationships load. The original PolyArchy interaction.\n- **Reset** (toolbar) clears the canvas for a fresh lineage without losing anything:\n  everything fetched this session stays cached, so re-exploring the same people,\n  groups or cohorts rebuilds instantly with **zero extra Graph calls**. The status\n  bar shows when a neighbourhood was served from cache.\n- **Expand / Minimise** (toolbar) toggles the app between fullscreen and its inline\n  card. The automatic fullscreen claim happens only when a polyarchy opens, so this\n  is the way back to full canvas after minimising in the host. Hidden on hosts\n  without fullscreen support.\n- **Legend** checkboxes filter relationship kinds and object types in place.\n\nThe graph accumulates across dimensions: one intersecting polyarchy, not four separate\ncharts. **People** are shaded by degrees of separation from the focus (blue ramp);\n**groups, roles, apps and attribute hubs** wear the colour of the relationship that\nconnects them — matching their edges — faded with distance so the hop cue survives.\nLight and dark theme follow your MCP client.\n\n## Install (Claude Desktop example)\n\n```json\n{\n  \"mcpServers\": {\n    \"entrapulse-polyarchy\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"entrapulse-polyarchy\"]\n    }\n  }\n}\n```\n\nThat's it for most tenants — **no app registration needed**. Be aware of what that\nmeans: with no configuration the server signs you in through **Microsoft's first-party\n\"Microsoft Graph Command Line Tools\" public client**\n(client ID `14d82eec-204b-4c2f-b7e8-296a70dab67e`) — the same well-known app the Graph\nPowerShell/CLI tooling uses. It exists in every tenant and already has broad delegated\nconsent in many. Hardened environments commonly block or restrict this app (Conditional\nAccess, consent policies, or app management restrictions) — if that's your tenant, use\n[your own app registration](#hardened-tenants-bring-your-own-app-registration) instead;\neverything else works identically.\n\nSign-in happens on the first tool call — and then never again:\n\n- Tokens persist in your **OS keychain** (DPAPI/Keychain/libsecret).\n- The signed-in account is remembered in `~/.entrapulse-polyarchy/auth-record.json`,\n  so **freshly spawned server processes sign in silently** — MCP clients respawn stdio\n  servers freely, and none of those spawns re-prompt.\n- Token acquisition is **single-flighted and cached in-process**: a focus flip fires a\n  dozen-plus concurrent Graph calls (expansion + photos), and they all share one token\n  request instead of racing the MSAL cache.\n- Every auth event is mirrored to `~/.entrapulse-polyarchy/auth.log` with timings\n  (silent acquisitions are milliseconds; anything interactive is obvious) — the first\n  place to look if you ever see a prompt you didn't expect.\n\n## Auth modes\n\n| Mode | Configure | Notes |\n|---|---|---|\n| **Interactive** (default) | nothing — or `TENANT_ID` + `CLIENT_ID` to use your own app | System browser sign-in (random loopback port — register `http://localhost` portless); delegated permissions; `/me` is the default focus |\n| **Device code** | `USE_DEVICE_CODE=true` | Headless/SSH — code printed to the server log |\n| **App-only** | `TENANT_ID` + `CLIENT_ID` + `CLIENT_SECRET` | Application permissions; no `/me`, so always pass a person to `visualize-identity` / `polyarchy-report` |\n| **Client-provided token** | `USE_CLIENT_TOKEN=true` (+ optional `ACCESS_TOKEN`) | The MCP client supplies/refreshes a Graph bearer token via the `set-access-token` tool — seamless SSO for hosts like EntraPulse that already hold one |\n\nOther env vars: `POLYARCHY_DISABLE_TOKEN_CACHE=true` disables OS-keychain token\npersistence; `POLYARCHY_AUTH_RECORD=<path>` relocates the persisted sign-in record\n(delete the file to force a fresh sign-in).\n\n### Permissions (delegated)\n\n| Scope | Used for |\n|---|---|\n| `User.Read.All` | org hierarchy, search, attribute pivots |\n| `Group.Read.All` | group memberships and members |\n| `RoleManagement.Read.Directory` | directory roles |\n| `Application.Read.All` | app assignments |\n\nThe default first-party client typically has broad delegated consent already. Missing\nconsent shows up as a clear 403 message naming the scope — ask your assistant to run\n`get-auth-status` to see exactly which app registration, scopes and account your token\ncontains.\n\nScopes and directory roles are separate gates: the token must always carry the scopes\nabove (an admin role can't substitute for them), while on the user side plain member\ndefault permissions cover everything this app reads — no admin role required. Only\ntenants that restrict default user read access (or guest users) need a role that\nincludes directory read, for which **Directory Readers** is the least-privileged fit.\n\n### Hardened tenants: bring your own app registration\n\nIf the Graph Command Line Tools app is blocked, unconsented, or you simply want an\napp you control (own Conditional Access targeting, own consent trail), point the server\nat your own registration — supported in both interactive and device-code modes:\n\n1. **Entra admin center → App registrations → New registration** — single tenant is fine.\n2. **Authentication → Add a platform → Mobile and desktop applications** — add redirect\n   URI **`http://localhost`** (no port!), and enable **Allow public client flows** if you\n   want device-code sign-in. The port matters: interactive sign-in listens on a **random\n   loopback port** each time (e.g. `http://localhost:51106`), and Entra only ignores the\n   port when the registered redirect is the portless `http://localhost`. Registering a\n   fixed port like `:3000`, or reusing an app that only has web redirects (Graph\n   Explorer, for instance), fails with a reply-URL mismatch.\n3. **API permissions → Microsoft Graph → Delegated** — add the four scopes from the\n   table above, then **Grant admin consent**.\n4. Configure the server with your IDs:\n\n```json\n{\n  \"mcpServers\": {\n    \"entrapulse-polyarchy\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"entrapulse-polyarchy\"],\n      \"env\": {\n        \"TENANT_ID\": \"<your-tenant-guid>\",\n        \"CLIENT_ID\": \"<your-app-registration-client-id>\"\n      }\n    }\n  }\n}\n```\n\nSetting `TENANT_ID` alone (without `CLIENT_ID`) is also useful on its own: it pins\nsign-in to your tenant instead of the `common` endpoint, which multi-tenant users and\nguest accounts often want regardless of which client app is used.\n\n## Attribute pivots\n\nThe Attributes view groups people around shared values. The toolbar picker offers the\neveryday pivots (Department, Job title, Company, Office, City, State, Employee type),\nplus **Other attributes…** which opens a type-ahead over the full Graph user-attribute\ncatalog — all fifteen `onPremisesExtensionAttributes`, `employeeOrgData/costCenter`,\n`onPremisesSamAccountName`, `employeeId` and ~50 more. Matching is forgiving (`ext9`\nfinds `extensionAttribute9`), free text is accepted for anything uncatalogued, and\nattributes you pick join the dropdown for the rest of the session. Nested paths are\nresolved server-side: the needed property is `$select`ed on demand and cohort filters\nuse Graph advanced queries, with attribute paths validated before they reach an OData\nfilter.\n\n## Tools\n\n| Tool | Purpose |\n|---|---|\n| `visualize-identity` | Open the polyarchy focused on you, or `{search: \"name\"}` / `{userId}`. Ambiguous names don't guess: the tool returns the candidates (with object ids) so the assistant can ask which one you meant, then re-call with `userId`. A GUID passed as `search` is treated as an object id directly |\n| `polyarchy-expand` | Relationships for one node as a nodes/edges delta (org/groups/access/attributes; group/role members; attribute cohorts — `attr` accepts nested paths). The full delta — every node with object id, and group type / assigned-vs-dynamic for groups — is returned to the caller; it does not redraw an already-open canvas (the UI fetches its own data on interaction) |\n| `polyarchy-search` | Find people by name/UPN — returns each match with UPN, title/department and object id |\n| `polyarchy-report` | Structured JSON report of a user's relationships, no UI needed: full manager chain + direct reports, group memberships (with group type and assigned/dynamic), directory roles, app assignments, core attributes — pick `dimensions` or take `all` |\n| `set-access-token` / `get-auth-status` | Token passthrough + auth diagnostics |\n\n(`get-photo` and `get-manager` also exist but are visible only to the app UI, not the model.)\n\n## Development\n\n```bash\nnpm install\nnpm run build        # tsc (server → build/server) + vite single-file (UI → build/ui/mcp-app.html)\nnpm start            # run the server on stdio\n```\n\nTest interactively with the [MCPJam inspector](https://github.com/MCPJam/inspector) or any\nMCP Apps-capable host pointed at `node build/server/index.js`. The UI is one\nself-contained HTML file (D3 inlined) satisfying the MCP Apps default CSP — the iframe\nmakes zero network calls; all Graph traffic flows through the server via `tools/call`.\n\n### Releasing\n\n```bash\nnpm version patch    # bumps package.json + server.json (synced automatically) and tags\ngit push --follow-tags\n```\n\nThe tag triggers `.github/workflows/release.yml`, which publishes to npm (Trusted\nPublishing — OIDC, provenance attested, no tokens) and then to the MCP registry\n(`mcp-publisher login github-oidc`). No secrets are stored in the repo or in Actions.\n\n## Origin story\n\nMicrosoft demoed PolyArchy Server at TechEd 2003 and never shipped it. In 2017 Darren\napproximated it with MIM + Power BI + Journey Chart\n([blog post](https://blog.darrenjrobinson.com/graphically-visualizing-identity-hierarchy-and-relationships/)).\nIn 2026, MCP Apps made the real thing possible — an identity polyarchy living inside\nwhatever AI client you already use, part of the [EntraPulse](https://github.com/darrenjrobinson) family.\n\nMIT licensed.\n",
  "bytes": 12035,
  "sha": "55bf288a82efc6ac6e644498f9fdcdb513b4dcbf52bd3b0829ee6d39ace6cab6",
  "repo_slug": "darrenjrobinson/entrapulse-polyarchy",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_darrenjrobinson_entrapulse_pol_b10e6f20/readme"
}