AgentQL

Servidor MCP AgentQL

Este é um servidor Model Context Protocol (MCP) que integra as capacidades de extração de dados do AgentQL.

Funcionalidades

Ferramentas

• extract-web-data - extrai dados estruturados de uma 'url' fornecida, usando 'prompt' como descrição dos dados reais e seus campos a extrair.

Instalação

Para usar o Servidor MCP AgentQL para extrair dados de páginas web, você precisa instalá-lo via npm, obter uma chave de API no nosso Dev Portal e configurá-lo no seu aplicativo favorito que suporte MCP.

Instalar o pacote

npm install -g agentql-mcp

Configurar o Claude

• Abra as Configurações do Claude Desktop via ⌘+, (não confunda com as Configurações da Conta do Claude)
• Vá para a seção Developer na barra lateral
• Clique em Edit Config e abra o arquivo claude_desktop_config.json
• Adicione o servidor agentql dentro do dicionário mcpServers no arquivo de configuração
• Reinicie o aplicativo

{
  "mcpServers": {
    "agentql": {
      "command": "npx",
      "args": ["-y", "agentql-mcp"],
      "env": {
        "AGENTQL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Leia mais sobre a configuração do MCP no Claude aqui.

Configurar o VS Code

Para instalação com um clique, clique em um dos botões de instalação abaixo:

Instalação Manual

Clique nos botões de instalação no topo desta seção para o método de instalação mais rápido. Para instalação manual, siga estes passos:

Adicione o seguinte bloco JSON ao seu arquivo de Configurações do Usuário (JSON) no VS Code. Você pode fazer isso pressionando Ctrl + Shift + P e digitando Preferences: Open User Settings (JSON).

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "AgentQL API Key",
        "password": true
      }
    ],
    "servers": {
      "agentql": {
        "command": "npx",
        "args": ["-y", "agentql-mcp"],
        "env": {
          "AGENTQL_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

Opcionalmente, você pode adicioná-lo a um arquivo chamado .vscode/mcp.json no seu espaço de trabalho. Isso permitirá compartilhar a configuração com outras pessoas.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "AgentQL API Key",
      "password": true
    }
  ],
  "servers": {
    "agentql": {
      "command": "npx",
      "args": ["-y", "agentql-mcp"],
      "env": {
        "AGENTQL_API_KEY": "${input:apiKey}"
      }
    }
  }
}

Configurar o Cursor

• Abra as Configurações do Cursor
• Vá para MCP > MCP Servers
• Clique em + Add new MCP Server
• Insira o seguinte:
  • Nome: "agentql" (ou o nome de sua preferência)
  • Tipo: "command"
  • Comando: env AGENTQL_API_KEY=YOUR_API_KEY npx -y agentql-mcp

Leia mais sobre a configuração do MCP no Cursor aqui.

Configurar o Windsurf

• Abra o Windsurf: MCP Configuration Panel
• Clique em Add custom server+
• Alternativamente, você pode abrir ~/.codeium/windsurf/mcp_config.json diretamente
• Adicione o servidor agentql dentro do dicionário mcpServers no arquivo de configuração

{
  "mcpServers": {
    "agentql": {
      "command": "npx",
      "args": ["-y", "agentql-mcp"],
      "env": {
        "AGENTQL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Leia mais sobre a configuração do MCP no Windsurf aqui.

Validar a integração MCP

Dê ao seu agente uma tarefa que exija extrair dados da web. Por exemplo:

Extract the list of videos from the page https://www.youtube.com/results?search_query=agentql, every video should have a title, an author name, a number of views and a url to the video. Make sure to exclude ads items. Format this as a markdown table.

[!TIP] Caso seu agente reclame que não consegue abrir URLs ou carregar conteúdo da web em vez de usar o AgentQL, tente adicionar a dica "use tools" ou "use agentql tool".

Desenvolvimento

Instale as dependências:

npm install

Compile o servidor:

npm run build

Para desenvolvimento com recompilação automática:

npm run watch

Se quiser testar a versão de desenvolvimento, você pode usar a seguinte configuração em vez da padrão:

{
  "mcpServers": {
    "agentql": {
      "command": "/path/to/agentql-mcp/dist/index.js",
      "env": {
        "AGENTQL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

[!NOTE] Não se esqueça de remover a configuração padrão do servidor MCP AgentQL para não confundir o Claude com dois servidores semelhantes.

Depuração

Como os servidores MCP se comunicam via stdio, a depuração pode ser desafiadora. Recomendamos usar o MCP Inspector, que está disponível como um script de pacote:

npm run inspector

O Inspector fornecerá uma URL para acessar as ferramentas de depuração no seu navegador.