CopilotPcf_Template

Use when building, versioning, deploying, or binding a PCF (Power Apps Component Framework) control with the pac CLI — especially a dataset control hosted full-page as a table's grid. Covers the mandatory version bump before every push (stale-bundle cause), the build→push→publish→reload loop, and binding via the checked-in solution XML template, with bind-grid.mjs kept as the export-roundtrip fallback. Triggers: "pac pcf push", "deploy the control", "PCF version", "stale bundle", "bind the control to the table", "binding-template", "customcontroldefaultconfig", "grid control won't show up".

Use when designing or debugging the two-way loop between a PCF control and an M365 Copilot declarative agent brokered by an MCP server — the nudge/postMessage protocol, shared state over the web plane, and the hard runtime constraints (HTTPS/devtunnel, CSP, iframe sandbox). Read this before changing how the widget signals the app or how the app reconciles. Triggers: "nudge", "postMessage bridge", "agent to PCF", "shared state", "widget-resize", "set-theme", "mixed content", "frame-ancestors", "sandbox allow-same-origin", "the loop", "bi-directional".

Diagnostic playbook for when the PCF ↔ MCP ↔ M365 Copilot loop misbehaves. Use when "the component is blank", "the iframe won't load", "the nudge never arrives", "the pane card doesn't render", "I still see the old build", "fetch is blocked / CORS", "the agent won't call my tool", or "it opened the wrong agent". Indexed symptom → cause → check/fix, plus where to look. Cross-references bidirectional-pcf-agent, pcf-develop-deploy, and declarative-agent-sync.

Use when the Dataverse MCP server is not yet reachable from the agent — enabling it on a Power Platform environment, registering the Entra ID client app (mcp.tools permission, PKCE, redirect URIs), allow-listing the client, and connecting Codex CLI / Claude Code / Claude Desktop / GitHub Copilot to /api/mcp. Triggers: "set up the Dataverse MCP server", "connect Codex to Dataverse", "connect Claude to Dataverse", "codex mcp login", "mcp.tools", "api/mcp", "Dataverse MCP not connected", "enable MCP on the environment", "add the Dataverse MCP server".

Use when a demo needs to read from or create supporting structures in Dataverse via the Dataverse MCP server (assumed already configured and connected). Covers read-only queries, creating demo tables and columns, the publisher-prefix gotcha, and how logical names map to the TDS/SQL endpoint. Triggers: "query Dataverse", "read_query", "create a table", "create_table", "Dataverse MCP", "hosting table", "supporting table for the demo", "what columns does <table> have".

Wire the M365 Copilot declarative agent (Agents Toolkit / ATK) to the template's MCP server, and keep its tool list in sync with the server. Use whenever you add/rename/remove a server tool, when "the agent can't see my tool" / "the tool isn't being called" / "the pane card doesn't render", when scaffolding or publishing the agent, or when editing appPackage/{mcp-tools.json, ai-plugin.json, instruction.txt}. Always run this right after mcp-apps-tool-dev — a server tool is invisible to Copilot until the agent is synced.

Add or modify a tool on the template's MCP (Apps) server — the core loop of every new demo built from this template. Use when the user says "add an MCP tool", "add a tool to the server", "make the agent able to do X", "return a UI/card/chart from a tool", "wire up a new server capability", or when you are editing server.ts / src/tools/*. Covers the registerAppTool pattern, structuredContent, the viewer-resource decision, per-call logging, the vanilla-only widget constraint, inline-vs-fetch rendering, and the probe-first inner loop. After changing a tool, ALWAYS follow with declarative-agent-sync.

Use when wiring the Xrm.Copilot client APIs in a model-driven Power Apps demo — opening the M365 Copilot pane, sending prompts to a declarative agent (with gptId), or receiving agent actions. Covers usage from BOTH a PCF control and an MCP Apps widget, the ambient-typing pattern for window.Xrm, and the gptId discovery gotcha. Triggers: "Xrm.Copilot", "openM365CopilotPanel", "sendPromptToM365Copilot", "sendPrompt to agent", "addActionHandler", "getCurrentAgent", "gptId", "agentId", "open the Copilot panel".