远程MCP反应客户端

Name: 远程MCP反应客户端
Author: box-community

作者：box-community2 星标更新：2025-08-19

安装使用来源：spider==github.com

项目介绍

Box MCP 客户端 React

基于React的客户端应用程序，通过模型上下文协议（MCP）与Box进行交互。此应用程序提供了一个聊天界面，用于与Box MCP服务器通信并访问Box内容和工具。

功能

Box OAuth认证：使用OAuth 2.0安全登录Box
MCP集成：连接到Box MCP服务器以访问Box工具和资源
聊天界面：交互式聊天UI，用于与MCP服务器通信
工具执行：从聊天界面直接执行Box MCP工具
开发模式：当未配置MCP服务器时，模拟响应
现代UI：使用styled-components和TypeScript的响应式设计
错误处理：全面的错误边界和用户友好的消息

架构

React 应用程序 → MCP 客户端 → Box MCP 服务器

应用程序遵循分层架构：

表示层：带有styled-components的React组件
服务层：身份验证和服务
集成层：Box API和MCP协议处理器

技术栈

前端：React 19与TypeScript
构建工具：Vite
样式：带有主题提供商的Styled Components
MCP SDK：@modelcontextprotocol/sdk（官方TypeScript SDK）
身份验证：与Box的OAuth 2.0
开发：热重载和快速刷新

快速开始

先决条件

Node.js 18或更高版本
npm或yarn包管理器
一个Box开发者账户
部署的Box MCP服务器（开发可选）

安装

克隆并安装依赖项：

git clone <repository-url>
cd box-mcp-client-react
npm install

设置环境变量：

cp .env.example .env

编辑.env文件以添加您的配置：

# 必需：Box OAuth凭证
VITE_BOX_CLIENT_ID=your_box_client_id_here
VITE_BOX_CLIENT_SECRET=your_box_client_secret_here
VITE_BOX_REDIRECT_URI=http://localhost:3000/auth/callback

# 可选：Box MCP服务器URL
VITE_BOX_MCP_SERVER_URL=https://your-box-mcp-server.example.com

# OpenAI API配置
V
VITE_OPENAI_API_KEY=your_openai_key

# 可选：调试模式
VITE_DEBUG=false

运行开发服务器：
```
npm run dev
```
打开浏览器： 导航至http://localhost:3000

Box开发者设置

创建Box应用：
- 访问Box开发者控制台
- 创建一个新的自定义应用，使用OAuth 2.0（用户身份验证）
- 记录您的客户端ID和客户端密钥
配置OAuth：
- 将重定向URI设置为：http://localhost:3000/auth/callback
- 启用所需的范围（通常为“读取所有文件和文件夹”）
更新环境：
- 在.env文件中添加您的客户端ID和密钥

MCP服务器集成

此客户端与实现模型上下文协议的Box MCP服务器兼容。

使用真实的MCP服务器

部署一个Box MCP服务器（参见MCP服务器）
在您的.env文件中设置VITE_BOX_MCP_SERVER_URL
应用程序将连接并显示可用工具

开发模式

如果未配置MCP服务器URL，应用程序将以开发模式运行，并使用模拟响应。这允许您：

测试身份验证流程
探索聊天界面
开发UI组件

使用方法

身份验证：
- 点击“使用Box登录”进行身份验证
- 在弹出窗口/重定向中完成OAuth流程
聊天界面：
- 身份验证后，使用聊天界面
- 发送消息与MCP服务器互动
- 查看可用工具和资源
工具命令：
- 使用!tool <toolname> [参数]执行MCP工具
- 示例：!tool list_files path=/

项目结构

src/
├── components/
│   ├── Auth/                 # 身份验证组件
│   │   ├── LoginButton.tsx
│   │   └── AuthCallback.tsx
│   ├── Chat/                 # 聊天界面组件
│   │   ├── ChatContainer.tsx
│   │   ├── ChatHeader.tsx
│   │   ├── MessageList.tsx
│   │   ├── MessageBubble.tsx
│   │   ├── MessageInput.tsx
│   │   └── TypingIndicator.tsx
│   └── Common/               # 共享组件
│       ├── ThemeProvider.tsx
│       ├── GlobalStyles.tsx
│       └── ErrorBoundary.tsx
├── services/
│   ├── authService.ts        # Box OAuth处理
│   └── mcpClient.ts          # MCP客户端实现
├── hooks/
│   └── useAuth.ts            # 身份验证钩子
├── types/
│   ├── auth.ts               # 身份验证类型
│   ├── chat.ts               # 聊天消息类型
│   └── mcp.ts                # MCP协议类型
├── styles/
│   └── theme.ts              # 主题配置
├── utils/
│   └── crypto.ts             # 令牌加密实用工具
├── App.tsx                   # 主应用程序组件
└── index.tsx                 # 应用程序入口点

可用脚本

npm run dev - 在端口3000启动开发服务器
npm run build - 构建生产版本
npm run preview - 预览生产构建
npm test - 运行测试（尚未配置）

安全特性

令牌加密：访问令牌在存储前被加密
仅HTTPS：所有通信均使用HTTPS
PKCE流：带有代码交换证明密钥的OAuth 2.1
安全头：所有MCP请求的适当授权头
错误边界：防止应用程序崩溃传播

MCP协议实现

应用程序实现了模型上下文协议规范：

身份验证：每次请求上的Bearer令牌身份验证
会话管理：适当的会话创建和清理
传输：带会话ID头的流式HTTP
错误处理：全面的MCP错误响应处理
工具调用：支持Box特定的MCP工具
资源访问：通过MCP访问Box资源

故障排除

常见问题

身份验证失败
- 验证Box客户端ID是否正确
- 检查重定向URI是否匹配Box应用配置
- 生产环境中确保使用HTTPS
MCP连接问题
- 验证MCP服务器URL是否可访问
- 检查网络连接
- 查看浏览器控制台中的详细错误信息
构建问题
- 确保Node.js版本兼容性
- 清除npm缓存：npm cache clean --force
- 删除node_modules并重新安装

调试模式

启用调试日志记录，设置：

REACT_APP_DEBUG=true

贡献

分叉仓库
创建功能分支
进行更改
如适用，添加测试
提交拉取请求

许可

该项目根据ISC许可发布。

支持

对于以下相关问题：

Box API：参见Box开发者文档
MCP协议：参见模型上下文协议文档
此应用程序：在此仓库中打开一个问题