MCP App Studio Starter

MCP应用程序工作室入门

用于为AI助手构建交互式应用程序的入门模板 MCP应用程序工作室.

注： 运行时会自动下载此模板 npx mcp-app-studio。您不需要直接克隆此仓库。

支持的平台

一次构建，随处部署：

• ChatGPT --作为MCP Apps主机（标准 ui/* 桥梁）
• 克劳德桌面版 --作为MCP Apps主机
• 任何MCP应用程序主机 --与任何支持MCP的AI助手兼容

快速开始

# npm (default)
npm install
npm run dev

打开http://localhost:3002--你在工作台上。

此项目也适用于pnpm/yarn/bun（使用等效的install+run命令）。

如果您切换包管理器（例如。 pnpm → npm)，删除 node_modules/ 首先是为了避免混淆安装程序。

MCP服务器（当 server/ 存在）运行于 http://localhost:3001/mcp 默认情况下。如果3001已在使用中，它将选择下一个可用端口并将其写入 server/.mcp-port.

工作台在iframe中模拟MCP Apps主机。它还安装了 window.openai 垫片，这样你就可以锻炼了 仅支持ChatGPT的扩展 在...期间 开发（可选，非标准）。

代理工作流

使用 .agent/skills/mcp-app-development/SKILL.md 作为此仓库的默认编码代理工作流。它定义了80/20能力切片循环：

• 在一个块中构建UI和真正的MCP工具
• 使用TDD(red -> green)用于奇偶校验
• 切勿将仅模仿的行为视为已完成

命令

项目结构

app/                        Next.js pages
components/
├── examples/               Example widgets (POI Map)
├── workbench/              Workbench UI components
└── ui/                     Shared UI components
lib/
├── sdk/                    SDK exports for production
├── workbench/              React hooks + dev environment
└── export/                 Production bundler
server/                     MCP server (if included)

构建您的小部件

1.创建组件

// components/my-widget/index.tsx
import {
  useToolInput,
  useCallTool,
  useTheme,
  useCapabilities,
  useUpdateModelContext,
  useWidgetState,
} from "@/lib/sdk";

export function MyWidget() {
  const input = useToolInput();
  const callTool = useCallTool();
  const theme = useTheme();
  const capabilities = useCapabilities();
  const updateModelContext = useUpdateModelContext();
  const [widgetState, setWidgetState] = useWidgetState();

  const handleSearch = async () => {
    const result = await callTool("search", { query: input.query });
    console.log(result.structuredContent);
  };

  return (
    

      
Query: {input.query}

      Search

      {/* Platform-specific features */}
      {capabilities.modelContext && (
        
            updateModelContext({ structuredContent: { query: input.query } })
          }
        >
          Update model context (host-dependent)
        
      )}
      {capabilities.widgetState && (
        
            setWidgetState({
              ...(widgetState ?? {}),
              savedAt: Date.now(),
            })
          }
        >
          Save widget state (ChatGPT extensions)
        
      )}
    

  );
}

2.在工作台上注册

将您的组件添加到 lib/workbench/component-registry.tsx.

3.添加模拟数据

在中配置模拟工具响应 lib/workbench/mock-config/.

React Hooks参考

完整文档： lib/workbench/README.md

通用挂钩（推荐）

这些挂钩在MCP主机（包括ChatGPT）上的工作方式相同：

平台检测（需要时）

主机依赖/扩展（高级）

这些挂钩仅在特定平台上工作。先检查可用性：

useWidgetState() 不是标准的MCP Apps持久性原语。 对于便携式MCP应用程序，使用应用程序管理的持久性，如localStorage或 服务器支持的工具。

工具结果元数据(_meta)可通过以下方式获得 readToolResponseMetadata() 当主机暴露时 window.openai.toolResponseMetadata.

平台特定功能

MCP App Studio是MCP第一：更喜欢MCP Apps桥接器(ui/*)和特征检测 可选的ChatGPT扩展(window.openai)必要时。

使用 useCapabilities() 或 useFeature() 以有条件地启用功能。

模态制导

• 为了跨主机兼容性，更喜欢本地/小部件内模式。
• 使用 window.openai.requestModal() 仅当您特别需要ChatGPT托管的模式模板时。
• 始终进行功能检测并提供回退：

if (typeof window !== "undefined" && window.openai?.requestModal) {
  await window.openai.requestModal({ title: "Details", params: { id } });
} else {
  // Fallback: local modal state or route navigation
}

结账指南（ChatGPT测试版扩展）

• window.openai.requestCheckout(...) 目前是ChatGPT私有测试版扩展。
• 将结账视为可选：功能检测并提供回退（例如，外部结账）。
• 如果你在ChatGPT菜单中暴露了一个伴随的深度链接，请使用 window.openai.setOpenInAppUrl({ href }).

import { requestCheckout, setOpenInAppUrl } from "@/lib/sdk";

setOpenInAppUrl("https://your-app.com/orders/123");

const outcome = await requestCheckout(
  { id: "checkout_123", payment_mode: "test" },
  () => window.open("https://your-app.com/checkout/123", "_blank"),
);

if (outcome.mode === "fallback") {
  // Non-ChatGPT host or checkout beta unavailable.
}

出口用于生产

npm run export

默认值为 --entry 和 --export-name 从以下内容读取 mcp-app-studio.config.json （在构建项目时由CLI编写）。您可以通过标志覆盖它们。

生成：

export/
├── widget/
│   └── index.html      Self-contained widget
├── manifest.json       App manifest
└── README.md           Deployment instructions

导出的小部件使用 mcp-app-studio SDK自动检测主机平台并使用适当的网桥。

MCP元数据默认值（导出）

• ui.* 元数据在导出的服务器代码中是规范的。
• 导出的MCP元数据不支持来自旧ChatGPT应用程序集成的旧元数据密钥。
• 可见性默认为主机默认值(["model","app"])当没有设置可见性键时。
• 小部件资源以MCP Apps MIME类型发出 text/html;profile=mcp-app.

小部件资源CSP必须使用MCP标准密钥：

ui: {
  csp: {
    connectDomains: ["https://api.example.com"],
    resourceDomains: ["https://cdn.example.com"],
    frameDomains: ["https://www.youtube.com"],
    baseUriDomains: ["https://cdn.example.com"],
  },
}

部署

小部件

部署 export/widget/ 对于任何静态主机：

# Vercel
cd export/widget && vercel deploy

# Netlify
netlify deploy --dir=export/widget

# Or any static host (S3, Cloudflare Pages, etc.)

MCP服务器

如果你有 server/ 目录：

cd server
npm run build
# Deploy to Vercel, Railway, Fly.io, etc.

在平台注册

对于ChatGPT：

1. 更新 manifest.json 使用您部署的小部件URL
2. 首选 ChatGPT应用仪表板
3. 创建新应用程序并连接您的MCP服务器
4. 在新的ChatGPT对话中进行测试

对于Claude Desktop：

1. 在Claude Desktop设置中配置MCP服务器
2. 当调用带有UI的工具时，小部件将呈现

配置

SDK指南（可选）

工作台包括一个AI驱动的SDK指南。要启用：

cp .env.example .env.local
# then set:
# OPENAI_API_KEY="your-key"

MCP服务器CORS

对于生产，将CORS限制在您的小部件域中：

cp server/.env.example server/.env
# then set:
# CORS_ORIGIN=https://your-widget-domain.com

深色模式

导出的小部件继承主机主题和令牌变量。遵循中的框架无关契约 lib/workbench/THEMING_CONTRACT.md.

至少，支持 data-theme / .dark 以及语义标记：

.my-element {
  background: var(--background);
  color: var(--foreground);
  border-color: var(--border);
}

了解更多

• MCP应用程序工作室 --CLI和SDK文档
• MCP规范 --模型上下文协议
• ChatGPT MCP应用程序 --ChatGPT作为MCP主机