MCP Server Box

描述

MCP Server Box 是一个 Python 项目，它与 Box API 集成，以执行各种操作，例如文件搜索、文本提取、基于 AI 的查询和数据提取。它利用 box-sdk-gen 库，并提供一组工具来与 Box 文件和文件夹进行交互。

模型上下文协议 (MCP) 是一个框架，旨在标准化模型与各种数据源和服务交互的方式。 在此项目中，MCP 用于促进与 Box API 的无缝集成，从而能够对 Box 文件和文件夹执行高效且可扩展的操作。 MCP Server Box 项目旨在提供一个强大而灵活的解决方案，用于使用先进的 AI 和机器学习技术来管理和处理 Box 数据。

已实现的工具

Box 工具

box_who_am_i

获取您当前的用户信息并检查连接状态。

返回： 用户信息字符串

box_authorize_app_tool

启动 Box 应用程序授权过程。

返回： 授权状态消息

box_search_tool

在 Box 中搜索文件。

参数：

• query (str)：搜索查询
• file_extensions (List[str], optional)：要按其进行过滤的文件扩展名
• where_to_look_for_query (List[str], optional)：搜索位置（NAME、DESCRIPTION、FILE_CONTENT、COMMENTS、TAG）
• ancestor_folder_ids (List[str], optional)：要在其中搜索的文件夹 ID

返回： 搜索结果

box_read_tool

读取 Box 文件的文本内容。

参数：

• file_id (str)：要读取的文件的 ID

返回： 文件内容

box_ask_ai_tool

向 Box AI 询问有关文件的信息。

参数：

• file_id (str)：文件的 ID
• prompt (str)：AI 的问题

返回： AI 响应

box_search_folder_by_name

按名称查找文件夹。

参数：

• folder_name (str)：文件夹的名称

返回： 文件夹 ID

box_ai_extract_data

使用 AI 从文件中提取数据。

参数：

• file_id (str)：文件的 ID
• fields (str)：要提取的字段

返回： JSON 格式的提取数据

box_list_folder_content_by_folder_id

列出文件夹内容。

参数：

• folder_id (str)：文件夹的 ID
• is_recursive (bool)：是否递归列出

返回： JSON 格式的文件夹内容，包含 id、name、type 和 description

box_manage_folder_tool

在 Box 中创建、更新或删除文件夹。

参数：

• action (str)：要执行的操作：“create”、“delete”或“update”
• folder_id (str, optional)：文件夹的 ID（删除/更新时必需）
• name (str, optional)：文件夹名称（创建时必需，更新时可选）
• parent_id (str, optional)：父文件夹 ID（创建时必需，更新时可选）
• description (str, optional)：文件夹描述（更新时可选）
• recursive (bool, optional)：是否递归删除（删除时可选）

返回： 包含文件夹详细信息的 Status message

box_upload_file_tool

将内容作为文件上传到 Box。

参数：

• content (str)：要作为文件上传的内容
• file_name (str)：在 Box 中为文件指定的名称
• folder_id (Any, optional)：要上传到的文件夹的 ID

返回： 包含文件 ID 和名称的上传状态

box_download_file_tool

从 Box 下载文件并返回其内容。

参数：

• file_id (Any)：要下载的文件的 ID
• save_file (bool, optional)：是否在本地保存文件
• save_path (str, optional)：保存文件的路径

返回： 文件内容，可以是文本、base64 编码的图像或保存状态消息

要求

• Python 3.13 或更高版本
• Box API 凭据（客户端 ID、客户端密钥等）

安装

1. 克隆存储库：

   git clone https://github.com/box-community/mcp-server-box.git
   cd mcp-server-box
   

2. 如果尚未安装 uv，请安装它：

   2.1 MacOS+Linux

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   2.2 Windows

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   

3. 创建并设置我们的项目：

   3.1 MacOS+Linux

   # 创建虚拟环境并激活它
   uv venv
   source .venv/bin/activate
   
   # 锁定依赖项
   uv lock
   

   3.1 Windows

   # 创建虚拟环境并激活它
   uv venv
   .venv\Scripts\activate
   
   # 锁定依赖项
   uv lock
   

4. 在根目录中创建一个 .env 文件，并添加您的 Box API 凭据：

   BOX_CLIENT_ID=your_client_id
   BOX_CLIENT_SECRET=your_client_secret
   

用法

运行 MCP 服务器

要启动 MCP 服务器，请运行以下命令：

uv --directory /Users/anovotny/Desktop/mcp-server-box run src/mcp_server_box.py

使用 Claude 作为客户端

1. 编辑您的 claude_desktop_config.json

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. 并添加以下内容：

{
    "mcpServers": {
        "mcp-server-box": {
            "command": "uv",
            "args": [
                "--directory",
                "/Users/anovotny/Desktop/mcp-server-box",
                "run",
                "src/mcp_server_box.py"
            ]
        }
    }
}

3. 如果 CLaude 正在运行，请重新启动它

## 运行测试

该项目包含一套测试，用于验证 Box API 功能。 在运行测试之前，您需要更新测试文件中的文件和文件夹 ID，以匹配您的 Box 帐户中的文件。

### 设置测试

1. **更新文件和文件夹 ID**：
   - 每个测试文件（在 `tests/` 目录中）都包含 Box 文件和文件夹的硬编码 ID
   - 您需要将这些 ID 替换为您 Box 帐户中的文件和文件夹的 ID
   - 示例：在 `test_box_api_read.py` 中，将 `"1728677291168"` 替换为您 Box 帐户中的文件的 ID

2. **测试文件 ID 引用**：
   - `test_box_api_read.py`：需要一个有效的文档文件 ID（例如，Word 文档）
   - `test_box_api_search.py`：更新搜索查询和文件扩展名以匹配您的内容
   - `test_box_api_ai.py`：需要一个文件 ID 来测试 AI 提取功能
   - 其他测试文件可能需要特定的文件夹 ID 或文件类型

### 运行测试

更新文件 ID 后，您可以使用 pytest 运行测试：

```bash
# 运行所有测试
pytest

# 运行特定的测试文件
pytest tests/test_box_api_file_ops.py

# 运行带有详细输出的测试
pytest -v

# 运行测试并显示打印语句
pytest -v -s

可用测试

• test_box_auth.py：测试身份验证功能
• test_box_api_basic.py：基本 Box API 测试
• test_box_api_read.py：测试文件读取功能
• test_box_api_search.py：测试搜索功能
• test_box_api_ai.py：测试基于 AI 的功能
• test_box_api_file_ops.py：测试文件上传和下载操作

创建新测试

创建新测试时：

1. 遵循现有测试文件中的模式
2. 使用 box_client fixture 进行身份验证的 API 访问
3. 清理测试期间创建的任何测试文件或文件夹
4. 添加适当的断言以验证功能

故障排除