Unstructured MCP Server

Servidor MCP da API Unstructured

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 origem 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:

Origem 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 Otimizado para LLM: Usando invoke_firecrawl_llmtxt para gerar texto e check_llmtxt_status para recuperar resultados

Como o Firecrawl funciona:

Processo de Rastreamento Web:

• Começa 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
• Jobs podem ser cancelados com cancel_crawlhtml_job se necessário
• Use isso se você 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 de texto limpo e significativo das páginas rastreadas
• Gera formatos de texto otimizados especificamente para modelos de linguagem de grande porte
• Os resultados são enviados automaticamente para o local S3 especificado
• Nota: Trabalhos de geração de texto para LLM não podem ser cancelados depois de iniciados. 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 da 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 abrir 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 você 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 (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 o 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 fornecendo-a pelo usuário ou chamando a ferramenta get_workflow_info, pois esta ferramenta não funciona como um aplicador de patch, ela substitui completamente 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