MCP Apps SDK

<img width="718" height="542" alt="2025-11-04 下午10:41:53的屏幕截图" src="https://gips2.baidu.com/it/u=3051019687,1793968146&fm=3081&app=3081&f=PNG?w=1435&h=1083" />

开源SDK，用于构建与模型上下文协议（MCP）兼容的应用程序，该协议与OpenAI Apps SDK兼容。

此SDK对两种类型的开发者有用：

• 代理开发者：希望将基于MCP的应用UI集成到他们自己的代理中。
• MCP应用开发者：正在开发可以与ChatGPT和其他代理集成的基于MCP的应用。

演示视频

https://github.com/user-attachments/assets/7d13d4f8-2da7-40b1-a102-7745a1d5cc95

安装

通过一个命令快速开始：

npm install @xalia/mcp-apps-sdk

这将安装构建MCP驱动应用程序所需的一切！✨

包含内容

• MCP客户端 - 连接到并与MCP服务器通信
• 适配器 - 集成流行的人工智能框架（如OpenAI、Vercel AI SDK）
• 小部件组件 - 用于渲染MCP应用界面的React组件

替代方案：模块化安装

对于希望减小捆绑包大小的高级用户，仅安装所需的部分：

# 对于代理开发者 - 仅渲染MCP应用小部件
npm install @xalia/mcp-apps-widget

# 对于MCP应用开发者 - 仅客户端和适配器
npm install @xalia/mcp-client @xalia/mcp-apps-adapters

包

这个单体仓库包含四个包：

@xalia/mcp-apps-sdk ⭐

完整的SDK - 统一的包，包含一切。安装此包以获得最简单的设置。

@xalia/mcp-apps-widget

React组件和工具，用于在安全的iframe中通过PostMessage通信渲染MCP应用小部件。

@xalia/mcp-client

用于连接和与MCP服务器交互的TypeScript客户端，包括工具发现和执行。

@xalia/mcp-apps-adapters

适配器，用于将MCP工具与流行的AI框架（如Vercel AI SDK和OpenAI）集成。

快速开始

先决条件

• Node.js 18+
• pnpm 10+
• 正在运行的MCP服务器（默认：http://localhost:8002/mcp）

安装

# 克隆包含子模块的仓库
git clone --recurse-submodules https://github.com/general-intelligence-labs/mcp-apps-sdk.git
cd mcp-apps-sdk

# 或者如果你已经克隆但没有子模块
git submodule update --init --recursive

# 安装依赖项
pnpm install

# 构建所有包
pnpm build

运行示例

聊天机器人示例需要一个MCP服务器和一个小部件的静态文件服务器。请参阅examples/chatbot/README.md获取详细的设置说明。

快速开始：

# 终端1：启动静态文件服务器
cd examples/openai-apps-sdk-examples
pnpm install && pnpm build
pnpm run serve  # 在4444端口提供服务

# 终端2：启动MCP服务器
cd examples/openai-apps-sdk-examples/solar-system_server_python
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --port 8002

# 终端3：启动聊天机器人
cd examples/chatbot
pnpm dev

打开http://localhost:3000查看具有MCP工具集成的聊天机器人。

开发

项目结构

mcp-apps-sdk/
├── packages/
│   ├── mcp-apps-sdk/             # ⭐ 完整的SDK（伞形包）
│   ├── mcp-apps-widget/          # 小部件渲染组件
│   ├── mcp-client/               # MCP协议客户端
│   └── mcp-apps-adapters/        # AI框架适配器
├── examples/
│   ├── chatbot/                  # 示例Next.js聊天机器人应用
│   └── openai-apps-sdk-examples/ # OpenAI SDK示例（git子模块）
└── package.json                  # 根package.json

可用脚本

# 构建所有包
pnpm build

# 在开发模式下运行所有包
pnpm dev

# 运行测试
pnpm test

# 代码检查
pnpm lint

# 清理所有构建产物
pnpm clean

📚 使用

简单导入（推荐）

安装完整的SDK并从一个地方导入所有内容：

npm install @xalia/mcp-apps-sdk

import { 
  createMCPClient, 
  connectMCPClient,
  createVercelAITools,
  AssistantAppEmbed 
} from '@xalia/mcp-apps-sdk';

// 连接到MCP服务器
const client = await createMCPClient({ name: 'my-app', version: '1.0.0' });
await connectMCPClient(client, transport);

// 将MCP工具转换为可用于AI SDK的形式
const tools = await createVercelAITools(client);

模块化导入（优化捆绑包大小）

当你需要细粒度控制时，使用特定的入口点：

// 仅客户端
import { createMCPClient } from '@xalia/mcp-apps-sdk/client';

// 适配器
import { createOpenAIFunctions } from '@xalia/mcp-apps-sdk/adapters/openai';
import { createVercelAITools } from '@xalia/mcp-apps-sdk/adapters/vercel';

// 小部件组件
import { AssistantAppEmbed } from '@xalia/mcp-apps-sdk/widget';

对于代理开发者

如果你只需要渲染MCP应用小部件：

npm install @xalia/mcp-apps-widget

import { AssistantAppEmbed } from '@xalia/mcp-apps-widget';

function MyApp() {
  return (
    <AssistantAppEmbed
      widgetHtml={widgetHtml}
      toolOutput={result}
      metadata={metadata}
    />
  );
}

社区

加入我们的Discord社区进行讨论、支持和更新：

贡献

我们欢迎贡献！请参阅我们的贡献指南了解详情。

许可证

MIT许可证 - 详情见LICENSE。

外部资源

• OpenAI Apps SDK 文档
• 模型上下文协议（MCP）