Run any Skill in Manus with one click

bridge-troubleshooting

Stars0

Forks0

UpdatedJuly 6, 2026 at 07:29

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.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

adner

adner/CopilotPcf_Template

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name

bridge-troubleshooting

description

Bridge troubleshooting playbook

The loop has three hops: PCF → Copilot (Xrm.Copilot.sendPromptToM365Copilot), agent → MCP tool, tool/viewer → PCF (the nudge). Most failures are one specific misconfiguration. Find the symptom.

Symptom → cause → fix

Component iframe is blank / nothing loads (often NO console error). → Mixed content. The server URL is http://… (or http://localhost) but the Power App is served over HTTPS, so the browser silently blocks the sub-resource. Fix: run the server behind the HTTPS devtunnel and set PUBLIC_BASE_URL (mcp-server .env), the PCF serverBaseUrl property, and the manifest external-service-usage domain all to that same https://…devtunnels.ms base. See bidirectional-pcf-agent for the coupling.

You keep seeing the OLD PCF build after pushing. → ControlManifest version not bumped. UCI caches the bundle by control version. Fix: bump version in ControlManifest.Input.xml (patch is fine) before every npm run build && pac pcf push, then hard-reload the app (Ctrl+Shift+R); if still stale, Publish all customizations and wait ~1 min. See pcf-develop-deploy.

The table shows the DEFAULT read-only grid, not your PCF (no console error). → The CustomControlDefaultConfig grid binding didn't apply. Two causes seen: (a) wrong placement — the <CustomControlDefaultConfigs> block was written inside the inner <entity Name="…"> instead of on the outer <Entity> (sibling of <FormXml>/<SavedQueries>/<RibbonDiffXml>); import silently drops it. (b) the carrier solution was deleted — the binding rides in the unmanaged solution you imported it through, and deleting that solution removes the binding. Fix: re-run bind-grid.mjs (correct placement, handles the split Entities/<table>/Entity.xml layout), keep the carrier solution, and verify by re-exporting the solution and confirming the block sits under the outer <Entity>. See pcf-develop-deploy.

pac pcf push fails with System.Xml.XmlException or a noAposStringType XSD error. → The manifest has an XML- or XSD-invalid attribute value that the webpack build didn't catch: a raw </>/&, or an apostrophe in a display-name-key/description-key. Escape the entities and remove apostrophes. See pcf-develop-deploy RULE 1b.

Component's own fetch of its /data (or /state) fails with a null-origin / CORS error. → iframe sandbox missing allow-same-origin. A sandboxed iframe without it gets an opaque origin, so every self-fetch becomes a null-origin CORS failure. Fix: sandbox="allow-scripts allow-same-origin" on the tile iframe.

fetch blocked by the document's own Content-Security-Policy. → The assembled document's <meta> CSP lacks connect-src. Fix: ensure connect-src 'self' (and img-src data: if you embed images) in the doc's META CSP. Framing blocked instead? That's the tile response header Content-Security-Policy: frame-ancestors … — it must allow https://*.dynamics.com.

The nudge never arrives at the PCF (agent ran, pane showed the card, but the PCF didn't react). → Two common causes: (a) frame depth — the Copilot pane is a nested iframe; the viewer must post the message to window.top, window.parent, AND window.parent.parent. (b) single registration — the PCF must listen via BOTH Xrm.Copilot.addActionHandler(action, h) and a raw window.addEventListener("message", …) filtering on eventName + action. Wire only one and it's flaky. Also confirm the eventName/action strings match exactly on both ends. See bidirectional-pcf-agent.

The pane card never renders (the tool ran — you see it in the logs — but no UI in Copilot). → Missing _meta.ui.resourceUri on the tool's entry in the agent's mcp-tools.json (it must match the viewer URI the server registers). This is the easiest sync step to forget. See declarative-agent-sync.

The agent never calls your new tool. → The tool isn't in run_for_functions[] in ai-plugin.json, and/or isn't described in instruction.txt. Re-do the three-file sync (mcp-tools.json tools[], ai-plugin.json functions[] + run_for_functions[], instruction.txt). See declarative-agent-sync.

sendPromptToM365Copilot opens the WRONG agent (or a generic Copilot). → Wrong gptId. You passed TEAMS_APP_ID; it must be M365_TITLE_ID (T_<guid> / U_<guid>.declarativeAgentPowerApps). Verify the live value: open the agent, run Xrm.Copilot.getCurrentAgent() in DevTools.

A generated widget renders blank even though data is present. → The render code created elements but never appendChild'd them, or reached for an external resource/eval that the host CSP blocked (silent). Keep widget code vanilla-only and confirm every created node is attached. See mcp-apps-tool-dev.

npm run serve shows a "viewer not built" fallback page. → You didn't npm run build first. The viewer is a Vite single-file bundle; build before serve.

Where to look (observation points)

mcp-server/logs/*.jsonl — one file per tool call; the user-facing error carries a (log: <8char>) handle that matches the filename. Start here for tool failures.
VS Code "MCP" output channel — server stderr mirror / connection status (.vscode/mcp.json points the client at http://localhost:3101/mcp).
DevTools inside the Copilot pane — for postMessage/CSP/nudge issues; run Xrm.Copilot.getCurrentAgent() here to confirm the live gptId, and watch the Console for CSP violations and the Network tab for blocked fetches.
npm run probe — reproduce a tool host-free before blaming the host. If probe is green but Copilot fails, the problem is in the agent sync or the bridge, not the tool.

Rule of thumb

Isolate the hop. If probe works, the tool is fine → suspect the agent sync (tool not routed) or the bridge (nudge/CSP/sandbox). If the component won't even load, suspect mixed content or a stale bundle first — those two account for most "it just doesn't work" reports.

More from this repository

same repository

pcf-develop-deploy

adner/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".

2026-07-060

bidirectional-pcf-agent

adner/CopilotPcf_Template

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".

2026-07-060

dataverse-mcp-setup

adner/CopilotPcf_Template

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".

2026-07-060

dataverse-mcp-usage

adner/CopilotPcf_Template

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".

2026-07-060

declarative-agent-sync

adner/CopilotPcf_Template

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.

2026-07-060

mcp-apps-tool-dev

adner/CopilotPcf_Template

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.

2026-07-060

name

bridge-troubleshooting

description

Bridge troubleshooting playbook

Symptom → cause → fix

npm run serve shows a "viewer not built" fallback page. → You didn't npm run build first. The viewer is a Vite single-file bundle; build before serve.

Where to look (observation points)

mcp-server/logs/*.jsonl — one file per tool call; the user-facing error carries a (log: <8char>) handle that matches the filename. Start here for tool failures.
VS Code "MCP" output channel — server stderr mirror / connection status (.vscode/mcp.json points the client at http://localhost:3101/mcp).
DevTools inside the Copilot pane — for postMessage/CSP/nudge issues; run Xrm.Copilot.getCurrentAgent() here to confirm the live gptId, and watch the Console for CSP violations and the Network tab for blocked fetches.
npm run probe — reproduce a tool host-free before blaming the host. If probe is green but Copilot fails, the problem is in the agent sync or the bridge, not the tool.