MCP Server Box

Box MCP-Server

Beschreibung

Der Box MCP Server ist ein Python-Projekt, das in die Box-API integriert ist und verschiedene Operationen wie Dateisuche, Textextraktion, KI-basierte Abfragen und Datenextraktion durchführt. Es nutzt die Bibliothek box-sdk-gen und bietet eine Reihe von Tools für die Interaktion mit Box-Dateien und -Ordnern.

Das Model Context Protocol (MCP) ist ein Framework zur Standardisierung der Interaktion von Modellen mit verschiedenen Datenquellen und Diensten. In diesem Projekt wird MCP verwendet, um die nahtlose Integration mit der Box-API zu ermöglichen und so effiziente und skalierbare Operationen an Box-Dateien und -Ordnern zu ermöglichen. Das Box MCP Server-Projekt zielt darauf ab, eine robuste und flexible Lösung für die Verwaltung und Verarbeitung von Box-Daten mithilfe fortschrittlicher KI- und Machine-Learning-Techniken bereitzustellen.

Implementierte Tools

Box-API-Tools

box_who_am_i

Rufen Sie Ihre aktuellen Benutzerinformationen ab und überprüfen Sie den Verbindungsstatus.

• Rückgabe: Benutzerinformationszeichenfolge

box_authorize_app_tool

Starten Sie den Autorisierungsprozess der Box-Anwendung.

• Rückgabe: Autorisierungsstatusmeldung

box_search_tool

Suchen Sie in Box nach Dateien.

• Parameter:
  • query (str): Die zu suchende Abfrage.
  • file_extensions (Liste[str], optional): Dateierweiterungen zum Filtern der Ergebnisse.
  • where_to_look_for_query (Liste[str], optional): Zu suchende Orte (z. B. NAME, BESCHREIBUNG, DATEIINHALT, KOMMENTARE, TAG).
  • ancestor_folder_ids (Liste[str], optional): Liste der Ordner-IDs, in denen gesucht werden soll.
• Gibt zurück: Die Suchergebnisse als durch Zeilenumbrüche getrennte Liste von Dateinamen und IDs.

box_read_tool

Lesen Sie den Textinhalt einer Box-Datei.

Parameter:

• file_id (str): ID der zu lesenden Datei

Rückgabe: Dateiinhalt

box_ask_ai_tool

Fragen Sie Box AI nach einer Datei.

Parameter:

• file_id (str): ID der Datei
• prompt (str): Frage an die KI

Rückgaben: KI-Antwort

box_hubs_ask_ai_tool

Fragen Sie Box AI nach einem Hub. Derzeit gibt es keine Möglichkeit, die Hub-ID über die API zu ermitteln. Sie müssen daher die ID kennen, um dieses Tool zu verwenden. Wir werden dies in Zukunft beheben.

Parameter:

• hubs_id (str): ID des Hubs
• prompt (str): Frage an die KI

Rückgaben: KI-Antwort

box_search_folder_by_name

Suchen Sie einen Ordner anhand des Namens.

Parameter:

• folder_name (str): Name des Ordners

Gibt zurück: Ordner-ID

box_ai_extract_data

Extrahieren Sie mithilfe von KI Daten aus einer Datei.

Parameter:

• file_id (str): ID der Datei
• fields (str): Zu extrahierende Felder

Gibt zurück: Extrahierte Daten im JSON-Format

box_list_folder_content_by_folder_id

Ordnerinhalte auflisten.

Parameter:

• folder_id (str): ID des Ordners
• is_recursive (bool): Ob rekursiv aufgelistet werden soll

Gibt zurück: Ordnerinhalt im JSON-Format mit ID, Name, Typ und Beschreibung

box_manage_folder_tool

Erstellen, aktualisieren oder löschen Sie Ordner in Box.

Parameter:

• action (str): Auszuführende Aktion: „Erstellen“, „Löschen“ oder „Aktualisieren“
• folder_id (str, optional): ID des Ordners (erforderlich zum Löschen/Aktualisieren)
• name (str, optional): Ordnername (erforderlich zum Erstellen, optional zum Aktualisieren)
• parent_id (str, optional): ID des übergeordneten Ordners (erforderlich zum Erstellen, optional zum Aktualisieren)
• description (str, optional): Ordnerbeschreibung (optional für Update)
• recursive (bool, optional): Ob rekursiv gelöscht werden soll (optional für Löschen)

Rückgabe: Statusmeldung mit Ordnerdetails

box_upload_file_tool

=======

• Parameter:
  • file_id (str): Die ID der zu lesenden Datei.
• Gibt zurück: Textinhalt der Datei.

box_ask_ai_tool

Abfragebox-KI bezüglich einer einzelnen Datei.

• Parameter:
  • file_id (str): Die Dateikennung.
  • prompt (str): Abfrage oder Anweisung für die KI.
• Gibt zurück: KI-Antwort basierend auf dem Dateiinhalt.

box_ask_ai_tool_multi_file

Query Box AI mit mehreren Dateien.

• Parameter:
  • file_ids (Liste[str]): Liste der Datei-IDs.
  • prompt (str): Anweisung für die KI basierend auf dem aggregierten Inhalt.
• Rückgabe: KI-generierte Antwort unter Berücksichtigung aller bereitgestellten Dateien.

box_search_folder_by_name

Suchen Sie in Box anhand seines Namens nach einem Ordner.

• Parameter:
  • folder_name (str): Name des Ordners.
• Gibt zurück: Informationen (Name und ID) zu übereinstimmenden Ordnern.

box_ai_extract_data

Extrahieren Sie mithilfe von KI bestimmte Felder aus einer Datei.

• Parameter:
  • file_id (str): ID der Datei.
  • fields (str): Durch Kommas getrennte Liste der zu extrahierenden Felder.
• Gibt zurück: Extrahierte Daten im JSON-String-Format.

box_list_folder_content_by_folder_id

Listen Sie den Inhalt eines Ordners anhand seiner ID auf.

• Parameter:
  • folder_id (str): Ordner-ID.
  • is_recursive (bool, optional): Ob der Inhalt rekursiv aufgelistet werden soll.
• Gibt zurück: Ordnerinhalt als JSON-Zeichenfolge einschließlich ID, Name, Typ und Beschreibung.

box_manage_folder_tool

Erstellen, aktualisieren oder löschen Sie einen Ordner in Box.

• Parameter:
  • action (str): Auszuführende Aktion: „Erstellen“, „Löschen“ oder „Aktualisieren“.
  • folder_id (str, optional): Ordner-ID (erforderlich zum Löschen und Aktualisieren).
  • name (str, optional): Ordnername (erforderlich zum Erstellen, optional zum Aktualisieren).
  • parent_id (str, optional): ID des übergeordneten Ordners (Standardwert: „0“ für „root“).
  • description (str, optional): Beschreibung für den Ordner (zum Aktualisieren).
  • recursive (bool, optional): Zum rekursiven Löschen.
• Gibt zurück: Statusmeldung mit Ordnerdetails.

box_upload_file_from_path_tool

Laden Sie eine Datei von einem lokalen Dateisystempfad in Box hoch.

• Parameter:
  • file_path (str): Lokaler Dateipfad.
  • folder_id (str, optional): Zielordner-ID (Standardwert: „0“).
  • new_file_name (str, optional): Neuer Dateiname (falls nicht angegeben, wird der ursprüngliche Dateiname verwendet).
• Gibt zurück: Details zur hochgeladenen Datei (ID und Name) oder eine Fehlermeldung.

box_upload_file_from_content_tool

Laden Sie Inhalte als Datei in Box hoch.

• Parameter:
  • content (str | Bytes): Hochzuladender Inhalt (Text oder Binär).
  • file_name (str): Der der Datei zuzuweisende Name.
  • folder_id (str, optional): Zielordner-ID (Standardwert: „0“).
  • is_base64 (bool, optional): Gibt an, ob der bereitgestellte Inhalt Base64-codiert ist.
• Gibt zurück: Upload-Erfolgsmeldung mit Datei-ID und -Name.

box_download_file_tool

Laden Sie eine Datei von Box herunter.

• Parameter:
  • file_id (str): Die ID der herunterzuladenden Datei.
  • save_file (bool, optional): Ob die Datei lokal gespeichert werden soll.
  • save_path (str, optional): Der lokale Pfad, in dem die Datei gespeichert werden soll.
• Rückgabewerte: Gibt bei Textdateien den Inhalt zurück; bei Bildern werden base64-codierte Daten zurückgegeben; bei anderen Typen wird eine Fehler- oder Speicherbestätigungsmeldung ausgegeben.

Box Doc Gen Tools

box_docgen_create_batch_tool

Generieren Sie Dokumente mithilfe einer Box Doc Gen-Vorlage und einer lokalen JSON-Datei.

• Parameter:
  • file_id (str): Vorlagendatei-ID.
  • destination_folder_id (str): Ordner-ID, in der generierte Dokumente gespeichert werden sollen.
  • user_input_file_path (str): Pfad zu einer JSON-Datei mit Eingabedaten.
  • output_type (str, optional): Ausgabeformat (Standard ist „pdf“).
• Gibt zurück: Das Ergebnis des Dokumentgenerierungsstapels als JSON-Zeichenfolge.

box_docgen_get_job_tool

Rufen Sie einen einzelnen Doc Gen-Job anhand seiner ID ab.

• Parameter:
  • job_id (str): Die Jobkennung.
• Gibt zurück: Auftragsdetails in einer Zeichenfolge im JSON-Format.

box_docgen_list_jobs_tool

Listet alle Doc Gen-Jobs auf, die dem aktuellen Benutzer zugeordnet sind.

• Parameter:
  • marker (str | Keine, optional): Seitennummerierungsmarker.
  • limit (int | Keine, optional): Maximale Anzahl der zurückzugebenden Jobs.
• Gibt zurück: Paginierte Liste der Jobs in schön gedrucktem JSON.

box_docgen_list_jobs_by_batch_tool

Listen Sie Doc Gen-Jobs auf, die zu einem bestimmten Stapel gehören.

• Parameter:
  • batch_id (str): Die Batch-ID.
  • marker (str | Keine, optional): Seitennummerierungsmarker.
  • limit (int | Keine, optional): Maximale Anzahl der zurückzugebenden Jobs.
• Gibt zurück: Details zu Batch-Jobs als JSON.

box_docgen_template_create_tool

Markieren Sie eine Datei als Box Doc Gen-Vorlage.

• Parameter:
  • file_id (str): Als Vorlage zu markierende Datei-ID.
• Rückgabe: Vorlagendetails nach der Markierung.

box_docgen_template_list_tool

Listen Sie alle verfügbaren Box Doc Gen-Vorlagen auf.

• Parameter:
  • marker (str | Keine, optional): Seitennummerierungsmarker.
  • limit (int | Keine, optional): Maximale Anzahl aufzulistender Vorlagen.
• Gibt zurück: Liste der Vorlagen im JSON-Format.

box_docgen_template_delete_tool

Entfernen Sie die Doc Gen-Vorlagenmarkierung aus einer Datei.

• Parameter:
  • template_id (str): Die Vorlagenkennung.
• Rückgabe: Löschbestätigung als JSON.

box_docgen_template_get_by_id_tool

Rufen Sie Details einer bestimmten Doc Gen-Vorlage ab.

• Parameter:
  • template_id (str): Die Vorlagenkennung.
• Gibt zurück: Vorlagendetails als JSON.

box_docgen_template_list_tags_tool

Listen Sie alle Tags auf, die mit einer Box Doc Gen-Vorlage verknüpft sind.

• Parameter:
  • template_id (str): Die Vorlagen-ID.
  • template_version_id (str | Keine, optional): Spezifische Versions-ID.
  • marker (str | Keine, optional): Seitennummerierungsmarker.
  • limit (int | Keine, optional): Maximale Anzahl der zurückzugebenden Tags.
• Gibt zurück: Liste der Tags im JSON-Format.

box_docgen_template_list_jobs_tool

Listen Sie alle Doc Gen-Jobs auf, die eine bestimmte Vorlage verwendet haben.

• Parameter:
  • template_id (str): Die Vorlagenkennung.
  • marker (str | Keine, optional): Seitennummerierungsmarker.
  • limit (int | Keine, optional): Maximale Anzahl aufzulistender Jobs.
• Gibt zurück: Jobdetails für die Vorlage als JSON-Zeichenfolge.

Anforderungen

• Python 3.13 oder höher
• Box-API-Anmeldeinformationen (Client-ID, Client-Geheimnis usw.)

Installation

1. Klonen Sie das Repository:
   git clone https://github.com/box-community/mcp-server-box.git cd mcp-server-box
2. Installieren Sie uv , falls es noch nicht installiert ist: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. Erstellen und Einrichten unseres Projekts: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. Erstellen Sie eine .env Datei im Stammverzeichnis und fügen Sie Ihre Box-API-Anmeldeinformationen hinzu:
   BOX_CLIENT_ID=your_client_id BOX_CLIENT_SECRET=your_client_secret

Verwendung

Ausführen des MCP-Servers

Um den MCP-Server zu starten, führen Sie den folgenden Befehl aus:

Claude als Client verwenden

1. Bearbeiten Sie Ihre claude_desktop_config.json :
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
2. Fügen Sie die Konfiguration hinzu:
   { "mcpServers": { "mcp-server-box": { "command": "uv", "args": [ "--directory", "/Users/anovotny/Desktop/mcp-server-box", "run", "src/mcp_server_box.py" ] } } }
3. Starten Sie Claude neu, falls es ausgeführt wird.

Verwenden von Cursor als Client

1. Öffnen Sie Ihre IDE mit Cursor.
2. Wählen Sie in den Einstellungen Cursor settings aus.
3. Wählen Sie in der linken Navigationsleiste MCP aus.
4. Klicken Sie oben links auf Add new global MCP server .
5. Fügen Sie den folgenden JSON-Code ein (aktualisieren Sie ihn für Ihre lokalen Werte):
   { "mcpServers": { "box": { "command": "uv", "args": [ "--directory", "/Users/shurrey/local/mcp-server-box", "run", "src/mcp_server_box.py" ] } } }
6. Speichern und schließen Sie die Datei mcp.json und starten Sie gegebenenfalls neu.

Ausführen von Tests

Das Projekt umfasst eine Reihe von Tests zur Überprüfung der Box-API-Funktionalität. Aktualisieren Sie vor dem Ausführen der Tests die Datei- und Ordner-IDs in den Testdateien, sodass sie mit denen in Ihrem Box-Konto übereinstimmen.

Einrichten von Tests

1. Datei- und Ordner-IDs aktualisieren :
   • Jede Testdatei (im Verzeichnis tests/ “) verwendet fest codierte IDs für Box-Dateien und -Ordner.
   • Ersetzen Sie diese IDs durch gültige IDs aus Ihrem Box-Konto.
2. Datei-ID-Referenzen :
   • Ersetzen Sie beispielsweise in tests/test_box_api_read.py``"1728677291168" durch eine gültige Datei-ID.

Ausführen von Tests

Nachdem Sie die IDs aktualisiert haben, können Sie die Tests mit pytest ausführen:

Verfügbare Test-Suiten

• test_box_auth.py : Testet die Authentifizierungsfunktionalität.
• test_box_api_basic.py : Grundlegende Box-API-Tests.
• test_box_api_read.py : Testet die Dateilesefunktionen.
• test_box_api_search.py : Testet die Suchfunktion.
• test_box_api_ai.py : Testet KI-basierte Funktionen.
• test_box_api_file_ops.py : Testet Datei-Upload- und Download-Vorgänge.
• Zusätzliche Tests decken Ordnervorgänge und Doc Gen-Funktionen ab.

Fehlerbehebung

Wenn Sie beim Ausführen des MCP-Servers mit Claude Desktop unter MacOS die Fehlermeldung Error: spawn uv ENOENT erhalten, können Sie:

• Entfernen Sie uv und installieren Sie es mit Homebrew neu: brew install uv
• Oder geben Sie den vollständigen Pfad zur ausführbaren UV-Datei in Ihrer Konfiguration an:
  /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py

[!NOTE] Stellen Sie sicher, dass Ihre Box-API-Anmeldeinformationen in .env richtig eingestellt sind.