Unstructured MCP Server

Unstructured API MCP 서버

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

사용 가능한 도구

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

커넥터를 생성/업데이트/삭제하는 도구를 사용하려면 해당 커넥터의 자격 증명을 .env 파일에 정의해야 합니다. 다음은 지원하는 커넥터의 credentials 목록입니다:

Firecrawl 소스

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 서버를 설정하고 구성하는 단계별 지침을 제공합니다.

사전 요구 사항

• Python 3.12 이상
• 환경 관리를 위한 uv
• Unstructured의 API 키. 여기에서 가입하고 API 키를 얻을 수 있습니다.

uv 사용 (권장)

uvx 사용 시 실행을 처리하므로 추가 설치가 필요하지 않습니다. 그러나 패키지를 직접 설치하려는 경우:

uv pip install uns_mcp

Claude Desktop 구성

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

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

uvx 명령 사용:

{
   "mcpServers": {
      "UNS_MCP": {
         "command": "uvx",
         "args": ["uns_mcp"],
         "env": {
           "UNSTRUCTURED_API_KEY": "<your-key>"
         }
      }
   }
}

또는 Python 패키지 사용:

{
   "mcpServers": {
      "UNS_MCP": {
         "command": "python",
         "args": ["-m", "uns_mcp"],
         "env": {
           "UNSTRUCTURED_API_KEY": "<your-key>"
         }
      }
   }
}

소스 코드 사용

1. 리포지토리를 복제합니다.

2. 종속성을 설치합니다:

   uv sync
   

3. Unstructured API 키를 환경 변수로 설정합니다. 루트 디렉터리에 다음 내용으로 .env 파일을 생성합니다:

   UNSTRUCTURED_API_KEY="YOUR_KEY"
   

   구성 가능한 환경 변수는 .env.template를 참조하세요.

이제 다음 방법 중 하나로 서버를 실행할 수 있습니다:

uvx pip install -e .

{
  "mcpServers": {
    "UNS_MCP": {
      "command": "uvx",
      "args": ["uns_mcp"]
    }
  }
}

{
  "mcpServers": {
    "UNS_MCP": {
      "command": "ABSOLUTE/PATH/TO/.local/bin/uv",
      "args": [
        "--directory",
        "ABSOLUTE/PATH/TO/YOUR-UNS-MCP-REPO/uns_mcp",
        "run",
        "server.py"
      ]
    }
  }
}

uv run python minimal_client/client.py uns_mcp/server.py

추가 로컬 클라이언트 구성

환경 변수를 사용하여 최소 클라이언트 구성:

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

디버깅 도구

Anthropic은 MCP 서버를 디버그/테스트하기 위한 MCP Inspector 도구를 제공합니다. 다음 명령을 실행하여 디버깅 UI를 시작하세요. 여기에서 왼쪽 창에 환경 변수(로컬 환경을 가리킴)를 추가할 수 있습니다. 개인 API 키를 환경 변수로 포함하세요. tools로 이동하여 MCP 서버에 추가한 기능을 테스트할 수 있습니다.

mcp dev uns_mcp/server.py

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

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

@wonderwhy-er/desktop-commander를 사용하여 최소 클라이언트에 터미널 액세스를 추가할 것입니다. 이는 MCP 파일 시스템 서버를 기반으로 구축되었습니다. 이제 클라이언트(및 LLM)가 비공개 파일에 액세스할 수 있으므로 주의하세요.

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

npx @wonderwhy-er/desktop-commander setup

그런 다음 추가 매개변수로 클라이언트를 시작하세요:

uv run python minimal_client/client.py "http://127.0.0.1:8080/sse" "@wonderwhy-er/desktop-commander@^0.2.11"
# or
make sse-client-terminal

도구의 하위 집합 사용

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

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

알려진 문제

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

CHANGELOG.md

새로 개발된 기능/수정 사항/개선 사항은 CHANGELOG.md에 추가됩니다. 안정 버전으로 올리기 전에 0.x.x-dev 사전 릴리스 형식이 선호됩니다.

문제 해결

• Error: spawn <command> ENOENT 관련 문제가 발생하면 <command>이 설치되지 않았거나 PATH에 표시되지 않는 것을 의미합니다:
  • 설치하고 PATH에 추가했는지 확인하세요.
  • 또는 구성의 command 필드에 명령의 절대 경로를 제공하세요. 예를 들어 python을 /opt/miniconda3/bin/python로 바꾸세요.