Unstructured API MCP Server

Unstructured API MCP Server

Uma implementação de servidor MCP para interagir com a API da 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 suporta atualmente. 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 trabalhos 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
• Os trabalhos 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 da Unstructured limpa muito bem :smile:

Geração de Texto LLM:

• Após o rastreamento, extrai conteúdo de texto limpo e significativo das páginas rastreadas
• Gera formatos de texto otimizados especificamente formatados para grandes modelos de linguagem
• Os resultados são automaticamente enviados para o local S3 especificado
• Nota: Os trabalhos de geração de texto LLM não podem ser cancelados após o início. A função cancel_llmtxt_job é fornecida para 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 da 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 lida com a execução. No entanto, se você 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 da 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': Desative a confirmação de uso de ferramentas 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 daí, 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 os recursos que adicionou ao servidor MCP.

mcp dev uns_mcp/server.py

Se você precisar registrar parâmetros de chamada de solicitaçã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 solicitaçã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 no MCP Filesystem Server. Tenha cuidado, pois o cliente (também 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 parâmetro extra:

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

Usando subconjunto de ferramentas

Se o seu cliente suportar 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 junto com a ferramenta create_workflow, pois contém descrição detalhada sobre como criar e configurar 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 essa ferramenta não funciona como aplicador 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 passarmos 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