MCP 服务器盒

描述

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

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

实施的工具

Box API 工具

box_who_am_i

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

• **返回：**用户信息字符串

box_authorize_app_tool

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

• **返回：**授权状态消息

box_search_tool

在 Box 中搜索文件。

• 参数：

  • query （str）：要搜索的查询。

  • file_extensions （List[str]，可选）：用于过滤结果的文件扩展名。

  • where_to_look_for_query （List[str]，可选）：要搜索的位置（例如 NAME、DESCRIPTION、FILE_CONTENT、COMMENTS、TAG）。

  • ancestor_folder_ids （List[str]，可选）：要搜索的文件夹 ID 列表。

• **返回：**搜索结果以换行符分隔的文件名和 ID 列表形式返回。

box_read_tool

读取 Box 文件的文本内容。

参数：

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

**返回：**文件内容

box_ask_ai_tool

向 Box AI 询问文件。

参数：

• file_id (str): 文件的ID

• prompt (str): 向 AI 提问

返回： AI响应

box_hubs_ask_ai_tool

向 Box AI 咨询有关 Hub 的信息。目前无法通过 API 获取 Hub ID，因此您必须知道该 ID 才能使用此工具。我们将在未来修复此问题。

参数：

• hubs_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、名称、类型和描述

box_manage_folder_tool

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

参数：

• action (str): 要执行的操作：“创建”、“删除”或“更新”

• folder_id (str，可选)：文件夹的 ID（删除/更新时必需）

• name (str，可选)：文件夹名称（创建时必需，更新时可选）

• parent_id (str, 可选)：父文件夹 ID（创建时必需，更新时可选）

• description （str，可选）：文件夹描述（更新时可选）

• recursive （bool，可选）：是否递归删除（删除时可选）

**返回：**带有文件夹详细信息的状态消息

box_upload_file_tool

=======

• 参数：

  • file_id (str): 需要读取的文件的ID。

• **返回：**文件的文本内容。

box_ask_ai_tool

关于单个文件的查询框 AI。

• 参数：

  • file_id (str): 文件标识符。

  • prompt （str）：针对 AI 的查询或指令。

• **返回：**基于文件内容的AI响应。

box_ask_ai_tool_multi_file

使用多个文件查询 Box AI。

• 参数：

  • file_ids (List[str])：文件 ID 列表。

  • prompt （str）：基于聚合内容的AI指令。

• **返回：**考虑到所有提供的文件，AI 生成的答案。

box_search_folder_by_name

通过名称在 Box 中定位文件夹。

• 参数：

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

• **返回：**有关匹配文件夹的信息（名称和 ID）。

box_ai_extract_data

使用 AI 从文件中提取特定字段。

• 参数：

  • file_id (str)：文件的 ID。

  • fields （str）：要提取的字段的逗号分隔列表。

• **返回：**以 JSON 字符串格式提取的数据。

box_list_folder_content_by_folder_id

使用文件夹 ID 列出文件夹的内容。

• 参数：

  • folder_id (str): 文件夹 ID。

  • is_recursive （bool，可选）：是否以递归方式列出内容。

• **返回：**文件夹内容作为 JSON 字符串，包括 id、名称、类型和描述。

box_manage_folder_tool

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

• 参数：

  • action (str): 要执行的操作：“创建”、“删除”或“更新”。

  • folder_id (str，可选)：文件夹 ID（删除和更新时必需）。

  • name （str，可选）：文件夹名称（创建时必需，更新时可选）。

  • parent_id （str，可选）：父文件夹 ID（根文件夹默认为“0”）。

  • description （str，可选）：文件夹的描述（用于更新）。

  • recursive （bool，可选）：用于递归删除。

• **返回：**带有文件夹详细信息的状态消息。

box_upload_file_from_path_tool

从本地文件系统路径上传文件到 Box。

• 参数：

  • file_path (str)：本地文件路径。

  • folder_id （str���可选）：目标文件夹 ID（默认为“0”）。

  • new_file_name （str，可选）：新文件名（如果未提供，则使用原始文件名）。

• **返回：**有关上传文件的详细信息（ID 和名称）或错误消息。

box_upload_file_from_content_tool

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

• 参数：

  • content （str | bytes）：要上传的内容（文本或二进制）。

  • file_name (str)：分配给文件的名称。

  • folder_id （str，可选）：目标文件夹 ID（默认为“0”）。

  • is_base64 （bool，可选）：指示所提供的内容是否是 base64 编码的。

• **返回：**上传成功消息，包括文件 ID 和名称。

box_download_file_tool

从 Box 下载文件。

• 参数：

  • file_id (str): 要下载的文件的 ID。

  • save_file （bool，可选）：是否在本地保存文件。

  • save_path （str，可选）：应保存文件的本地路径。

• **返回：**对于文本文件，返回内容；对于图像，返回 base64 编码数据；对于其他类型，返回错误或保存确认消息。

Box Doc Gen 工具

box_docgen_create_batch_tool

使用 Box Doc Gen 模板和本地 JSON 文件生成文档。

• 参数：

  • file_id (str): 模板文件 ID。

  • destination_folder_id (str)：应存储生成的文档的文件夹 ID。

  • user_input_file_path (str)：包含输入数据的 JSON 文件的路径。

  • output_type （str，可选）：输出格式（默认为“pdf”）。

• **返回：**文档生成批次的结果作为 JSON 字符串。

box_docgen_get_job_tool

通过 ID 获取单个 Doc Gen 作业。

• 参数：

  • job_id (str)：作业标识符。

• 返回： JSON 格式的字符串形式的作业详细信息。

box_docgen_list_jobs_tool

列出与当前用户相关的所有 Doc Gen 作业。

• 参数：

  • marker （str | None，可选）：分页标记。

  • limit （int | None，可选）：要返回的最大作业数。

• **返回：**以漂亮打印的 JSON 格式分页的作业列表。

box_docgen_list_jobs_by_batch_tool

列出属于特定批次的 Doc Gen 作业。

• 参数：

  • batch_id （str）：批次标识符。

  • marker （str | None，可选）：分页标记。

  • limit （int | None，可选）：要返回的最大作业数。

• **返回：**批处理作业详细信息（JSON 格式）。

box_docgen_template_create_tool

将文件标记为 Box Doc Gen 模板。

• 参数：

  • file_id (str)：要标记为模板的文件 ID。

• **返回：**标记后的模板详情。

box_docgen_template_list_tool

列出所有可用的 Box Doc Gen 模板。

• 参数：

  • marker （str | None，可选）：分页标记。

  • limit （int | None，可选）：列出的模板的最大数量。

• 返回： JSON 格式的模板列表。

box_docgen_template_delete_tool

从文件中删除 Doc Gen 模板标记。

• 参数：

  • template_id (str)：模板标识符。

• **返回：**以 JSON 格式确认删除。

box_docgen_template_get_by_id_tool

检索特定 Doc Gen 模板的详细信息。

• 参数：

  • template_id (str)：模板标识符。

• 返回： JSON 格式的模板详细信息。

box_docgen_template_list_tags_tool

列出与 Box Doc Gen 模板相关的所有标签。

• 参数：

  • template_id (str): 模板 ID。

  • template_version_id （str | None，可选）：特定版本 ID。

  • marker （str | None，可选）：分页标记。

  • limit （int | None，可选）：要返回的最大标签数。

• 返回： JSON 格式的标签列表。

box_docgen_template_list_jobs_tool

列出所有使用特定模板的 Doc Gen 作业。

• 参数：

  • template_id (str): 模板标识符。

  • marker （str | None，可选）：分页标记。

  • limit （int | None，可选）：要列出的最大作业数。

• **返回：**模板的作业详细信息（以 JSON 字符串形式）。

要求

• 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

   # Create virtual environment and activate it uv venv source .venv/bin/activate # Lock the dependencies uv lock

   3.2 Windows

   # Create virtual environment and activate it uv venv .venv\Scripts\activate # Lock the dependencies uv lock

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

   BOX_CLIENT_ID=your_client_id BOX_CLIENT_SECRET=your_client_secret

用法

运行 MCP 服务器

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

使用克劳德作为客户

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 正在运行，请重新启动它。

使用 Cursor 作为客户端

1. 使用 Cursor 打开您的 IDE。

2. 在设置中，选择Cursor settings 。

3. 在左侧导航中，选择MCP 。

4. 在左上角，点击Add new global MCP server 。

5. 粘贴以下 JSON（更新您的本地值）：

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

6. 保存并关闭 mcp.json 文件，如有必要，请重新启动。

运行测试

该项目包含一套用于验证 Box API 功能的测试。运行测试之前，请更新测试文件中的文件和文件夹 ID，使其与您的 Box 帐户中的 ID 一致。

设置测试

1. 更新文件和文件夹 ID ：

   • 每个测试文件（在tests/目录中）都使用 Box 文件和文件夹的硬编码 ID。

   • 将这些 ID 替换为 Box 帐户中的有效 ID。

2. 文件 ID 参考：

   • 例如，在tests/test_box_api_read.py中，将"1728677291168"替换为有效的文件 ID。

运行测试

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

可用的测试套件

• 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 ：测试文件上传和下载操作。

• 附加测试涵盖文件夹操作和 Doc Gen 功能。

故障排除

如果您在使用 Claude Desktop 运行 MCP 服务器时在 MacOS 上收到错误Error: spawn uv ENOENT ，您可以：

• 删除 uv 并使用 Homebrew 重新安装： brew install uv

• 或者在您的配置中提供 uv 可执行文件的完整路径：

  /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py

[!NOTE] 确保.env中的 Box API 凭据设置正确。