adaptive-cards-mcp

Adaptive Cards MCP

一个 MCP 服务，可帮助 AI 助手为 Teams、Outlook、Copilot 和其他 Microsoft 产品界面生成有效且易于访问的 Adaptive Cards。提供 9 个工具、3 种引导式工作流和 924 项测试。

博客：我构建了一个 MCP 服务，让 AI 处理 Adaptive Cards 的能力提升 10 倍

演示

您的浏览器不支持 video 标签。

快速开始

无需安装——npx 会自动下载并运行。

1. 添加到 AI 助手

claude mcp add adaptive-cards-mcp -- npx adaptive-cards-mcp

{
  "servers": {
    "adaptive-cards-mcp": {
      "command": "npx",
      "args": ["adaptive-cards-mcp"]
    }
  }
}

{
  "mcpServers": {
    "adaptive-cards-mcp": {
      "command": "npx",
      "args": ["adaptive-cards-mcp"]
    }
  }
}

{
  "mcpServers": {
    "adaptive-cards-mcp": {
      "command": "npx",
      "args": ["adaptive-cards-mcp"]
    }
  }
}

TRANSPORT=sse PORT=3001 npx adaptive-cards-mcp

# With auth enabled
TRANSPORT=sse MCP_API_KEY=your-secret npx adaptive-cards-mcp

2. 开始使用

只需用自然语言向 AI 助手提出请求：

> Create an expense approval card for Teams

> Convert this JSON data into an Adaptive Card table

> Validate this card and fix accessibility issues

> Make this card work on Outlook (v1.4)

AI 会选择合适的工具，生成有效卡片并进行验证，最后返回可直接粘贴到 Adaptive Cards Designer 中预览的生产就绪 JSON。

用法

自然语言（推荐）

描述你的需求，AI 会确定要调用哪些工具：

审批和工作流：

> Create an expense approval card for Teams with requester photo, amount,
  category, line items, and approve/reject/comment buttons

> Build a time-off request card — employee name, dates, remaining PTO balance,
  manager approval with optional rejection reason

通知和提醒：

> Create a CI/CD deployment notification: service name, environment, build number,
  commit SHA, deploy status with rollback button

> Generate a PagerDuty-style incident alert card — severity P1, affected service,
  start time, on-call engineer, acknowledge/escalate actions

数据和报告：

> Here's our Q1 sales data, turn it into a card:
  [{"region":"APAC","revenue":1250000,"growth":"12%"},
   {"region":"EMEA","revenue":980000,"growth":"8%"},
   {"region":"Americas","revenue":2100000,"growth":"15%"}]

> Convert this CSV to a card:
  Employee,Department,Start Date,Status
  Jane Kim,Engineering,2026-01-15,Active
  Bob Lee,Design,2026-02-01,Active
  Carol Wu,PM,2026-03-10,Onboarding

表单和输入：

> Create an employee onboarding checklist — new hire name, start date,
  assigned buddy, IT setup tasks with checkboxes, and a submit button

> Build a customer feedback survey card with a 1-5 star rating,
  comment field, and NPS score dropdown

个人资料和状态：

> Create a team member profile card with photo, name, title, department,
  skills tags, and contact buttons for email/chat/calendar

> Build a service health dashboard card showing 5 microservices
  with status indicators (healthy/degraded/down) and last check time

跨主机和版本管理：

> This card works in Teams but breaks in Outlook — fix it
> Make this card work on Webex (v1.3 only, no Table, no Action.Execute)
> Downgrade this v1.6 card to v1.4 for Viva Connections

验证和优化：

> Validate this card and tell me what's wrong — I'm getting render errors
> Make this card accessible — it needs to work with screen readers
> This card is too complex, optimize it for performance and compact layout

斜杠命令（MCP 提示词）

如需引导式的多步工作流，可直接使用内置提示词：

创建卡片：

> /adaptive-cards-mcp:create-adaptive-card
  description: "Expense approval with requester photo, line items table, total amount,
                and approve/reject buttons with comment field"
  host: teams
  intent: approval

运行：生成 → 验证 → 优化 → 主机配置

> /adaptive-cards-mcp:create-adaptive-card
  description: "CI/CD deployment notification with service name, environment,
                build number, status badge, and rollback action"
  host: teams
  intent: notification

> /adaptive-cards-mcp:create-adaptive-card
  description: "Employee profile card with photo, name, title, department,
                contact info, and skills tags"
  host: outlook
  intent: profile

将数据转换为卡片：

> /adaptive-cards-mcp:convert-data-to-card
  data: [
    { "task": "Review PR #482", "assignee": "Jane", "due": "2026-03-21", "status": "pending" },
    { "task": "Deploy hotfix v2.1.3", "assignee": "Bob", "due": "2026-03-19", "status": "in-progress" },
    { "task": "Update API docs", "assignee": "Carol", "due": "2026-03-22", "status": "done" }
  ]
  title: "Sprint Tasks"
  presentation: table

> /adaptive-cards-mcp:convert-data-to-card
  data: { "service": "api-gateway", "cpu": "92%", "memory": "78%", "requests": "12.4k/min",
          "p99_latency": "245ms", "error_rate": "0.3%", "uptime": "99.97%" }
  title: "Service Health — api-gateway"
  presentation: facts

运行：分析数据 → 选择最佳布局 → 验证输出

审核现有卡片：

> /adaptive-cards-mcp:review-adaptive-card
  card: { "type": "AdaptiveCard", "version": "1.6", "body": [...your card...] }
  host: outlook

运行：验证架构和无障碍性 → 自动修复问题 → 生成摘要报告

npm 库（编程方式）

如需在自己的代码（机器人、API、CI 流水线）中使用，请安装此软件包：

npm install adaptive-cards-mcp

import { generateCard, validateCardFull, dataToCard, optimizeCard } from 'adaptive-cards-mcp';

const result = await generateCard({
  content: "Create a flight status card",
  host: "teams",
  intent: "display"
});

console.log(result.card);       // Adaptive Card JSON
console.log(result.cardId);     // Reference ID for subsequent calls
console.log(result.validation); // Schema + accessibility + host compat

完整详情请参阅库 API 参考。

返回内容

生成卡片的工具会返回两个清晰的内容块：可复制的卡片 JSON，以及元数据摘要：

```json
{
  "type": "AdaptiveCard",
  "version": "1.6",
  "body": [ ... ],
  "actions": [ ... ]
}
```

---

**Validation:** Valid
**Accessibility Score:** 100/100
**Elements:** 7 | **Nesting Depth:** 2 | **Version:** 1.6
**Card ID:** card-abc123
**Steps:** generate → validate → optimize
**Try it out:** Paste the card JSON into the [Adaptive Cards Designer](https://adaptivecards.microsoft.com/designer)
**Local Preview:** file:///tmp/ac-preview-xyz.html

工具、提示词和用法

参考

MCP 工具（9 个）

MCP 提示词（3 个）

MCP 资源（5）+ 模板（2）

宿主兼容性

配置

注意： 通过 MCP（Claude Code、Copilot、Cursor）使用时，宿主大模型会提供智能能力 — 无需 API 密钥。仅在独立使用或作为库使用时才需设置 API 密钥。

遥测与隐私

遥测采用选择加入方式，默认处于禁用状态。启用后，服务会收集 匿名使用指标，并将汇总数据发送到 PostHog，以帮助改进项目。

启用方式：

• VS Code 扩展： 首次安装时会出现一次性许可提示。你可以随时在“设置” → Adaptive Cards → Telemetry 中更改此设置。
• CLI / MCP 服务： 在环境中设置 MCP_TELEMETRY=true，或编辑 ~/.adaptive-cards-mcp/config.json 并设置 "telemetry": true。

发送的内容： 工具名称、调用次数、耗时、错误率、平台（操作系统）、 Node 版本、软件包版本、传输类型。

绝不会发送的内容： 卡片内容、用户提示词、数据负载、IP 地址、 文件路径、环境变量。

每次服务启动时都会生成一个随机会话 ID — 不会跨会话存储持久标识符。

禁用方式： 设置 MCP_TELEMETRY=false，或保持未配置状态（默认关闭）。

开发

cd packages/core
npm install
npm run build         # TypeScript + copy data files
npm test              # 924 tests (vitest)
npm run test:coverage # With coverage report
npm run lint          # TypeScript type check
npm run lint:eslint   # ESLint check
npm run format        # Prettier formatting

本地测试

对所有工具和提示词进行冒烟测试：

./test-mcp-tools.sh --local     # 28 tests — all 9 tools with real-world scenarios
./test-mcp-prompts.sh --local   # 10 tests — all 3 prompts (guided workflows)
./test-mcp-tools.sh             # same tests against published npm package
./test-mcp-prompts.sh           # same tests against published npm package

MCP Inspector（可视化 UI）：

cd packages/core && npm run build
npx @modelcontextprotocol/inspector node dist/server.js
# Opens http://localhost:6274 — pick a tool, enter params, click Run

终端（stdio）：

cd packages/core
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"generate_card","arguments":{"content":"expense approval card","intent":"approval","host":"teams"}}}' \
  | node dist/server.js 2>/dev/null | tail -1 | python3 -m json.tool

SSE 模式：

TRANSPORT=sse PORT=3001 node packages/core/dist/server.js
curl http://localhost:3001/health

架构

packages/core/src/
├── server.ts              # MCP server (stdio + SSE, 9 tools, 3 prompts)
├── index.ts               # Library exports
├── types/                 # TypeScript interfaces
├── core/                  # Schema validator, analyzer, accessibility, host compat
├── generation/            # 21 layout patterns, data analyzer, assembler, LLM client
├── tools/                 # 9 tool handlers
├── utils/                 # Logger, input guards, rate limiter, card store, auth, telemetry, preview
└── data/                  # v1.6 schema, 36 examples, host configs

生态系统

v2.3.0 新增内容

• 无障碍评分 100/100 — 现在所有生成的卡片都会自动包含 speak 属性
• 不再生成损坏的 JSON — 清理内容中的换行符，标题不再在版本号处被截断
• 感知宿主的生成 — generate_and_validate 会自动为 Outlook（v1.4）、Webex（v1.3）降级卡片版本
• CSV 修复 — 在构建 FactSet/Table 卡片之前正确解析 CSV 数据
• 遥测 — /metrics 端点支持会话跟踪、按工具统计调用分布，以及宿主/意图用量统计
• MCP Registry — 已列入官方 MCP Registry
• 端到端测试套件 — 包含 28 项工具测试和 10 项提示词测试，并设置质量门槛（无障碍评分、元素数量）

详情请参阅完整的 CHANGELOG。

链接

• npm — 安装和软件包详情
• GitHub — 源代码、问题和贡献
• MCP Registry — 官方 MCP 服务列表

相关项目

• AdaptiveCards-Mobile — 跨平台 Adaptive Cards 渲染器
• openclaw-adaptive-cards — 使用此库的 OpenClaw AI Agent 插件
• Adaptive Cards Documentation — 官方文档
• Adaptive Cards Designer — 交互式卡片设计器
• Adaptive Cards Schema Explorer — 交互式架构参考

许可证

MIT