mcp-create-adaptive-cards

---
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]
---

# MCPプラグン用Adaptive Cardsの作成

MCPベースのAPIプラグインにAdaptive Cardレスポンステンプレートを追加し、Microsoft 365 Copilotでのデータ表示を視覚的に強化します。

## Adaptive Cardの種類

### 静的レスポンステンプレート
APIが常に同じ型のアイテムを返し、フォーマットが頻繁に変わらない場合に使用します。

ai-plugin.jsonの`response_semantics.static_template`で定義します:

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

### 動的レスポンステンプレート
APIが複数の型を返し、各アイテムが異なるテンプレートを必要とする場合に使用します。

**ai-plugin.jsonの設定:**
```json
{
  "name": "GetTransactions",
  "description": "Returns transaction details with dynamic templates",
  "capabilities": {
    "response_semantics": {
      "data_path": "$.transactions",
      "properties": {
        "template_selector": "$.displayTemplate"
      }
    }
  }
}
```

**埋め込みテンプレート付きのAPIレスポンス:**
```json
{
  "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"
    }
  }
}
```

### 静的テンプレートと動的テンプレートの組み合わせ
アイテムにtemplate_selectorがない場合、またはvalueが解決されない場合のデフォルトとして静的テンプレートを使用します。

```json
{
  "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
          }
        ]
      }
    }
  }
}
```

## レスポンスセマンティクスのプロパティ

### data_path
APIレスポンス内のデータ位置を示すJSONPathクエリ:
```json
"data_path": "$"           // レスポンスのルート
"data_path": "$.results"   // resultsプロパティ内
"data_path": "$.data.items"// ネストされたパス
```

### properties
Copilot引用用にレスポンスフィールドをマッピング:
```json
"properties": {
  "title": "$.name",            // 引用のタイトル
  "subtitle": "$.description",  // 引用のサブタイトル
  "url": "$.link"               // 引用のリンク
}
```

### template_selector
各アイテムで使用するテンプレートを示すプロパティ:
```json
"template_selector": "$.displayTemplate"
```

## Adaptive Cardテンプレート言語

### 条件付きレンダリング
```json
{
  "type": "TextBlock",
  "text": "${if(field, field, 'N/A')}"  // フィールドを表示または'N/A'を表示
}
```

### 数値フォーマット
```json
{
  "type": "TextBlock",
  "text": "${formatNumber(amount, 2)}"  // 小数点以下2桁
}
```

### データバインディング
```json
{
  "type": "Container",
  "$data": "${$root}",  // ルートコンテキストに切り替え
  "items": [ ... ]
}
```

### 条件付き表示
```json
{
  "type": "Image",
  "url": "${imageUrl}",
  "$when": "${imageUrl != null}"  // imageUrlが存在する場合のみ表示
}
```

## カード要素

### TextBlock
```json
{
  "type": "TextBlock",
  "text": "テキスト内容",
  "size": "medium",      // small, default, medium, large, extraLarge
  "weight": "bolder",    // lighter, default, bolder
  "color": "attention",  // default, dark, light, accent, good, warning, attention
  "wrap": true
}
```

### FactSet
```json
{
  "type": "FactSet",
  "facts": [
    {
      "title": "ラベル",
      "value": "値"
    }
  ]
}
```

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

### Container
```json
{
  "type": "Container",
  "$data": "${items}",  // 配列を反復処理
  "items": [
    {
      "type": "TextBlock",
      "text": "${name}"
    }
  ]
}
```

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

### Actions
```json
{
  "type": "Action.OpenUrl",
  "title": "詳細を表示",
  "url": "https://example.com/item/${id}"
}
```

## レスポンシブデザインのベストプラクティス

### シングルカラムレイアウト
- 狭いビューポート用にシングルカラムを使用
- 可能な限りマルチカラムレイアウトを避ける
- 最小ビューポート幅でカードが機能することを確認

### 柔軟な幅
- 要素に固定幅を割り当てない
- width プロパティに「auto」または「stretch」を使用
- ビューポートのサイズ変更に応じて要素をリサイズさせる
- 固定幅はアイコン/アバター用のみOK

### テキストと画像
- テキストと画像を同じ行に配置しない
- 例外: 小さいアイコンやアバター
- テキスト内容に「wrap」: trueを使用
- 様々なビューポート幅でテスト

### ハブ間でテスト
カードを以下で検証:
- Teams (デスクトップとモバイル)
- Word
- PowerPoint
- 様々なビューポート幅 (UI の拡大/縮小)

## 完全な例

**ai-plugin.json:**
```json
{
  "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}"
              }
            ]
          }
        }
      }
    }
  ]
}
```

## ワークフロー

ユーザーに以下を確認:
1. APIが返すデータの種類は?
2. すべてのアイテムが同じ型(静的)か、異なる型(動的)か?
3. カードに表示されるべきフィールドは?
4. アクション(例:「詳細を表示」)があるべきか?
5. 異なるテンプレートが必要な複数の状態またはカテゴリがあるか?

その後、以下を生成:
- 適切なresponse_semantics設定
- 静的テンプレート、動的テンプレート、または両方
- 条件付きレンダリングを含む適切なデータバインディング
- レスポンシブなシングルカラムレイアウト
- 検証用のテストシナリオ

## リソース

- [Adaptive Card Designer](https://adaptivecards.microsoft.com/designer) - ビジュアルデザインツール
- [Adaptive Card Schema](https://adaptivecards.io/schemas/adaptive-card.json) - フルスキーマリファレンス
- [Template Language](https://learn.microsoft.com/en-us/adaptive-cards/templating/language) - バインディング構文ガイド
- [JSONPath](https://www.rfc-editor.org/rfc/rfc9535) - パスクエリ構文

## 一般的なパターン

### 画像付きリスト
```json
{
  "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
            }
          ]
        }
      ]
    }
  ]
}
```

### ステータスインジケータ
```json
{
  "type": "TextBlock",
  "text": "${status}",
  "color": "${if(status == 'Completed', 'good', if(status == 'In Progress', 'attention', 'default'))}"
}
```

### 通貨フォーマット
```json
{
  "type": "TextBlock",
  "text": "$${formatNumber(amount, 2)}"
}
```