Сервер Box MCP

Описание

Box MCP Server — это проект Python, который интегрируется с Box API для выполнения различных операций, таких как поиск файлов, извлечение текста, запросы на основе ИИ и извлечение данных. Он использует библиотеку box-sdk-gen и предоставляет набор инструментов для взаимодействия с файлами и папками Box.

Model Context Protocol (MCP) — это фреймворк, разработанный для стандартизации способа взаимодействия моделей с различными источниками данных и службами. В этом проекте MCP используется для упрощения интеграции с API Box, что позволяет выполнять эффективные и масштабируемые операции с файлами и папками Box. Проект Box MCP Server направлен на предоставление надежного и гибкого решения для управления и обработки данных Box с использованием передовых методов искусственного интеллекта и машинного обучения.

Related MCP server: Box MCP Server

Инструменты Реализованы

Инструменты API Box

box_who_am_i

Получите информацию о текущем пользователе и проверьте статус подключения.

• Возвращает: строку с информацией о пользователе.

box_authorize_app_tool

Запустите процесс авторизации приложения Box.

• Возвращает: сообщение о статусе авторизации

box_search_tool

Поиск файлов в Box.

• Параметры:

  • query (str): Запрос для поиска.

  • file_extensions (List[str], необязательно): Расширения файлов для фильтрации результатов.

  • where_to_look_for_query (Список[str], необязательно): Места для поиска (например, NAME, DESCRIPTION, FILE_CONTENT, COMMENTS, TAG).

  • ancestor_folder_ids (List[str], необязательно): Список идентификаторов папок, в которых следует выполнять поиск.

• Возвращает: Результаты поиска представляют собой список имен файлов и идентификаторов, разделенных новой строкой.

box_read_tool

Прочитать текстовое содержимое файла Box.

Параметры:

• file_id (str): идентификатор файла для чтения

Возвращает: Содержимое файла

box_ask_ai_tool

Задайте вопрос Box AI о файле.

Параметры:

• file_id (str): идентификатор файла

• prompt (str): Вопрос для ИИ

Возвращает: ответ ИИ

box_hubs_ask_ai_tool

Спросите Box AI о концентраторе. В настоящее время нет возможности через API узнать идентификатор концентратора, поэтому для использования этого инструмента вам необходимо знать идентификатор. Мы исправим это в будущем.

Параметры:

• hubs_id (str): идентификатор концентратора

• prompt (str): Вопрос для ИИ

Возвращает: ответ ИИ

box_search_folder_by_name

Найдите папку по имени.

Параметры:

• folder_name (str): Имя папки

Возвращает: идентификатор папки

box_ai_extract_data

Извлечение данных из файла с помощью ИИ.

Параметры:

• file_id (str): идентификатор файла

• fields (str): Поля для извлечения

Возвращает: извлеченные данные в формате JSON.

box_list_folder_content_by_folder_id

Список содержимого папки.

Параметры:

• folder_id (str): идентификатор папки

• is_recursive (bool): следует ли перечислять рекурсивно

Возвращает: содержимое папки в формате JSON с идентификатором, именем, типом и описанием.

box_manage_folder_tool

Создавайте, обновляйте или удаляйте папки в Box.

Параметры:

• action (str): Действие для выполнения: «создать», «удалить» или «обновить»

• folder_id (str, необязательно): идентификатор папки (требуется для удаления/обновления)

• name (str, необязательно): Имя папки (обязательно для создания, необязательно для обновления)

• parent_id (str, необязательно): идентификатор родительской папки (обязательно для создания, необязательно для обновления)

• description (str, необязательно): Описание папки (необязательно для обновления)

• recursive (bool, необязательно): удалять ли рекурсивно (необязательно для delete)

Возвращает: сообщение о состоянии с подробностями папки.

box_upload_file_tool

=======

• Параметры:

  • file_id (str): идентификатор файла для чтения.

• Возвращает: Текстовое содержимое файла.

box_ask_ai_tool

ИИ-запросы по одному файлу.

• Параметры:

  • file_id (str): идентификатор файла.

  • prompt (str): Запрос или инструкция для ИИ.

• Возвращает: ответ ИИ на основе содержимого файла.

box_ask_ai_tool_multi_file

Query Box AI с использованием нескольких файлов.

• Параметры:

  • file_ids (List[str]): Список идентификаторов файлов.

  • prompt (str): Инструкция для ИИ на основе совокупного контента.

• Возвращает: ответ, сгенерированный ИИ с учетом всех предоставленных файлов.

box_search_folder_by_name

Найдите папку в Box по ее названию.

• Параметры:

  • folder_name (str): Имя папки.

• Возвращает: информацию (имя и идентификатор) о соответствующих папках.

box_ai_extract_data

Извлечение определенных полей из файла с помощью ИИ.

• Параметры:

  • file_id (str): идентификатор файла.

  • fields (str): список полей для извлечения, разделенных запятыми.

• Возвращает: извлеченные данные в формате строки JSON.

box_list_folder_content_by_folder_id

Вывести список содержимого папки, используя ее идентификатор.

• Параметры:

  • folder_id (str): Идентификатор папки.

  • is_recursive (bool, необязательно): следует ли рекурсивно выводить содержимое.

• Возвращает: содержимое папки в виде строки JSON, включая идентификатор, имя, тип и описание.

box_manage_folder_tool

Создание, обновление или удаление папки в Box.

• Параметры:

  • action (str): Действие для выполнения: «создать», «удалить» или «обновить».

  • folder_id (str, необязательно): идентификатор папки (требуется для удаления и обновления).

  • name (str, необязательно): Имя папки (обязательно для создания, необязательно для обновления).

  • parent_id (str, необязательно): идентификатор родительской папки (по умолчанию «0» для корня).

  • description (str, необязательно): Описание папки (для обновления).

  • recursive (bool, необязательно): для рекурсивного удаления.

• Возвращает: сообщение о состоянии с подробностями папки.

box_upload_file_from_path_tool

Загрузите файл в Box из локальной файловой системы.

• Параметры:

  • file_path (str): Локальный путь к файлу.

  • folder_id (str, необязательно): идентификатор папки назначения (по умолчанию «0»).

  • new_file_name (str, необязательно): Новое имя файла (если не указано, используется исходное имя файла).

• Возвращает: сведения о загруженном файле (идентификатор и имя) или сообщение об ошибке.

box_upload_file_from_content_tool

Загрузите контент в виде файла в Box.

• Параметры:

  • content (str | bytes): Контент для загрузки (текст или двоичный).

  • file_name (str): Имя, присваиваемое файлу.

  • folder_id (str, необязательно): идентификатор папки назначения (по умолчанию «0»).

  • is_base64 (bool, необязательно): указывает, закодирован ли предоставленный контент в формате base64.

• Возвращает: сообщение об успешной загрузке с идентификатором и именем файла.

box_download_file_tool

Загрузите файл из Box.

• Параметры:

  • file_id (str): Идентификатор файла для загрузки.

  • save_file (bool, необязательно): сохранять ли файл локально.

  • save_path (str, необязательно): Локальный путь, по которому следует сохранить файл.

• Возвращает: для текстовых файлов возвращает содержимое; для изображений возвращает данные в кодировке base64; для других типов — сообщение об ошибке или подтверждение сохранения.

Инструменты для создания коробочных документов

box_docgen_create_batch_tool

Создавайте документы, используя шаблон Box Doc Gen и локальный файл JSON.

• Параметры:

  • file_id (str): Идентификатор файла шаблона.

  • destination_folder_id (str): идентификатор папки, в которой должны храниться сгенерированные документы.

  • user_input_file_path (str): Путь к JSON-файлу с входными данными.

  • output_type (str, необязательно): Формат вывода (по умолчанию «pdf»).

• Возвращает: результат пакета генерации документа в виде строки JSON.

box_docgen_get_job_tool

Получить одно задание 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): Идентификатор файла, который необходимо отметить как шаблон.

• Возврат: Детали шаблона после маркировки.

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): идентификатор шаблона.

  • template_version_id (str | None, необязательно): Конкретный идентификатор версии.

  • 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 или выше

• Учетные данные API Box (идентификатор клиента, секрет клиента и т. д.)

Установка

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 Окна

   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 Окна

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

4. Создайте файл .env в корневом каталоге и добавьте свои учетные данные API Box:

   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, если он запущен.

Использование курсора в качестве клиента

1. Откройте 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, при необходимости перезапустите его.

Проведение тестов

Проект включает набор тестов для проверки функциональности API Box. Перед запуском тестов обновите идентификаторы файлов и папок в тестовых файлах, чтобы они соответствовали идентификаторам в вашей учетной записи Box.

Настройка тестов

1. Обновить идентификаторы файлов и папок :

   • Каждый тестовый файл (в каталоге tests/ ) использует жестко запрограммированные идентификаторы для файлов и папок Box.

   • Замените эти идентификаторы действительными идентификаторами из вашей учетной записи Box.

2. Ссылки на идентификатор файла :

   • Например, в tests/test_box_api_read.py замените "1728677291168" на действительный идентификатор файла.

Проведение тестов

После обновления идентификаторов вы можете запустить тесты с помощью pytest:

Доступные тестовые наборы

• test_box_auth.py : Тестирует функциональность аутентификации.

• test_box_api_basic.py : Базовые тесты API Box.

• test_box_api_read.py : Тестирует возможности чтения файлов.

• test_box_api_search.py : Тестирует функциональность поиска.

• test_box_api_ai.py : Тестирует функции на основе искусственного интеллекта.

• test_box_api_file_ops.py : Тестирует операции загрузки и скачивания файлов.

• Дополнительные тесты охватывают операции с папками и функции Doc Gen.

Поиск неисправностей

Если вы получаете сообщение об ошибке Error: spawn uv ENOENT на MacOS при запуске сервера MCP с Claude Desktop, вы можете:

• Удалите uv и переустановите его с помощью Homebrew: brew install uv

• Или укажите полный путь к исполняемому файлу uv в вашей конфигурации:

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

[!ПРИМЕЧАНИЕ] Убедитесь, что ваши учетные данные API Box в .env установлены правильно.