Développement du serveur Copilot MCP

Marquage télémétrique

Avant d'exécuter toute commande CLI atk, définissez la variable d'environnement de session afin que tous les appels CLI soient marqués comme ayant été lancés par une skill :

export ATK_CLI_SKILL=true

Exécutez cette commande une seule fois au début de la session. Toutes les commandes atk suivantes dans le même terminal en hériteront.

🔀 SÉLECTION DU PARCOURS

Avant de continuer, demandez à l’utilisateur quel chemin il souhaite emprunter à l’aide de AskUserQuestion. Les deux options sont prises en charge pour le rendu du widget M365 Copilot. Présentez-lui les avantages et inconvénients de chaque option et laissez-le choisir :

Demandez : « Souhaitez-vous développer une application OAI (SDK OpenAI Apps — éprouvé, fonctionne dans ChatGPT et M365 Copilot) ou une application MCP (nouvelle norme officielle — fonctionne dans M365 Copilot, ChatGPT, VSCode, et plus encore) ? »

• Applications OAI → Continuez ci-dessous. Cette compétence couvre tout ce dont vous avez besoin.
• Applications MCP → Installez le plugin modelcontextprotocol/ext-apps (voir ci-dessous), puis utilisez la compétence appropriée de ce plugin.

Applications MCP : installer le plugin ext-apps

Si l’utilisateur choisit les applications MCP, effectuez cette opération automatiquement (ne vous contentez pas d’une simple explication) :

1. Exécutez /plugin marketplace add modelcontextprotocol/ext-apps
2. Exécutez /plugin install mcp-apps@mcp-apps
3. Vérifiez que le plugin est disponible, puis invoquez la compétence ext-apps appropriée en fonction de l’intention de l’utilisateur

Si les commandes du plugin ne sont pas disponibles dans l’environnement actuel, fournissez les commandes exactes ci-dessous et demandez à l’utilisateur de les exécuter une fois, puis poursuivez en invoquant la compétence ext-apps sélectionnée.

Commandes de référence :

Pour créer une application MCP, installez le plugin ext-apps depuis le marketplace :

1. /plugin marketplace add modelcontextprotocol/ext-apps
2. /plugin install mcp-apps@mcp-apps

Utilisez ensuite l’une des compétences suivantes de ce plugin :
- create-mcp-app      — Créer de toutes pièces une nouvelle application MCP avec une interface utilisateur interactive
- add-app-to-server   — Ajouter une interface utilisateur interactive aux outils d’un serveur MCP existant
- migrate-oai-app     — Convertit une application OAI existante pour qu’elle utilise les applications MCP
- convert-web-app     — Transforme une application web en une application hybride web + MCP

Une fois l’installation terminée, invoquez la compétence appropriée pour continuer.

Remarque : le plugin ext-apps se trouve sur la place de marché external modelcontextprotocol/ext-apps — il ne fait pas partie de cette collection de plugins.

Mappage de transfert après l’installation :

• Nouvelle application MCP créée à partir de zéro → create-mcp-app
• Ajouter l’interface utilisateur d’une application à un serveur MCP existant → add-app-to-server
• Migrer une application OAI existante → migrate-oai-app
• Convertir une application web existante → convert-web-app

📛 DÉTECTION DE PROJET 📛

Cette compétence se déclenche lors de la création de serveurs MCP avec une application OAI ou un rendu de widget pour Microsoft 365 Copilot Chat. Le serveur MCP peut être écrit dans n’importe quel langage prenant en charge le protocole MCP (TypeScript, Python, C#, etc.). Le projet d’agent et le serveur MCP peuvent se trouver dans le même dépôt, dans des dossiers distincts ou dans des projets totalement différents.

Routage des scénarios

🚨 RÈGLES D'EXÉCUTION CRITIQUES 🚨

APPLICATION DE FLUENT UI (OBLIGATOIRE) : les implémentations de widgets DOIVENT utiliser React + les composants Fluent UI. Avant d’écrire le moindre code de widget, l’agent DOIT lire et respecter :

• references/widget-patterns.md
• references/best-practices.md EXIGENCE RELATIVE AU PAQUET FLUENT UI (OBLIGATOIRE) : le projet de widget DOIT inclure les dépendances Fluent UI avant toute implémentation. Au minimum, installez et conservez les éléments suivants dans les dépendances du paquet du widget :
• @fluentui/react-components
• react
• react-dom

Si l'un de ces paquets est manquant, installez-le automatiquement avant de poursuivre la génération du code du widget.

Si le widget généré ne comprend pas de fichiers d’entrée React (par exemple, widgets/src//main.tsx et un fichier de composant React) ni les importations Fluent provenant de @fluentui/react-components, la tâche est incomplète et DOIT être corrigée avant de renvoyer des résultats.

PAS DE WIDGETS EN HTML BRUT UNIQUEMENT (PAR DÉFAUT) : N’implémentez pas le contenu de l’application directement à l’aide de modèles HTML statiques et de code JavaScript en ligne comme solution finale pour le widget. Un fichier HTML minimal de base est autorisé uniquement en tant que chargeur pour les ressources React compilées. Les widgets bruts/autonomes composés uniquement de code HTML ne sont autorisés que lorsque l’utilisateur demande explicitement un prototype non-React.

PROCESSUS D'ARRIÈRE-PLAN : le serveur MCP et devtunnel DOIVENT être lancés en tant que processus indépendants du système d’exploitation — ils NE DOIVENT PAS s’exécuter au sein de la session shell de l’agent. isBackground: true, mode: « async » et Start-Job s’exécutent tous au sein de la session shell de l’agent et seront interrompus entre deux messages. La seule approche fiable consiste à lancer un processus système détaché.

Windows — utilisez Start-Process -WindowStyle Hidden:

# Démarrer devtunnel
$t = Start-Process -FilePath "devtunnel" `
    -ArgumentList "host","","-a" `
    -WindowStyle Hidden -PassThru `
    -RedirectStandardOutput "tunnel.log" -RedirectStandardError "tunnel-err.log"

# Démarrer le serveur MCP — utilisez cmd.exe /c pour définir le répertoire de travail et hériter du PATH
$s = Start-Process -FilePath "cmd.exe" `
    -ArgumentList "/c","cd /d  && " `
    -WindowStyle Hidden -PassThru `
    -RedirectStandardOutput "server.log" -RedirectStandardError "server-err.log"

# Enregistrer les PID afin de pouvoir les arrêter ultérieurement
"$($t.Id),$($s.Id)" | Out-File pids.txt
Write-Host "Tunnel démarré : PID $($t.Id), serveur : PID $($s.Id)"

Pour arrêter : Stop-Process -Id (Get-Content pids.txt).Split(',') ou Stop-Process -Id .

Linux/Mac — utilisez nohup avec &:

nohup devtunnel host  > tunnel.log 2>tunnel-err.log &
echo "tunnel:$!" >> pids.txt
nohup  > server.log 2>server-err.log &
echo "server:$!" >> pids.txt

Pour arrêter : kill $(grep -oP '\d+' pids.txt).

Après le démarrage, surveillez les fichiers journaux pour vérifier que les deux processus sont bien en cours d'exécution avant de continuer :

# Windows
Start-Sleep 3; Get-Content tunnel.log, server.log

# Linux/Mac
sleep 3 && tail tunnel.log server.log

AUTOMATISATION TOTALE : ne demandez jamais à l’utilisateur d’exécuter des commandes manuellement. Installez les outils, authentifiez-vous, démarrez les services — faites tout automatiquement. Ne demandez à l’utilisateur une intervention interactive que lorsque cela est vraiment nécessaire (comme la confirmation du code du périphérique lors de la connexion de l’utilisateur devtunnel avec les options -g -d). Si un outil n’est pas installé, installez-le. Si un service doit être démarré, démarrez-le. L’utilisateur s’attend à une automatisation complète.

CHOIX DU CHEMIN (OBLIGATOIRE — S'ARRÊTER AVANT TOUTE ÉCRITURE DE CODE) : Vous DEVEZ utiliser AskUserQuestion pour demander à l’utilisateur s’il souhaite les applications OAI ou l’extension MCP Apps avant d’écrire le moindre code, d’exécuter la moindre commande ou de prendre la moindre décision architecturale.

Il n’y a aucune exception à cette règle. L’erreur la plus courante consiste à penser que « la demande de l’utilisateur est évidente, donc lui demander est superflu ». Ce raisonnement est toujours erroné — appelez AskUserQuestion quoi qu’il arrive. Un utilisateur qui dit « créez un serveur MCP avec des widgets » n’apporte PAS de réponse à cette question. Un utilisateur qui invoque cette compétence par son nom n’apporte PAS de réponse. Seule une réponse explicite à la question compte. Voir la section « SÉLECTION DU PARCOURS » ci-dessus pour connaître la question exacte à poser.

PROVISIONNEMENT DE L’AGENT : un nouveau provisionnement n’est nécessaire que lorsque le manifeste de l’agent change (par exemple, les définitions d’outils dans mcpPlugin.json, l’URL du serveur MCP, declarativeAgent.json, instruction.txt). Les modifications du code du serveur MCP (implémentations d’outils, code des widgets React, logique du serveur) ne nécessitent PAS de réapprovisionner l’agent : l’exécution ou le déploiement du serveur prend automatiquement en compte ces modifications.

Lorsqu’un provisionnement est nécessaire :

1. Mettez à jour la version dans manifest.json (incrémenter la version de correctif, par exemple 1.0.0 → 1.0.1)
2. Déployez l’agent :

   npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local
   
   

LIENS DE TEST DES WIDGETS : Chaque fois que vous transmettez un résultat à l’utilisateur alors que le serveur MCP est en cours d’exécution, vous DEVEZ inclure les liens vers TOUS les widgets afin qu’il puisse les tester localement. Format :

🧪 Tester les widgets localement :
- http://localhost:3001/widgets/widget-name.html
- http://localhost:3001/widgets/another-widget.html

Répertoriez tous les fichiers .html du répertoire mcp-server/widgets/ (ou du dossier de widgets équivalent). Cela permet aux utilisateurs de vérifier le rendu des widgets avant de les tester dans Copilot.

DÉPLOIEMENT AUTOMATIQUE À LA FIN (OBLIGATOIRE — NE PAS IGNORER) : Une fois le codage terminé, passez automatiquement à l’étape suivante sans attendre l’utilisateur :

1. Démarrez le serveur MCP et devtunnel en arrière-plan (conformément à la section PROCESSUS EN ARRIÈRE-PLAN ci-dessus)
2. Effectuez une vérification de bout en bout avec MCP Inspector (conformément à la section « RÈGLE DE CONFIGURATION DES OUTILS MCP » ci-dessous) — corrigez les éventuels échecs avant de continuer
3. Provisionnez l’agent si nécessaire (conformément à la section « PROVISIONNEMENT DE L’AGENT » ci-dessus)
4. Imprimer un résumé du projet au format suivant :

## ✅  — Prêt

### Widgets
- [widget-name.html](http://localhost:/widgets/widget-name.html)
- [nom-du-widget2.html](http://localhost:/widgets/nom-du-widget2.html)

### Points de terminaison
- Serveur MCP : http://localhost:/mcp
- MCP via un tunnel : https:///mcp

### Test dans Copilot
Local :      https://m365.cloud.microsoft/chat/?titleId={M365_TITLE_ID issu de env/.env.local}
Autres environnements : {SHARE_LINK issu de env/.env.{environment}}

DÉLÉGATION DE PROJET D'AGENT : cette compétence crée des serveurs et des widgets MCP, et NON des projets d'agent déclaratifs. Si la requête de l’utilisateur implique la création ou la configuration de l’agent déclaratif lui-même (scaffolding, m365agents.yml, m365agents.local.yml, declarativeAgent.json, cycle de vie du manifeste), déléguez à la compétence « declarative-agent-developer ».

ENREGISTREMENT DES RESSOURCES MCP : chaque widget DOIT disposer d’une ressource MCP correspondante. Sans ressources, Copilot ne peut pas récupérer les coques de widgets via le protocole MCP et les widgets ne s’afficheront pas.

Pour chaque nouveau widget, suivez cette liste de contrôle :

1. ☐ Créez un fichier HTML de coque de widget dans le répertoire widgets/ et une entrée de widget React sous widgets/src// (voir widget-patterns.md)
2. ☐ Définissez une constante URI ui://widget/.html
3. ☐ Ajoutez une entrée Resource au tableau resources avec :
   • uri: l’URI ui://widget/.html
   • mimeType: « text/html+skybridge »
   • _meta: configuration CSP avec openai/widgetDomain et openai/widgetCSP (provenant de l'environnement)
4. ☐ Ajouter un gestionnaire pour resources/read qui renvoie le code HTML du shell du widget correspondant à cette URI
5. ☐ Ajouter l’outil avec _meta.openai/outputTemplate pointant vers la même URI ui://widget/.html
6. ☐ Vérifier que les capacités du serveur incluent resources: {} dans la réponse d’initialisation

Considérations relatives à la structure du widget et aux ressources :

• Préféré (React + Fluent UI): le code HTML de la ressource doit être une structure minimale renvoyant vers des ressources JS/CSS intégrées, servies depuis la route /assets/ du serveur MCP.
• Exception uniquement: le code HTML autonome via resources/read est réservé aux prototypes explicitement demandés par l’utilisateur. La voie par défaut et de production est React + Fluent UI.

Exemple de structure pour la sortie de compilation React :

Utilisez la variable d’environnement WIDGET_BASE_URL ou MCP_SERVER_URL comme base d’URL pour les ressources (voir la section « URL de base configurable pour les widgets » du fichier mcp-server-pattern.md).

Consultez le fichier mcp-server-pattern.md pour connaître l’ensemble des modèles de mise à disposition des ressources et des éléments.

⚠️ RÈGLE DE CONFIGURATION DES OUTILS MCP ⚠️

N’écrivez JAMAIS manuellement les définitions d’outils dans mcpPlugin.json. Utilisez toujours MCP Inspector pour récupérer les définitions complètes des outils à partir du serveur MCP en cours d’exécution.

CONVENTION DE NOMINATION DES OUTILS : Les noms d’outils DOIVENT respecter le modèle ^[A-Za-z0-9_]+$ (lettres, chiffres et traits de soulignement uniquement). N’utilisez JAMAIS de tirets (-) dans les noms d’outils. Utilisez plutôt des traits de soulignement (par exemple, render_profile et non render-profile).

PROCÉDURE OBLIGATOIRE :

1. Démarrez le serveur MCP (en arrière-plan)
2. Utilisez MCP Inspector pour récupérer les dernières définitions d’outils :

   npx @modelcontextprotocol/[email protected] --cli https://my-mcp-server.example.com --transport http --method tools/list
   
   

3. Copiez la définition COMPLÈTE de l’outil depuis l’inspector (y compris le nom, la description, inputSchema, _meta, les annotations, le titre)
4. Collez-la dans mcpPlugin.json sous runtimes[].spec.mcp_tool_description.tools (à l’intérieur de l’objet spec du runtime RemoteMCPServer )
5. Effectuez une vérification de bout en bout via le devtunnel : appelez chaque outil et vérifiez que la réponse contient « structuredContent » et « _meta.openai/widgetAccessible: true » :

   npx @modelcontextprotocol/[email protected] --cli https:///mcp --transport http --method tools/call --tool-name 
   
   

   Vérifiez également que la requête GET https:///health renvoie {"status":"ok"}. Corrigez tout échec avant le provisionnement.

MCP Inspector affiche le schéma exact des outils de votre serveur. Copiez-le intégralement — ne rédigez ni ne modifiez manuellement ces définitions. Cela garantit que le fichier mcpPlugin.json reste synchronisé avec le serveur MCP.

Créez des serveurs MCP qui s’intègrent à Microsoft 365 Copilot Chat et affichent des widgets interactifs riches.

Architecture

M365 Copilot ──▶ mcpPlugin.json ──▶ Serveur MCP ──▶ structuredContent ──▶ Widget React + Fluent UI
     │              (RemoteMCPServer)    (Streamable HTTP)                  (window.openai.toolOutput)
     │
     └── Les fonctionnalités (Personnes, etc.) fournissent des données à transmettre aux outils MCP

Structure du projet

Exemple de structure de projet ; il ne s’agit pas d’une exigence stricte, mais d’un modèle courant pour organiser le développement du serveur MCP et des widgets :

project/
├── appPackage/
│   ├── manifest.json           # Manifeste des équipes (incrémenter la version lors du déploiement)
│   ├── declarativeAgent.json   # Configuration de l’agent + capacités
│   ├── mcpPlugin.json          # Définitions d’outils avec _meta
│   └── instruction.txt         # Instructions de comportement de l’agent
├── mcp-server/
│   ├── src/index.ts            # Serveur avec Streamable HTTP
│   ├── widgets/                # Coques de widgets + code source React
│   │   ├── my-widget.html      # Coque minimale renvoyée par resources/read
│   │   └── src/my-widget/      # Code source React + Fluent UI
│   ├── assets/                 # Bundles de widgets compilés, servis à l'adresse /assets
│   └── package.json
├── scripts/
│   ├── setup-devtunnel.sh      # Configuration du devtunnel sous Linux/Mac
│   └── setup-devtunnel.ps1     # Configuration du devtunnel sous Windows
└── env/.env.local              # MCP_SERVER_URL, MCP_SERVER_DOMAIN

Remarque concernant le langage: ceci illustre la structure d’un projet TypeScript. Pour Python, remplacez mcp-server/src/index.ts par votre point d'entrée Python (par exemple, server.py). Pour C#, utilisez une structure de projet .NET standard. Les répertoires appPackage/, widgets/, scripts/ et env/ sont indépendants du langage.

Protocole des widgets Copilot

Votre serveur MCP doit respecter ces exigences de protocole pour afficher des widgets dans Copilot Chat. Cela s’applique quel que soit le langage :

1. Transport HTTP streamable — point de terminaison /mcp gérant les requêtes POST, GET et DELETE avec gestion des sessions
2. En-têtes CORS — Vérification de l’origine sur /mcp autorisant m365.cloud.microsoft et *.m365.cloud.microsoft, avec les en-têtes MCP requis
3. Capacités du serveur — la réponse d’initialisation doit déclarer les ressources : {} et les outils : {}
4. Ressources MCP — Enregistrement des widgets avec les URI ui://widget/.html, le type MIME text/html+skybridge et le paramètre CSP _meta
5. Format de réponse des outils — Renvoyer le contenu (text) + structuredContent (données du widget) + _meta avec openai/outputTemplate
6. Diffusion des widgets — Route HTTP à l’adresse /widgets/*.html pour les fichiers shell et /assets/* pour les bundles compilés, les deux avec vérification d’origine CORS

Pour obtenir tous les détails du protocole, les structures JSON et une liste de contrôle pour l’adaptation des serveurs MCP existants, consultez le fichier references/copilot-widget-protocol.md.

Implémentation

Modèle de serveur MCP (référence TypeScript)

Consultez le fichier references/mcp-server-pattern.md pour l’implémentation complète.

Pour les autres langages, implémentez les exigences décrites dans le protocole Copilot Widget à l’aide du SDK MCP de votre langage. Consultez le tableau « Références des SDK par langage » pour connaître les paquets SDK.

Exigences de base :

• Exposer le transport HTTP Streamable sur /mcp
• Renvoyer structuredContent + _meta avec openai/outputTemplate
• Fournir les widgets via un point de terminaison HTTP
• Gérer le CORS pour les requêtes inter-origines
• Gérer les données partielles de manière appropriée (remplacer les champs manquants par « Unknown »)

Format de réponse de l'outil :

return {
  content: [{ type: "text", text: "Résumé" }],
  structuredContent: { /* données du widget */ },
  _meta: { "openai/outputTemplate": "ui://widget/name.html", "openai/widgetAccessible": true }
};

Gestion des données partielles

Toujours normaliser les données d'entrée pour gérer les champs manquants :

server.setRequestHandler(CallToolRequestSchema, async (request: CallToolRequest) => {
  const args = request.params.arguments as { title?: string; items?: Partial[] };

  // Normaliser les données – remplacer les champs manquants par « Unknown »
  const title = args.title || "Titre par défaut";
  const items = (args.items || []).map(item => ({
    name: item.name || "Unknown",
    value: item.value || « Inconnu »,
  }));

  // Créer le contenu structuré pour le widget
  const structuredContent = { title, items };
  // ...
});

Modèle de widget

Consultez le fichier references/widget-patterns.md pour des exemples complets.

Exigences de base :

• Utilisez React et les composants Fluent UI (@fluentui/react-components)
• S'assurer que les dépendances du package du widget incluent @fluentui/react-components, react et react-dom
• Appliquer un thème à l'aide de FluentProvider (webLightTheme/webDarkTheme) et des jetons Fluent
• Accéder aux données via des hooks partagés (par exemple, useOpenAiGlobal("toolOutput"))
• Débogage de secours : données factices intégrées lorsque window.openai n'est pas disponible
• Gérer les valeurs « inconnues » de manière appropriée (par exemple, masquer les boutons d’action)

Schéma du plugin

Consultez le fichier references/plugin-schema.md pour connaître le format du fichier mcpPlugin.json.

Exigences de base :

• schéma v2.4 avec le runtime RemoteMCPServer
• Tableaurun_for_functions correspondant aux noms des outils
• _meta dans les définitions d'outils pour la liaison des widgets
• inputSchema: rendre les propriétés facultatives pour plus de flexibilité, décrire les valeurs par défaut dans les descriptions

Configuration de DevTunnels

Test local uniquement. Les DevTunnels sont destinés au développement et aux tests sur votre machine. Avant de partager l’agent à plus grande échelle, déployez à la fois le serveur MCP et les ressources des widgets dans un environnement hébergé (par exemple, Azure App Service, Azure Static Web Apps ou un autre fournisseur d’hébergement) et mettez à jour les URL du manifeste de l’agent en conséquence.

Les DevTunnels exposent votre serveur MCP localhost à M365 Copilot à l’aide de tunnels nommés pour des URL stables. Consultez le fichier references/devtunnels.md pour les scripts de configuration, la référence des commandes et le dépannage.

Le script d’installation (npm run tunnel / npm run tunnel:win) :

1. Crée un tunnel nommé lors de la première exécution (ou réutilise celui qui existe déjà)
2. Lance l’hébergement du tunnel sur le port configuré
3. Met à jour le fichier env/.env.local avec MCP_SERVER_URL et MCP_SERVER_DOMAIN (lors de la première exécution uniquement)
4. Poursuit l’hébergement du tunnel

Démarrage rapide

Terminal 1 - Démarrer le serveur MCP :

cd mcp-server
npm install
npm run dev

Terminal 2 - Démarrer DevTunnel :

npm run tunnel
# Ou sous Windows :
npm run tunnel:win

Lors du premier lancement, provisionnez l'agent une fois le tunnel établi (voir la règle PROVISIONNEMENT DE L'AGENT). Lors des lancements suivants, l'URL du tunnel reste stable — aucun réapprovisionnement n'est nécessaire, sauf en cas de modification du manifeste de l'agent.

Workflow de développement

1. Démarrez le serveur MCP (mode développement avec rechargement à chaud) :

   • TypeScript : cd mcp-server && npm install && npm run dev
   • Python : cd mcp-server && pip install -r requirements.txt && python server.py
   • C# : cd mcp-server && dotnet run

2. Démarrez devtunnel (crée un tunnel nommé lors de la première exécution, le réutilise lors des exécutions suivantes) :

   npm run tunnel
   

3. Provisionnement + test — voir la règle AGENT PROVISIONING pour savoir quand cela est nécessaire ; mettez à jour la version dans manifest.json si Copilot ne reflète pas les modifications

Bonnes pratiques

Consultez le fichier references/best-practices.md pour obtenir des conseils détaillés.

Points clés :

1. Outils de rendu: acceptez les données en entrée, ne les récupérez pas en interne
2. Instructions: demandez d’abord à l’agent d’utiliser ses capacités, puis transmettez les données aux outils MCP
3. Thèmes: utilisez FluentProvider + les jetons Fluent pour la prise en charge des modes sombre/clair
4. Mode débogage: inclure des données de secours pour les tests de widgets en local
5. Données partielles: gérer les champs manquants avec des valeurs par défaut « Inconnu »
6. Boutons d’action: masquer les boutons d’e-mail/de chat lorsque les données sont « Inconnues »
7. Mise à jour de la version: mettre à jour la version du manifeste lorsque les modifications ne sont pas prises en compte dans Copilot