Unstructured MCP Server

Unstructured API MCP-сервер

Реализация MCP-сервера для взаимодействия с Unstructured API. Этот сервер предоставляет инструменты для получения списка источников и рабочих процессов.

Доступные инструменты

Ниже приведён список коннекторов, которые в настоящее время поддерживает сервер UNS-MCP. Полный список коннекторов источников, поддерживаемых платформой Unstructured, смотрите здесь, а список назначений — здесь. Мы планируем добавить ещё больше!

Чтобы использовать инструмент, который создаёт/обновляет/удаляет коннектор, учётные данные для этого конкретного коннектора должны быть определены в вашем файле .env. Ниже приведён список credentials для поддерживаемых нами коннекторов:

Источник Firecrawl

Firecrawl — это API для веб-краулинга, который предоставляет две основные возможности в нашем MCP:

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 предоставлена для единообразия, но в настоящее время не поддерживается API Firecrawl.

Примечание: для использования этих функций необходимо установить переменную окружения FIRECRAWL_API_KEY.

Установка и настройка

Это руководство содержит пошаговые инструкции по установке и настройке сервера UNS_MCP с использованием Python 3.12 и инструмента uv.

Предварительные требования

• Python 3.12+
• uv для управления окружением
• API-ключ от Unstructured. Вы можете зарегистрироваться и получить свой 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. Установите ваш API-ключ Unstructured в качестве переменной окружения. Создайте файл .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 Inspector для отладки/тестирования вашего MCP-сервера. Выполните следующую команду, чтобы запустить отладочный интерфейс. Оттуда вы сможете добавить переменные окружения (указывающие на ваше локальное окружение) на левой панели. Укажите там ваш личный API-ключ как переменную окружения. Перейдите в tools, чтобы протестировать возможности, которые вы добавляете на MCP-сервер.

mcp dev uns_mcp/server.py

Если вам нужно регистрировать параметры вызовов запросов к UnstructuredClient, установите переменную окружения DEBUG_API_REQUESTS=false. Логи сохраняются в файл с форматом unstructured-client-{date}.log, который можно изучить для отладки параметров вызовов запросов к функциям UnstructuredClient.

Добавление доступа к терминалу для минимального клиента

Мы собираемся использовать @wonderwhy-er/desktop-commander, чтобы добавить доступ к терминалу для минимального клиента. Он построен на базе MCP Filesystem Server. Будьте осторожны, так как клиент (а также 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 - необходимо иметь в контексте конфигурацию рабочего процесса, который он обновляет, либо предоставив ее пользователем, либо вызвав инструмент get_workflow_info, так как этот инструмент не работает как аппликатор patch, он полностью заменяет конфигурацию рабочего процесса.

CHANGELOG.md

Любые новые разработанные функции/исправления/улучшения будут добавляться в CHANGELOG.md. Предпочтителен формат предварительного выпуска 0.x.x-dev до перехода к стабильной версии.

Устранение неполадок

• Если у вас возникли проблемы с Error: spawn <command> ENOENT, это означает, что <command> не установлен или не виден в вашем PATH:
  • Убедитесь, что он установлен и добавлен в ваш PATH.
  • или укажите абсолютный путь к команде в поле command вашей конфигурации. Так, например, замените python на /opt/miniconda3/bin/python