MCP Server Box

MCP 서버 박스

설명

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

모델 컨텍스트 프로토콜(MCP)은 모델이 다양한 데이터 소스 및 서비스와 상호 작용하는 방식을 표준화하도록 설계된 프레임워크입니다. 이 프로젝트에서는 MCP를 사용하여 Box API와의 원활한 통합을 촉진하고, Box 파일 및 폴더에 대한 효율적이고 확장 가능한 작업을 지원합니다. MCP 서버 Box 프로젝트는 고급 AI 및 머신러닝 기술을 사용하여 Box 데이터를 관리하고 처리하는 강력하고 유연한 솔루션을 제공하는 것을 목표로 합니다.

구현된 도구

Box API 도구

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 목록입니다.
• 반환: 검색 결과는 파일 이름과 ID를 줄바꿈으로 구분한 목록으로 표시됩니다.

box_read_tool

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

매개변수:

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

반환: 파일 내용

box_ask_ai_tool

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

매개변수:

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

반환: AI 응답

box_hubs_ask_ai_tool

Box AI에 허브에 대해 문의해 보세요. 현재 API를 통해 허브 ID를 확인할 수 있는 방법이 없으므로, 이 도구를 사용하려면 ID를 알아야 합니다. 이 문제는 향후 수정될 예정입니다.

매개변수:

• hubs_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

=======

• 매개변수:
  • file_id (str): 읽을 파일의 ID입니다.
• 반환값: 파일의 텍스트 내용.

box_ask_ai_tool

단일 파일에 대한 Query Box AI입니다.

• 매개변수:
  • file_id (str): 파일 식별자.
  • prompt (str): AI에 대한 쿼리 또는 지시.
• 반환: 파일 내용을 기반으로 한 AI 응답입니다.

box_ask_ai_tool_multi_file

여러 파일을 사용하여 Box AI 쿼리하기.

• 매개변수:
  • file_ids (List[str]): 파일 ID 목록입니다.
  • prompt (str): 집계된 콘텐츠를 기반으로 한 AI에 대한 지침입니다.
• 반환: 제공된 모든 파일을 고려하여 AI가 생성한 답변입니다.

box_search_folder_by_name

Box에서 폴더 이름을 찾아 보세요.

• 매개변수:
  • folder_name (str): 폴더의 이름.
• 반환: 일치하는 폴더에 대한 정보(이름 및 ID)

box_ai_extract_data

AI를 사용하여 파일에서 특정 필드를 추출합니다.

• 매개변수:
  • file_id (str): 파일의 ID입니다.
  • fields (str): 추출할 필드의 쉼표로 구분된 목록입니다.
• 반환: JSON 문자열 형식으로 추출된 데이터입니다.

box_list_folder_content_by_folder_id

폴더의 ID를 사용하여 폴더의 내용을 나열합니다.

• 매개변수:
  • folder_id (str): 폴더 ID.
  • is_recursive (bool, 선택 사항): 콘텐츠를 재귀적으로 나열할지 여부입니다.
• 반환: ID, 이름, 유형, 설명을 포함한 JSON 문자열 형태의 폴더 내용입니다.

box_manage_folder_tool

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

• 매개변수:
  • action (str): 수행할 작업: "생성", "삭제" 또는 "업데이트".
  • folder_id (str, 선택 사항): 폴더 ID(삭제 및 업데이트에 필요).
  • name (str, 선택 사항): 폴더 이름(생성 시 필수, 업데이트 시 선택 사항).
  • parent_id (str, 선택 사항): 상위 폴더 ID(루트의 경우 기본값은 "0")
  • description (str, 선택 사항): 폴더에 대한 설명(업데이트용).
  • recursive (bool, 선택 사항): 재귀적 삭제를 위해.
• 반환: 폴더 세부 정보가 포함된 상태 메시지입니다.

box_upload_file_from_path_tool

로컬 파일 시스템 경로에서 Box에 파일을 업로드합니다.

• 매개변수:
  • file_path (str): 로컬 파일 경로.
  • folder_id (str, 선택 사항): 대상 폴더 ID(기본값은 "0")
  • new_file_name (str, 선택 사항): 새 파일 이름(제공되지 않으면 원래 파일 이름을 사용함).
• 반환: 업로드된 파일에 대한 세부정보(ID 및 이름) 또는 오류 메시지.

box_upload_file_from_content_tool

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

• 매개변수:
  • content (str | bytes): 업로드할 콘텐츠(텍스트 또는 바이너리).
  • file_name (str): 파일에 지정할 이름입니다.
  • folder_id (str, 선택 사항): 대상 폴더 ID(기본값은 "0")
  • is_base64 (bool, 선택 사항): 제공된 콘텐츠가 base64로 인코딩되었는지 여부를 나타냅니다.
• 반환: 파일 ID와 이름이 포함된 업로드 성공 메시지.

box_download_file_tool

Box에서 파일을 다운로드합니다.

• 매개변수:
  • file_id (str): 다운로드할 파일의 ID입니다.
  • save_file (bool, 선택 사항): 파일을 로컬에 저장할지 여부입니다.
  • save_path (문자열, 선택 사항): 파일을 저장할 로컬 경로입니다.
• 반환: 텍스트 파일의 경우 콘텐츠를 반환하고, 이미지의 경우 base64로 인코딩된 데이터를 반환하고, 다른 유형의 경우 오류 또는 저장 확인 메시지를 반환합니다.

Box Doc Gen 도구

box_docgen_create_batch_tool

Box Doc Gen 템플릿과 로컬 JSON 파일을 사용하여 문서를 생성합니다.

• 매개변수:
  • file_id (str): 템플릿 파일 ID.
  • destination_folder_id (str): 생성된 문서를 저장할 폴더 ID입니다.
  • user_input_file_path (str): 입력 데이터가 포함된 JSON 파일의 경로입니다.
  • output_type (str, 선택 사항): 출력 형식(기본값은 "pdf")입니다.
• 반환값: JSON 문자열 형태의 문서 생성 배치 결과입니다.

box_docgen_get_job_tool

ID로 단일 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): 템플릿으로 표시할 파일 ID입니다.
• 반환: 채점 후 템플릿 세부 정보.

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): 템플릿 ID입니다.
  • template_version_id (str | None, 선택 사항): 특정 버전 ID입니다.
  • 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 이상
• 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.2 윈도우
   # 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 편집하세요:
   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 파일을 저장하고 닫은 다음, 필요한 경우 다시 시작합니다.

테스트 실행

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

테스트 설정

1. 파일 및 폴더 ID 업데이트 :
   • 각 테스트 파일( tests/ 디렉토리에 있음)은 Box 파일과 폴더에 대한 하드코딩된 ID를 사용합니다.
   • 이 ID를 Box 계정의 유효한 ID로 바꾸세요.
2. 파일 ID 참조 :
   • 예를 들어 tests/test_box_api_read.py 에서 "1728677291168" 유효한 파일 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 : 파일 업로드 및 다운로드 작업을 테스트합니다.
• 추가 테스트에는 폴더 작업과 Doc Gen 기능에 대한 내용이 포함됩니다.

문제 해결

MacOS에서 Claude Desktop으로 MCP 서버를 실행할 때 Error: spawn uv ENOENT 오류가 발생하면 다음을 수행할 수 있습니다.

• uv를 제거하고 Homebrew로 다시 설치하세요: brew install uv
• 또는 구성에서 uv 실행 파일의 전체 경로를 제공하세요.
  /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py

[!NOTE] .env 에 있는 Box API 자격 증명이 올바르게 설정되었는지 확인하세요.