MCP Server Box

Caja de servidor MCP

Descripción

MCP Server Box es un proyecto de Python que se integra con la API de Box para realizar diversas operaciones, como búsqueda de archivos, extracción de texto, consultas basadas en IA y extracción de datos. Utiliza la biblioteca box-sdk-gen y proporciona un conjunto de herramientas para interactuar con los archivos y carpetas de Box.

El Protocolo de Contexto de Modelo (MCP) es un marco diseñado para estandarizar la interacción de los modelos con diversas fuentes y servicios de datos. En este proyecto, MCP se utiliza para facilitar una integración fluida con la API de Box, lo que permite operaciones eficientes y escalables en archivos y carpetas de Box. El proyecto MCP Server Box busca proporcionar una solución robusta y flexible para la gestión y el procesamiento de datos de Box mediante técnicas avanzadas de IA y aprendizaje automático.

Herramientas implementadas

Herramientas API de Box

box_who_am_i

Obtenga su información de usuario actual y verifique el estado de la conexión.

• Devuelve: cadena de información del usuario

box_authorize_app_tool

Iniciar el proceso de autorización de la aplicación Box.

• Devoluciones: Mensaje de estado de autorización

box_search_tool

Buscar archivos en Box.

• Parámetros:
  • query (str): La consulta a buscar.
  • file_extensions (List[str], opcional): extensiones de archivo para filtrar resultados.
  • where_to_look_for_query (List[str], opcional): Ubicaciones para buscar (por ejemplo, NOMBRE, DESCRIPCIÓN, CONTENIDO_DEL_ARCHIVO, COMENTARIOS, ETIQUETA).
  • ancestor_folder_ids (List[str], opcional): Lista de ID de carpetas en las que buscar.
• Devuelve: Los resultados de la búsqueda como una lista de nombres de archivos e identificaciones separados por nuevas líneas.

box_read_tool

Leer el contenido de texto de un archivo Box.

Parámetros:

• file_id (str): ID del archivo a leer

Devuelve: Contenido del archivo

box_ask_ai_tool

Pregúntele a Box AI sobre un archivo.

Parámetros:

• file_id (str): ID del archivo
• prompt (str): Pregunta para la IA

Devoluciones: Respuesta de IA

box_hubs_ask_ai_tool

Pregunta a Box AI sobre un centro. Actualmente no es posible obtener el ID de un centro mediante la API, por lo que debes conocerlo para usar esta herramienta. Lo solucionaremos más adelante.

Parámetros:

• hubs_id (str): ID del concentrador
• prompt (str): Pregunta para la IA

Devoluciones: Respuesta de IA

box_search_folder_by_name

Localizar una carpeta por nombre.

Parámetros:

• folder_name (str): Nombre de la carpeta

Devuelve: ID de carpeta

box_ai_extract_data

Extraer datos de un archivo usando IA.

Parámetros:

• file_id (str): ID del archivo
• fields (str): Campos a extraer

Devuelve: Datos extraídos en formato JSON

box_list_folder_content_by_folder_id

Listado del contenido de la carpeta.

Parámetros:

• folder_id (str): ID de la carpeta
• is_recursive (bool): si se debe enumerar recursivamente

Devuelve: Contenido de la carpeta en formato JSON con id, nombre, tipo y descripción

box_manage_folder_tool

Crear, actualizar o eliminar carpetas en Box.

Parámetros:

• action (str): Acción a realizar: "crear", "eliminar" o "actualizar"
• folder_id (str, opcional): ID de la carpeta (obligatorio para eliminar/actualizar)
• name (str, opcional): nombre de la carpeta (obligatorio para crear, opcional para actualizar)
• parent_id (str, opcional): ID de la carpeta principal (obligatorio para la creación, opcional para la actualización)
• description (str, opcional): Descripción de la carpeta (opcional para actualización)
• recursive (bool, opcional): si se debe eliminar recursivamente (opcional para eliminar)

Devuelve: Mensaje de estado con detalles de la carpeta

box_upload_file_tool

=======

• Parámetros:
  • file_id (str): El ID del archivo que se leerá.
• Devuelve: Contenido de texto del archivo.

box_ask_ai_tool

Consulta Box AI sobre un único archivo.

• Parámetros:
  • file_id (str): El identificador del archivo.
  • prompt (str): Consulta o instrucción para la IA.
• Devuelve: Respuesta de IA basada en el contenido del archivo.

box_ask_ai_tool_multi_file

Consulta de Box AI usando múltiples archivos.

• Parámetros:
  • file_ids (List[str]): Lista de ID de archivos.
  • prompt (str): Instrucción para la IA basada en el contenido agregado.
• Devuelve: Respuesta generada por IA considerando todos los archivos proporcionados.

box_search_folder_by_name

Localice una carpeta en Box por su nombre.

• Parámetros:
  • folder_name (str): Nombre de la carpeta.
• Devuelve: Información (nombre e ID) sobre las carpetas coincidentes.

box_ai_extract_data

Extraer campos específicos de un archivo usando IA.

• Parámetros:
  • file_id (str): ID del archivo.
  • fields (str): lista separada por comas de campos para extraer.
• Devuelve: datos extraídos en formato de cadena JSON.

box_list_folder_content_by_folder_id

Enumere el contenido de una carpeta usando su ID.

• Parámetros:
  • folder_id (str): ID de la carpeta.
  • is_recursive (bool, opcional): si desea enumerar el contenido de forma recursiva.
• Devuelve: el contenido de la carpeta como una cadena JSON que incluye identificación, nombre, tipo y descripción.

box_manage_folder_tool

Crear, actualizar o eliminar una carpeta en Box.

• Parámetros:
  • action (str): Acción a realizar: "crear", "eliminar" o "actualizar".
  • folder_id (str, opcional): ID de carpeta (obligatorio para eliminar y actualizar).
  • name (str, opcional): nombre de la carpeta (obligatorio para crear, opcional para actualizar).
  • parent_id (str, opcional): ID de la carpeta principal (predeterminado a "0" para la raíz).
  • description (str, opcional): Descripción de la carpeta (para actualización).
  • recursive (bool, opcional): para eliminación recursiva.
• Devuelve: Mensaje de estado con detalles de la carpeta.

box_upload_file_from_path_tool

Sube un archivo a Box desde una ruta del sistema de archivos local.

• Parámetros:
  • file_path (str): Ruta del archivo local.
  • folder_id (str, opcional): ID de la carpeta de destino (predeterminado a "0").
  • new_file_name (str, opcional): nuevo nombre de archivo (si no se proporciona, utiliza el nombre de archivo original).
• Devuelve: Detalles sobre el archivo cargado (ID y nombre) o un mensaje de error.

box_upload_file_from_content_tool

Subir contenido como archivo a Box.

• Parámetros:
  • content (str | bytes): Contenido a cargar (texto o binario).
  • file_name (str): El nombre para asignar al archivo.
  • folder_id (str, opcional): ID de la carpeta de destino (predeterminado a "0").
  • is_base64 (bool, opcional): indica si el contenido proporcionado está codificado en base64.
• Devuelve: Mensaje de éxito de carga con ID y nombre de archivo.

box_download_file_tool

Descargue un archivo de Box.

• Parámetros:
  • file_id (str): El ID del archivo a descargar.
  • save_file (bool, opcional): si se debe guardar el archivo localmente.
  • save_path (str, opcional): la ruta local donde se debe guardar el archivo.
• Devuelve: para archivos de texto, devuelve el contenido; para imágenes, devuelve datos codificados en base64; para otros tipos, un mensaje de error o de confirmación de guardado.

Herramientas de generación de documentos de Box

box_docgen_create_batch_tool

Genere documentos utilizando una plantilla de Box Doc Gen y un archivo JSON local.

• Parámetros:
  • file_id (str): ID del archivo de plantilla.
  • destination_folder_id (str): ID de la carpeta donde se deben almacenar los documentos generados.
  • user_input_file_path (str): Ruta a un archivo JSON con datos de entrada.
  • output_type (str, opcional): Formato de salida (el valor predeterminado es "pdf").
• Devuelve: El resultado del lote de generación de documentos como una cadena JSON.

box_docgen_get_job_tool

Obtener un solo trabajo Doc Gen por su ID.

• Parámetros:
  • job_id (str): El identificador del trabajo.
• Devuelve: detalles del trabajo en una cadena con formato JSON.

box_docgen_list_jobs_tool

Enumere todos los trabajos de Doc Gen asociados con el usuario actual.

• Parámetros:
  • marker (str | Ninguno, opcional): Marcador de paginación.
  • limit (int | Ninguno, opcional): Número máximo de trabajos a devolver.
• Devuelve: Lista paginada de trabajos en formato JSON bien impreso.

box_docgen_list_jobs_by_batch_tool

Enumere los trabajos de Doc Gen que pertenecen a un lote específico.

• Parámetros:
  • batch_id (str): El identificador del lote.
  • marker (str | Ninguno, opcional): Marcador de paginación.
  • limit (int | Ninguno, opcional): Número máximo de trabajos a devolver.
• Devuelve: Detalles de trabajos por lotes en formato JSON.

box_docgen_template_create_tool

Marcar un archivo como una plantilla de Box Doc Gen.

• Parámetros:
  • file_id (str): ID del archivo para marcar como plantilla.
• Devuelve: Detalles de la plantilla después de marcar.

box_docgen_template_list_tool

Enumere todas las plantillas de Box Doc Gen disponibles.

• Parámetros:
  • marker (str | Ninguno, opcional): Marcador de paginación.
  • limit (int | Ninguno, opcional): Número máximo de plantillas a enumerar.
• Devuelve: Lista de plantillas en formato JSON.

box_docgen_template_delete_tool

Eliminar la marca de plantilla Doc Gen de un archivo.

• Parámetros:
  • template_id (str): El identificador de la plantilla.
• Devuelve: Confirmación de eliminación como JSON.

box_docgen_template_get_by_id_tool

Recupere detalles de una plantilla Doc Gen específica.

• Parámetros:
  • template_id (str): El identificador de la plantilla.
• Devuelve: Detalles de la plantilla como JSON.

box_docgen_template_list_tags_tool

Enumere todas las etiquetas asociadas con una plantilla de Box Doc Gen.

• Parámetros:
  • template_id (str): El ID de la plantilla.
  • template_version_id (str | Ninguno, opcional): ID de versión específica.
  • marker (str | Ninguno, opcional): Marcador de paginación.
  • limit (int | Ninguno, opcional): Número máximo de etiquetas a devolver.
• Devuelve: Lista de etiquetas en formato JSON.

box_docgen_template_list_jobs_tool

Enumere todos los trabajos de Doc Gen que utilizaron una plantilla específica.

• Parámetros:
  • template_id (str): El identificador de la plantilla.
  • marker (str | Ninguno, opcional): Marcador de paginación.
  • limit (int | Ninguno, opcional): Número máximo de trabajos a enumerar.
• Devuelve: Detalles del trabajo para la plantilla como una cadena JSON.

Requisitos

• Python 3.13 o superior
• Credenciales de API de Box (ID de cliente, secreto de cliente, etc.)

Instalación

1. Clonar el repositorio:
   git clone https://github.com/box-community/mcp-server-box.git cd mcp-server-box
2. Instalar uv si aún no está instalado:2.1 MacOS+Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   2.2 Ventanas
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
3. Crea y configura nuestro proyecto:3.1 MacOS+Linux
   # Create virtual environment and activate it uv venv source .venv/bin/activate # Lock the dependencies uv lock
   3.2 Ventanas
   # Create virtual environment and activate it uv venv .venv\Scripts\activate # Lock the dependencies uv lock
4. Cree un archivo .env en el directorio raíz y agregue sus credenciales de Box API:
   BOX_CLIENT_ID=your_client_id BOX_CLIENT_SECRET=your_client_secret

Uso

Ejecución del servidor MCP

Para iniciar el servidor MCP, ejecute el siguiente comando:

Usando a Claude como cliente

1. Edite su claude_desktop_config.json :
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
2. Añade la configuración:
   { "mcpServers": { "mcp-server-box": { "command": "uv", "args": [ "--directory", "/Users/anovotny/Desktop/mcp-server-box", "run", "src/mcp_server_box.py" ] } } }
3. Reinicie Claude si está ejecutándose.

Usando Cursor como cliente

1. Abra su IDE con Cursor.
2. En configuración, seleccione Cursor settings .
3. En el panel de navegación izquierdo, seleccione MCP .
4. En la parte superior izquierda, haga clic en Add new global MCP server .
5. Pegue el siguiente JSON (actualizado para sus valores locales):
   { "mcpServers": { "box": { "command": "uv", "args": [ "--directory", "/Users/shurrey/local/mcp-server-box", "run", "src/mcp_server_box.py" ] } } }
6. Guarde y cierre el archivo mcp.json y reinicie si es necesario.

Ejecución de pruebas

El proyecto incluye un conjunto de pruebas para verificar la funcionalidad de la API de Box. Antes de ejecutar las pruebas, actualice los ID de los archivos y carpetas de prueba para que coincidan con los de su cuenta de Box.

Configuración de pruebas

1. Actualizar los ID de archivos y carpetas :
   • Cada archivo de prueba (en el directorio tests/ ) utiliza identificaciones codificadas para archivos y carpetas de Box.
   • Reemplace estas identificaciones con identificaciones válidas de su cuenta de Box.
2. Referencias de ID de archivo :
   • Por ejemplo, en tests/test_box_api_read.py , reemplace "1728677291168" con un ID de archivo válido.

Ejecución de pruebas

Una vez que haya actualizado los ID, puede ejecutar las pruebas usando pytest:

Conjuntos de pruebas disponibles

• test_box_auth.py : prueba la funcionalidad de autenticación.
• test_box_api_basic.py : Pruebas básicas de API de Box.
• test_box_api_read.py : prueba las capacidades de lectura de archivos.
• test_box_api_search.py : prueba la funcionalidad de búsqueda.
• test_box_api_ai.py : prueba funciones basadas en IA.
• test_box_api_file_ops.py : prueba las operaciones de carga y descarga de archivos.
• Las pruebas adicionales cubren operaciones de carpeta y funciones de Doc Gen.

Solución de problemas

Si recibe el error Error Error: spawn uv ENOENT en MacOS al ejecutar el servidor MCP con Claude Desktop, puede:

• Eliminar uv y volver a instalarlo con Homebrew: brew install uv
• O proporcione la ruta completa al ejecutable uv en su configuración:
  /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py

[!NOTA] Asegúrese de que sus credenciales de Box API en .env estén configuradas correctamente.