/platform-mcp-tool-widget-coordinate

name: platform-mcp-tool-widget-coordinate
description: "Orchestrate object-based Lightning Type + HXL widget generation to render the output of a custom MCP server tool backed by an Apex Invocable Action. TRIGGER only when the prompt EXPLICITLY involves rendering an MCP tool result: user says 'MCP server', 'MCP tool', 'custom MCP server', references a tool 'output schema' / 'tool output' / 'outputValues' envelope, names an 'invocable action' backing an MCP tool, or asks to build a widget or rich UI rendition for the output of an Apex-invocable-backed MCP tool. DO NOT TRIGGER when: customizing an Apex-backed agent action output (use platform-lightning-type-widget-coordinate), authoring only a Custom Lightning Type (use platform-custom-lightning-type-generate), authoring only an Apex class (use platform-apex-generate), or building a standalone widget with no Lightning Type or MCP tool involved (use platform-widget-generate)."
metadata:
  version: "1.0"
  minApiVersion: "68.0"
  relatedSkills:
    - "platform-apex-generate"
    - "platform-custom-lightning-type-generate"
    - "platform-lightning-type-widget-coordinate"
    - "platform-widget-generate"
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6.0"
    - tool: ["sf"]
      semver: ">=2.0.0"

Rendering a Custom MCP Tool Output With a Widget

Coordinate **two object-based Custom Lightning Types (CLTs)** and an **HXL widget** to render the output of a custom MCP server tool whose implementation is an Apex `@InvocableMethod`. This skill never authors content directly — it loads and invokes leaf skills in dependency order, gates progress on user approval, and runs validation gates before reporting completion.

Scope

Custom MCP server tools backed by an Apex Invocable Action only. The MCP tool returns the platform's **invocable-action result envelope** — an object with `actionName`, `isSuccess`, and an `outputValues` node that carries the tool's real payload. To render this envelope with a widget, model it as **two object-based CLTs** (`lightning__objectType`) of equal standing — the only reason there are two is that one must reference the other by name (a CLT cannot reference itself), so they need distinct deployed names. Name and describe each by what it actually models — never by an invented role-label pair like "Payload CLT"/"Envelope CLT" or "Inner CLT"/"Outer CLT":

• The CLT that mimics the tool-result envelope, named `<toolApiName>`. Its `outputValues` property is typed to the other CLT via `c__<responseCLT>`.
• The CLT that is the exact shape of the Invocable Action's **response** (`@InvocableVariable` fields on the `@InvocableMethod` response class), named `<toolApiName>Response` — "Response" here is not an invented role word, it's the same word the Apex source already uses for that class (e.g. `GetAccountSummaryResponse`).

The widget grounds on the **response fields** (flat), and the **default `renderer.json` in the envelope CLT** bridges the envelope nesting to the flat widget via `{!$attrs.outputValues.<field>}`.

**Out of scope, route elsewhere:**

• Customizing an **Apex-backed agent action** output (Apex-backed CLT `@apexClassType/...`, single CLT, surface-specific renderer) → `platform-lightning-type-widget-coordinate`.
• A standalone widget with no MCP tool / Lightning Type → `platform-widget-generate`.
• Authoring only a CLT or only an Apex class → `platform-custom-lightning-type-generate` / `platform-apex-generate`.

> **Beta cardinality:** the invocable-action result is a bulk array (`content[]`). For the beta release this skill models and renders a **single response** — the first element of `content[]`. The CLT envelope models one result object, not the `content[]` wrapper.

---

How this differs from `platform-lightning-type-widget-coordinate`

| Dimension | agent-action flow (`...lightning-type-widget-coordinate`) | this MCP-tool flow | |---|---|---| | CLT kind | Apex-backed (`@apexClassType/...`) | Object-based (`lightning__objectType`) | | Number of CLTs | one | **two** (envelope + response) | | Field source | `@AuraEnabled` | **`@InvocableVariable`** on the response class | | Renderer location | `lightningTypes/<T>/lightningDesktopGenAi/renderer.json` (surface-specific) | `lightningTypes/<toolCLT>/renderer.json` (**default, parallel to `schema.json`**) | | Renderer binding | flat `{!$attrs.<field>}` | **nested `{!$attrs.outputValues.<field>}`** |

---

Phase Graph

| Phase | Purpose | Output | |---|---|---| | 1 — Input selection | Determine the payload source: an **invocable action API name** (preferred), an Apex Invocable class, or a pasted tool-output JSON sample. | `source` (`action` \| `apex` \| `sample`), tool API name | | 2 — Payload discovery | Describe the invocable action via the Actions REST API and read its typed `outputs` (or parse the response class from source, or `outputValues` from the sample). | `payloadFields` (name + `lightning:type`) | | 3 — Build plan | Print the plan in full; proceed unless the next reply explicitly pushes back. | printed plan | | 4 — Generation | Load and invoke leaf skills: response CLT → envelope CLT → widget → inline default renderer in the envelope CLT. | files written | | 5 — Validation | Run hard gates (block) and warn gates (advisory). | gate report | | 6 — Summary | Files, validations, deploy order, preview readiness. | summary |

**Per-phase pattern:** load the skill fresh → execute its workflow → verify outputs → checkpoint before the next phase. Even if you remember a leaf skill's content, skills evolve — always load fresh.

---

Phase 1 — Input selection

Determine where the payload shape comes from. Prefer the sources top-to-bottom:

| Source | Trigger | Phase 2 action | |---|---|---| | `action` | Prompt gives an **invocable action API name** — directly, or via an Apex class name that resolves to one — AND an authenticated org is available. **Preferred.** | Describe the action via the Actions REST API and read its typed `outputs`. | | `