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 de caja

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): consulta de búsqueda
• file_extensions (List[str], opcional): extensiones de archivo para filtrar por
• where_to_look_for_query (List[str], opcional): Dónde buscar (NOMBRE, DESCRIPCIÓN, CONTENIDO_DEL_ARCHIVO, COMENTARIOS, ETIQUETA)
• ancestor_folder_ids (List[str], opcional): ID de carpeta para buscar dentro

Devoluciones: Resultados de búsqueda

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_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

Subir contenido como archivo a Box.

Parámetros:

• content (str): El contenido que se cargará como archivo
• file_name (str): El nombre que se le dará al archivo en Box
• folder_id (Cualquiera, opcional): El ID de la carpeta a la que cargar

Devuelve: Estado de carga con ID y nombre de archivo

box_download_file_tool

Descargue un archivo de Box y devuelva su contenido.

Parámetros:

• file_id (Cualquiera): El ID del archivo a descargar
• save_file (bool, opcional): si se debe guardar el archivo localmente
• save_path (str, opcional): Ruta donde guardar el archivo

Devuelve: el contenido del archivo como texto, imagen codificada en base64 o mensaje de estado de guardado

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.1 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

2. Y añade lo siguiente:

[!NOTA] Si usa MacOS, deberá instalar uv con brew: brew install uv o proporcione la ruta completa al ejecutable uv: /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py

3. Si Claude se está ejecutando, reinícielo.

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, seleccione Add new global MCP server .
5. Pasa el siguiente json, asegurándote de actualizarlo con tus valores locales:

6. Guarde y cierre el archivo mcp.json y asegúrese de que el servidor MCP esté habilitado. Es posible que tenga que reiniciar.

Ejecución de pruebas

El proyecto incluye un conjunto de pruebas para verificar la funcionalidad de la API de Box. Antes de ejecutarlas, deberá actualizar los ID de los archivos y carpetas de los archivos 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/ ) contiene identificaciones codificadas para archivos y carpetas de Box
   • Debe reemplazar estos ID con los ID de archivos y carpetas en su cuenta de Box
   • Ejemplo: En test_box_api_read.py , reemplace "1728677291168" con el ID de un archivo en su cuenta de Box
2. Referencias de ID de archivo de prueba :
   • test_box_api_read.py : necesita un ID de archivo de documento válido (por ejemplo, un documento de Word)
   • test_box_api_search.py : actualiza las consultas de búsqueda y las extensiones de archivo para que coincidan con tu contenido
   • test_box_api_ai.py : Necesita un ID de archivo para probar las capacidades de extracción de IA
   • Es posible que otros archivos de prueba requieran identificadores de carpeta o tipos de archivos específicos

Ejecución de pruebas

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

Pruebas disponibles

• test_box_auth.py : prueba la funcionalidad de autenticación
• test_box_api_basic.py : Pruebas básicas de la 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

Creación de nuevas pruebas

Al crear nuevas pruebas:

1. Siga el patrón en los archivos de prueba existentes
2. Utilice el accesorio box_client para el acceso a la API autenticado
3. Limpie cualquier archivo o carpeta de prueba creados durante las pruebas
4. Agregue afirmaciones adecuadas para verificar la funcionalidad

Solución de problemas

Si está en MacOS y ejecuta el servidor MCP con Claude Desktop y ve el siguiente error:

Error: spawn uv ENOENT

puedes eliminar uv y reinstalarlo con brew: brew install uv o proporcionar la ruta completa al ejecutable uv: /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py