# Intune Assignment Checker MCP

A local, read-only Model Context Protocol server for inspecting and explaining Microsoft Intune assignments through Microsoft Graph `/beta`.

This repository is the TypeScript port and MCP surface. The existing PowerShell product remains separate and is the behavioral reference for assignment resolution.

[![Intune Assignment Checker MCP overview](https://raw.githubusercontent.com/ugurkocde/IntuneAssignmentChecker-MCP/main/docs/images/mcp-overview.png)](https://intuneassignmentchecker.ugurkoc.de/mcp)

Explore the installation guide and security model at
[intuneassignmentchecker.ugurkoc.de/mcp](https://intuneassignmentchecker.ugurkoc.de/mcp).

## Current implementation

The first delegated vertical slice is implemented:

- Local MCP transport over stdio.
- Interactive browser sign-in with delegated Microsoft Graph permissions.
- OS-protected persistent MSAL cache (Windows DPAPI, macOS Keychain, or Linux libsecret), with memory-only fallback if secure persistence is unavailable.
- `get_connection_status`.
- `search_policies`.
- `list_all_device_assignments` for direct All Devices policy and application targeting.
- `list_all_user_assignments` for direct All Users policy and application targeting.
- `list_unassigned_policies` for policies and applications with no assignments.
- `get_policy_assignments`.
- Strict Microsoft Graph `/beta` URL construction and continuation validation.
- Bounded calls, pages, execution time, response bytes, retries, and result sizes.
- Opaque, one-time, tenant-bound MCP cursors; raw Graph `@odata.nextLink` values never enter model context.
- Complete page records and opaque continuation cursors in both model-visible text and typed `structuredContent` for client compatibility.
- Assignment collections reconcile Graph's sometimes-stale `isAssigned` flag; duplicate policy names require stable ID-based disambiguation.
- Explicit partial-coverage and delegated-RBAC uncertainty reporting.

The one production app registration has been created, its public-client ID is
embedded, and the package is available from npm. The code contains no second
development registration. The embedded client ID also makes source builds
testable without supplying a separate registration.

## Architecture

```text
AI client
  -> local stdio MCP process
     -> MSAL delegated sign-in in the user's browser
     -> OS-protected local token cache
     -> internally generated, read-only Microsoft Graph /beta requests
```

There is no hosted MCP endpoint, Auth0 tenant, customer token database, service certificate, or server-side Graph token exchange.

## Install from npm

Requirements: Node.js 20 or newer and a supported local stdio MCP client. The
client launches the package on demand; users do not install it globally or
create an Entra app registration, client secret, or certificate.

### Claude Desktop

Open **Settings → Developer → Edit Config** and add:

```json
{
  "mcpServers": {
    "intune-assignment-checker": {
      "command": "npx",
      "args": ["-y", "intune-assignment-checker-mcp@latest"]
    }
  }
}
```

Restart Claude Desktop after saving the configuration.

### Claude Code

Add the server at user scope so it is available in every project:

```bash
claude mcp add --transport stdio --scope user intune-assignment-checker -- npx -y intune-assignment-checker-mcp@latest
```

Run `claude mcp list` or open `/mcp` inside Claude Code to verify the connection.

### ChatGPT Desktop and Codex

The ChatGPT desktop app, Codex CLI, and the Codex IDE extension share MCP
configuration on the same machine. Add the server with:

```bash
codex mcp add intune-assignment-checker -- npx -y intune-assignment-checker-mcp@latest
```

The equivalent `~/.codex/config.toml` entry is:

```toml
[mcp_servers.intune-assignment-checker]
command = "npx"
args = ["-y", "intune-assignment-checker-mcp@latest"]
```

### Cursor

Add this server to Cursor's MCP configuration:

```json
{
  "mcpServers": {
    "intune-assignment-checker": {
      "command": "npx",
      "args": ["-y", "intune-assignment-checker-mcp@latest"]
    }
  }
}
```

### VS Code

Add this server through **MCP: Add Server** or place the following in the
appropriate VS Code `mcp.json` file:

```json
{
  "servers": {
    "intune-assignment-checker": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "intune-assignment-checker-mcp@latest"]
    }
  }
}
```

### First use

Ask the client an Intune assignment question. The first functional tool call
opens Microsoft sign-in in the browser. After delegated consent, the MCP stores
the token cache under the current OS user's protection and reuses it on later
launches. Sign in or revoke the local cache explicitly with:

```bash
npx -y intune-assignment-checker-mcp@latest login
npx -y intune-assignment-checker-mcp@latest status
npx -y intune-assignment-checker-mcp@latest logout
```

ChatGPT Web and Claude.ai cannot directly launch an `npx` process on the user's
machine. This local installation path targets their desktop clients and other
local stdio MCP hosts.

## Local development

Requirements: Node.js 20 or newer. Linux secure persistence also requires a Secret Service implementation such as GNOME Keyring/libsecret.

```bash
npm install
npm run check
npm run build
```

The production client ID is embedded. `IAC_MCP_CLIENT_ID` remains available only
as an explicit override for controlled testing:

```bash
export IAC_MCP_CLIENT_ID="your-test-public-client-id"
```

Optionally pin guest or multi-tenant administrators to a specific tenant GUID:

```bash
export IAC_MCP_TENANT_ID="your-tenant-id"
```

Sign in explicitly, or let the first functional tool open sign-in:

```bash
node dist/index.js login
node dist/index.js status
node dist/index.js logout
```

For a headless session:

```bash
node dist/index.js login --device-code
```

Set `IAC_MCP_AUTO_SIGN_IN=false` if model-triggered tool calls must return `auth_required` instead of opening a browser.

### Diagnostics

The server logs to stderr only; stdout stays reserved for MCP JSON-RPC framing.
Set `IAC_MCP_LOG_LEVEL` to `debug`, `info` (default), `warn`, or `error`. The
startup line includes the running version, and every tool result carries a
correlation ID that matches a stderr entry:

```bash
export IAC_MCP_LOG_LEVEL=debug
node dist/index.js --version
```

## MCP client configuration during development

Build first, then point the client to the absolute local file:

```json
{
  "mcpServers": {
    "intune-assignment-checker": {
      "command": "node",
      "args": ["/absolute/path/to/IntuneAssignmentChecker-MCP/dist/index.js"]
    }
  }
}
```

The public `npx` configurations are documented in [Install from npm](#install-from-npm).

## The one Entra app registration

The standard path uses exactly one publisher-owned registration named **Intune Assignment Checker MCP**:

- Supported accounts: any organizational directory.
- Public/native client; no client secret or certificate.
- Delegated Graph permissions only.
- Loopback redirect URI: `http://localhost`.
- Authority: `organizations`, with `IAC_MCP_TENANT_ID` override.
- No exposed MCP API and no application Graph permissions.

The current tools request only:

- `DeviceManagementConfiguration.Read.All`
- `DeviceManagementApps.Read.All`
- `GroupMember.Read.All`

Additional delegated permissions will be added to this same registration only when the tools that use them ship. `CloudPC.Read.All` remains optional and is not part of the current consent bundle.

The publisher-only setup script is idempotent, requires the intended publisher
tenant GUID, and supports `-WhatIf`:

```powershell
./scripts/Register-IntuneAssignmentCheckerMcpApp.ps1 -TenantId '<publisher-tenant-guid>' -WhatIf
./scripts/Register-IntuneAssignmentCheckerMcpApp.ps1 -TenantId '<publisher-tenant-guid>'
```

The script refuses an unexpected tenant, another API, or application permissions,
and always converges on the exact three current read-only delegated scopes. It
does not grant customer consent. The production registration was created and
read back through Microsoft Graph `/beta`; live delegated consent and tool calls
are verified separately before package publication.

## Security and privacy boundaries

- Tokens never appear in tool arguments, tool results, stdout, or application logs.
- stdout is reserved for MCP JSON-RPC; diagnostics use stderr.
- No tool accepts a Graph URL or arbitrary Graph path.
- Graph redirects are rejected rather than followed.
- Policy, group, and filter names are untrusted data: control characters are stripped and lengths are bounded.
- Delegated Intune RBAC can silently narrow successful Graph results. Coverage reports this uncertainty; an empty result is not proof that the tenant has no matching object.
- Policy names, group names, filter rules, and other returned fields are sent by the MCP client to its configured model provider. Tokens and raw Graph payloads are not.
- Secure cache initialization never falls back to an unencrypted token file. If the OS keyring is unavailable, tokens remain in memory for that process only.

Because this is a shared multi-tenant public client, the publisher registration itself is security-critical. Its owners should use phishing-resistant MFA and privileged access controls, and changes to redirect URIs, permissions, or credentials should be monitored.

## Supported policy categories

The first slice includes configuration policies, device configurations, compliance policies, mobile applications, and managed app configuration policies. Search uses client-side matching because Intune `$filter`/`$search` behavior is inconsistent across these collections.

The live verification tenant confirmed that these collections can return `@odata.nextLink`, assignment targets are polymorphic and include assignment-filter fields, empty `value` arrays are valid, and `@odata.type` is returned automatically but rejected when placed in `$select`.

## Verification

```bash
npm run format:check
npm run lint
npm run typecheck
npm test
npm run build
npm audit
```

The tests cover URL and `/beta` enforcement, opaque cursor isolation, throttling, polymorphic targets, filter/group normalization, category contracts, and an in-memory MCP client/server exchange.

## Automated PowerShell parity

The PowerShell module remains the behavioral reference, but synchronization is
now enforced rather than assumed:

1. `Tests/Parity/Export-McpParityFixtures.ps1` in the PowerShell repository
   generates a deterministic, versioned Graph `beta` fixture.
2. PowerShell Pester tests fail when that committed fixture is stale.
3. `npm run parity:sync` vendors the fixture into this repository.
4. The TypeScript parity suite runs the same raw policies, polymorphic targets,
   filters, groups, app intents, and platform values through the MCP normalizer.
5. Cross-repository CI fails until the TypeScript result matches the current
   PowerShell result.

Run the complete local handoff from this repository with:

```bash
npm run parity:sync
npm run parity:check
npm run check
npm run build
```

The MCP workflow also checks the PowerShell `main` branch every day. In the
PowerShell GitHub repository, set the Actions variable
`IAC_MCP_REPOSITORY=ugurkocde/IntuneAssignmentChecker-MCP` after this repository
is published. If the MCP repository is private, also add an
`IAC_MCP_REPOSITORY_TOKEN` secret with read access. Until that remote exists and
the variable is configured, the PowerShell-side cross-repository job is safely
skipped; local parity and the PowerShell fixture-drift test remain active.

This automation detects and blocks behavioral drift. It deliberately does not
translate arbitrary PowerShell into TypeScript. After a reviewed version change
is released on GitHub, the npm publication is performed by the provenance-enabled
workflow documented in [RELEASING.md](RELEASING.md).