Unstructured API MCP Server

비정형 API MCP 서버

비정형 API와 상호 작용하기 위한 MCP 서버 구현입니다. 이 서버는 소스와 워크플로를 나열하는 도구를 제공합니다.

사용 가능한 도구

아래는 UNS-MCP 서버가 현재 지원하는 커넥터 목록입니다. Unstructured 플랫폼에서 지원하는 소스 커넥터의 전체 목록은 여기에서 , 대상 커넥터 목록은 여기에서 확인하세요. 더 많은 커넥터를 추가할 계획입니다!

커넥터를 생성/업데이트/삭제하는 도구를 사용하려면 해당 커넥터의 사용자 인증 정보를 .env 파일에 정의해야 합니다. 아래는 지원되는 커넥터의 credentials 목록입니다.

파이어크롤 소스

Firecrawl 은 MCP에서 두 가지 주요 기능을 제공하는 웹 크롤링 API입니다.

1. HTML 콘텐츠 검색 : invoke_firecrawl_crawlhtml 사용하여 크롤링 작업을 시작하고 check_crawlhtml_status 사용하여 모니터링합니다.
2. LLM 최적화된 텍스트 생성 : invoke_firecrawl_llmtxt 사용하여 텍스트를 생성하고 check_llmtxt_status 사용하여 결과를 검색합니다.

Firecrawl 작동 방식:

웹 크롤링 프로세스:

• 지정된 URL로 시작하여 이를 분석하여 링크를 식별합니다.
• 사이트맵이 있으면 사용하고, 그렇지 않으면 웹사이트에서 찾은 링크를 따릅니다.
• 각 링크를 재귀적으로 탐색하여 모든 하위 페이지를 발견합니다.
• 방문한 모든 페이지에서 콘텐츠를 수집하고 JavaScript 렌더링 및 속도 제한을 처리합니다.
• 필요한 경우 cancel_crawlhtml_job 사용하여 작업을 취소할 수 있습니다.
• 모든 정보를 원시 HTML로 추출해야 하는 경우 이것을 사용하세요. Unstructured의 워크플로가 이를 정말 잘 정리해 줍니다. :smile:

LLM 텍스트 생성:

• 크롤링 후 크롤링된 페이지에서 깔끔하고 의미 있는 텍스트 콘텐츠를 추출합니다.
• 대규모 언어 모델에 맞게 특별히 포맷된 최적화된 텍스트 형식을 생성합니다.
• 결과는 지정된 S3 위치에 자동으로 업로드됩니다.
• 참고: LLM 텍스트 생성 작업은 시작된 후에는 취소할 수 없습니다. cancel_llmtxt_job 함수는 일관성을 위해 제공되지만, 현재 Firecrawl API에서는 지원되지 않습니다.

참고: 이러한 기능을 사용하려면 FIRECRAWL_API_KEY 환경 변수를 설정해야 합니다.

설치 및 구성

이 가이드에서는 Python 3.12와 uv 도구를 사용하여 UNS_MCP 서버를 설정하고 구성하는 단계별 지침을 제공합니다.

필수 조건

• 파이썬 3.12+
• 환경 관리를 위한 uv
• Unstructured의 API 키입니다. 여기에서 가입하고 API 키를 받으실 수 있습니다.

uv 사용 (추천)

uvx 사용하면 실행을 처리하므로 추가 설치가 필요하지 않습니다. 하지만 패키지를 직접 설치하려면 다음을 수행하세요.

지엑스피1

Claude Desktop 구성

Claude Desktop과 통합하려면 claude_desktop_config.json 에 다음 내용을 추가하세요.

참고: 해당 파일은 ~/Library/Application Support/Claude/ 디렉토리에 있습니다.

uvx 명령 사용:

또는 Python 패키지를 사용합니다.

소스 코드 사용

1. 저장소를 복제합니다.
2. 종속성 설치:
   uv sync
3. 비정형 API 키를 환경 변수로 설정하세요. 루트 디렉터리에 다음 내용으로 .env 파일을 생성하세요.
   UNSTRUCTURED_API_KEY="YOUR_KEY"
   구성 가능한 환경 변수는 .env.template 참조하세요.

이제 다음 방법 중 하나를 사용하여 서버를 실행할 수 있습니다.

Claude Desktop 구성을 업데이트하세요.

참고 : 패키지를 설치한 환경에서 uvx 실행 파일을 가리키도록 하세요.

참고: Claude Desktop에서는 지원되지 않습니다.

SSE 프로토콜의 경우 클라이언트와 서버를 분리하면 더 쉽게 디버깅할 수 있습니다.

1. 한 터미널에서 서버를 시작합니다.
   uv run python uns_mcp/server.py --host 127.0.0.1 --port 8080 # or make sse-server
2. 다른 터미널에서 로컬 클라이언트를 사용하여 서버를 테스트하세요.
   uv run python minimal_client/client.py "http://127.0.0.1:8080/sse" # or make sse-client

참고: 서비스를 중지하려면 먼저 클라이언트에서 Ctrl+C 사용한 다음 서버에서 Ctrl+C를 사용하세요.

Claude Desktop을 stdio를 사용하도록 구성합니다.

또는 로컬 클라이언트를 실행합니다.

추가 로컬 클라이언트 구성

환경 변수를 사용하여 최소 클라이언트를 구성합니다.

• LOG_LEVEL="ERROR" : LLM에서 디버그 출력을 억제하고 사용자에게 명확한 메시지를 표시합니다.
• CONFIRM_TOOL_USE='false' : 실행 전 도구 사용 확인을 비활성화합니다. 특히 개발 중에는 LLM이 비용이 많이 드는 워크플로를 실행하거나 데이터를 삭제할 수 있으므로 주의해서 사용해야 합니다 .

디버깅 도구

Anthropic은 MCP 서버를 디버깅/테스트할 수 있는 MCP Inspector 도구를 제공합니다. 다음 명령을 실행하여 디버깅 UI를 실행하세요. 그러면 왼쪽 창에 로컬 환경을 가리키는 환경 변수를 추가할 수 있습니다. 개인 API 키를 환경 변수로 입력하세요. tools 에서 MCP 서버에 추가한 기능을 테스트해 보세요.

UnstructuredClient 에 요청 호출 매개변수를 로깅해야 하는 경우, 환경 변수 DEBUG_API_REQUESTS=false 설정하세요. 로그는 unstructured-client-{date}.log 형식의 파일에 저장되며, 이 파일을 검토하여 UnstructuredClient 함수에 대한 요청 호출 매개변수를 디버깅할 수 있습니다.

최소 클라이언트에 터미널 액세스 추가

@wonderwhy-er/desktop-commander를 사용하여 최소 클라이언트에 터미널 접근 권한을 추가하겠습니다. 이 클라이언트는 MCP 파일 시스템 서버를 기반으로 합니다. 클라이언트(LLM 포함)가 이제 개인 파일에 접근할 수 있으므로 주의하십시오.

다음 명령을 실행하여 패키지를 설치하세요.

그런 다음 추가 매개변수로 클라이언트를 시작합니다.

도구 하위 집합 사용

클라이언트가 다음 도구의 하위 집합만 사용하는 것을 지원하는 경우 알아야 할 사항은 다음과 같습니다.

• update_workflow 도구는 사용자 정의 노드를 만들고 구성하는 방법에 대한 자세한 설명을 포함하고 있으므로 create_workflow 도구와 함께 컨텍스트에 로드해야 합니다.

알려진 문제

• update_workflow - 사용자가 제공하거나 get_workflow_info 도구를 호출하여 업데이트하려는 워크플로 구성을 컨텍스트에 포함해야 합니다. 이 도구는 patch 적용 도구로 작동하지 않고 워크플로 구성을 완전히 대체합니다.

변경 로그.md

새로 개발된 기능/수정/향상 사항은 CHANGELOG.md에 추가됩니다. 안정적인 버전으로 전환하기 전에는 0.xx-dev 사전 릴리스 형식을 사용하는 것이 좋습니다.

문제 해결

• Error: spawn <command> ENOENT 문제가 발생하는 경우 <command> 가 설치되지 않았거나 PATH에 표시되지 않는다는 의미입니다.
  • 꼭 설치하고 PATH에 추가하세요.
  • 또는 설정의 command 필드에 명령의 절대 경로를 입력하세요. 예를 들어 python``/opt/miniconda3/bin/python 으로 바꾸세요.