{"_id":"@apigene/mcp-app-playground","_rev":"3-c38f9d058d84632895f15ca7d6ef3831","name":"@apigene/mcp-app-playground","dist-tags":{"latest":"0.0.4"},"versions":{"0.0.1":{"name":"@apigene/mcp-app-playground","version":"0.0.1","keywords":["mcp","model-context-protocol","templates","mcp-apps","apigene","claude","mcpjam"],"author":{"url":"https://apigene.ai","name":"Apigene","email":"hello@apigene.ai"},"license":"MIT","_id":"@apigene/mcp-app-playground@0.0.1","maintainers":[{"name":"senkevichdv","email":"senkevichdv@me.com"},{"name":"yanivshani100","email":"yaniv@apigene.ai"}],"homepage":"https://apigene.ai","bin":{"mcp-app-playground":"bin/mcp-app-playground.mjs"},"dist":{"shasum":"c5f579d5f134da466140743e042b20d0641b3ab1","tarball":"https://registry.npmjs.org/@apigene/mcp-app-playground/-/mcp-app-playground-0.0.1.tgz","fileCount":307,"integrity":"sha512-bIUSHCgTDyHDvQCrq2qRqlQJEqysfjNwhxb0OzwX/DRGb1RWApr5FQFyYB/xxGnlXnIyBSJzTS6DBiWFVj1Skg==","signatures":[{"sig":"MEQCIFZEgl2pZRjMEZJShftMbhoY6rn+LcGkB8v6vZzzAvkSAiB71hoL8doHfo64u4WovZxduPRCj3yVdUQoM7V0nmCQ0w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4463993},"type":"module","engines":{"node":">=18"},"gitHead":"0ce22bbaa00ad3f2cbad75b7ecae3007d9a1a499","scripts":{"lab":"node tools/template-lab/server.mjs","list":"node bin/mcp-app-playground.mjs list","start":"node bin/mcp-app-playground.mjs start","mcp:http":"npm run server:http --prefix tools/template-mcp-server","mcp:stdio":"npm run server:stdio --prefix tools/template-mcp-server"},"_npmUser":{"name":"senkevichdv","email":"senkevichdv@me.com"},"_npmVersion":"10.9.3","description":"MCP app templates with local preview and MCP demo tools","directories":{},"_nodeVersion":"22.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp-app-playground_0.0.1_1770904632080_0.518591341398718","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@apigene/mcp-app-playground","version":"0.0.2","keywords":["mcp","model-context-protocol","templates","mcp-apps","apigene","claude","mcpjam"],"author":{"url":"https://apigene.ai","name":"Apigene","email":"hello@apigene.ai"},"license":"MIT","_id":"@apigene/mcp-app-playground@0.0.2","maintainers":[{"name":"senkevichdv","email":"senkevichdv@me.com"},{"name":"yanivshani100","email":"yaniv@apigene.ai"}],"homepage":"https://apigene.ai","bin":{"mcp-app-playground":"bin/mcp-app-playground.mjs"},"dist":{"shasum":"17cd7a09d5dd4e0dbb1af012ed937ece08f1a592","tarball":"https://registry.npmjs.org/@apigene/mcp-app-playground/-/mcp-app-playground-0.0.2.tgz","fileCount":307,"integrity":"sha512-DJCfV+zwCADq5cinE0O5biTx+Yt/i+ttIEsOY9Ocl/Jc1w2lqDZmU2NtB2PKMCKWse9tny8+nRsEdD5YwcYq4A==","signatures":[{"sig":"MEUCIQCoJWoeKNcvNfHYPEkp9P8zrDJqAOSD7R+/2L++GSiN/gIgXD/fIABYNG9zU6dfT/vV3KCg1zcDXxmd3mqU4JYq3T0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4464289},"type":"module","engines":{"node":">=18"},"gitHead":"0ce22bbaa00ad3f2cbad75b7ecae3007d9a1a499","scripts":{"lab":"node tools/template-lab/server.mjs","list":"node bin/mcp-app-playground.mjs list","start":"node bin/mcp-app-playground.mjs start","mcp:http":"node --import tsx tools/template-mcp-server/main.ts","mcp:stdio":"node --import tsx tools/template-mcp-server/main.ts --stdio"},"_npmUser":{"name":"senkevichdv","email":"senkevichdv@me.com"},"_npmVersion":"10.9.3","description":"MCP app templates with local preview and MCP demo tools","directories":{},"_nodeVersion":"22.18.0","dependencies":{"tsx":"^4.21.0","zod":"^3.24.1","cors":"^2.8.5","express":"^5.1.0","@modelcontextprotocol/sdk":"^1.24.0","@modelcontextprotocol/ext-apps":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp-app-playground_0.0.2_1770904784866_0.8684996306411992","host":"s3://npm-registry-packages-npm-production"}},"0.0.4":{"name":"@apigene/mcp-app-playground","publishConfig":{"access":"public"},"version":"0.0.4","description":"MCP app templates with local preview and MCP demo tools","type":"module","author":{"name":"Apigene","email":"hello@apigene.ai","url":"https://apigene.ai"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/apigene/mcp-apps.git"},"homepage":"https://github.com/apigene/mcp-apps","keywords":["mcp","model-context-protocol","templates","mcp-apps","apigene","claude","mcpjam"],"dependencies":{"@modelcontextprotocol/ext-apps":"^1.0.0","@modelcontextprotocol/sdk":"^1.24.0","cors":"^2.8.5","express":"^5.1.0","tsx":"^4.21.0","zod":"^3.24.1"},"bin":{"mcp-app-playground":"bin/mcp-app-playground.mjs"},"scripts":{"build":"echo 'No build step — examples run as ES modules'","dev":"node bin/mcp-app-playground.mjs start","start":"node bin/mcp-app-playground.mjs start","lab":"node playground/playground-app/server.mjs","list":"node bin/mcp-app-playground.mjs list","mcp:http":"node --import tsx playground/playground-mcp-server/main.ts","mcp:stdio":"node --import tsx playground/playground-mcp-server/main.ts --stdio","build:examples":"node bin/mcp-app-playground.mjs build"},"engines":{"node":">=18"},"devDependencies":{"@types/express":"^5.0.6"},"gitHead":"c90028da5931a7c52c805c507415447adf06df49","_id":"@apigene/mcp-app-playground@0.0.4","bugs":{"url":"https://github.com/apigene/mcp-apps/issues"},"_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-QP7o2LH5PLUQQF8Zih9NuTAl0PFLX4I7KYJdpVHBac9zoJcDasFfpClOdKtUQiYRsjFq5GPAxLNVAZO/SHeqsg==","shasum":"8223827c335477d799da466b42dfd98b344ba2f1","tarball":"https://registry.npmjs.org/@apigene/mcp-app-playground/-/mcp-app-playground-0.0.4.tgz","fileCount":550,"unpackedSize":23305815,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@apigene%2fmcp-app-playground@0.0.4","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCzDDZaU6cbCWr8QYPCUmyKvmHC9DU92TqYaBu24ObuEAIgI5RAjhNnM4ku+1o9UdlikxcD1IFsMyBs7RpcqiCLwls="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:357f41ef-2ad2-4dff-af37-69ddaf744db1"}},"directories":{},"maintainers":[{"name":"senkevichdv","email":"senkevichdv@me.com"},{"name":"yanivshani100","email":"yaniv@apigene.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-app-playground_0.0.4_1771926319436_0.8071139758351722"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-12T13:57:11.987Z","modified":"2026-02-24T09:45:20.075Z","0.0.1":"2026-02-12T13:57:12.342Z","0.0.2":"2026-02-12T13:59:45.163Z","0.0.4":"2026-02-24T09:45:19.801Z"},"author":{"name":"Apigene","email":"hello@apigene.ai","url":"https://apigene.ai"},"license":"MIT","homepage":"https://github.com/apigene/mcp-apps","keywords":["mcp","model-context-protocol","templates","mcp-apps","apigene","claude","mcpjam"],"description":"MCP app templates with local preview and MCP demo tools","maintainers":[{"name":"senkevichdv","email":"senkevichdv@me.com"},{"name":"yanivshani100","email":"yaniv@apigene.ai"}],"readme":"# MCP Apps\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![npm version](https://img.shields.io/npm/v/@apigene/mcp-app-playground.svg)](https://www.npmjs.com/package/@apigene/mcp-app-playground)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n\n---\n\n## What is MCP App Playground?\n\n**MCP App Playground** is a collection of **dozens of mock MCP App examples** inspired by real-world services (GitHub, Slack, Google Analytics, Shopify, Datadog, and many more). Each example is a small, self-contained UI that shows how to build an [MCP App](https://modelcontextprotocol.io) — an interactive HTML/TypeScript/CSS component that runs inside iframes in Claude and other AI hosts and displays tool results.\n\nUse this repo to **see how MCP Apps are implemented** and to **simulate and evaluate** them locally. It ships with **one MCP server** you can run on your machine: point your AI client (e.g. Claude, Cursor) at it, invoke the demo tools, and see how the apps render and behave — no need to build your own server or real integrations first.\n\n\n## Quick Start\n\n### Run the Playground (preview any template instantly)\n\n**Without cloning (from anywhere):**\n\n```bash\nnpx @apigene/mcp-app-playground\n```\n\nOpens:\n- **MCP Apps Playground** at `http://localhost:4311` — preview templates with mock data\n- **MCP HTTP endpoint** at `http://localhost:3001/mcp` — for full host integration\n\n\n**From the repo (after cloning):**\n\n```bash\ncd mcp-apps\nnpm install\nnpm start\n```\n\n\n\n### Create a New Template\n\n```bash\n# Copy the base template\ncp -r examples/base-template examples/my-app\ncd examples/my-app\nnpm install\nnpm run build\n# Output: dist/mcp-app.html (single-file bundle)\n```\n\nThen open `examples/my-app/src/mcp-app.ts` and implement `renderData()`.\n\n---\n\n## Example Templates\n\n| Template | Description |\n|----------|-------------|\n| `github-list-commits` | GitHub commit history with author info |\n| `github-commit-diff` | Side-by-side diffs with syntax highlighting |\n| `google-analytics` | Analytics dashboard with charts |\n| `google-search-console` | Search performance table |\n| `slack-search-messages` | Message search results |\n| `spotify-search` | Track/album search cards |\n| `shopify-get-product-details` | Product detail view |\n| `vercel-get-deployments` | Deployment status list |\n| `datadog-listlogs` | Log stream viewer |\n| `notion-search` | Notion page search results |\n| `tesla-controls` | Vehicle control panel |\n| `firecrawl-scrape-url` | Web scrape results |\n| `tavily-search` | AI-powered search results |\n| `apollo-people-search` | People search cards |\n| `brightdata-*` | 10+ Brightdata API integrations |\n| `google-maps-search` | Location search with map preview |\n| … | [44 more in `examples/`](examples/) |\n\n---\n\n## Base Template\n\n### `examples/base-template`\n\nThe single base template for all MCP Apps. It uses the official `@modelcontextprotocol/ext-apps` SDK (theme, fonts, host styling) and builds to a single `dist/mcp-app.html` via Vite.\n\n**Includes:** Dark mode, responsive layout, host context (theme/fonts/display mode), tool result/cancel/teardown handling.\n\n```bash\ncd examples/base-template\nnpm install && npm run build\n```\n\nSee `examples/base-template/README.md` for SDK usage, event handlers, and customization. For Content Security Policy (e.g. external scripts/fonts), see `examples/base-template/CSP_GUIDE.md`.\n\n---\n\n## Template Architecture\n\nEvery MCP App template follows the same contract (from `examples/base-template`):\n\n```\nmy-app/\n├── mcp-app.html          # Entry point (loads CSS and TS module for dev)\n├── src/\n│   ├── mcp-app.ts        # ★ Implement renderData() here; SDK + handlers\n│   ├── mcp-app.css       # App-specific styles\n│   └── global.css        # Shared base styles (do not modify)\n├── package.json          # Scripts: build, dev; deps: @modelcontextprotocol/ext-apps\n├── vite.config.ts        # Vite + single-file output\n├── template-metadata.json # Optional: uiElements, mcpFeatures for playground\n├── CSP_GUIDE.md          # Content Security Policy for external resources\n├── response.json         # Optional: mock payload for playground preview\n└── dist/\n    └── mcp-app.html      # Built single-file bundle (npm run build)\n```\n\n### Key customization points in `src/mcp-app.ts`\n\n| Symbol | Purpose |\n|--------|---------|\n| `APP_NAME` | App identifier |\n| `APP_VERSION` | Semantic version string |\n| `renderData(data)` | **Main function** — renders tool result into DOM |\n| `unwrapData(data)` | Strips nested wrappers from MCP payloads |\n| `escapeHtml(str)` | XSS-safe HTML insertion |\n| `showError(msg)`, `showEmpty(msg)` | Error and empty-state UI |\n\nThe template uses the SDK `App` and registers handlers before `app.connect()`: `app.ontoolresult`, `app.onhostcontextchanged`, `app.ontoolcancelled`, `app.onteardown`, etc. See `examples/base-template/README.md` for the full list.\n\n### MCP protocol (under the SDK)\n\n| Message | SDK / behavior |\n|---------|----------------|\n| `ui/notifications/tool-result` | `app.ontoolresult` → `renderData()` |\n| `ui/notifications/host-context-changed` | `app.onhostcontextchanged` → theme, fonts, display mode |\n| `ui/notifications/tool-cancelled` | `app.ontoolcancelled` → error UI |\n| `ui/resource-teardown` | `app.onteardown` → cleanup, `result: {}` |\n\n---\n\n## CLI Reference\n\n```bash\nnpx @apigene/mcp-app-playground                 # Start playground + MCP server\nnpx @apigene/mcp-app-playground start           # Same as above\nnpx @apigene/mcp-app-playground lab             # Playground only\nnpx @apigene/mcp-app-playground mcp http        # MCP HTTP server only\nnpx @apigene/mcp-app-playground mcp stdio       # MCP stdio transport\nnpx @apigene/mcp-app-playground list            # List all examples\nnpx @apigene/mcp-app-playground build           # Build all examples\n```\n\nFrom the repo root:\n\n```bash\nnpm run dev              # Start playground + MCP server\nnpm run lab              # Playground only\nnpm run mcp:http         # MCP HTTP server only\nnpm run mcp:stdio        # MCP stdio transport\nnpm run build:examples   # Build all examples\nnpm run list             # List all examples\n```\n\n---\n\n## Development\n\n### Prerequisites\n\n- Node.js ≥ 18 (Node 22 recommended — see `.nvmrc`)\n- npm\n\n### Setup\n\n```bash\ngit clone https://github.com/apigene/mcp-apps.git\ncd mcp-apps\nnpm install\nnpm run dev\n```\n\n### Creating a Template (step by step)\n\n1. **Copy the base template**\n\n   ```bash\n   cp -r examples/base-template examples/my-service-my-tool\n   cd examples/my-service-my-tool\n   ```\n\n2. **Install and build**\n\n   ```bash\n   npm install\n   npm run build\n   ```\n\n3. **Set app metadata** in `src/mcp-app.ts`:\n\n   ```typescript\n   const APP_NAME = \"my-service-my-tool\";\n   const APP_VERSION = \"1.0.0\";\n   ```\n\n4. **Implement `renderData()`** based on your tool's response shape:\n\n   ```typescript\n   function renderData(data: any): void {\n     const items = unwrapData(data);\n     const app = document.getElementById(\"app\")!;\n     app.innerHTML = items.map((item: any) => `\n       <div class=\"item\">\n         <h3>${escapeHtml(item.title)}</h3>\n         <p>${escapeHtml(item.description)}</p>\n       </div>\n     `).join(\"\");\n   }\n   ```\n\n5. **Add `response.json`** — a real API response for local preview:\n\n   ```json\n   { \"results\": [{ \"title\": \"Example\", \"description\": \"Test item\" }] }\n   ```\n\n6. **Preview** in the playground:\n\n   ```bash\n   cd ../..\n   npm run lab\n   # Open http://localhost:4311 and select your template\n   ```\n\n### Conventions\n\n- Never modify `src/global.css` — it's the shared base\n- Always support dark mode via `body.dark` CSS class\n- Always escape user data with `escapeHtml()`\n- Register SDK event handlers before calling `app.connect()`\n- Clean up resources in `app.onteardown`\n- System fonts only — no external font imports (or configure CSP per `CSP_GUIDE.md`)\n- Current protocol version: `2026-01-26`\n\n---\n\n## Using with Cursor / AI Agents\n\nThe `docs/` folder contains prompts optimized for AI-assisted development:\n\n- [`docs/CURSOR_PROMPT_MCP_APP_SIMPLE.md`](docs/CURSOR_PROMPT_MCP_APP_SIMPLE.md) — create a template from a response.json\n- [`docs/CURSOR_PROMPT_MCP_APP_FROM_OPENAPI.md`](docs/CURSOR_PROMPT_MCP_APP_FROM_OPENAPI.md) — generate a template from an OpenAPI spec\n\nEach example also contains `AGENTS.md` with coding-agent-specific guidance.\n\n---\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nWays to contribute:\n- Add a new example template for an API/service\n- Improve the base templates or playground tooling\n- Fix bugs or improve documentation\n- Share your custom templates via a PR\n\n---\n\n## License\n\n[MIT](LICENSE) © [Apigene](https://apigene.ai)\n","readmeFilename":"README.md","repository":{"type":"git","url":"git+https://github.com/apigene/mcp-apps.git"},"bugs":{"url":"https://github.com/apigene/mcp-apps/issues"}}