企业官网建设流程全解析

MCP Apps 项目配置终极指南：tsconfig、vite.config 与 package.json 全解析

【免费下载链接】ext-appsOfficial repo for spec & SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP servers项目地址: https://gitcode.com/GitHub_Trending/ex/ext-apps

对于想开发 AI 聊天界面插件的新手来说，MCP Apps 是官方推出的 MCP Apps 协议规范与 SDK 仓库，它让 MCP 服务器能在 Claude Desktop 等对话客户端中直接渲染交互式 UI。而要让项目跑起来，最关键的三个配置文件是package.json、tsconfig.json和vite.config.ts。本文带你用 5 分钟看懂这套配置的每一项设计意图，快速搭建并运行你的第一个 MCP App。

package.json：SDK 的多入口与脚本体系

根目录的 package.json 是整个仓库的“总开关”，几个新手最容易忽略的细节：

📌多入口导出：exports字段把 SDK 拆成了 5 个入口——.（核心 App 类）、./react、./server、./app-bridge、./schema.json。写服务器端代码时引入@modelcontextprotocol/ext-apps/server即可，这正是 examples/quickstart/server.ts 的用法。

📌核心脚本（新手只需记住这 3 个）：

• npm run examples:dev—— 开发模式，同时启动所有示例服务器（start是它的别名）
• npm run build—— 生成 schema、同步示例代码片段，再用 Bun 打包 SDK 本体
• npm run test:e2e—— 用 Playwright 对全部示例做端到端截图回归测试

依赖版本约定

根package.json的peerDependencies声明了 SDK 与宿主项目的协作关系：@modelcontextprotocol/sdk ^1.29.0是必选 peer 依赖；react为可选 peer 依赖（peerDependenciesMeta中optional: true），意味着非 React 用户（Vue、Svelte、原生 JS 示例）不会被迫安装 React。

tsconfig.json：双配置分离前后端

每个示例项目都有两份tsconfig，这是 MCP Apps 项目最有辨识度的配置模式：

前端配置：tsconfig.json

以 examples/quickstart/tsconfig.json 为例：

• noEmit: true—— 前端代码只检查不输出，真正打包交给 Vite
• moduleResolution: "bundler"—— 适配 Vite 的包管理解析方式，允许allowImportingTsExtensions
• strict+noUnusedLocals+noUnusedParameters—— 严格模式加防呆检查，保证 UI 代码质量

根目录的 tsconfig.json 则面向 SDK 本体：emitDeclarationOnly: true让 tsc 只产出类型声明文件到dist/，JS 产物交给 Bun 处理。

服务器配置：tsconfig.server.json

examples/quickstart/tsconfig.server.json 服务于server.ts和main.ts：

• module: "NodeNext"+moduleResolution: "NodeNext"—— 服务器运行在 Node 环境，必须用 Node 的模块解析规则
• emitDeclarationOnly: true+outDir: "./dist"—— 为服务器代码生成类型声明
• target: "ES2022"—— 与前端ESNext区分，锁定 Node 实际支持的语法级别

💡 一句话总结：前端用bundler解析交给 Vite，后端用NodeNext解析交给 Node——两份配置各司其职，互不干扰。

vite.config.ts：为什么 UI 要打成单个 HTML

MCP Apps 的 UI 是通过 MCP 资源（resource）以文本形式发给宿主、再嵌入 iframe 渲染的，所以它必须是一个自包含的单文件 HTML。这正是 examples/quickstart/vite.config.ts 的设计核心：

plugins: [viteSingleFile()], rollupOptions: { input: INPUT }, // INPUT 由环境变量指定，如 mcp-app.html outDir: "dist",

• vite-plugin-singlefile：把 JS、CSS 全部内联进一个 HTML，产出dist/mcp-app.html，服务器直接读文件返回即可（见 server.ts 中fs.readFile的用法）
• INPUT环境变量：入口不在配置里写死，而是通过cross-env INPUT=mcp-app.html注入，同一个 vite 配置可复用于多个入口页（lazy-auth-server 就有两个 HTML 入口）
• 开发体验：NODE_ENV=development时开启 inline sourcemap 便于调试，发布时自动压缩 CSS 和 JS

React 用户在此基础上只需多加一个react()插件，对比 examples/basic-server-react/vite.config.ts 即可一目了然。

一键配置：build 与 start 脚本的分工

examples/quickstart/package.json 的 scripts 是整套配置的“总装配线”：

build: tsc --noEmit \ && tsc -p tsconfig.server.json \ && cross-env INPUT=mcp-app.html vite build start: concurrently --raw \ "cross-env NODE_ENV=development INPUT=mcp-app.html vite build --watch" \ "tsx watch main.ts"

执行顺序非常讲究：

1. tsc --noEmit：用前端 tsconfig 做全量类型检查（不产出文件）
2. tsc -p tsconfig.server.json：为服务器代码生成声明文件
3. vite build：把 UI 打包成单文件 HTML

start则用concurrently同时跑两个进程：Vite 的--watch增量构建 +tsx watch热重启服务器，改完代码即时生效。

配置检查清单：跑不起来先查这 4 处

下一步：从 Quickstart 到你的 MCP App

配置理解到位后，建议按这个路径学习（均为仓库内置示例，可直接npm start运行）：

1. 快速上手：docs/quickstart.md 手把手教你搭建"获取服务器时间"应用，完整代码在 examples/quickstart/
2. 原生 JS 进阶：examples/basic-server-vanillajs/ 演示主题、生命周期等宿主通信能力
3. 框架版本：React / Vue / Svelte / Preact / Solid 五种实现分别在 examples/basic-server-react/ 等目录
4. 协议规范：specification/draft/apps.mdx 是协议草案原文，specification/2026-01-26/apps.mdx 为已发布版本

掌握package.json的多入口与脚本、双tsconfig的前后端分离、vite.config.ts的单文件打包这三块，你就能独立修改并扩展 examples/ 下任何一个 MCP Apps 示例，开始构建自己的交互式 AI 界面了。

【免费下载链接】ext-appsOfficial repo for spec & SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP servers项目地址: https://gitcode.com/GitHub_Trending/ex/ext-apps