EntraID MCP Server (Microsoft Graph FastMCP)

Este projecte ofereix un servidor FastMCP modular i orientat a recursos per a interactuar amb l'API Microsoft Graph. Està dissenyat per a ser extensible, mantenible i segur, i suporta consultes avançades per a usuaris, registres d'inici de sessió, estat MFA i usuaris privilegiats.

Característiques

• Estructura modular de recursos:
  • Cada recurs (usuaris, registres d'inici de sessió, MFA, etc.) està implementat en el seu propi mòdul dins src/msgraph_mcp_server/resources/.
  • Fàcil d'extendre amb nous recursos (per exemple, grups, dispositius).
• Client Graph centralitzat:
  • Gestiona l'autenticació i la inicialització del client.
  • Compartit per a tots els mòduls de recursos.
• Operacions d'usuari complet:
  • Buscar usuaris per nom/correu electrònic.
  • Obtenir usuari per ID.
  • Llistar tots els usuaris privilegiats (membres de rols de directori).
• Ciclo de vida complet del grup i gestió de membres:
  • Crear, llegir, actualitzar i esborrar grups.
  • Afegeix/elimina membres i propietaris de grups.
  • Buscar i llistar grups i membres de grups.
• Gestió d'aplicacions i principals de servei:
  • Llistar, crear, actualitzar i esborrar aplicacions (registracions d'aplicació).
  • Llistar, crear, actualitzar i esborrar principals de servei.
  • Veure assignacions de rols d'aplicació i permisos delegats tant per a aplicacions com principals de servei.
• Operacions de registre d'inici de sessió:
  • Consultar registres d'inici de sessió d'un usuari per als últims X dies.
• Operacions MFA:
  • Obtenir l'estat MFA d'un usuari.
  • Obtenir l'estat MFA de tots els membres d'un grup.
• Gestió de contrasenyes:
  • Restablir contrasenyes d'usuaris directament amb contrasenyes personalitzades o generades automàticament.
  • Opció per requerir canvi de contrasenya a la propera inici de sessió.
• Assistent de permisos:
  • Suggereix permisos Microsoft Graph adequats per a tasques comunes.
  • Cerca i explora permisos Graph disponibles.
  • Ajudar a implementar el principi del menor privilegi recomanant només els permisos necessaris.
• Gestió d'errors i registre:
  • Gestió d'errors consistent i informe de progressos via el context FastMCP.
  • Registre detallat per a la resolució de problemes.
• • Els fitxers .env i secrets estan exclosos del control de versió.
  • Utilitza les millors pràctiques de Microsoft per a l'autenticació.

Estructura del projecte

src/msgraph_mcp_server/
├── auth/           # Lògica d'autenticació (GraphAuthManager)
├── resources/      # Mòduls de recursos (users, signin_logs, mfa, ...)
│   ├── users.py            # Operacions d'usuari (buscar, obtenir per ID, etc.)
│   ├── signin_logs.py      # Operacions de registre d'inici de sessió
│   ├── mfa.py              # Operacions d'estat MFA
│   ├── permissions_helper.py # Utilitats i suggeriments de permisos Graph
│   ├── applications.py       # Operacions d'aplicació (registració d'aplicació)
│   ├── service_principals.py # Operacions de principal de servei
│   └── ...                 # Altres mòduls de recursos
├── utils/          # GraphClient principal i altres utilitats, com generador de contrasenyes
├── server.py       # Punt d'entrada del servidor FastMCP (registra eines/recursos)
├── __init__.py     # Marcador de paquet

Ús

1. Configuració

• Clona el repositori.
• Crea un fitxer config/.env amb les teves credencials Azure AD:

  TENANT_ID=el-teu-id-de-tenant
  CLIENT_ID=el-teu-id-de-cliente
  CLIENT_SECRET=el-teu-secret-de-cliente
  

• (Opcional) Configura l'autenticació basada en certificat si cal.

2. Prova i desenvolupament

Pots provar i desenvolupar el teu servidor MCP directament amb la CLI FastMCP:

fastmcp dev '/path/to/src/msgraph_mcp_server/server.py'

Això llança un entorn de desenvolupament interactiu amb l'Inspector MCP. Per a més informació i ús avançat, consulta la documentació de FastMCP.

3. Eines disponibles

Eines d'Usuari

• search_users(query, ctx, limit=10) — Buscar usuaris per nom/correu electrònic
• get_user_by_id(user_id, ctx) — Obtenir detalls d'un usuari per ID
• get_privileged_users(ctx) — Llistar tots els usuaris en rols privilegiats del directori
• get_user_roles(user_id, ctx) — Obtenir tots els rols de directori assignats a un usuari
• get_user_groups(user_id, ctx) — Obtenir tots els grups (incloent membres transitius) d'un usuari

Eines de Grup

• get_all_groups(ctx, limit=100) — Obtenir tots els grups (amb paginació)
• get_group_by_id(group_id, ctx) — Obtenir un grup específic per ID
• search_groups_by_name(name, ctx, limit=50) — Buscar grups per nom de visualització
• get_group_members(group_id, ctx, limit=100) — Obtenir membres d'un grup per ID de grup
• create_group(ctx, group_data) — Crear un nou grup (veure més avall per camps group_data)
• update_group(group_id, ctx, group_data) — Actualitzar un grup existent (camps: displayName, mailNickname, description, visibility)
• delete_group(group_id, ctx) — Esborrar un grup per ID
• add_group_member(group_id, member_id, ctx) — Afegir un membre (usuari, grup, dispositiu, etc.) a un grup
• remove_group_member(group_id, member_id, ctx) — Eliminar un membre d'un grup
• add_group_owner(group_id, owner_id, ctx) — Afegir un propietari a un grup
• remove_group_owner(group_id, owner_id, ctx) — Eliminar un propietari d'un grup

Exemple de Creació/Actualització de Grup:

• group_data per a create_group i update_group ha de ser un diccionari amb claus com:
  • displayName (obligatori per a crear)
  • mailNickname (obligatori per a crear)
  • description (opcional)
  • groupTypes (opcional, per ex.: ["Unified"])
  • mailEnabled (opcional)
  • securityEnabled (opcional)
  • visibility (opcional, "Private" o "Public")
  • owners (opcional, llista d'IDs d'usuaris)
  • members (opcional, llista d'IDs)
  • membershipRule (obligatori per a grups dinàmics)
  • membershipRuleProcessingState (opcional, "On" o "Paused")

Consulta els docstrings de groups.py per a més detalls sobre els camps i comportaments suportats.

Eines de Registre d'Inici de Sessió

• get_user_sign_ins(user_id, ctx, days=7) — Obtenir registres d'inici de sessió d'un usuari

Eines MFA

• get_user_mfa_status(user_id, ctx) — Obtenir l'estat MFA d'un usuari
• get_group_mfa_status(group_id, ctx) — Obtenir l'estat MFA de tots els membres d'un grup

Eines de Dispositiu

• get_all_managed_devices(filter_os=None) — Obtenir tots els dispositius gestionats (opcionalment filtrar per SO)
• get_managed_devices_by_user(user_id) — Obtenir tots els dispositius gestionats d'un usuari específic

Eines de Política d'Accés Condicional

• get_conditional_access_policies(ctx) — Obtenir totes les polítiques d'accés condicional
• get_conditional_access_policy_by_id(policy_id, ctx) — Obtenir una política d'accés condicional per ID

Eines de Registre d'Auditoria

• get_user_audit_logs(user_id, days=30) — Obtenir tots els registres d'auditoria rellevants del directori per a un usuari en els últims N dies

Eines de Gest Geburt de Contrasenyes

• reset_user_password(user_id, new_password, require_change=False) — Restablir contrasenya d'un usuari directament amb contrasenya personalitzada o generada automàticament

Assistent de Permisos

• suggest_permissions(task_name) — Suggereix permisos Graph adequats per a una tasca donada
• search_graph_permissions(query) — Cerca permisos Graph disponibles

Gestió d'Errors i Registre

• handle_error(error, ctx) — Maneja errors de manera consistent i informa via context FastMCP
• log_debug(message) — Registra missatges de depuració detallats

Seguretat

• Els fitxers .env i secrets estan exclosos del control de versió.
• Utilitza les millors pràctiques de Microsoft per a l'autenticació.

License

MIT