SuperAPI AI 工具集

mcp

编程与开发

查看项目

更新于 10-16 09:22

技能介绍

用途

@json-render/mcp 是 json-render 的 MCP Apps 集成,用于在 Claude、ChatGPT、Cursor、VS Code 以及其他支持 MCP 的客户端中,把 json-render 界面作为交互式 MCP Apps 提供。适用于构建能在上述客户端中渲染交互式 UI 的 MCP 服务器,或将 json-render 界面集成到 MCP 能力客户端中。

主要能力

  • 通过 createMcpApp() 创建完整的 MCP 服务器,注册 render-ui 工具和一个 ui:// HTML 资源。
  • 工具描述中会包含 catalog 提示,使 LLM 了解如何生成有效的 spec。
  • HTML 资源是由 Vite 打包的单文件 React 应用,内含 json-render 渲染器。
  • 在 iframe 内部,useJsonRenderApp() 通过 postMessage 连接宿主并渲染 spec。

使用方式

服务器端(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>
  );
}

服务器 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 文件:

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"]
    }
  }
}

依赖安装:

# Server
npm install @json-render/mcp @json-render/core @modelcontextprotocol/sdk

# Client (iframe)
npm install @json-render/react @json-render/shadcn react react-dom

# Build tools
npm install -D vite @vitejs/plugin-react vite-plugin-singlefile

架构说明

  • createMcpApp() 创建一个 McpServer,注册 render-ui 工具和 ui:// HTML 资源。
  • 工具描述包含 catalog 提示,供 LLM 生成有效 spec。
  • HTML 资源是 Vite 打包的单文件 React 应用,内置 json-render 渲染器。
  • iframe 内使用 useJsonRenderApp() 通过 postMessage 连接宿主并渲染 spec。

限制

资料未提供支持的平台最低版本、性能上限、收费或价格等信息,暂未提供。