К основному содержанию
скилл CX Codex

mcp-visual-output — скилл для Claude Code: интерактивные дашборды

Скилл mcp-visual-output для Claude Code преобразует JSON-результаты инструментов MCP в интерактивные дашборды. Он запускается, когда требуется визуальное представление данных вместо обычного текста.

MIT 105 установок ★ 305 обновлён 2026-10-24

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add yonatangross/orchestkit --skill mcp-visual-output -a claude-code
Открыть на GitHub

Что делает mcp-visual-output

Скилл mcp-visual-output улучшает стандартные ответы инструментов MCP, превращая их в интерактивные дашборды прямо внутри диалогов с ИИ. Он работает на базе @json-render/mcp, который связывает систему спецификаций json-render с моделью инструментов и ресурсов MCP.

ИИ генерирует типизированную JSON-спецификацию, а изолированный iframe отображает её как интерактивный пользовательский интерфейс. Этот скилл предназначен для слоя визуального вывода уже работающего MCP-сервера, а не для его создания. Для работы необходима совместимость с Claude Code версии 2.1.277 или выше.

Какие задачи решает

  • Визуализировать JSON-результаты MCP-инструментов
  • Создать интерактивные дашборды из структурированных данных
  • Отобразить метрики и статусы в виде таблиц или бейджей
  • Представить данные в интерактивном UI внутри чата ИИ

Примеры запросов агенту

  • Покажи результаты выполнения в виде дашборда.
  • Сформируй отчёт по этим данным с помощью интерактивной панели.
  • Отобрази статус проекта как набор виджетов.

Как установить mcp-visual-output

1Через Skills CLI (Vercel)

npx skills add yonatangross/orchestkit --skill mcp-visual-output -a claude-code

2Вручную: положить файлы

~/.claude/skills/mcp-visual-output/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/mcp-visual-output/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о mcp-visual-output

Как установить mcp-visual-output в Claude Code?

Чтобы установить скилл в Claude Code, используйте команду: npx skills add yonatangross/orchestkit --skill mcp-visual-output -a claude-code.

Что делает скилл mcp-visual-output?

Скилл mcp-visual-output преобразует JSON-ответы от инструментов MCP в интерактивные дашборды, которые отображаются в изолированном iframe внутри интерфейса ИИ. Он позволяет визуализировать структурированные данные, используя готовые компоненты.

Что нужно для работы mcp-visual-output?

Для работы скилла mcp-visual-output требуется совместимость с Claude Code версии 2.1.277+. Он предназначен для визуального вывода после того, как MCP-сервер уже запущен.

Исходный текст

SKILL.md · MIT
---
name: mcp-visual-output
compatibility: "Claude Code 2.1.277+"
description: "Renders MCP tool JSON results as dashboards via @json-render/mcp (stat grids, tables, badges). Use when a result reads better visually. Not for building the server."
user-invocable: false
disable-model-invocation: false
context: inherit
metadata:
  category: mcp
  upstream-package: "@json-render/mcp"
  upstream-version-tested: "0.21.3"
  version: "1.1.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "mcp, json-render, visual-output, dashboard, iframe, sandbox, interactive-ui, genui"
---

Upstream version reference: `@json-render/mcp` 0.21.3 (2026-10-24).

# MCP Visual Output

Upgrade plain MCP tool responses to interactive dashboards rendered inside AI conversations. Built on `@json-render/mcp`, which bridges the json-render spec system with MCP's tool/resource model -- the AI generates a typed JSON spec, and a sandboxed iframe renders it as an interactive UI.

> **Building an MCP server from scratch?** Use `ork-extras:mcp-patterns` for server setup, transport, and security. This skill focuses on the **visual output layer** after your server is running.
>
> **Need the full component catalog?** See `ork:json-render-catalog` for all available components, props, and composition patterns.

## Decision Tree -- Which File to Read

```
What are you doing?
|
+-- Setting up visual output for the first time
|   +-- New MCP server -----------> rules/mcp-app-setup.md
|   +-- Existing MCP server ------> rules/mcp-app-setup.md (registerJsonRenderTool section)
|
+-- Configuring security / sandbox
|   +-- CSP declarations ----------> rules/sandbox-csp.md
|   +-- Iframe permissions --------> rules/sandbox-csp.md
|
+-- Rendering strategy
|   +-- Progressive streaming -----> rules/streaming-output.md
|   +-- Dashboard layouts ----------> rules/dashboard-patterns.md
|
+-- API reference
|   +-- Server-side API -----------> references/mcp-integration.md
|   +-- Component recipes ----------> references/component-recipes.md
```

## Quick Reference

| Category | Rule | Impact | Key Pattern |
|----------|------|--------|-------------|
| **Setup** | `mcp-app-setup.md` | HIGH | createMcpApp() and registerJsonRenderTool() |
| **Security** | `sandbox-csp.md` | HIGH | CSP declarations, iframe sandboxing |
| **Rendering** | `streaming-output.md` | MEDIUM | Progressive rendering via JSON Patch |
| **Patterns** | `dashboard-patterns.md` | MEDIUM | Stat grids, status badges, data tables |

**Total: 4 rules across 3 categories**

## How It Works

1. **Define a catalog** -- typed component schemas using `defineCatalog()` + Zod
2. **Register with MCP** -- `createMcpApp()` for new servers or `registerJsonRenderTool()` for existing ones
3. **AI generates specs** -- the model produces a JSON spec conforming to the catalog
4. **Iframe renders it** -- a bundled React app inside a sandboxed iframe renders the spec with `useJsonRenderApp()` + `<Renderer />`

The AI never writes HTML or CSS. It produces a structured JSON spec that references catalog components by type. The iframe app renders those components using a pre-built registry.

## Quick Start -- New MCP Server

```typescript
import { createMcpApp } from '@json-render/mcp'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { buildAppHtml } from '@json-render/mcp/app'
import { catalog } from './catalog'

// Generate the iframe HTML from the bundled JS/CSS (docs-prescribed generator).
const bundledHtml = buildAppHtml({ entry: './app.tsx' })

// 1. Create the MCP app (async; returns an McpServer, no .start()/.close()).
//    name + version are required; tool config nests under `tool`
//    (default tool name is 'render-ui'). There is no top-level `csp`.
const server = await createMcpApp({
  name: 'my-app',
  version: '1.0.0',
  catalog,           // component schemas the AI can use
  html: bundledHtml, // pre-built iframe app (single HTML file)
  tool: {
    name: 'render-dashboard',
    description: 'Render an interactive dashboard from a json-render spec',
  },
})

// 2. Connect a transport -- stdio, Streamable HTTP, or any MCP transport
await server.connect(new StdioServerTransport())
```

## Quick Start -- Enhance Existing Server with Visual Output

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { registerJsonRenderTool, registerJsonRenderResource } from '@json-render/mcp'
import { buildAppHtml } from '@json-render/mcp/app'
import { catalog } from './catalog'

const server = new McpServer({ name: 'my-server', version: '1.0.0' })

// Generate the iframe HTML from the bundled JS/CSS (docs-prescribed generator).
const bundledHtml = buildAppHtml({ entry: './app.tsx' })

const resourceUri = 'ui://my-server/dashboard'

// Register the render tool (lets the model return specs).
// name, title, description, and resourceUri are all required.
registerJsonRenderTool(server, {
  catalog,
  name: 'render-dashboard',
  title: 'Render Dashboard',
  description: 'Render an interactive dashboard from a json-render spec',
  resourceUri,
})

// Serve the bundled HTML iframe app as a resource (new in 0.15).
// resourceUri must match the tool's resourceUri.
registerJsonRenderResource(server, { resourceUri, html: bundledHtml })
```

`registerJsonRenderResource()` was added in 0.15 to separate **tool registration** from **UI resource serving** — useful when the host caches the bundled HTML (clients: Claude, ChatGPT, Cursor, VS Code Copilot, Goose, Postman). Transports: stdio **and** Streamable HTTP (Express) both supported. This skill is verified against `@json-render/mcp` **0.20.0**, which shipped zero code change: every published file is byte-identical to 0.19.0 apart from the version and its pinned `@json-render/core` dependency. New capability in that release therefore belongs to core and react, not to this package. What reaches an MCP-rendered iframe indirectly is named slots and nested repeats, plus a fix so named `onSuccess`/`onError` chained actions actually receive their configured `params`.

## Smallest Proof: One Tool, UI Resource Plus Text Fallback

`scripts/glyph-card-server.mjs` is a dependency-free MCP server (stdio, or `--http <port>` for Streamable HTTP) with one tool, `render_glyph_card`. The tool lists `_meta.ui.resourceUri` (plus the legacy `ui/resourceUri` and the ChatGPT alias `openai/outputTemplate`), serves a `ui://` resource as `text/html;profile=mcp-app`, and returns a glyph text card in `content` with the same rows in `structuredContent`. Hosts without UI use the text; MCP Apps hosts draw the card. One caveat: Claude Code passes `structuredContent` JSON to the model when it is present, so the text card is not what the model sees there. The HTTP mode refuses any non-local Host or Origin with 403 unless you name one host with `--allow-host <host>`, so a tunnel serves only that name. Unit tests: `tests/unit/test-mcp-glyph-card.mjs`.

## Client-Side Iframe App

The iframe app receives specs from the MCP host and renders them:

```typescript
import { useJsonRenderApp } from '@json-render/mcp/app'
import { Renderer } from '@json-render/react'
import { registry } from './registry'

function App() {
  const { spec, loading } = useJsonRenderApp()
  if (loading) return <Skeleton />
  return <Renderer spec={spec} registry={registry} />
}
```

## Catalog Definition

Catalogs define what components the AI can use. Each component has typed props via Zod:

```typescript
import { defineCatalog } from '@json-render/core'
import { schema } from '@json-render/react/schema'
import { z } from 'zod'

export const dashboardCatalog = defineCatalog(schema, {
  components: {
    StatGrid: {
      props: z.object({
        items: z.array(z.object({
          label: z.string(),
          value: z.string(),
          trend: z.enum(['up', 'down', 'flat']).optional(),
          color: z.enum(['green', 'red', 'yellow', 'blue']).optional(),
        })),
      }),
      children: false,
    },
    StatusBadge: {
      props: z.object({
        label: z.string(),
        status: z.enum(['success', 'warning', 'error', 'info', 'pending']),
      }),
      children: false,
    },
    DataTable: {
      props: z.object({
        columns: z.array(z.object({ key: z.string(), label: z.string() })),
        rows: z.array(z.record(z.string())),
      }),
      children: false,
    },
  },
})
```

## Example: Eval Results Dashboard

The AI generates a spec like this -- flat element map, no nesting beyond 2 levels:

```json
{
  "root": "dashboard",
  "elements": {
    "dashboard": {
      "type": "Card",
      "props": { "title": "Eval Results -- v7.21.1" },
      "children": ["stats", "table"]
    },
    "stats": {
      "type": "StatGrid",
      "props": {
        "items": [
          { "label": "Skills Evaluated", "value": "94", "trend": "flat" },
          { "label": "Pass Rate", "value": "97.8%", "trend": "up", "color": "green" },
          { "label": "Avg Score", "value": "8.2/10", "trend": "up" }
        ]
      }
    },
    "table": {
      "type": "DataTable",
      "props": {
        "columns": [
          { "key": "skill", "label": "Skill" },
          { "key": "score", "label": "Score" },
          { "key": "status", "label": "Status" }
        ],
        "rows": [
          { "skill": "implement", "score": "9.1", "status": "pass" },
          { "skill": "verify", "score": "8.7", "status": "pass" }
        ]
      }
    }
  }
}
```

## Key Decisions

| Decision | Recommendation |
|----------|----------------|
| New vs existing server | `createMcpApp()` for new; `registerJsonRenderTool()` to add to existing |
| CSP policy | Minimal -- only declare domains you actually need |
| Streaming | Always enable progressive rendering; never wait for full spec |
| Dashboard depth | Keep element trees flat (2-3 levels max) for streamability |
| Component count | 3-5 component types per catalog covers most dashboards |
| Visual vs text | Use visual output for multi-metric views; plain text for single values |

> **CC 2.1.113** fixed MCP concurrent-call timeout handling — hanging tool calls now error cleanly instead of blocking the queue. Parallel tool invocation from dashboards is safer; no workarounds needed.

## When to Use Visual Output vs Plain Text

| Scenario | Use Visual Output | Use Plain Text |
|----------|------------------|----------------|
| Multiple metrics at a glance | Yes -- StatGrid | No |
| Tabular data (5+ rows) | Yes -- DataTable | No |
| Status of multiple systems | Yes -- StatusBadge grid | No |
| Single value answer | No | Yes |
| Error message | No | Yes |
| File content / code | No | Yes |

## Common Mistakes

1. Returning raw HTML strings from MCP tools instead of json-render specs (breaks type safety, no streaming)
2. Deeply nested component trees that cannot stream progressively (keep flat)
3. Using `script-src 'unsafe-inline'` in CSP declarations (security risk, unnecessary)
4. Waiting for the full spec before rendering (defeats progressive rendering)
5. Defining 20+ component types in a single catalog (increases prompt token cost)
6. Missing `html` bundle in `createMcpApp()` config (iframe has nothing to render)

## Related Skills

- `ork-extras:mcp-patterns` -- MCP server building, transport, security
- `ork:json-render-catalog` -- Full component catalog and composition patterns
- `ork:multi-surface-render` -- Rendering across Claude, Cursor, ChatGPT, web
- `ork-extras:ai-ui-generation` -- GenUI patterns for AI-generated interfaces

© OrchestKit · MIT · yonatangross/orchestkit

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
mcp vercel-labs Скилл помогает собирать MCP-серверы с интерактивными json-render UI для Claude, ChatGPT, Cursor и VS Code. CX Codex +1 5 900установок vue vercel-labs Учит их строить Vue 3-интерфейсы по JSON-спецификации через @json-render/vue. CX Codex +1 1 400установок critique-visual-hierarchy Owl-Listener Скилл critique-visual-hierarchy для Claude Code оценивает визуальную иерархию готового экрана. Находит элементы, которые перетягивают внимание или мешают дойти до главного действия. CX Codex +1 2 600установок visual-regression-tester patricio0312rev Скилл visual-regression-tester настраивает визуальное регрессионное тестирование: снимает скриншоты, сравнивает их с базовыми и ловит случайные изменения интерфейса. CX Codex +1 351установок roku typeui.sh Скилл дизайн-системы Roku для Claude Code, Cursor, Codex и других агентов. Задаёт фиолетовую эстетику, top-bar навигацию и карточные лейауты для дашбордов приложений. CX Codex +1 2 400установок ui-craft-dense-dashboard educlopez Скилл ui-craft-dense-dashboard для Claude Code, Codex, Cursor и других агентов, который фиксирует стиль плотного оперативного интерфейса: DENSITY=9, сетка 4/8px, IBM Plex, спарклайны. CX Codex +1 1 400установок

Из того же набора86

Весь набор →
chain-patterns Скилл chain-patterns собирает паттерны для многофазных пайплайнов: обнаружение MCP, handoff-файлы, возобновление после сбоя и изолированные worktree-агенты. CX Codex +1 118установок design-to-code Скилл design-to-code для Claude Code преобразует скриншоты, текстовые описания и URL страниц в компоненты React. Запускается при вёрстке интерфейсов по макетам с повторным использованием готовых блоков проекта. CX Codex +1 116установок testing-unit Скилл testing-unit задаёт шаблоны для модульных тестов, моков HTTP и фикстур в Vitest, Jest и pytest. Включается при написании тестов или настройке тестовых данных. CX Codex +1 116установок design-context-extract Скилл design-context-extract извлекает цвета, типографику, отступы, компоненты и анимации из скриншотов, URL или записи экрана. Результат отдаёт в токенах или конфигурации Tailwind. CX Codex +1 112установок component-search Скилл component-search для Claude Code ищет React-компоненты в каталоге 21st.dev и ранжирует результаты. Запускается по запросу найти компонент интерфейса или его замену. CX Codex +1 106установок cover Скилл cover для Claude Code и Codex создаёт недостающие тесты разных уровней. Запускается при разработке новых модулей или когда в проекте не хватает тестового покрытия. CX Codex +1 100установок json-render-catalog Скилл json-render-catalog для Claude Code помогает описать каталог компонентов для интерфейсов, которые генерирует ИИ. Включается при настройке каталога и правил для его компонентов. CX Codex +1 100установок OrchestKit Docs MCP Сервер OrchestKit Docs MCP только для чтения документации OrchestKit. Позволяет искать материалы полнотекстовым поиском и загружать страницы в Markdown без токенов. CX Codex +1 ★ 305звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой