Unstructured

Máy chủ MCP API Unstructured

[!NOTE] Máy chủ này tương tác với API Unstructured để quản lý nguồn, đích và quy trình làm việc. Nó không được bảo trì tích cực và được giữ ở đây để tham khảo.

Nếu bạn muốn phân tích và chuyển đổi tệp thành đầu ra có cấu trúc (markdown, JSON, HTML hoặc văn bản thuần túy), hãy sử dụng máy chủ Unstructured Transform MCP thay thế.

Unstructured Transform mang đến khả năng xử lý tài liệu cấp sản xuất cho các tác nhân của bạn dưới dạng máy chủ MCP được lưu trữ. Nó cho phép chúng chuyển đổi hơn 60 loại tệp thành dữ liệu có cấu trúc sẵn sàng cho ứng dụng, cơ sở dữ liệu vector và bất kỳ quy trình hạ nguồn nào bằng cách phân tích, làm giàu, phân đoạn và nhúng tệp trực tiếp trong phiên làm việc hiện tại của chúng.

Bạn có thể bắt đầu sử dụng nó bằng cách đăng ký tại đây.

Một triển khai máy chủ MCP để tương tác với API Unstructured. Máy chủ này cung cấp các công cụ để liệt kê nguồn và quy trình làm việc.

Công cụ khả dụng

Dưới đây là danh sách các trình kết nối mà máy chủ UNS-MCP hiện hỗ trợ, vui lòng xem danh sách đầy đủ các trình kết nối nguồn mà nền tảng Unstructured hỗ trợ tại đây và danh sách đích tại đây. Chúng tôi đang có kế hoạch bổ sung thêm!

Để sử dụng công cụ tạo/cập nhật/xóa một trình kết nối, thông tin xác thực cho trình kết nối cụ thể đó phải được định nghĩa trong tệp .env của bạn. Dưới đây là danh sách credentials cho các trình kết nối chúng tôi hỗ trợ:

Nguồn Firecrawl

Firecrawl là một API thu thập dữ liệu web cung cấp hai khả năng chính trong MCP của chúng tôi:

1. Truy xuất nội dung HTML: Sử dụng invoke_firecrawl_crawlhtml để bắt đầu các công việc thu thập và check_crawlhtml_status để giám sát chúng
2. Tạo văn bản tối ưu hóa cho LLM: Sử dụng invoke_firecrawl_llmtxt để tạo văn bản và check_llmtxt_status để truy xuất kết quả

Cách Firecrawl hoạt động: Quy trình Thu thập Dữ liệu Web:

• Bắt đầu với một URL được chỉ định và phân tích nó để xác định các liên kết
• Sử dụng sơ đồ trang web nếu có; nếu không, theo các liên kết tìm thấy trên trang web
• Duyệt đệ quy từng liên kết để khám phá tất cả các trang con
• Thu thập nội dung từ mọi trang đã truy cập, xử lý kết xuất JavaScript và giới hạn tốc độ
• Các công việc có thể bị hủy bằng cancel_crawlhtml_job nếu cần
• Sử dụng tính năng này nếu bạn cần tất cả thông tin được trích xuất thành HTML thô, quy trình làm việc của Unstructured sẽ làm sạch nó rất tốt :smile:

Tạo Văn bản LLM:

• Sau khi thu thập, trích xuất nội dung văn bản sạch, có ý nghĩa từ các trang đã thu thập
• Tạo ra các định dạng văn bản tối ưu được định dạng đặc biệt cho các mô hình ngôn ngữ lớn
• Kết quả được tự động tải lên vị trí S3 được chỉ định
• Lưu ý: Các công việc tạo văn bản LLM không thể bị hủy sau khi bắt đầu. Hàm cancel_llmtxt_job được cung cấp để nhất quán nhưng hiện không được API Firecrawl hỗ trợ.

Lưu ý: Phải đặt biến môi trường FIRECRAWL_API_KEY để sử dụng các hàm này.

Cài đặt & Cấu hình

Hướng dẫn này cung cấp các bước chi tiết để thiết lập và cấu hình máy chủ UNS_MCP sử dụng Python 3.12 và công cụ uv.

Điều kiện tiên quyết

• Python 3.12+
• uv để quản lý môi trường
• Một khóa API từ Unstructured. Bạn có thể đăng ký và lấy khóa API của mình tại đây.

Sử dụng uv (Khuyến nghị)

Không cần cài đặt thêm khi sử dụng uvx vì nó xử lý việc thực thi. Tuy nhiên, nếu bạn muốn cài đặt gói trực tiếp:

uv pip install uns_mcp

Cấu hình Claude Desktop

Để tích hợp với Claude Desktop, thêm nội dung sau vào claude_desktop_config.json của bạn:

Lưu ý: Tệp nằm trong thư mục ~/Library/Application Support/Claude/.

Sử dụng Lệnh uvx:

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

Hoặc, Sử dụng Gói Python:

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

Sử dụng Mã nguồn

1. Sao chép kho lưu trữ.

2. Cài đặt các phụ thuộc:

   uv sync
   

3. Đặt khóa API Unstructured của bạn làm biến môi trường. Tạo tệp .env trong thư mục gốc với nội dung sau:

   UNSTRUCTURED_API_KEY="YOUR_KEY"
   

   Tham khảo .env.template để biết các biến môi trường có thể cấu hình.

Bây giờ bạn có thể chạy máy chủ bằng một trong các phương pháp sau:

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

Cấu hình Máy khách Cục bộ Bổ sung

Cấu hình máy khách tối thiểu bằng các biến môi trường:

• LOG_LEVEL="ERROR": Đặt để chặn đầu ra gỡ lỗi từ LLM, hiển thị thông báo rõ ràng cho người dùng.
• CONFIRM_TOOL_USE='false': Vô hiệu hóa xác nhận sử dụng công cụ trước khi thực thi. Sử dụng thận trọng, đặc biệt trong quá trình phát triển, vì LLM có thể thực thi các quy trình làm việc tốn kém hoặc xóa dữ liệu.

Công cụ gỡ lỗi

Anthropic cung cấp công cụ MCP Inspector để gỡ lỗi/kiểm tra máy chủ MCP của bạn. Chạy lệnh sau để khởi động giao diện người dùng gỡ lỗi. Từ đó, bạn có thể thêm các biến môi trường (trỏ đến môi trường cục bộ của bạn) trên ngăn bên trái. Bao gồm khóa API cá nhân của bạn ở đó dưới dạng biến môi trường. Đi tới tools, bạn có thể kiểm tra các khả năng bạn thêm vào máy chủ MCP.

mcp dev uns_mcp/server.py

Nếu bạn cần ghi nhật ký các tham số gọi yêu cầu đến UnstructuredClient, hãy đặt biến môi trường DEBUG_API_REQUESTS=false. Các nhật ký được lưu trữ trong một tệp có định dạng unstructured-client-{date}.log, có thể được kiểm tra để gỡ lỗi các tham số gọi yêu cầu đến các hàm UnstructuredClient.

Thêm quyền truy cập terminal vào máy khách tối thiểu

Chúng ta sẽ sử dụng @wonderwhy-er/desktop-commander để thêm quyền truy cập terminal vào máy khách tối thiểu. Nó được xây dựng trên MCP Filesystem Server. Hãy cẩn thận, vì máy khách (cũng như LLM) giờ đây có quyền truy cập vào các tệp riêng tư.

Thực thi lệnh sau để cài đặt gói:

npx @wonderwhy-er/desktop-commander setup

Sau đó khởi động máy khách với tham số bổ sung:

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

Sử dụng tập hợp con các công cụ

Nếu máy khách của bạn hỗ trợ chỉ sử dụng tập hợp con các công cụ, đây là danh sách những điều bạn nên biết:

• Công cụ update_workflow phải được tải trong ngữ cảnh cùng với công cụ create_workflow, vì nó chứa mô tả chi tiết về cách tạo và cấu hình nút tùy chỉnh.

Các vấn đề đã biết

• update_workflow - cần có trong ngữ cảnh cấu hình của quy trình làm việc mà nó đang cập nhật, bằng cách được cung cấp bởi người dùng hoặc bằng cách gọi công cụ get_workflow_info, vì công cụ này không hoạt động như bộ áp dụng patch, nó thay thế hoàn toàn cấu hình quy trình làm việc.

CHANGELOG.md

Bất kỳ tính năng/sửa lỗi/cải tiến mới được phát triển nào sẽ được thêm vào CHANGELOG.md. Định dạng tiền phát hành 0.x.x-dev được ưu tiên trước khi chúng tôi nâng lên phiên bản ổn định.

Khắc phục sự cố

• Nếu bạn gặp sự cố với Error: spawn <command> ENOENT, điều đó có nghĩa là <command> chưa được cài đặt hoặc không hiển thị trong PATH của bạn:
  • Đảm bảo cài đặt nó và thêm nó vào PATH của bạn.
  • hoặc cung cấp đường dẫn tuyệt đối đến lệnh trong trường command của cấu hình của bạn. Vì vậy, ví dụ thay thế python bằng /opt/miniconda3/bin/python