Serveur MCP

Le serveur Power Portals Pro MCP donne aux assistants de codage IA une connaissance directe de ce framework pendant la construction. C’est un serveur Model Context Protocol , il est livré avec le framework, et il n’y a pas de clé de licence ni de quoi s’inscrire.

Pourquoi il existe

Deux choses qu’un agent ne peut pas obtenir uniquement avec la documentation, et les deux provoquent un code cassé :

Ce qu’il répond

Note

Tous les outils Dataverse lisent les métadonnées. Aucun d’eux ne lit, écrit ou supprime un enregistrement, donc pointer un agent vers un environnement de production lui permet d’apprendre la forme de vos données sans pouvoir y toucher.

L’ajouter à un projet

Deux endroits où il peut vivre

Il y a ici un jeu de la poule et de l’œuf qui mérite d’être explicite. Les modèles écrivent la configuration dans le projet qu’ils créent — mais le serveur est à son meilleur niveau avant que ce projet n’existe, lorsque vous choisissez un modèle et ses options. Installez-le donc une fois pour vous-même, et laissez le fichier par projet prendre le relais.

Une fois par machine, pour n’importe quel dossier

Cela rend le serveur accessible partout, y compris dans un dossier vide dans lequel vous allez vous installer. Il peut alors répondre à quel modèle utiliser, ce que signifient les options, et ce qu’il faut configurer ensuite. Délibérément déconnecté, pour suivre la dernière version :

Visual Studio lit un fichier utilisateur .mcp.json depuis votre dossier de profil, Cursor utilise ~/.cursor/mcp.json, et VS Code a une configuration MCP au niveau utilisateur dans ses paramètres. Chacun prend le même servers bloc.

Par projet, épinglé à sa version

Les projets créés à partir des modèles Power Portals Pro sont déjà câblés : le modèle écrit a .mcp.json à la racine de la solution, épinglé à la version serveur correspondante. Il n’y a rien à faire.

Pour l’ajouter à un projet existant, exécutez ceci dans le dossier projet — il écrit la même .mcp.json chose pour vous :

Notez ce que cela ne fait pas : cela laisse le serveur non épinglé, donc le dossier reçoit le serveur publié le plus récent plutôt que celui correspondant aux PowerPortalsPro.* paquets que votre projet consulte. C’est le bon défaut pour un projet qui suit la version en cours, et le mauvais pour un projet délibérément conservé sur une version plus ancienne — épinglez-le en ajoutant la version, comme le font les modèles :

Ou écrivez le fichier vous-même, à la racine de votre solution :

Quel fichier lit votre éditeur

Visual Studio 2022 17.14+ et Visual Studio 2026 lisent .mcp.json depuis le dossier solution, tout comme Claude Code. VS Code lit .vscode/mcp.json et Cursor .cursor/mcp.json lit — les deux utilisent le même servers bloc, donc copiez-le d’un côté à l’autre.

dnx est livré avec le SDK .NET 10, que vous avez déjà : chaque projet Power Portals Pro est hébergé par ASP.NET Core, React SPA inclus. La première exécution télécharge le paquet et le met en cache.

Avoir les deux est la configuration prévue. Les deux entrées utilisent le même nom de serveur, donc un client qui comprend les deux portées utilise celles du projet — ce qui signifie que vous obtenez les réponses correspondantes à la version à l’intérieur d’un projet, et les dernières réponses ailleurs.

La commande ppp-mcp, si vous la souhaitez

Les commandes du terminal sur cette page — login, status, logout et les autres — s’exécutent dnx sans rien d’installé : dnx PowerPortalsPro.Mcp login. Si vous préférez taper ppp-mcp login, installez le paquet comme un outil global .NET :

Cela met ppp-mcp sur votre PATH: le SDK .NET ajoute normalement son dossier global tools — %USERPROFILE%\.dotnet\tools sous Windows, ~/.dotnet/tools macOS et Linux — à celui-ci. Si la commande n’est pas trouvée, ouvrez un nouveau terminal ; si ce n’est toujours pas le cas, ajoutez ce dossier à PATH vous-même.

Un outil global reste sur la version que vous avez installée, où dnx il récupère la dernière version, donc mettez-le à jour comme décrit ci-dessous. Votre client MCP peut continuer à lancer le serveur dans dnx les deux cas : tous deux lisent les mêmes liaisons de dossiers et les mêmes connexions enregistrées.

Vérifier que ça fonctionne

Demandez à votre assistant quelque chose auquel seul le serveur peut répondre — par exemple « utilisez get_component_api pour m’afficher tous les paramètres sur MainGrid ». Si l’outil n’est pas disponible, le client n’a pas détecté le fichier de configuration ; la plupart ont besoin d’un redémarrage après son ajoute.

Mise à jour

La façon dont vous mettez à jour dépend de la façon dont vous l’avez installée.

Installé comme outil global (dotnet tool install --global PowerPortalsPro.Mcp, qui met ppp-mcp sur votre PATH:

Important

Fermez d’abord votre client MCP. Un serveur en cours d’exécution maintient ses propres fichiers ouverts, et la mise à jour échoue avec Access to the Path ... refusé jusqu’à ce que plus rien ne les utilise. Redémarrez le client ensuite pour charger la nouvelle version.

Connexion à Dataverse

Les outils de documentation n’ont besoin d’aucune configuration. Les outils de métadonnées ont besoin d’une connexion à votre environnement, et cette connexion appartient au dossier, pas à la machine. Exécutez ceci une fois dans le projet :

Les environnements appartiennent au dossier

Cela lie ce dossier à un environnement. Si vous travaillez avec plusieurs clients, chaque projet reste connecté à son propre environnement et les agents dans différents dossiers ne se croisent jamais. C’est la seule chose pac auth select qu’il ne peut pas faire — cela change un profil à l’échelle de la machine, donc changer de client en un seul endroit le change partout.

La connexion utilise par défaut le flux de code de l’appareil, donc ça fonctionne via SSH, à l’intérieur d’un conteneur et en WSL, et tu peux le finir sur un téléphone. Passe --browser si tu préfères en ouvrir un.

Plusieurs environnements dans un seul dossier

Un dossier peut être connecté à plusieurs environnements simultanément — par exemple les environnements de développement, de test et de production d’un client. Chaque login environnement avec un autre environnement l’ajoute à la liste du dossier, et --name lui donne le nom que vous utiliserez :

Le premier environnement est le principal, et chaque outil agit dessus sauf si vous en demandez un autre : « listez les vues sur le contact dans le test » est répondu depuis test, et la question suivante revient au principal. Passez --make-primary à login pour ajouter un environnement comme principal à la place, ou demandez à votre assistant de les réorganiser.

Chaque réponse qui touche Dataverse commence par nommer l’environnement d’où elle vient — son nom, sa position et son URL — donc un changement effectué en production ne se lit jamais de la même manière qu’un changement effectué en développement.

Où les objets sont stockés

Le cache de jetons est indexé par environnement, donc un second clone du dépôt du même client ne vous demande pas de vous reconnecter, tandis qu’un autre client le fait toujours — et chaque environnement ajouté à un dossier le fait aussi.

Commandements

Exécutez-les comme dnx PowerPortalsPro.Mcp <command>, ou comme ppp-mcp <command> si vous aviez installé l’outil global. Tous ces éléments agissent sur le dossier actuel sauf si vous passez --workspace.

Autres façons de se connecter

L’environnement et les identifiants sont réglés dans cet ordre, de sorte que la déclaration d’intention la plus explicite l’emporte :

  1. Variables d’environnement — PPP_D365_URL, PPP_D365_CLIENT_ID et PPP_D365_CLIENT_SECRET dans le bloc du serveur env . Un principal de service, et la façon de le câbler dans CI ou un conteneur partagé. PPP_D365_URL devient l’environnement principal, avant tout au dossier lié, et le principal de service est utilisé uniquement pour le principal.
  2. La connexion du dossier — écrite par login. Le chemin normal.
  3. Les paramètres propres au projet — les mêmes D365:Url, D365:ClientId et D365:ClientSecret (ou D365:Secret) le portail lui-même lit à partir des secrets utilisateur et appsettings. Un projet Power Portals Pro configuré n’a donc souvent besoin d’aucune connexion.

Profils CLI Power Platform

Si vous gardez déjà des environnements dans pac, vous pouvez partir d’un au lieu de chercher une URL :

La CLI n’a pas de commande qui délivre un jeton d’accès, et elle conserve les identifiants dans son propre magasin, donc sa session ne peut pas être réutilisée directement. Ce qui --pac-profile le fait, c’est prendre l’environnement et le compte d’un profil et se connecter en tant que compte — généralement sans qu’on le demande, car vous avez déjà une session.

Note

Le profil actif propre de la CLI n’est jamais modifié. pac auth select est délibérément interdit : il déplacerait chaque projet en même temps.

Les outils

Il est rare de nommer un outil — les assistants les choisissent dans les descriptions — mais il est utile de savoir ce qui s’y trouve.

Documentation, toujours disponible

Votre environnement, une fois connecté

Choisir entre les environnements

Chaque outil qui atteint Dataverse prend un nom optionnel environment — un nom tel que test, une position comme 2, ou l’URL — et utilise le principal sans référence. Un nom qui ne correspond à rien est refusé avec la liste des environnements existants, jamais associé au plus proche.

Ajouter un environnement nécessite une connexion, donc seulement login cela le fait. Le reste est fait par votre assistant quand vous le demandez. Déplacer un environnement en position 1 change de sorte que chaque écriture ultérieure se fait par défaut, donc set_environment_index il vous demande en premier quand il changera le primaire, et remove_environment demande toujours.

Les disques eux-mêmes

Les métadonnées indiquent quelle est la forme ; elles indiquent ce qu’elle contient réellement — quelle valeur d’option une ligne porte, si une recherche est remplie, si la ligne que votre code vient d’écrire est correcte. Un agent qui ne peut pas consulter devinera à la place.

La lecture se lit comme vous — le principal du service ou l’utilisateur connecté, jamais un utilisateur du portail. Aucune des permissions de tableau, des colonnes ou des filtres de lignes du portail ne s’applique, donc cela montre ce qui se trouve dans l’environnement et non ce qu’un utilisateur donné verrait apparaître. Le FetchXML d’une vue sauvegardée s’exécute mot pour mot.

Lancer un nouveau projet

get_upgrade_plan c’est celui à appeler avant de changer une chaîne de version. Il lit la version à laquelle ce projet fait référence, détermine quelles versions se situent entre celle-ci et la cible, et renvoie chaque changement décisif avec ses instructions de migration — aux côtés des fichiers qui nomment une version, y compris la broche serveur que .mcp.json rien d’autre ne détecterait. Déplacer les paquets sans cette version produit des erreurs de compilation dont la cause est plusieurs versions plus tôt.

La solution gérée

Le framework doit PowerPortalsProCore être installé avant qu’un portail ne fonctionne, et PowerPortalsProLocalization si vous localisez. Ces fichiers récupèrent une version et l’importent sans la interface de ligne de commande Power Platform, donc l’environnement auquel ils atteignent est celui auquel ce dossier est lié plutôt que celui pac vers lequel il est pointé.

Une importation est de longue durée, donc install_solution elle la lance et rend un identifiant de travail ; get_solution_import_status rapporte l’avancement et le résultat, avec le message propre de Dataverse en cas d’échec.

Note

publish_customizations est la même action que Publier toutes les personnalisations dans le portail créateur, donc il publie tout ce qui est en attente dans l’environnement, pas seulement vos propres modifications — sur un environnement de développement partagé qui peut rendre le travail à moitié terminé d’un collègue en vie. Ce n’est pas nécessaire après install_solution: importer une solution managée publie ce qu’elle apporte.

Votre propre solution

Les modifications apportées par le serveur à un environnement — un rôle de sécurité créé, un privilège accordé ou repris — vont dans une solution de votre propre main, enregistrée pour cet environnement dans .ppp/mcp.json. create_solution configurez le publieur et la solution une fois, dans l’environnement que vous construisez ; jusqu’à ce qu’un soit enregistré, les outils qui personnalisent Dataverse refusent, car un changement effectué en dehors d’une solution est bloqué dans la solution par défaut où rien ne peut l’exporter.

Le binding enregistre aussi si la solution voyage sans gestion (par défaut, pour les environnements dans lesquels ils sont aussi intégrés) ou si elle est gérée (pour les environnements qui ne la reçoivent qu’un seul). export_solution Affiche la dernière partie de la version et sauvegarde le zip dans l’espace de travail, puis push_solution l’exporte et l’importe dans un autre environnement lié au même dossier — développement intégré, push to test et production. Une solution qui dépend de Power Portals Pro ne s’importe pas tant que la cible ne possède pas celle-là aussi.

Rôles du portail

Un rôle de portail est moitié code et moitié données. Le développeur décide ce que le nom « Dealer » accorde ; un administrateur décide qui le détient ; rien ne lie les deux à part la chaîne. Ces rôles maintiennent la moitié Dataverse du même endroit où l’appel AddPortalRole est écrit.

La chaîne correspond à toute la jointure. Une faute de frappe entre l’enregistrement et l’enregistrement produit un rôle qui est enregistré, assignable, et n’accorde rien — sans aucune erreur nulle part. Laisser l’agent qui vient d’écrire l’enregistrement créer l’enregistrement correspondant comble cet écart et check_setup détecte les incompatibilités déjà présentes : il compare chaque nom de rôle écrit dans le projet avec les enregistrements, et signale ceux qui manquent ou sont inactifs.

Une ligne de configuration de rôle du portail décide quels nouveaux utilisateurs enregistrés reçoivent un rôle : chacun d’eux, ou ceux correspondant aux critères FetchXML. Les critères sont vérifiés par rapport aux règles que le portail applique avant l’écriture de la ligne, car le portail échoue à se fermer sur de mauvais critères et une règle brisée ressemble exactement à une règle qui n’a correspondu correctement à personne. Les administrateurs modifient les mêmes lignes sur la page de configuration des rôles du portail.

Note

Supprimer un rôle jette toutes ses attributions et rien ne se souvient de qui l’a détenu. Désactiver ne donne rien et ne crée aucune revendication non plus, mais conserve les attributions, donc c’est la manière réversible de désactiver un rôle. Les deux outils de suppression vous demandent de confirmer d’abord.

Sites web sous licence

Un enregistrement Power Portals Pro est ce qui licencie un portail servi à partir d’une URL donnée. Ces documents les listent, les ajoutent et les maintiennent — généralement une fois par environnement, puis à nouveau lorsqu’un portail passe vers son hôte de production.

C’est la première chose à vérifier lorsque chaque point de terminaison retourne 402. Sans enregistrement actif correspondant, chaque point de terminaison de données sur cet hôte refuse la requête. Supprimer un enregistrement prend la licence à partir de la requête suivante, donc préférez désactiver pendant l’enquête ; la suppression vous demande de confirmer.

Azure deployment

La plupart de ces outils ne font que lire. Ils n’ont besoin que de Reader sur l’abonnement, et ils répondent aux questions qui coûtent des jours aux gens. check_deployment C’est celui qu’il faut savoir : il compare ce dont le projet a besoin avec ce que possède réellement le service d’application, et nomme la défaillance — un paramètre obligatoire qui n’existait que dans vos secrets utilisateur, l’environnement laissé en développement, des WebSockets désactivés sur un portail Blazor, un enregistrement Portal Website qui ne couvre pas l’hébergeur déployé, un portail qui ne peut pas accéder à Dataverse.

Sept outils modifient le service d’applications : create_app_service, configure_app_service, set_app_service_settings, deploy_to_app_service, restart_app_service, et create_deployment_slot swap_slots. Chacun d’eux vous demande de confirmer et vous indique combien cela coûtera avant que vous répondiez — le chiffre mensuel réel pour votre région, lu dans la liste publique des prix d’Azure, avec une note indiquant que la liste de détail ignore tout accord d’entreprise ou réservation que vous détenez. Les nouvelles ressources par défaut sont le niveau le moins cher qui peut rester chaud, pour tous les environnements y compris la production, à condition que l’augmentation de l’échelle plus tard soit une minute et que le surprovisionnement soit une facture que personne ne revient.

Sur un forfait Standard ou Premium, un portail peut avoir des emplacements de déploiement, chacun fonctionnant sur son propre environnement Dataverse — un uat emplacement contre UAT, tandis que la production fonctionne contre la production. create_deployment_slot Crée un emplacement et le relie à l’environnement, donc lorsque vous travaillez en UAT et demandez un déploiement, la compilation va vers le slot UAT plutôt qu’en production. Les paramètres qui nomment un environnement sont marqués pour rester dans leur emplacement, ce qui swap_slots permet de promouvoir la version testée en production et elle démarre contre les données de production. Un échange est refusé lorsque cela transporterait un environnement vers un autre.

Note

Ces derniers n’utilisent pas la CLI Azure et ne lisent jamais ni ne modifient son état de connexion. Exécutez ppp-mcp azure login dans le dossier : comme pour la liaison Dataverse, l’abonnement appartient uniquement à ce dossier, donc plusieurs projets peuvent cibler différents clients en même temps. az account show Ne vous dit rien sur ce que ces outils feront.

Inscriptions à l’application Entra

Les deux enregistrements dont un portail a besoin, ainsi que les tâches qui les suivent. Ce sont les étapes qui bloquent la plupart des configurations : ce sont deux enregistrements distincts plutôt qu’un seul, l’application de connexion nécessite une URL de réponse portant un port aléatoire que le modèle a aléatoire, et un client secret expire un an plus tard et arrête le portail en commençant par une erreur qui ne mentionne jamais Entra.

Les outils ne détiennent aucun droit propre. Chaque appel est envoyé sur un jeton délégué pour le compte avec lequel vous vous êtes connecté, émis à un client public qui ne détient aucun secret — donc chaque opération réussit exactement quand vous auriez pu l’effectuer à la main dans le portail, et est refusée avec un 403 nommant le rôle d’annuaire dont vous auriez besoin alors que vous ne pouviez pas. Connectez-vous en tant que développeur d’application titulaire d’un compte ou au-dessus et ces fonctions fonctionnent ; connectez-vous en tant que n’importe qui d’autre et ils ne peuvent pas causer de préjudice. Aucune autorisation API n’est demandée et aucun consentement administrateur n’est accordé, car aucune des inscriptions n’en nécessite.

Les deux moitiés, car aucune ne fonctionne seule. Une inscription d’application reçoit un jeton ; un utilisateur d’application Dataverse décide de ce que ce jeton peut faire. Une inscription sans jeton s’authentifie parfaitement et est ensuite refusée par chaque appel, ce qui se lit comme une connexion coupée plutôt que comme un objet manquant — et un utilisateur d’application sans rôle de sécurité est créé, visible, apparemment en bon état, et autorisé à ne rien faire. create_dataverse_application_user fait la seconde moitié et attribue le rôle à la même étape. C’est le seul endroit où le serveur écrit en dehors de ses trois tables, admis parce qu’un utilisateur d’application est une infrastructure plutôt que des données client ; aucun outil ne crée, modifie ou supprime un enregistrement métier.

Ils travaillent sur des enregistrements déjà existants. Chaque create_*_registration outil accepte un clientId, et avec un, il adopte cet enregistrement au lieu d’en créer un — ajoute un secret, fusionne toutes les nouvelles URL de réponse, écrit les identifiants là où vous avez demandé. La confirmation dit alors d’ajouter un secret à l’enregistrement existant plutôt que de créer, donc vous n’approuvez jamais une opération et n’en obtenez jamais une autre. Les outils qui modifient un enregistrement existant, add_app_registration_redirect_uri et add_app_registration_secret, prennent aussi un identifiant client, et le préfèrent : les noms d’affichage ne sont pas uniques, et un locataire avec trois inscriptions appelé « Portal » est normal.

Un secret client créé n’est pas retourné par défaut. Il passe directement de la réponse Graph aux secrets utilisateur du projet, à un paramètre d’application d’application, ou aux deux, et l’outil indique où il est allé et quand il expire plutôt que ce qu’il était. Lorsqu’un secret doit atteindre un endroit où le serveur ne peut pas écrire — la machine d’un collègue, un magasin secret CI, un coffre-fort dans un autre abonnement — demandez destination: "return" et la valeur vous est affichée pour que vous la copierez. La confirmation le dit avant que vous acceptiez, et le résultat porte l’avertissement qui l’obtient : le secret est alors dans la transcription, donc considérez-le comme exposé si cette transcription est stockée, et faites-la pivoter en cas de doute. Les secrets sont créés par défaut pendant 24 mois — le plus long délai offert par le portail d’Entra — car l’échec que subit réellement ce cadre est un secret dépassé plutôt qu’un vol : le portail cesse de commencer à une date que personne n’a remarquée, avec une erreur qui ne mentionne jamais Entra. Ce plafond appartient à l’interface utilisateur du portail, pas à l’API, donc expiryMonths accepte tout ce qui peut aller jusqu’à 120 (10 ans) alors que vous préférez tourner une fois tous les cinq ans plutôt que de risquer une interruption. Ce n’est pas le défaut, car un identifiant qu’aucun administrateur n’aurait pu créer à la main est surprenant à trouver — donc la confirmation vous indique combien d’années vous avez demandé et que le portail n’a pas pu le produire.

Une application peut se connecter avec un certificat au lieu d’un secret. Crée add_app_registration_certificate un certificat dans Key Vault dont la clé privée ne peut jamais être exportée, et ajoute sa moitié publique à l’enregistrement. Associe un environnement à cette application ppp-mcp login --environment <url> --client-id <id> --certificate <url> et le coffre signe chaque connexion pour celui qui détient Key Vault Crypto User, afin qu’aucun secret ne soit installé sur aucune machine. Pour faire tourner, lance à nouveau le même outil ; remove_app_registration_certificate retire l’ancien certificat dès que plus rien ne l’utilise.

Note

Deux choses manquent délibérément. Supprimer un enregistrement peut supprimer la connexion pour chaque application dans un locataire et n’est récupérable que dans une fenêtre de 30 jours. Accorder le consentement administrateur est l’opération qui transforme un acte délégué étroit en une autorisation permanente à l’échelle du locataire. Aucun n’est nécessaire pour lancer un portail, donc aucun n’est proposé. Créer l’utilisateur de l’application Dataverse pour le nouvel identifiant client est aussi une étape distincte — la sortie de l’outil vous donne la commande.

Supprimer le secret qui expire

Un secret client est la partie d’un portail déployé qui cesse de fonctionner à une date que personne n’a notée. Ces éléments le retirent, ou déplacent ce qui reste quelque part où il peut être tourné sans redéployement.

Réglez D365__ManagedIdentityId sur l’identifiant client de l’identité — et non sur l’identifiant objet ou principal que le portail Azure affiche en premier — et donnez à cet identifiant client son propre utilisateur d’application Dataverse, comme create_dataverse_application_user n’importe quel autre. Le portail se connecte alors sans aucun secret.

L’expéditeur de l’e-mail

Le portail envoie des courriels de confirmation et de réinitialisation de mot de passe depuis une adresse qui doit se résoudre vers une file d’attente ou un utilisateur activé dans Dataverse. create_email_queue crée la file d’attente, approuve sa boîte aux lettres et exécute Test & Enable, rapportant le résultat ; check_email_sender explique pourquoi un expéditeur ne livre pas. Une file d’attente, plutôt que la boîte aux lettres d’une personne, est l’expéditeur approprié pour une adresse sans réponse.

Important

Deux choses qu’il ne peut pas faire pour vous. L’adresse nécessite une boîte aux lettres dans Exchange Online — une boîte aux lettres partagée, qui ne nécessite pas de licence — et seul un administrateur global Office 365 ou Exchange Administrator peut l’approuver. Lorsque l’un ou l’autre manque, l’outil indique lequel des choses, et le relancer une fois corrigé termine le travail. Jusqu’à la réussite de Test & Enable Target, Dataverse accepte le courrier du portail et ne livre rien — indiscernable d’un succès du côté du portail, c’est pourquoi l’outil le teste plutôt que de rapporter une finition propre.

Travailler dans d’autres langues

La connaissance que le serveur retourne est en anglais, et c’est délibéré. C’est votre assistant qui la lit — vous ne voyez jamais une réponse d’outil directement — donc elle traduit pour vous : demandez dans votre propre langue, et elle répond dans votre propre langue. Ce qu’il ne doit pas traduire, c’est le code. Les noms des composants, paramètres et colonnes sont en anglais dans chaque projet, quelle que soit la langue de la conversation, donc garder la référence en anglais empêche un assistant d’inventer un nom de paramètre traduit qui n’existe pas.

Note

Les questions qui nomment quelque chose “MainGrid Ansichten konfigurieren” — fonctionnent déjà dans n’importe quelle langue, car les noms des composants sont identiques partout. Les outils indiquent aussi à votre assistant de chercher en anglais, donc les questions qui ne nomment rien fonctionnent aussi.

Dépannage