MCP Server Box

Сервер Box MCP

Описание

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

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

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

Инструменты 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 установлены правильно.