# 🎯 MCP Hunter

> **Servidor MCP (Model Context Protocol) para OSINT, Prospecção Ativa, Busca Web, Scraping Profundo e Enriquecimento de Dados de Empresas e Pessoas.**

O **MCP Hunter** conecta assistentes de inteligência artificial (como Gemini Antigravity, Claude Desktop, Cursor e Windsurf) diretamente à internet e a fontes de dados abertas. Ele é capaz de pesquisar no Google/Web, raspar e limpar páginas de forma inteligente, extrair contatos (e-mails, WhatsApp, telefones, redes sociais) e enriquecer perfis de empresas com dados oficiais da Receita Federal (CNPJ, Sócios/QSA, Capital Social e Endereço).

---

## ✨ Principais Funcionalidades

- 🔍 **Busca na Web sem Chaves Pagas:** Pesquisa rápida com suporte a operadores avançados (`site:`, `inurl:`, `filetype:`) e foco regional no Brasil (`br-pt`).
- 🌐 **Scraping e Limpeza Inteligente de Conteúdo:** Utiliza `trafilatura` e `BeautifulSoup` para extrair somente o texto principal, eliminando anúncios, menus e códigos.
- 📞 **Extrator Cirúrgico de Contatos:** Algoritmos de Regex e heurísticas para identificar:
  - E-mails válidos (com filtro anti-lixo e anti-imagens);
  - Telefones fixos e celulares no padrão brasileiro;
  - Links diretos de WhatsApp (`wa.me/` e `api.whatsapp.com`);
  - Perfis oficiais em redes sociais (Instagram, LinkedIn, Facebook, X/Twitter, YouTube, TikTok, GitHub);
  - Números de CNPJ com validação matemática dos dígitos verificadores.
- 🏛️ **Consulta Oficial à Receita Federal (BrasilAPI):** Obtém Razão Social, Nome Fantasia, Situação Cadastral, Data de Abertura, Capital Social, Atividade Principal (CNAE), Endereço e Quadro de Sócios e Administradores (QSA).
- 🏢 **Modo Mestre (`hunt_company`):** Recebe o nome de uma empresa e executa a investigação 360º de ponta a ponta em segundos.
- 👤 **Investigação de Pessoas (`hunt_person`):** Varre menções públicas, perfis no LinkedIn e artigos sobre uma pessoa.

---

## 🛠️ Ferramentas (Tools) Expostas

| Ferramenta | Descrição | Parâmetros Principais |
| :--- | :--- | :--- |
| `hunter_search` | Pesquisa na Web/Google retornando links, títulos e snippets resumidos. | `query` (str), `max_results` (int, default: 5), `region` (str, default: 'br-pt') |
| `scrape_website` | Entra no site, extrai o texto legível e varre subpáginas de contato (`/contato`, `/sobre`, `/termos`). | `url` (str), `deep_contacts` (bool, default: true) |
| `extract_contacts` | Analisa uma URL ou texto bruto e extrai e-mails, telefones, WhatsApp, redes e CNPJ. | `url` (str, opcional), `text` (str, opcional) |
| `consult_cnpj` | Consulta a base da Receita Federal via BrasilAPI / MinhaReceita. | `cnpj` (str) |
| `hunt_company` | **Dossiê 360º de Empresa**: busca site, extrai contatos, redes sociais, CNPJ e quadro societário. | `company_name` (str), `domain_or_url` (str, opcional) |
| `hunt_person` | Investiga presença pública, perfis no LinkedIn e menções na web sobre uma pessoa. | `name` (str), `context` (str, opcional) |

---

## 🚀 Instalação e Execução

Este projeto utiliza o gerenciador de pacotes ultra-rápido **[`uv`](https://docs.astral.sh/uv/)**.

### 1. Clonar o repositório
```bash
git clone <URL_DO_REPOSITORIO>
cd "MCP Hunter"
```

### 2. Instalar dependências automaticamente
```bash
uv sync
```

### 3. Executar os testes automatizados
```bash
uv run python tests/test_tools.py
```

### 4. Iniciar o servidor MCP (modo stdio)
```bash
uv run mcp-hunter
```

---

## 🔌 Configuração nos Clientes MCP

### Antigravity / Claude Desktop / Cursor / Windsurf
Adicione a configuração abaixo no seu arquivo de configuração MCP (`claude_desktop_config.json` ou similar):

```json
{
  "mcpServers": {
    "mcp-hunter": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\caminho\\para\\MCP Hunter",
        "run",
        "mcp-hunter"
      ]
    }
  }
}
```

---

## 📂 Estrutura do Projeto

```
MCP Hunter/
├── src/
│   └── mcp_hunter/
│       ├── __init__.py        # Definição do pacote
│       ├── server.py          # Servidor FastMCP e registro das Tools
│       ├── search.py          # Motor de buscas na Web (DuckDuckGo/DDGS)
│       ├── scraper.py         # Motor de requisições HTTP e scraping (Trafilatura/BS4)
│       ├── extractor.py       # Extração de contatos, regex e validação de CNPJ
│       ├── cnpj.py            # Integração com BrasilAPI e Receita Federal
│       └── py.typed           # Marcador de tipagem PEP 561
├── tests/
│   ├── test_hunter.py         # Testes unitários dos módulos internos
│   └── test_tools.py          # Testes de integração das ferramentas MCP
├── mcp_config_example.json    # Exemplo de configuração de cliente MCP
├── pyproject.toml             # Configuração do projeto e dependências
├── uv.lock                    # Lockfile de dependências
└── README.md                  # Documentação oficial
```

---

## 📄 Licença

Distribuído sob a licença MIT. Consulte `LICENSE` para obter mais informações.