mcp-create-adaptive-cards

✓ Official★ 36,200

by github · part of github/awesome-copilot

Adaptive Card response templates for MCP-based API plugins in Microsoft 365 Copilot. Supports static templates for consistent data formats, dynamic templates for multiple item types, and combined approaches with fallback defaults Includes JSONPath-based data mapping, conditional rendering, number formatting, and responsive single-column layouts optimized for Teams, Word, and PowerPoint Provides card elements like TextBlock, FactSet, Image, Container, ColumnSet, and actions with template...

🔥🔥🔥✓ VerifiedFreeQuick setup

#automation #git #design #video-editing

🧩 One of 7 skills in the github/awesome-copilot package — works on its own, and pairs well with its siblings.

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

by github

Copy & paste — that's it

---
mode: 'agent'
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
description: 'Add Adaptive Card response templates to MCP-based API plugins for visual data presentation in Microsoft 365 Copilot'
model: 'gpt-4.1'
tags: [mcp, adaptive-cards, m365-copilot, api-plugin, response-templates]
---

# Create Adaptive Cards for MCP Plugins

Add Adaptive Card response templates to MCP-based API plugins to enhance how data is presented visually in Microsoft 365 Copilot.

## Adaptive Card Types

### Static Response Templates
Use when API always returns items of the same type and format doesn't change often.

Define in `response_semantics.static_template` in ai-plugin.json:

```json
{
 "functions": [
 {
 "name": "GetBudgets",
 "description": "Returns budget details including name and available funds",
 "capabilities": {
 "response_semantics": {
 "data_path": "$",
 "properties": {
 "title": "$.name",
 "subtitle": "$.availableFunds"
 },
 "static_template": {
 "type": "AdaptiveCard",
 "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
 "version": "1.5",
 "body": [
 {
 "type": "Container",
 "$data": "${$root}",
 "items": [
 {
 "type": "TextBlock",
 "text": "Name: ${if(name, name, 'N/A')}",
 "wrap": true
 },
 {
 "type": "TextBlock",
 "text": "Available funds: ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}",
 "wrap": true
 }
 ]
 }
 ]
 }
 }
 }
 }
 ]
}

Dynamic Response Templates

Use when API returns multiple types and each item needs a different template.

ai-plugin.json configuration:

Copy & paste — that's it

{
 "name": "GetTransactions",
 "description": "Returns transaction details with dynamic templates",
 "capabilities": {
 "response_semantics": {
 "data_path": "$.transactions",
 "properties": {
 "template_selector": "$.displayTemplate"
 }
 }
 }
}

API Response with Embedded Templates:

Copy & paste — that's it

{
 "transactions": [
 {
 "budgetName": "Fourth Coffee lobby renovation",
 "amount": -2000,
 "description": "Property survey for permit application",
 "expenseCategory": "permits",
 "displayTemplate": "$.templates.debit"
 },
 {
 "budgetName": "Fourth Coffee lobby renovation",
 "amount": 5000,
 "description": "Additional funds to cover cost overruns",
 "expenseCategory": null,
 "displayTemplate": "$.templates.credit"
 }
 ],
 "templates": {
 "debit": {
 "type": "AdaptiveCard",
 "version": "1.5",
 "body": [
 {
 "type": "TextBlock",
 "size": "medium",
 "weight": "bolder",
 "color": "attention",
 "text": "Debit"
 },
 {
 "type": "FactSet",
 "facts": [
 {
 "title": "Budget",
 "value": "${budgetName}"
 },
 {
 "title": "Amount",
 "value": "${formatNumber(amount, 2)}"
 },
 {
 "title": "Category",
 "value": "${if(expenseCategory, expenseCategory, 'N/A')}"
 },
 {
 "title": "Description",
 "value": "${if(description, description, 'N/A')}"
 }
 ]
 }
 ],
 "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
 },
 "credit": {
 "type": "AdaptiveCard",
 "version": "1.5",
 "body": [
 {
 "type": "TextBlock",
 "size": "medium",
 "weight": "bolder",
 "color": "good",
 "text": "Credit"
 },
 {
 "type": "FactSet",
 "facts": [
 {
 "title": "Budget",
 "value": "${budgetName}"
 },
 {
 "title": "Amount",
 "value": "${formatNumber(amount, 2)}"
 },
 {
 "title": "Description",
 "value": "${if(description, description, 'N/A')}"
 }
 ]
 }
 ],
 "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
 }
 }
}

Combined Static and Dynamic Templates

Use static template as default when item doesn't have template_selector or when value doesn't resolve.

Copy & paste — that's it

{
 "capabilities": {
 "response_semantics": {
 "data_path": "$.items",
 "properties": {
 "title": "$.name",
 "template_selector": "$.templateId"
 },
 "static_template": {
 "type": "AdaptiveCard",
 "version": "1.5",
 "body": [
 {
 "type": "TextBlock",
 "text": "Default: ${name}",
 "wrap": true
 }
 ]
 }
 }
 }
}

Response Semantics Properties

data_path

JSONPath query indicating where data resides in API response:

Copy & paste — that's it

"data_path": "$" // Root of response
"data_path": "$.results" // In results property
"data_path": "$.data.items"// Nested path

properties

Map response fields for Copilot citations:

Copy & paste — that's it

"properties": {
 "title": "$.name", // Citation title
 "subtitle": "$.description", // Citation subtitle
 "url": "$.link" // Citation link
}

template_selector

Property on each item indicating which template to use:

Copy & paste — that's it

"template_selector": "$.displayTemplate"

Adaptive Card Template Language

Conditional Rendering

Copy & paste — that's it

{
 "type": "TextBlock",
 "text": "${if(field, field, 'N/A')}" // Show field or 'N/A'
}

Number Formatting

Copy & paste — that's it

{
 "type": "TextBlock",
 "text": "${formatNumber(amount, 2)}" // Two decimal places
}

Data Binding

Copy & paste — that's it

{
 "type": "Container",
 "$data": "${$root}", // Break to root context
 "items": [ ... ]
}

Conditional Display

Copy & paste — that's it

{
 "type": "Image",
 "url": "${imageUrl}",
 "$when": "${imageUrl != null}" // Only show if imageUrl exists
}

Card Elements

TextBlock

Copy & paste — that's it

{
 "type": "TextBlock",
 "text": "Text content",
 "size": "medium", // small, default, medium, large, extraLarge
 "weight": "bolder", // lighter, default, bolder
 "color": "attention", // default, dark, light, accent, good, warning, attention
 "wrap": true
}

FactSet

Copy & paste — that's it

{
 "type": "FactSet",
 "facts": [
 {
 "title": "Label",
 "value": "Value"
 }
 ]
}

Image

Copy & paste — that's it

{
 "type": "Image",
 "url": "https://example.com/image.png",
 "size": "medium", // auto, stretch, small, medium, large
 "style": "default" // default, person
}

Container

Copy & paste — that's it

{
 "type": "Container",
 "$data": "${items}", // Iterate over array
 "items": [
 {
 "type": "TextBlock",
 "text": "${name}"
 }
 ]
}

ColumnSet

Copy & paste — that's it

{
 "type": "ColumnSet",
 "columns": [
 {
 "type": "Column",
 "width": "auto",
 "items": [ ... ]
 },
 {
 "type": "Column",
 "width": "stretch",
 "items": [ ... ]
 }
 ]
}

Actions

Copy & paste — that's it

{
 "type": "Action.OpenUrl",
 "title": "View Details",
 "url": "https://example.com/item/${id}"
}

Responsive Design Best Practices

Single-Column Layouts

Use single columns for narrow viewports
Avoid multi-column layouts when possible
Ensure cards work at minimum viewport width

Flexible Widths

Don't assign fixed widths to elements
Use "auto" or "stretch" for width properties
Allow elements to resize with viewport
Fixed widths OK for icons/avatars only

Text and Images

Avoid placing text and images in same row
Exception: Small icons or avatars
Use "wrap": true for text content
Test at various viewport widths

Test Across Hubs

Validate cards in:

Teams (desktop and mobile)
Word
PowerPoint
Various viewport widths (contract/expand UI)

Complete Example

ai-plugin.json:

Copy & paste — that's it

{
 "functions": [
 {
 "name": "SearchProjects",
 "description": "Search for projects with status and details",
 "capabilities": {
 "response_semantics": {
 "data_path": "$.projects",
 "properties": {
 "title": "$.name",
 "subtitle": "$.status",
 "url": "$.projectUrl"
 },
 "static_template": {
 "type": "AdaptiveCard",
 "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
 "version": "1.5",
 "body": [
 {
 "type": "Container",
 "$data": "${$root}",
 "items": [
 {
 "type": "TextBlock",
 "size": "medium",
 "weight": "bolder",
 "text": "${if(name, name, 'Untitled Project')}",
 "wrap": true
 },
 {
 "type": "FactSet",
 "facts": [
 {
 "title": "Status",
 "value": "${status}"
 },
 {
 "title": "Owner",
 "value": "${if(owner, owner, 'Unassigned')}"
 },
 {
 "title": "Due Date",
 "value": "${if(dueDate, dueDate, 'Not set')}"
 },
 {
 "title": "Budget",
 "value": "${if(budget, formatNumber(budget, 2), 'N/A')}"
 }
 ]
 },
 {
 "type": "TextBlock",
 "text": "${if(description, description, 'No description')}",
 "wrap": true,
 "separator": true
 }
 ]
 }
 ],
 "actions": [
 {
 "type": "Action.OpenUrl",
 "title": "View Project",
 "url": "${projectUrl}"
 }
 ]
 }
 }
 }
 }
 ]
}

Workflow

Ask the user:

What type of data does the API return?
Are all items the same type (static) or different types (dynamic)?
What fields should appear in the card?
Should there be actions (e.g., "View Details")?
Are there multiple states or categories requiring different templates?

Then generate:

Appropriate response_semantics configuration
Static template, dynamic templates, or both
Proper data binding with conditional rendering
Responsive single-column layout
Test scenarios for validation

Resources

Adaptive Card Designer - Visual design tool
Adaptive Card Schema - Full schema reference
Template Language - Binding syntax guide
JSONPath - Path query syntax

Common Patterns

List with Images

Copy & paste — that's it

{
 "type": "Container",
 "$data": "${items}",
 "items": [
 {
 "type": "ColumnSet",
 "columns": [
 {
 "type": "Column",
 "width": "auto",
 "items": [
 {
 "type": "Image",
 "url": "${thumbnailUrl}",
 "size": "small",
 "$when": "${thumbnailUrl != null}"
 }
 ]
 },
 {
 "type": "Column",
 "width": "stretch",
 "items": [
 {
 "type": "TextBlock",
 "text": "${title}",
 "weight": "bolder",
 "wrap": true
 }
 ]
 }
 ]
 }
 ]
}

Status Indicators

Copy & paste — that's it

{
 "type": "TextBlock",
 "text": "${status}",
 "color": "${if(status == 'Completed', 'good', if(status == 'In Progress', 'attention', 'default'))}"
}

Currency Formatting

Copy & paste — that's it

{
 "type": "TextBlock",
 "text": "$${formatNumber(amount, 2)}"
}

Copy & paste — that's it