{
  "markdown": "# Adaptive Cards MCP\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)\n[![Adaptive Cards](https://img.shields.io/badge/Adaptive%20Cards-v1.6-blue.svg)](https://adaptivecards.io/)\n[![CI](https://github.com/VikrantSingh01/adaptive-cards-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/VikrantSingh01/adaptive-cards-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/adaptive-cards-mcp.svg)](https://www.npmjs.com/package/adaptive-cards-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/adaptive-cards-mcp.svg)](https://www.npmjs.com/package/adaptive-cards-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-brightgreen.svg)](https://registry.modelcontextprotocol.io/?q=adaptive)\n[![GitHub stars](https://img.shields.io/github/stars/VikrantSingh01/adaptive-cards-mcp.svg?style=social)](https://github.com/VikrantSingh01/adaptive-cards-mcp)\n\n<p align=\"center\">\n  <img src=\"media/hero.png\" alt=\"adaptive-cards-mcp — 9 tools, 21 patterns, 924 tests, 0 competitors\" width=\"800\">\n</p>\n\nAn MCP server that helps AI assistants generate valid, accessible Adaptive Cards for Teams, Outlook, Copilot, and other Microsoft surfaces. 9 tools, 3 guided workflows, 924 tests.\n\n> **Blog:** [I Built an MCP Server That Makes AI 10x Better at Adaptive Cards](https://singhvikrant.substack.com/p/i-built-an-mcp-server-that-makes)\n\n## Demo\n\n<p align=\"center\">\n  <video src=\"https://github.com/user-attachments/assets/372655ce-776c-4e31-a77a-4b2f79f638d2\" width=\"800\" autoplay loop muted playsinline>\n    Your browser does not support the video tag.\n  </video>\n</p>\n\n## Quick Start\n\nNo install needed — `npx` downloads and runs it automatically.\n\n### 1. Add to your AI assistant\n\n<details open>\n<summary><strong>Claude Code</strong></summary>\n\n```bash\nclaude mcp add adaptive-cards-mcp -- npx adaptive-cards-mcp\n```\n</details>\n\n<details>\n<summary><strong>GitHub Copilot (VS Code)</strong></summary>\n\nAdd to `.vscode/mcp.json`:\n```json\n{\n  \"servers\": {\n    \"adaptive-cards-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"adaptive-cards-mcp\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\nAdd to `.cursor/mcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"adaptive-cards-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"adaptive-cards-mcp\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Windsurf</strong></summary>\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"adaptive-cards-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"adaptive-cards-mcp\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Microsoft 365 Copilot / Copilot Studio (HTTP/SSE)</strong></summary>\n\n```bash\nTRANSPORT=sse PORT=3001 npx adaptive-cards-mcp\n\n# With auth enabled\nTRANSPORT=sse MCP_API_KEY=your-secret npx adaptive-cards-mcp\n```\n\n1. Open [Copilot Studio](https://copilotstudio.microsoft.com/) → your agent → Tools → Add a tool → New tool → **Model Context Protocol**\n2. Enter your MCP server URL (e.g., `https://your-server.azurewebsites.net/sse`)\n3. Select the tools to expose\n</details>\n\n<details>\n<summary><strong>OpenAI ChatGPT</strong></summary>\n\n1. Enable [Developer mode](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta) in ChatGPT settings\n2. Go to Settings → Connectors → Create\n3. Enter your MCP server HTTPS URL\n</details>\n\n### 2. Start using it\n\nJust ask your AI assistant in natural language:\n\n```\n> Create an expense approval card for Teams\n```\n```\n> Convert this JSON data into an Adaptive Card table\n```\n```\n> Validate this card and fix accessibility issues\n```\n```\n> Make this card work on Outlook (v1.4)\n```\n\nThe AI picks the right tools, generates a valid card, validates it, and returns production-ready JSON you can paste directly into the [Adaptive Cards Designer](https://adaptivecards.microsoft.com/designer) to preview.\n\n## Usage\n\n### Natural language (recommended)\n\nDescribe what you need — the AI figures out which tools to call:\n\n**Approvals and workflows:**\n```\n> Create an expense approval card for Teams with requester photo, amount,\n  category, line items, and approve/reject/comment buttons\n```\n```\n> Build a time-off request card — employee name, dates, remaining PTO balance,\n  manager approval with optional rejection reason\n```\n\n**Notifications and alerts:**\n```\n> Create a CI/CD deployment notification: service name, environment, build number,\n  commit SHA, deploy status with rollback button\n```\n```\n> Generate a PagerDuty-style incident alert card — severity P1, affected service,\n  start time, on-call engineer, acknowledge/escalate actions\n```\n\n**Data and reports:**\n```\n> Here's our Q1 sales data, turn it into a card:\n  [{\"region\":\"APAC\",\"revenue\":1250000,\"growth\":\"12%\"},\n   {\"region\":\"EMEA\",\"revenue\":980000,\"growth\":\"8%\"},\n   {\"region\":\"Americas\",\"revenue\":2100000,\"growth\":\"15%\"}]\n```\n```\n> Convert this CSV to a card:\n  Employee,Department,Start Date,Status\n  Jane Kim,Engineering,2026-01-15,Active\n  Bob Lee,Design,2026-02-01,Active\n  Carol Wu,PM,2026-03-10,Onboarding\n```\n\n**Forms and input:**\n```\n> Create an employee onboarding checklist — new hire name, start date,\n  assigned buddy, IT setup tasks with checkboxes, and a submit button\n```\n```\n> Build a customer feedback survey card with a 1-5 star rating,\n  comment field, and NPS score dropdown\n```\n\n**Profiles and status:**\n```\n> Create a team member profile card with photo, name, title, department,\n  skills tags, and contact buttons for email/chat/calendar\n```\n```\n> Build a service health dashboard card showing 5 microservices\n  with status indicators (healthy/degraded/down) and last check time\n```\n\n**Cross-host and versioning:**\n```\n> This card works in Teams but breaks in Outlook — fix it\n> Make this card work on Webex (v1.3 only, no Table, no Action.Execute)\n> Downgrade this v1.6 card to v1.4 for Viva Connections\n```\n\n**Validation and optimization:**\n```\n> Validate this card and tell me what's wrong — I'm getting render errors\n> Make this card accessible — it needs to work with screen readers\n> This card is too complex, optimize it for performance and compact layout\n```\n\n| What you say | What the AI calls |\n|-------------|-------------------|\n| \"Create a leave approval card for Teams\" | `generate_and_validate` → optimized card with Approve/Reject actions |\n| \"Here's my API response, make it a card\" | `data_to_card` → auto-picks Table/FactSet/List based on data shape |\n| \"Is this card valid for Outlook?\" | `validate_card` → schema errors, accessibility score, host compatibility |\n| \"Make this card accessible\" | `optimize_card` → adds wrap, altText, speak, heading styles |\n| \"Convert this card to a reusable template\" | `template_card` → static values become `${expression}` bindings |\n| \"This card needs to work on v1.3\" | `transform_card` → downgrades, removes unsupported features |\n| \"What layout should I use for a dashboard?\" | `suggest_layout` → pattern recommendation with rationale |\n\n### Slash commands (MCP prompts)\n\nFor guided, multi-step workflows, use the built-in prompts directly:\n\n**Create a card:**\n```\n> /adaptive-cards-mcp:create-adaptive-card\n  description: \"Expense approval with requester photo, line items table, total amount,\n                and approve/reject buttons with comment field\"\n  host: teams\n  intent: approval\n```\nRuns: generate → validate → optimize → host config\n\n```\n> /adaptive-cards-mcp:create-adaptive-card\n  description: \"CI/CD deployment notification with service name, environment,\n                build number, status badge, and rollback action\"\n  host: teams\n  intent: notification\n```\n\n```\n> /adaptive-cards-mcp:create-adaptive-card\n  description: \"Employee profile card with photo, name, title, department,\n                contact info, and skills tags\"\n  host: outlook\n  intent: profile\n```\n\n**Convert data to a card:**\n```\n> /adaptive-cards-mcp:convert-data-to-card\n  data: [\n    { \"task\": \"Review PR #482\", \"assignee\": \"Jane\", \"due\": \"2026-03-21\", \"status\": \"pending\" },\n    { \"task\": \"Deploy hotfix v2.1.3\", \"assignee\": \"Bob\", \"due\": \"2026-03-19\", \"status\": \"in-progress\" },\n    { \"task\": \"Update API docs\", \"assignee\": \"Carol\", \"due\": \"2026-03-22\", \"status\": \"done\" }\n  ]\n  title: \"Sprint Tasks\"\n  presentation: table\n```\n\n```\n> /adaptive-cards-mcp:convert-data-to-card\n  data: { \"service\": \"api-gateway\", \"cpu\": \"92%\", \"memory\": \"78%\", \"requests\": \"12.4k/min\",\n          \"p99_latency\": \"245ms\", \"error_rate\": \"0.3%\", \"uptime\": \"99.97%\" }\n  title: \"Service Health — api-gateway\"\n  presentation: facts\n```\n\nRuns: analyze data → pick best layout → validate output\n\n**Review an existing card:**\n```\n> /adaptive-cards-mcp:review-adaptive-card\n  card: { \"type\": \"AdaptiveCard\", \"version\": \"1.6\", \"body\": [...your card...] }\n  host: outlook\n```\nRuns: validate schema + accessibility → auto-fix issues → summary report\n\n### npm library (programmatic)\n\nFor use in your own code (bots, APIs, CI pipelines), install the package:\n\n```bash\nnpm install adaptive-cards-mcp\n```\n\n```typescript\nimport { generateCard, validateCardFull, dataToCard, optimizeCard } from 'adaptive-cards-mcp';\n\nconst result = await generateCard({\n  content: \"Create a flight status card\",\n  host: \"teams\",\n  intent: \"display\"\n});\n\nconsole.log(result.card);       // Adaptive Card JSON\nconsole.log(result.cardId);     // Reference ID for subsequent calls\nconsole.log(result.validation); // Schema + accessibility + host compat\n```\n\nSee the [Library API reference](packages/core/README.md#library-usage) for full details.\n\n## What you get back\n\nCard-producing tools return **two clean blocks** — card JSON you can copy, and a metadata summary:\n\n````\n```json\n{\n  \"type\": \"AdaptiveCard\",\n  \"version\": \"1.6\",\n  \"body\": [ ... ],\n  \"actions\": [ ... ]\n}\n```\n\n---\n\n**Validation:** Valid\n**Accessibility Score:** 100/100\n**Elements:** 7 | **Nesting Depth:** 2 | **Version:** 1.6\n**Card ID:** card-abc123\n**Steps:** generate → validate → optimize\n**Try it out:** Paste the card JSON into the [Adaptive Cards Designer](https://adaptivecards.microsoft.com/designer)\n**Local Preview:** file:///tmp/ac-preview-xyz.html\n````\n\n## Tools, Prompt and Usage\n\n<p align=\"center\">\n  <img src=\"media/mcp-tools.png\" alt=\"9 MCP tools for Adaptive Cards\" width=\"800\">\n</p>\n\n<p align=\"center\">\n  <img src=\"media/mcp-generate.png\" alt=\"generate_card producing a leave approval card for Teams\" width=\"800\">\n</p>\n\n## Reference\n\n### MCP Tools (9)\n\n| Tool | Description |\n|------|-------------|\n| `generate_card` | Natural language / data → valid Adaptive Card v1.6 JSON |\n| `validate_card` | Schema validation + accessibility score + host compatibility + suggested fixes |\n| `data_to_card` | Auto-select Table / FactSet / Chart / List from data shape |\n| `optimize_card` | Improve accessibility, performance, modernize actions |\n| `template_card` | Static card → `${expression}` data-bound template |\n| `transform_card` | Version upgrade/downgrade, host-config adaptation |\n| `suggest_layout` | Recommend best layout pattern for a description |\n| `generate_and_validate` | Generate + validate + optionally optimize in one call |\n| `card_workflow` | Multi-step pipeline: generate → optimize → template → transform |\n\n### MCP Prompts (3)\n\n| Prompt | Pipeline | Slash command |\n|--------|----------|---------------|\n| `create-adaptive-card` | generate → validate → optimize → host config | `/adaptive-cards-mcp:create-adaptive-card` |\n| `review-adaptive-card` | validate → auto-fix → before/after report | `/adaptive-cards-mcp:review-adaptive-card` |\n| `convert-data-to-card` | analyze data → pick presentation → validate | `/adaptive-cards-mcp:convert-data-to-card` |\n\n### MCP Resources (5) + Templates (2)\n\n| Resource | Description |\n|----------|-------------|\n| `ac://schema/v1.6` | Complete JSON Schema for Adaptive Cards v1.6 |\n| `ac://hosts` | Host compatibility matrix for all 7 hosts |\n| `ac://hosts/{hostName}` | Single host compatibility info |\n| `ac://examples` | 36 curated example cards catalog |\n| `ac://examples/{intent}` | Examples filtered by intent |\n| `ac://patterns` | 21 canonical layout patterns |\n| `ac://cards` | Session card store (cards by cardId) |\n\n### Host Compatibility\n\n| Host | Max Version | Notes |\n|------|-------------|-------|\n| Generic | 1.6 | Default — no host-specific constraints |\n| Teams | 1.6 | Max 6 actions, Action.Execute preferred |\n| Outlook | 1.4 | Limited elements, max 4 actions |\n| Web Chat | 1.6 | Full support |\n| Windows | 1.6 | Subset of elements |\n| Viva Connections | 1.4 | SPFx-based ACE framework |\n| Webex | 1.3 | No Table, no Action.Execute |\n\n### Configuration\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `TRANSPORT` | Transport mode: `stdio` or `sse` | `stdio` |\n| `PORT` | HTTP port for SSE transport | `3001` |\n| `MCP_API_KEY` | API key for HTTP auth | *(disabled)* |\n| `MCP_AUTH_MODE` | Auth mode: `bearer` for token validation | *(disabled)* |\n| `ANTHROPIC_API_KEY` | Anthropic Claude API key | *(deterministic mode)* |\n| `OPENAI_API_KEY` | OpenAI API key | *(deterministic mode)* |\n| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key | *(disabled)* |\n| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint URL | *(disabled)* |\n| `OLLAMA_BASE_URL` | Ollama local model URL | *(disabled)* |\n| `DEBUG` | Enable debug logging: `adaptive-cards-mcp` | *(disabled)* |\n| `MCP_RATE_LIMIT` | Enable rate limiting: `true` | `false` |\n| `MCP_TELEMETRY` | Enable telemetry: `true` to opt-in | `false` |\n| `POSTHOG_API_KEY` | PostHog project API key for remote reporting | *(disabled)* |\n| `POSTHOG_HOST` | PostHog API host | `https://eu.i.posthog.com` |\n\n> **Note:** When used via MCP (Claude Code, Copilot, Cursor), the host LLM provides the intelligence — no API key needed. Set an API key only for standalone/library usage.\n\n### Telemetry & Privacy\n\nTelemetry is **opt-in** and disabled by default. When enabled, the server collects\nanonymous usage metrics and sends aggregated data to PostHog to help improve the project.\n\n**How to enable:**\n- **VS Code extension:** A one-time consent prompt appears on first install. You can\n  change it anytime in Settings → Adaptive Cards → Telemetry.\n- **CLI / MCP server:** Set `MCP_TELEMETRY=true` in your environment, or edit\n  `~/.adaptive-cards-mcp/config.json` and set `\"telemetry\": true`.\n\n**What is sent:** Tool names, call counts, durations, error rates, platform (OS),\nNode version, package version, transport type.\n\n**What is never sent:** Card content, user prompts, data payloads, IP addresses,\nfile paths, environment variables.\n\nA random session ID is generated each time the server starts — no persistent\nidentifier is stored across sessions.\n\n**To disable:** Set `MCP_TELEMETRY=false` or leave unconfigured (default is off).\n\n## Development\n\n```bash\ncd packages/core\nnpm install\nnpm run build         # TypeScript + copy data files\nnpm test              # 924 tests (vitest)\nnpm run test:coverage # With coverage report\nnpm run lint          # TypeScript type check\nnpm run lint:eslint   # ESLint check\nnpm run format        # Prettier formatting\n```\n\n### Local Testing\n\n**Smoke test all tools and prompts:**\n```bash\n./test-mcp-tools.sh --local     # 28 tests — all 9 tools with real-world scenarios\n./test-mcp-prompts.sh --local   # 10 tests — all 3 prompts (guided workflows)\n./test-mcp-tools.sh             # same tests against published npm package\n./test-mcp-prompts.sh           # same tests against published npm package\n```\n\n**MCP Inspector (visual UI):**\n```bash\ncd packages/core && npm run build\nnpx @modelcontextprotocol/inspector node dist/server.js\n# Opens http://localhost:6274 — pick a tool, enter params, click Run\n```\n\n**Terminal (stdio):**\n```bash\ncd packages/core\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}\n{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"generate_card\",\"arguments\":{\"content\":\"expense approval card\",\"intent\":\"approval\",\"host\":\"teams\"}}}' \\\n  | node dist/server.js 2>/dev/null | tail -1 | python3 -m json.tool\n```\n\n**SSE mode:**\n```bash\nTRANSPORT=sse PORT=3001 node packages/core/dist/server.js\ncurl http://localhost:3001/health\n```\n\n### Architecture\n\n```\npackages/core/src/\n├── server.ts              # MCP server (stdio + SSE, 9 tools, 3 prompts)\n├── index.ts               # Library exports\n├── types/                 # TypeScript interfaces\n├── core/                  # Schema validator, analyzer, accessibility, host compat\n├── generation/            # 21 layout patterns, data analyzer, assembler, LLM client\n├── tools/                 # 9 tool handlers\n├── utils/                 # Logger, input guards, rate limiter, card store, auth, telemetry, preview\n└── data/                  # v1.6 schema, 36 examples, host configs\n```\n\n## Ecosystem\n\n| Package | Description |\n|---------|-------------|\n| [packages/core](packages/core/) | MCP server + npm library (9 tools) — [npm](https://www.npmjs.com/package/adaptive-cards-mcp) |\n| [packages/vscode-extension](packages/vscode-extension/) | VS Code extension — [adaptive-cards-ai-vscode](https://github.com/VikrantSingh01/adaptive-cards-ai-vscode) |\n\n## What's New in v2.3.0\n\n- **Accessibility 100/100** — All generated cards now include `speak` property automatically\n- **No more broken JSON** — Newlines in content sanitized, titles no longer truncate at version numbers\n- **Host-aware generation** — `generate_and_validate` auto-downgrades card version for Outlook (v1.4), Webex (v1.3)\n- **CSV fix** — CSV data correctly parsed before building FactSet/Table cards\n- **Telemetry** — `/metrics` endpoint with session tracking, per-tool call distribution, host/intent usage\n- **MCP Registry** — Listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/?q=adaptive)\n- **E2E test suite** — 28 tool tests + 10 prompt tests with quality gates (a11y score, element count)\n\nSee the full [CHANGELOG](CHANGELOG.md) for details.\n\n## Links\n\n- [npm](https://www.npmjs.com/package/adaptive-cards-mcp) — Install and package details\n- [GitHub](https://github.com/VikrantSingh01/adaptive-cards-mcp) — Source code, issues, and contributions\n- [MCP Registry](https://registry.modelcontextprotocol.io/?q=adaptive) — Official MCP server listing\n\n## Related Projects\n\n- [AdaptiveCards-Mobile](https://github.com/nicfera/AdaptiveCards-Mobile) — Cross-platform Adaptive Cards renderer\n- [openclaw-adaptive-cards](https://github.com/VikrantSingh01/openclaw-adaptive-cards) — OpenClaw AI agent plugin using this library\n- [Adaptive Cards Documentation](https://adaptivecards.microsoft.com/) — Official docs\n- [Adaptive Cards Designer](https://adaptivecards.microsoft.com/designer) — Interactive card designer\n- [Adaptive Cards Schema Explorer](https://adaptivecards.io/explorer/) — Interactive schema reference\n\n## License\n\nMIT\n",
  "bytes": 19021,
  "sha": "c1f1004e946a30505eb4ac2e5bb74483ad3d5a8175428481c49cb5cd05779770",
  "repo_slug": "vikrantsingh01/adaptive-cards-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vikrantsingh01_adaptive_cards__e83b763d/readme"
}