MCP 서버 박스

설명

MCP Server Box는 Box API와 통합되어 파일 검색, 텍스트 추출, AI 기반 쿼리, 데이터 추출 등 다양한 작업을 수행하는 Python 프로젝트입니다. box-sdk-gen 라이브러리를 활용하며 Box 파일 및 폴더와 상호 작용할 수 있는 도구 세트를 제공합니다.

모델 컨텍스트 프로토콜(MCP)은 모델이 다양한 데이터 소스 및 서비스와 상호 작용하는 방식을 표준화하도록 설계된 프레임워크입니다. 이 프로젝트에서는 MCP를 사용하여 Box API와의 원활한 통합을 촉진하고, Box 파일 및 폴더에 대한 효율적이고 확장 가능한 작업을 지원합니다. MCP 서버 Box 프로젝트는 고급 AI 및 머신러닝 기술을 사용하여 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 (List[str], 선택 사항): 검색할 위치(이름, 설명, 파일 내용, 주석, 태그)
• ancestor_folder_ids (List[str], 선택 사항): 검색할 폴더 ID

반환: 검색 결과

box_read_tool

Box 파일의 텍스트 내용을 읽습니다.

매개변수:

• file_id (str): 읽을 파일의 ID

반환: 파일 내용

box_ask_ai_tool

Box AI에 파일에 대해 문의하세요.

매개변수:

• file_id (str): 파일의 ID
• prompt (str): AI에 대한 질문

반환: AI 응답

box_search_folder_by_name

이름으로 폴더를 찾으세요.

매개변수:

• folder_name (str): 폴더 이름

반환: 폴더 ID

box_ai_extract_data

AI를 사용하여 파일에서 데이터를 추출합니다.

매개변수:

• file_id (str): 파일의 ID
• fields (str): 추출할 필드

반환: JSON 형식으로 추출된 데이터

box_list_folder_content_by_folder_id

폴더 내용을 나열합니다.

매개변수:

• folder_id (str): 폴더의 ID
• is_recursive (bool): 재귀적으로 나열할지 여부

반환: ID, 이름, 유형 및 설명이 포함된 JSON 형식의 폴더 콘텐츠

box_manage_folder_tool

Box에서 폴더를 만들고, 업데이트하고, 삭제합니다.

매개변수:

• action (str): 수행할 작업: "create", "delete" 또는 "update"
• folder_id (str, 선택 사항): 폴더의 ID(삭제/업데이트에 필요)
• name (str, 선택 사항): 폴더 이름(생성 시 필수, 업데이트 시 선택 사항)
• parent_id (str, 선택 사항): 상위 폴더 ID(생성 시 필수, 업데이트 시 선택 사항)
• description (str, 선택 사항): 폴더 설명(업데이트 시 선택 사항)
• recursive (bool, 선택 사항): 재귀적으로 삭제할지 여부(delete의 경우 선택 사항)

반환: 폴더 세부 정보가 포함된 상태 메시지

box_upload_file_tool

컨텐츠를 파일로 Box에 업로드합니다.

매개변수:

• content (str): 파일로 업로드할 콘텐츠
• file_name (str): Box에 지정할 파일 이름
• folder_id (선택 사항): 업로드할 폴더의 ID

반환: 파일 ID 및 이름이 포함된 업로드 상태

box_download_file_tool

Box에서 파일을 다운로드하고 내용을 반환합니다.

매개변수:

• file_id (Any): 다운로드할 파일의 ID
• save_file (bool, 선택 사항): 파일을 로컬에 저장할지 여부
• save_path (str, 선택 사항): 파일을 저장할 경로

반환: 텍스트, base64로 인코딩된 이미지 또는 저장 상태 메시지 형태의 파일 콘텐츠

요구 사항

• Python 3.13 이상
• Box API 자격 증명(클라이언트 ID, 클라이언트 비밀번호 등)

설치

1. 저장소를 복제합니다.지엑스피1
2. 아직 설치되지 않았다면 uv 설치하세요:2.1 맥OS+리눅스
   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 맥OS+리눅스
   # Create virtual environment and activate it uv venv source .venv/bin/activate # Lock the dependencies uv lock
   3.1 윈도우
   # Create virtual environment and activate it uv venv .venv\Scripts\activate # Lock the dependencies uv lock
4. 루트 디렉토리에 .env 파일을 만들고 Box API 자격 증명을 추가합니다.
   BOX_CLIENT_ID=your_client_id BOX_CLIENT_SECRET=your_client_secret

용법

MCP 서버 실행

MCP 서버를 시작하려면 다음 명령을 실행하세요.

Claude를 클라이언트로 사용

1. claude_desktop_config .json을 편집하세요

2. 그리고 다음을 추가합니다.

[!NOTE] MacOS를 사용하는 경우 brew를 사용하여 uv를 설치해야 합니다: brew install uv 또는 uv 실행 파일의 전체 경로를 제공하세요: /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/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을 지나서 로컬 값에 맞게 업데이트하세요.

6. mcp.json 파일을 저장하고 닫은 후 MCP 서버가 활성화되어 있는지 확인하세요. 다시 시작해야 할 수도 있습니다.

테스트 실행

이 프로젝트에는 Box API 기능을 검증하는 테스트가 포함되어 있습니다. 테스트를 실행하기 전에 테스트 파일의 파일 및 폴더 ID를 Box 계정의 파일과 일치하도록 업데이트해야 합니다.

테스트 설정

1. 파일 및 폴더 ID 업데이트 :
   • 각 테스트 파일( tests/ 디렉토리)에는 Box 파일 및 폴더에 대한 하드코딩된 ID가 포함되어 있습니다.
   • 이러한 ID를 Box 계정의 파일 및 폴더 ID로 바꿔야 합니다.
   • 예: test_box_api_read.py 에서 "1728677291168" Box 계정의 파일 ID로 바꾸세요.
2. 테스트 파일 ID 참조 :
   • test_box_api_read.py : 유효한 문서 파일 ID가 필요합니다(예: Word 문서)
   • test_box_api_search.py : 콘텐츠와 일치하도록 검색 쿼리와 파일 확장자를 업데이트합니다.
   • test_box_api_ai.py : AI 추출 기능 테스트를 위한 파일 ID가 필요합니다.
   • 다른 테스트 파일에는 특정 폴더 ID 또는 파일 유형이 필요할 수 있습니다.

테스트 실행

파일 ID를 업데이트하면 pytest를 사용하여 테스트를 실행할 수 있습니다.

사용 가능한 테스트

• test_box_auth.py : 인증 기능 테스트
• test_box_api_basic.py : 기본 Box API 테스트
• test_box_api_read.py : 파일 읽기 기능 테스트
• test_box_api_search.py : 검색 기능 테스트
• test_box_api_ai.py : AI 기반 기능 테스트
• test_box_api_file_ops.py : 파일 업로드 및 다운로드 작업을 테스트합니다.

새로운 테스트 만들기

새로운 테스트를 생성할 때:

1. 기존 테스트 파일의 패턴을 따르세요
2. 인증된 API 액세스를 위해 box_client 픽스처를 사용하세요
3. 테스트 중에 생성된 모든 테스트 파일이나 폴더를 정리하세요.
4. 기능을 확인하기 위해 적절한 어설션을 추가합니다.

문제 해결

MacOS를 사용하고 Claude Desktop으로 MCP 서버를 실행하면 다음 오류가 표시됩니다.

Error: spawn uv ENOENT

uv를 제거한 후 brew를 사용하여 다시 설치할 수 있습니다: brew install uv 또는 uv 실행 파일의 전체 경로를 제공합니다: /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py