/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"
  domains: ["Platform", "Agentforce"]
  minApiVersion: "67.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.

**Ownership boundary** — this skill owns only:

1. the **MCP-tool use case** — resolving the tool's output shape and orchestrating the leaf skills in the right order; and 2. the **envelope CLT's default `renderer.json`** — the one artifact it authors inline, bridging the envelope to the widget.

The **CLTs** are authored by `platform-custom-lightning-type-generate`, and **all widget metadata** (schema + body + `.uiwidget-meta.xml`) is authored and validated by `platform-widget-generate`. This skill never writes widget metadata and never modifies the Apex class — it supplies each leaf skill its inputs and wires the result together.

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-reference prefix — see the namespace note below).
• The CLT that is the exact shape of the Invocable Action's **response** (`@InvocableVariable` fields on the `@InvocableMethod` response class), named `<toolApiName>Response` — "Response" is not an invented role word; it is the word the Apex source itself uses for that class.

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>}`.

> **Namespace prefix provenance (`c__` / `@apexClassType/<ns>__…`):** the Actions REST describe returns bare, unprefixed class names (`Outer$Inner`) and no namespace — the prefix is the *org's CLT namespace*, added by this skill. It is `c__` in a namespace-less org (the common case, used literally throughout this doc) or the package namespace `<ns>__` in a packaged org (read from the class's `NamespacePrefix`; default to `c` only when the org has none). Every `c__` below is this prefix.

**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 top-level response class (referenced inner classes: public/`@AuraEnabled` — see Hard Rule 6) | | 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 | De