Entwicklung des Copilot-MCP-Servers

Telemetrie-Tagging

Bevor Sie ATK-CLI-Befehle ausführen, legen Sie die Umgebungsvariable der Sitzung fest, damit alle CLI-Aufrufe als durch eine Skill initiiert gekennzeichnet werden:

export ATK_CLI_SKILL=true

Führen Sie diesen Befehl einmal zu Beginn der Sitzung aus. Alle nachfolgenden atk -Befehle im selben Terminal übernehmen diese Einstellung.

🔀 PATH-AUSWAHL

Bevor Sie fortfahren, fragen Sie den Benutzer mithilfe von `AskUserQuestion`, welchen Pfad er einschlagen möchte. Beide Optionen werden für die Darstellung des M365 Copilot-Widgets unterstützt. Stellen Sie die Vor- und Nachteile dar und lassen Sie den Benutzer wählen:

Fragen Sie: „Möchten Sie eine OAI-App (OpenAI Apps SDK – praxiserprobt, funktioniert in ChatGPT und M365 Copilot) oder eine MCP-App (neuer offizieller Standard – funktioniert in M365 Copilot, ChatGPT, VSCode und mehr) entwickeln?“

• OAI-Apps → Fahren Sie unten fort. Diese Skill deckt alles ab, was Sie benötigen.
• MCP-Apps → Installieren Sie das Plugin „modelcontextprotocol/ext-apps“ (siehe unten) und verwenden Sie dann die entsprechende Funktion aus diesem Plugin.

MCP-Apps: Plugin „ext-apps“ installieren

Wenn der Benutzer sich für MCP-Apps entscheidet, führen Sie dies automatisch aus (beschränken Sie sich nicht auf eine reine Erklärung):

1. Führen Sie /plugin marketplace add modelcontextprotocol/ext-apps aus
2. Führen Sie /plugin install mcp-apps@mcp-apps aus
3. Überprüfen Sie, ob das Plugin verfügbar ist, und rufen Sie dann je nach Absicht des Benutzers die richtige „ext-apps“-Funktion auf

Falls die Plugin-Befehle in der aktuellen Umgebung nicht verfügbar sind, geben Sie die unten aufgeführten genauen Befehle an und bitten Sie den Benutzer, diese einmal auszuführen; fahren Sie anschließend mit dem Aufruf des ausgewählten „ext-apps“-Skills fort.

Referenzbefehle:

Um eine MCP-App zu erstellen, installieren Sie das „ext-apps“-Plugin aus dem Marketplace:

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

Verwenden Sie anschließend einen der folgenden Skills aus diesem Plugin:
- create-mcp-app      — Erstellen Sie von Grund auf eine neue MCP-App mit interaktiver Benutzeroberfläche
- add-app-to-server   — Fügen Sie einer bestehenden MCP-Serverumgebung eine interaktive Benutzeroberfläche hinzu
- migrate-oai-app     — Konvertiert eine bestehende OAI-App für die Verwendung mit MCP-Apps
- convert-web-app     — Wandelt eine Web-App in eine hybride Web- und MCP-App um

Rufen Sie nach der Installation die entsprechende Funktion auf, um fortzufahren.

Hinweis: Das Plugin „ext-apps“ befindet sich im Marktplatz „external modelcontextprotocol/ext-apps“ – es ist nicht Teil dieser Plugin-Sammlung.

Zuordnung nach der Installation:

• Neue MCP-App von Grund auf erstellen → create-mcp-app
• App-Benutzeroberfläche zu einem bestehenden MCP-Server hinzufügen → add-app-to-server
• Bestehende OAI-App migrieren → migrate-oai-app
• Vorhandene Web-App konvertieren → convert-web-app

📛 PROJEKTERKENNUNG 📛

Diese Funktion wird ausgelöst, wenn MCP-Server mit OAI-App oder Widget-Rendering für Microsoft 365 Copilot Chat erstellt werden. Der MCP-Server kann in jeder Sprache geschrieben sein, die das MCP-Protokoll unterstützt (TypeScript, Python, C# usw.). Das Agent-Projekt und der MCP-Server können sich im selben Repo, in separaten Ordnern oder in völlig unterschiedlichen Projekten befinden.

Szenario-Routing

🚨 WICHTIGE AUSFÜHRUNGSREGELN 🚨

FLUENT-UI-VORGABE (ERFORDERLICH): Widget-Implementierungen MÜSSEN React- und Fluent-UI-Komponenten verwenden. Bevor der Agent Widget-Code schreibt, MUSS er Folgendes lesen und befolgen:

• references/widget-patterns.md
• references/best-practices.md FLUENT-UI-PAKETANFORDERUNG (ERFORDERLICH): Das Widget-Projekt MUSS vor der Implementierung die Fluent-UI-Abhängigkeiten einbinden. Installiere mindestens die folgenden Komponenten und behalte sie in den Abhängigkeiten des Widget-Pakets bei:
• @fluentui/react-components
• react
• react-dom

Sollte eines dieser Pakete fehlen, installieren Sie es automatisch, bevor Sie mit der Generierung des Widget-Codes fortfahren.

Wenn das generierte Widget keine React-Einstiegsdateien (z. B. „widgets/src//main.tsx“ und eine React-Komponentendatei) sowie Fluent-Importe aus „@fluentui/react-components“ enthält, ist die Aufgabe unvollständig und MUSS korrigiert werden, bevor Ergebnisse zurückgegeben werden.

KEINE REINEN HTML-WIDGETS (STANDARD): Implementieren Sie den App-Inhalt nicht direkt mit statischen HTML-Vorlagen und Inline-JS als endgültige Widget-Lösung. Eine minimale HTML-Shell-Datei ist nur als Loader für gebaute React-Assets zulässig. Reine, in sich geschlossene HTML-Widgets sind nur zulässig, wenn der Benutzer explizit einen Nicht-React-Prototyp anfordert.

HINTERGRUNDPROZESSE: Der MCP-Server und der Devtunnel MÜSSEN als unabhängige Betriebssystemprozesse gestartet werden – sie dürfen NICHT innerhalb der Shell-Sitzung des Agenten ausgeführt werden. „isBackground: true“, „mode: ‚async‘“ und „Start-Job“ werden alle innerhalb der Shell-Sitzung des Agenten ausgeführt und zwischen den Nachrichten beendet. Der einzige zuverlässige Ansatz besteht darin, einen eigenständigen Betriebssystemprozess zu starten.

Windows – verwende Start-Process -WindowStyle Hidden:

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

# MCP-Server starten – verwende „cmd.exe /c“, um das Arbeitsverzeichnis festzulegen und den PATH zu übernehmen
$s = Start-Process -FilePath "cmd.exe" `
    -ArgumentList "/c", "cd /d  && " `
    -WindowStyle Hidden -PassThru `
    -RedirectStandardOutput "server.log" -RedirectStandardError "server-err.log"

# PIDs speichern, damit sie später beendet werden können
"$($t.Id),$($s.Id)" | Out-File pids.txt
Write-Host "Tunnel-PID $($t.Id), Server-PID $($s.Id) gestartet"

Zum Beenden: Stop-Process -Id (Get-Content pids.txt).Split(',') oder Stop-Process -Id .

Linux/Mac – verwende „nohup“ mit „&“:

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

Zum Beenden: kill $(grep -oP '\d+' pids.txt).

Überwachen Sie nach dem Start die Protokolle mit `tail`, um sicherzustellen, dass beide Prozesse laufen, bevor Sie fortfahren:

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

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

VOLLSTÄNDIGE AUTOMATISIERUNG: Fordere den Benutzer niemals auf, Befehle manuell auszuführen. Installiere Tools, führe die Authentifizierung durch, starte Dienste – erledige alles automatisch. Fordere den Benutzer nur dann zur interaktiven Eingabe auf, wenn dies wirklich erforderlich ist (z. B. bei der Bestätigung des Gerätecodes während der Anmeldung mit `devtunnel user login -g -d`). Wenn ein Tool nicht installiert ist, installieren Sie es. Wenn ein Dienst gestartet werden muss, starten Sie ihn. Der Benutzer erwartet vollständige Automatisierung.

PFADAUSWAHL (ERFORDERLICH – VOR JEDEM CODE ANHALTEN): Sie MÜSSEN „AskUserQuestion“ verwenden, um den Benutzer zu fragen, ob er die OAI-Apps oder die MCP-Apps-Erweiterung wünscht, bevor Sie Code schreiben, Befehle ausführen oder architektonische Entscheidungen treffen.

Es gibt keine Ausnahme von dieser Regel. Der häufigste Fehler besteht in der Argumentation: „Die Anfrage des Benutzers macht es offensichtlich, daher ist das Fragen überflüssig.“ Diese Argumentation ist immer falsch – rufen Sie „AskUserQuestion“ in jedem Fall auf. Die Aussage eines Nutzers „Erstelle einen MCP-Server mit Widgets“ ist KEINE Antwort auf diese Frage. Der Aufruf dieses Skills durch den Namen ist KEINE Antwort. Nur eine explizite Antwort auf die Frage zählt. Die genaue Fragestellung entnehmen Sie bitte dem obigen Abschnitt „PFADWAHL“.

AGENTEN-PROVISIONING: Eine Neuprovisionierung ist nur erforderlich, wenn sich das Agenten-Manifest ändert (z. B. mcpPlugin.json-Tool-Definitionen, MCP-Server-URL, declarativeAgent.json, instruction.txt). Änderungen am MCP-Servercode (Tool-Implementierungen, React-Widget-Code, Serverlogik) erfordern KEINE Neu-Provisionierung des Agenten – beim Ausführen oder Bereitstellen des Servers werden die Änderungen automatisch übernommen.

Wann eine Bereitstellung erforderlich ist:

1. Erhöhen Sie die Version in „manifest.json“ (erhöhen Sie die Patch-Version, z. B. 1.0.0 → 1.0.1)
2. Stellen Sie den Agenten bereit: `

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

LINKS ZUM TESTEN VON WIDGETS: Jedes Mal, wenn Sie dem Benutzer ein Ergebnis übermitteln, während der MCP-Server läuft, MÜSSEN Sie Links zu ALLEN Widgets beifügen, damit dieser sie lokal testen kann. Format:

🧪 Widgets lokal testen:
- http://localhost:3001/widgets/widget-name.html
- http://localhost:3001/widgets/another-widget.html

Listen Sie alle .html- Dateien im Verzeichnis „mcp-server/widgets/“ (oder einem entsprechenden Widget-Ordner) auf. Dies hilft den Benutzern, die Darstellung der Widgets zu überprüfen, bevor sie diese in Copilot testen.

AUTOMATISCHE BEREITSTELLUNG NACH ABSCHLUSS (ERFORDERLICH – NICHT ÜBERSPRINGEN): Wenn die Programmierung abgeschlossen ist, fahren Sie automatisch fort, ohne auf den Benutzer zu warten:

1. Starten Sie den MCP-Server + Devtunnel im Hintergrund (gemäß „HINTERGRUNDPROZESSE“ oben)
2. Führen Sie eine E2E-Überprüfung mit MCP Inspector durch (gemäß der unten stehenden „MCP-TOOL-KONFIGURATIONSREGEL“) – beheben Sie etwaige Fehler, bevor Sie fortfahren
3. Bereitstellen des Agenten, falls erforderlich (gemäß „AGENT-BEREITSTELLUNG“ oben)
4. Drucken Sie eine Projektzusammenfassung in diesem Format aus:

## ✅  — Bereit

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

### Endpunkte
- MCP-Server: http://localhost:/mcp
- MCP über Tunnel: https:///mcp

### Test in Copilot
Lokal:      https://m365.cloud.microsoft/chat/?titleId={M365_TITLE_ID aus env/.env.local}
Andere Umgebungen: {SHARE_LINK aus env/.env.{environment}}

AGENT-PROJEKT-DELEGIERUNG: Diese Funktion erstellt MCP-Server und Widgets, KEINE deklarativen Agentenprojekte. Wenn die Anfrage des Benutzers die Erstellung oder Konfiguration des deklarativen Agenten selbst betrifft (Scaffolding, m365agents.yml, m365agents.local.yml, declarativeAgent.json, Manifest-Lebenszyklus), delegieren Sie die Anfrage an die Skill „declarative-agent-developer “.

MCP-RESSOURCENREGISTRIERUNG: Jedes Widget MUSS über eine entsprechende MCP-Ressource verfügen. Ohne Ressourcen kann Copilot keine Widget-Shells über das MCP-Protokoll abrufen, und die Widgets werden nicht gerendert.

Führen Sie für jedes neue Widget diese Checkliste durch:

1. ☐ Erstellen Sie eine HTML-Datei für die Widget-Shell im Verzeichnis „widgets/“ und einen React-Widget-Eintrag unter „widgets/src//“ (siehe „widget-patterns.md“)
2. ☐ Definieren Sie eine URI-Konstante ui://widget/.html
3. ☐ Fügen Sie dem „resources “-Array einen „Resource “-Eintrag mit folgendem Inhalt hinzu:
   • uri: die URI „ui://widget/.html“
   • mimeType: „text/html+skybridge“
   • _meta: CSP-Konfiguration mit „openai/widgetDomain“ und „openai/widgetCSP“ (aus der Umgebung)
4. ☐ Fügen Sie einen Handler für „resources/read“ hinzu, der den HTML-Code der Widget-Shell für diese URI zurückgibt
5. ☐ Fügen Sie das Tool hinzu, wobei _meta.openai/outputTemplate auf dieselbe URI „ui://widget/.html“ verweist
6. ☐ Überprüfen, ob die Serverfähigkeiten in der Initialisierungsantwort „resources: {} “ enthalten

Überlegungen zur Widget-Shell und zu Assets:

• Bevorzugt (React + Fluent UI): Die Ressourcen-HTML-Datei sollte eine minimale Hülle sein, die auf vorgefertigte JS-/CSS-Assets verweist, die über die Route /assets/ des MCP-Servers bereitgestellt werden.
• Nur als Ausnahme: Eigenständige HTML-Dateien über „resources/read“ sind ausschließlich für explizit vom Benutzer angeforderte Prototypen vorgesehen. Der Standard- und Produktionspfad ist React + Fluent UI.

Beispiel-Shell für die React-Build-Ausgabe:

Verwenden Sie die Umgebungsvariable WIDGET_BASE_URL oder MCP_SERVER_URL als Basis-URL für Assets (siehe mcp-server-pattern.md, Abschnitt „Configurable Widget Base URL“).

Die vollständigen Muster für die Bereitstellung von Ressourcen und Assets finden Sie in mcp-server-pattern.md.

⚠️ REGEL ZUR MCP-TOOL-KONFIGURATION ⚠️

Schreiben Sie Tool-Definitionen NIEMALS manuell in die Datei „mcpPlugin.json“. Verwenden Sie immer den MCP Inspector, um die vollständigen Tool-Definitionen vom laufenden MCP-Server abzurufen.

KONVENTION FÜR DIE BENENNUNG VON TOOLS: Tool-Namen MÜSSEN dem Muster ^[A-Za-z0-9_]+$ entsprechen (nur Buchstaben, Zahlen und Unterstriche). Verwenden Sie NIEMALS Bindestriche (-) in Tool-Namen. Verwenden Sie stattdessen Unterstriche (z. B. „render_profile“ statt „render-profile“).

VORGESCHRIEBENER ARBEITSABLAUF:

1. Starten Sie den MCP-Server (im Hintergrund)
2. Verwenden Sie den MCP Inspector, um die neuesten Tool-Definitionen abzurufen:

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

3. Kopieren Sie die VOLLSTÄNDIGE Tool-Definition aus dem Inspector (einschließlich Name, Beschreibung, inputSchema, _meta, Anmerkungen, Titel)
4. Fügen Sie diese in die Datei ` mcpPlugin.json` unter ` runtimes[].spec.mcp_tool_description.tools `ein (innerhalb des `spec `-Objekts der ` RemoteMCPServer `-Laufzeitumgebung)
5. Führen Sie eine E2E-Überprüfung über den Devtunneldurch – rufen Sie jedes Tool auf und vergewissern Sie sich, dass die Antwort „structuredContent“ und „_meta.openai/widgetAccessible: true“ enthält:

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

   Überprüfen Sie außerdem, ob der GET-Aufruf https:///health den Wert {"status":"ok"} zurückgibt. Beheben Sie etwaige Fehler vor der Bereitstellung.

Der MCP Inspector zeigt das genaue Tool-Schema Ihres Servers an. Kopieren Sie es vollständig – schreiben oder ändern Sie diese Definitionen nicht manuell. Dadurch wird sichergestellt, dass mcpPlugin.json mit dem MCP-Server synchron bleibt.

Erstellen Sie MCP-Server, die sich in Microsoft 365 Copilot Chat integrieren lassen und reichhaltige, interaktive Widgets darstellen.

Architektur

M365 Copilot ──▶ mcpPlugin.json ──▶ MCP-Server ──▶ structuredContent ──▶ React + Fluent UI-Widget
     │              (RemoteMCPServer)    (Streamable HTTP)                  (window.openai.toolOutput)
     │
     └── Funktionen (Personen usw.) stellen Daten bereit, die an MCP-Tools weitergeleitet werden

Projektstruktur

Beispiel für eine Projektstruktur; keine zwingende Vorgabe, sondern ein gängiges Muster für die Organisation der MCP-Server- und Widget-Entwicklung:

project/
├── appPackage/
│   ├── manifest.json           # Teams-Manifest (Version bei Bereitstellung erhöhen)
│   ├── declarativeAgent.json   # Agentenkonfiguration + Funktionen
│   ├── mcpPlugin.json          # Tool-Definitionen mit _meta
│   └── instruction.txt         # Anweisungen zum Verhalten des Agenten
├── mcp-server/
│   ├── src/index.ts            # Server mit Streamable HTTP
│   ├── widgets/                # Widget-Shells + React-Quellcode
│   │   ├── my-widget.html      # Minimale Shell, die von `resources/read` zurückgegeben wird
│   │   └── src/my-widget/      # React + Fluent UI-Quellcode
│   ├── assets/                 # Gebaute Widget-Bundles, die unter /assets bereitgestellt werden
│   └── package.json
├── scripts/
│   ├── setup-devtunnel.sh      # Einrichtung des DevTunnels unter Linux/Mac
│   └── setup-devtunnel.ps1     # Einrichtung des DevTunnels unter Windows
└── env/.env.local              # MCP_SERVER_URL, MCP_SERVER_DOMAIN

Anmerkung zur Sprache: Hier wird die Struktur eines TypeScript-Projekts gezeigt. Für Python ersetzen Sie „mcp-server/src/index.ts“ durch Ihren Python-Einstiegspunkt (z. B. „server.py“). Für C# verwenden Sie eine standardmäßige .NET-Projektstruktur. Die Verzeichnisse „appPackage/“, „widgets/“, „scripts/“ und „env/“ sind sprachunabhängig.

Copilot-Widget-Protokoll

Ihr MCP-Server muss diese Protokollanforderungen erfüllen, um Widgets im Copilot-Chat darzustellen. Dies gilt unabhängig von der Sprache:

1. Streamfähiger HTTP-Transport – /mcp -Endpunkt, der POST, GET und DELETE mit Sitzungsverwaltung verarbeitet
2. CORS-Header – Herkunftsprüfung für /mcp, die m365.cloud.microsoft und *.m365.cloud.microsoft zulässt, mit den erforderlichen MCP-Headern
3. Serverfunktionen – Die „initialize “-Antwort muss „resources: {} “ und „tools: {}“ deklarieren
4. MCP-Ressourcen – Registrieren Sie Widgets mit den URIs „ui://widget/.html“, dem MIME-Typ „text/html+skybridge“ und CSP -_meta
5. Format der Tool-Antwort – Rückgabe von „content“ (Text) + „structuredContent“ (Widget-Daten) + „_meta“ mit „openai/outputTemplate“
6. Widget-Bereitstellung – HTTP-Route unter /widgets/*.html für Shell-Dateien und /assets/* für kompilierte Bundles, beide mit CORS-Herkunftsprüfung

Ausführliche Informationen zum Protokoll, JSON-Formate und eine Checkliste zur Anpassung bestehender MCP-Server finden Sie in references/copilot-widget-protocol.md.

Implementierung

MCP-Server-Muster (TypeScript-Referenz)

Die vollständige Implementierung finden Sie unter „references/mcp-server-pattern.md“.

Für andere Sprachen implementieren Sie die im Copilot-Widget-Protokoll beschriebenen Anforderungen mithilfe des MCP-SDK Ihrer Sprache. SDK-Pakete finden Sie in der Tabelle „Language SDK References“.

Kernanforderungen:

• Stellen Sie den Streamable-HTTP-Transport unter /mcp bereit
• Geben Sie „structuredContent“ + „_meta“ mit „openai/outputTemplate“ zurück
• Widgets über einen HTTP-Endpunkt bereitstellen
• CORS für Cross-Origin-Anfragen verarbeiten
• Teilweise Daten korrekt verarbeiten (fehlende Felder mit „Unknown“ auffüllen)

Antwortformat des Tools:

return {
  content: [{ type: "text", text: "Summary" }],
  structuredContent: { /* Widget-Daten */ },
  _meta: { "openai/outputTemplate": "ui://widget/name.html", "openai/widgetAccessible": true }
};

Umgang mit unvollständigen Daten

Normalisieren Sie Eingabedaten stets, um fehlende Felder zu behandeln:

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

  // Daten normalisieren – fehlende Felder mit „Unbekannt“ auffüllen
  const title = args.title || „Standardtitel“;
  const items = (args.items || []).map(item => ({
    name: item.name || „Unbekannt“,
    value: item.value || „Unbekannt“,
  }));

  // „structuredContent“ für das Widget erstellen
  const structuredContent = { title, items };
  // ...
});

Widget-Muster

Vollständige Beispiele finden Sie in „references/widget-patterns.md“.

Grundlegende Anforderungen:

• Verwende React + Fluent-UI-Komponenten (@fluentui/react-components)
• Stellen Sie sicher, dass die Abhängigkeiten des Widget-Pakets @fluentui/react-components, react und react-dom enthalten
• Theme mit FluentProvider (webLightTheme/webDarkTheme) und Fluent -Tokens
• Greifen Sie über gemeinsam genutzte Hooks auf Daten zu (z. B. useOpenAiGlobal("toolOutput"))
• Fehlerbehebung: Eingebettete Mock-Daten, wenn ` window.openai ` nicht verfügbar ist
• Behandeln Sie „Unknown“-Werte elegant (z. B. Aktionsschaltflächen ausblenden)

Plugin-Schema

Siehe references/plugin-schema.md für das Format von mcpPlugin.json.

Kernanforderungen:

• Schema v2.4 mit RemoteMCPServer -Laufzeitumgebung
• Das Array„run_for_functions“ muss mit den Tool-Namen übereinstimmen
• _meta in Tool-Definitionen für die Widget-Bindung
• inputSchema – Eigenschaften aus Gründen der Flexibilität optional gestalten, Standardwerte in den Beschreibungen angeben

Einrichtung von DevTunnels

Nur für lokale Tests. DevTunnels dienen der Entwicklung und dem Testen auf Ihrem Rechner. Bevor Sie den Agenten in größerem Umfang freigeben, stellen Sie sowohl den MCP-Server als auch die Widget-Assets in einer gehosteten Umgebung bereit (z. B. Azure App Service, Azure Static Web Apps oder bei einem anderen Hosting-Anbieter) und aktualisieren Sie die URLs im Agenten-Manifest entsprechend.

DevTunnels stellen Ihren lokalen MCP-Server über benannte Tunnel mit stabilen URLs für M365 Copilot bereit. Informationen zu Einrichtungsskripten, Befehlsreferenz und Fehlerbehebung finden Sie in „references/devtunnels.md“.

Das Einrichtungsskript (npm run tunnel / npm run tunnel:win):

1. Erstellt beim ersten Ausführen einen benannten Tunnel (oder verwendet den vorhandenen wieder)
2. Startet das Hosting des Tunnels auf dem konfigurierten Port
3. Aktualisiert die Datei „env/.env.local“ mit den Variablen „MCP_SERVER_URL“ und „MCP_SERVER_DOMAIN“ (nur beim ersten Start)
4. Setzt das Hosten des Tunnels fort

Schnellstart

Terminal 1 – MCP-Server starten:

cd mcp-server
npm install
npm run dev

Terminal 2 – DevTunnel starten:

npm run tunnel
# Oder unter Windows:
npm run tunnel:win

Stellen Sie beim ersten Durchlauf den Agenten bereit, sobald der Tunnel eingerichtet ist (siehe Regel „AGENT PROVISIONING“). Bei nachfolgenden Durchläufen ist die Tunnel-URL stabil – eine erneute Bereitstellung ist nicht erforderlich, es sei denn, das Agenten-Manifest ändert sich.

Entwicklungs-Workflow

1. Starten Sie den MCP-Server (Entwicklungsmodus mit Hot-Reload):

   • 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. Starten Sie den Devtunnel (erstellt beim ersten Lauf einen benannten Tunnel, der bei nachfolgenden Läufen wiederverwendet wird):

   npm run tunnel
   

3. Bereitstellung + Test – siehe Regel „AGENT PROVISIONING“, um zu erfahren, wann dies erforderlich ist; erhöhen Sie die Versionsnummer in „manifest.json“, falls Copilot die Änderungen nicht berücksichtigt

Bewährte Vorgehensweisen

Ausführliche Anleitungen finden Sie in „references/best-practices.md“.

Wichtige Punkte:

1. Rendering-Tools: Daten als Eingabe akzeptieren, nicht intern abrufen
2. Anweisungen: Weisen Sie den Agenten an, ZUERST die Funktionen zu nutzen, und leiten Sie die Daten anschließend an die MCP-Tools weiter
3. Themes: Verwenden Sie FluentProvider + Fluent-Token für die Unterstützung von Dunkel- und Hellmodus
4. Debug-Modus: Fügen Sie Fallback-Daten für lokale Widget-Tests ein
5. Unvollständige Daten: Behandeln Sie fehlende Felder mit „Unknown“-Standardwerten
6. Aktionsschaltflächen: E-Mail-/Chat-Schaltflächen ausblenden, wenn Daten „Unbekannt“ sind
7. Versionserhöhung: Die Manifest-Version erhöhen, wenn Änderungen nicht in Copilot übernommen werden