mcp

@json-render/mcp

MCP Apps 整合套件，可將 json-render UI 作為互動式 MCP App，提供給 Claude、ChatGPT、Cursor、VS Code 以及其他支援 MCP 的用戶端使用。

快速開始

伺服器端 (Node.js)

import { createMcpApp } from "@json-render/mcp";
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import fs from "node:fs";

const catalog = defineCatalog(schema, {
  components: { ...shadcnComponentDefinitions },
  actions: {},
});

const server = createMcpApp({
  name: "My App",
  version: "1.0.0",
  catalog,
  html: fs.readFileSync("dist/index.html", "utf-8"),
});

await server.connect(new StdioServerTransport());

用戶端 (React，位於 iframe 內)

import { useJsonRenderApp } from "@json-render/mcp/app";
import { JSONUIProvider, Renderer } from "@json-render/react";

function McpAppView({ registry }) {
  const { spec, loading, error } = useJsonRenderApp();
  if (error) return <div>Error: {error.message}</div>;
  if (!spec) return <div>Waiting...</div>;
  return (
    <JSONUIProvider registry={registry} initialState={spec.state ?? {}}>
      <Renderer spec={spec} registry={registry} loading={loading} />
    </JSONUIProvider>
  );
}

架構說明

1. createMcpApp() 會建立一個 McpServer，並註冊 render-ui 工具以及 ui:// HTML 資源
2. 工具描述中包含了 catalog prompt，讓 LLM 知道如何生成有效的 spec
3. HTML 資源是一個透過 Vite 打包的單一檔案 React 應用程式，內建 json-render 渲染器
4. 在 iframe 內部，useJsonRenderApp() 會透過 postMessage 與 host 建立連線並渲染 spec

伺服器端 API

• createMcpApp(options) - 主要入口，用於建立完整的 MCP 伺服器
• registerJsonRenderTool(server, options) - 在現有的伺服器上註冊 json-render 工具
• registerJsonRenderResource(server, options) - 註冊 UI 資源

用戶端 API (@json-render/mcp/app)

• useJsonRenderApp(options?) - React Hook，回傳 { spec, loading, connected, error, callServerTool }
• buildAppHtml(options) - 從打包好的 JS/CSS 生成 HTML

建置 iframe HTML

使用 Vite + vite-plugin-singlefile 將 React 應用程式打包成單一獨立的 HTML 檔案：

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { viteSingleFile } from "vite-plugin-singlefile";

export default defineConfig({
  plugins: [react(), viteSingleFile()],
  build: { outDir: "dist" },
});

用戶端設定

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "my-app": {
      "command": "npx",
      "args": ["tsx", "server.ts", "--stdio"]
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "my-app": {
      "command": "npx",
      "args": ["tsx", "/path/to/server.ts", "--stdio"]
    }
  }
}

相依套件

# 伺服器端
npm install @json-render/mcp @json-render/core @modelcontextprotocol/sdk

# 用戶端 (iframe)
npm install @json-render/react @json-render/shadcn react react-dom

# 建置工具
npm install -D vite @vitejs/plugin-react vite-plugin-singlefile