Unstructured

Servidor MCP da API Unstructured

[!NOTE] Este servidor interage com a API Unstructured para gerenciar fontes, destinos e fluxos de trabalho. Ele não é mantido ativamente e está aqui apenas para referência.

Se você quiser analisar e transformar arquivos em saída estruturada (markdown, JSON, HTML ou texto simples), use o servidor MCP Unstructured Transform.

O Unstructured Transform leva processamento de documentos de nível de produção para seus agentes como um servidor MCP hospedado. Ele dá a eles a capacidade de transformar mais de 60 tipos de arquivo em dados estruturados prontos para suas aplicações, bancos de dados vetoriais e quaisquer processos downstream, analisando, enriquecendo, dividindo em chunks e incorporando arquivos diretamente dentro da sessão atual.

Você pode começar a usá-lo inscrevendo-se aqui.

Uma implementação de servidor MCP para interagir com a API Unstructured. Este servidor fornece ferramentas para listar fontes e fluxos de trabalho.

Ferramentas Disponíveis

Abaixo está uma lista de conectores que o servidor UNS-MCP atualmente suporta. Consulte a lista completa de conectores de fonte que a plataforma Unstructured suporta aqui e a lista de destinos aqui. Estamos planejando adicionar mais!

Para usar a ferramenta que cria/atualiza/exclui um conector, as credenciais para esse conector específico devem ser definidas no seu arquivo .env. Abaixo está a lista de credentials para os conectores que suportamos:

Fonte Firecrawl

Firecrawl é uma API de rastreamento web que fornece duas capacidades principais em nosso MCP:

1. Recuperação de Conteúdo HTML: Usando invoke_firecrawl_crawlhtml para iniciar jobs de rastreamento e check_crawlhtml_status para monitorá-los
2. Geração de Texto Otimizada para LLM: Usando invoke_firecrawl_llmtxt para gerar texto e check_llmtxt_status para recuperar resultados

Como o Firecrawl funciona: Processo de Rastreamento Web:

• Inicia com uma URL especificada e a analisa para identificar links
• Usa o sitemap se disponível; caso contrário, segue os links encontrados no site
• Percorre recursivamente cada link para descobrir todas as subpáginas
• Coleta conteúdo de cada página visitada, lidando com renderização JavaScript e limites de taxa
• Tarefas podem ser canceladas com cancel_crawlhtml_job se necessário
• Use isto se precisar de todas as informações extraídas em HTML bruto, o fluxo de trabalho do Unstructured faz uma limpeza muito boa :smile:

Geração de Texto para LLM:

• Após o rastreamento, extrai conteúdo textual limpo e significativo das páginas rastreadas
• Gera formatos de texto otimizados especificamente para grandes modelos de linguagem
• Os resultados são enviados automaticamente para o local S3 especificado
• Nota: Tarefas de geração de texto para LLM não podem ser canceladas após iniciadas. A função cancel_llmtxt_job é fornecida por consistência, mas atualmente não é suportada pela API Firecrawl.

Nota: Uma variável de ambiente FIRECRAWL_API_KEY deve ser definida para usar essas funções.

Instalação e Configuração

Este guia fornece instruções passo a passo para configurar o servidor UNS_MCP usando Python 3.12 e a ferramenta uv.

Pré-requisitos

• Python 3.12+
• uv para gerenciamento de ambiente
• Uma chave de API do Unstructured. Você pode se cadastrar e obter sua chave de API aqui.

Usando uv (Recomendado)

Nenhuma instalação adicional é necessária ao usar uvx, pois ele gerencia a execução. No entanto, se preferir instalar o pacote diretamente:

uv pip install uns_mcp

Configurar o Claude Desktop

Para integração com o Claude Desktop, adicione o seguinte conteúdo ao seu claude_desktop_config.json:

Nota: O arquivo está localizado no diretório ~/Library/Application Support/Claude/.

Usando o Comando uvx:

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

Alternativamente, Usando o Pacote Python:

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

Usando o Código Fonte

1. Clone o repositório.

2. Instale as dependências:

   uv sync
   

3. Defina sua chave de API do Unstructured como uma variável de ambiente. Crie um arquivo .env no diretório raiz com o seguinte conteúdo:

   UNSTRUCTURED_API_KEY="YOUR_KEY"
   

   Consulte .env.template para as variáveis de ambiente configuráveis.

Agora você pode executar o servidor usando um dos seguintes métodos:

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

Configuração Adicional do Cliente Local

Configure o cliente mínimo usando variáveis de ambiente:

• LOG_LEVEL="ERROR": Defina para suprimir saídas de depuração do LLM, exibindo mensagens claras para os usuários.
• CONFIRM_TOOL_USE='false': Desabilita a confirmação de uso de ferramenta antes da execução. Use com cautela, especialmente durante o desenvolvimento, pois o LLM pode executar fluxos de trabalho caros ou excluir dados.

Ferramentas de depuração

A Anthropic fornece a ferramenta MCP Inspector para depurar/testar seu servidor MCP. Execute o seguinte comando para iniciar uma interface de depuração. A partir dela, você poderá adicionar variáveis de ambiente (apontando para seu ambiente local) no painel esquerdo. Inclua sua chave de API pessoal lá como variável de ambiente. Vá para tools, você pode testar as capacidades que adicionar ao servidor MCP.

mcp dev uns_mcp/server.py

Se precisar registrar parâmetros de chamada de requisição para UnstructuredClient, defina a variável de ambiente DEBUG_API_REQUESTS=false. Os logs são armazenados em um arquivo com o formato unstructured-client-{date}.log, que pode ser examinado para depurar parâmetros de chamada de requisição para funções UnstructuredClient.

Adicionar acesso ao terminal ao cliente mínimo

Vamos usar @wonderwhy-er/desktop-commander para adicionar acesso ao terminal ao cliente mínimo. Ele é construído sobre o Servidor de Sistema de Arquivos MCP. Tenha cuidado, pois o cliente (e também o LLM) agora tem acesso a arquivos privados.

Execute o seguinte comando para instalar o pacote:

npx @wonderwhy-er/desktop-commander setup

Em seguida, inicie o cliente com o parâmetro extra:

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

Usando um subconjunto de ferramentas

Se seu cliente suporta usar apenas um subconjunto de ferramentas, aqui está a lista de coisas que você deve estar ciente:

• A ferramenta update_workflow deve ser carregada no contexto juntamente com a ferramenta create_workflow, porque contém uma descrição detalhada sobre como criar e configurar um nó personalizado.

Problemas conhecidos

• update_workflow - precisa ter no contexto a configuração do fluxo de trabalho que está atualizando, seja fornecida pelo usuário ou chamando a ferramenta get_workflow_info, pois esta ferramenta não funciona como um aplicador patch, ela substitui totalmente a configuração do fluxo de trabalho.

CHANGELOG.md

Quaisquer novos recursos/correções/melhorias desenvolvidos serão adicionados ao CHANGELOG.md. O formato de pré-lançamento 0.x.x-dev é preferido antes de avançarmos para uma versão estável.

Solução de Problemas

• Se você encontrar problemas com Error: spawn <command> ENOENT, significa que <command> não está instalado ou visível no seu PATH:
  • Certifique-se de instalá-lo e adicioná-lo ao seu PATH.
  • ou forneça o caminho absoluto para o comando no campo command da sua configuração. Por exemplo, substitua python por /opt/miniconda3/bin/python