npm package: @justmpm/search-console
Description: MCP Server para Google Search Console - analytics, indexação, sitemaps
Author: Koda AI Studio
Latest version: 0.1.12

# @justmpm/search-console

MCP Server para Google Search Console focado em analise de dados de desempenho, indexacao e sitemaps.

Fluxo recomendado: analisar dados agregados primeiro e investigar URLs uma por vez com `url_inspect`.

## Instalação

```bash
npm install @justmpm/search-console
```

## Configuração

### 1. Criar Credenciais OAuth no Google Cloud Console

1. Acesse [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. Crie um novo projeto ou selecione um existente
3. Habilite a **Search Console API** em "Library"
4. Vá em "Credentials" > "Create Credentials" > "OAuth client ID"
5. Selecione "Web application"
6. Adicione authorized redirect URI: `http://localhost:3000/callback`
7. Copie o **Client ID** e **Client Secret**

### 2. Salvar Credenciais

Crie o arquivo de credenciais:

```bash
mkdir -p ~/.search-console
echo '{"client_id":"SEU_CLIENT_ID","client_secret":"SEU_CLIENT_SECRET","redirect_uri":"http://localhost:3000/callback"}' > ~/.search-console/credentials.json
```

### 3. Autorizar Acesso

Execute o fluxo de autorização OAuth:

```bash
npx @justmpm/search-console auth
```

Isso vai:
- Abrir o browser para você autorizar
- Receber o callback em servidor local
- Salvar os tokens em `~/.search-console/tokens.json`

## Uso como MCP

Adicione ao seu arquivo de configuração MCP:

```json
{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["@justmpm/search-console"]
    }
  }
}
```

## Tools Disponíveis

### search_analytics

Consulta dados de desempenho do Search Console.

**Parâmetros:**
- `siteUrl` (obrigatório): URL da propriedade
- `startDate` (obrigatório): Data inicial (YYYY-MM-DD)
- `endDate` (obrigatório): Data final (YYYY-MM-DD)
- `dimensions`: Agrupar por (date, query, page, country, device, searchAppearance)
- `type`: Tipo de busca (web, image, video, news, discover)
- `device`: Filtrar por dispositivo (DESKTOP, MOBILE, TABLET)
- `country`: Filtrar por país (código ISO 3166-1 alpha-3)
- `rowLimit`: Máximo de linhas (1-25000)

**Exemplo:**
```json
{
  "siteUrl": "https://example.com/",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "dimensions": ["query", "page"],
  "rowLimit": 100
}
```

### url_inspect

Verifica status de indexação de uma URL específica.

**Parâmetros:**
- `inspectionUrl` (obrigatório): URL a inspecionar
- `siteUrl` (obrigatório): URL da propriedade

**Retorna:**
- Status de indexação (indexada/não indexada)
- Motivos de não indexação
- Último crawl
- URL canônica do Google
- Rich Results detectados

### sitemap_audit

Auditoria de indexação focada em analise (sem operacoes de escrita e sem inspeção em lote).

**Parâmetros:**
- `siteUrl` (obrigatório): URL da propriedade
- `sitemapUrl` (obrigatório): URL do sitemap XML
- `listLimit`: Quantidade máxima de URLs para listar (1-200, padrão: 50)

**Retorna:**
- Taxa de indexação agregada do sitemap
- Erros e warnings do processamento
- Lista de URLs do sitemap para investigar com `url_inspect`

### list_sites

Lista todas as propriedades do Search Console.

### list_sitemaps

Lista sitemaps enviados para uma propriedade.

**Parâmetros:**
- `siteUrl` (obrigatório): URL da propriedade

## Fluxo Recomendado para IA

1. `list_sites` para descobrir o `siteUrl` correto
2. `list_sitemaps` para descobrir o `sitemapUrl` correto
3. `sitemap_audit` para resumo + lista de URLs
4. `url_inspect` para investigar cada URL importante
5. `search_analytics` para priorizar páginas com impacto

## Casos de Uso

### "Quais páginas têm mais tráfego?"

```json
{
  "name": "search_analytics",
  "arguments": {
    "siteUrl": "https://example.com/",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "dimensions": ["page"],
    "rowLimit": 20
  }
}
```

### "Essa URL está indexada?"

```json
{
  "name": "url_inspect",
  "arguments": {
    "siteUrl": "https://example.com/",
    "inspectionUrl": "https://example.com/minha-pagina"
  }
}
```

### "Qual a taxa de indexação do meu sitemap?"

```json
{
  "name": "sitemap_audit",
  "arguments": {
    "siteUrl": "https://example.com/",
    "sitemapUrl": "https://example.com/sitemap.xml",
    "listLimit": 100
  }
}
```

### "Desempenho mobile no Brasil"

```json
{
  "name": "search_analytics",
  "arguments": {
    "siteUrl": "https://example.com/",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "dimensions": ["query"],
    "device": "MOBILE",
    "country": "BRA"
  }
}
```

## Limitações

- **URL Inspection API**: Rate limit de ~2 requisições/segundo
- **Search Analytics**: Máximo 25.000 linhas por requisição
- **Sitemap Audit**: Lista até 200 URLs por execução

## Troubleshooting

### "Credenciais OAuth não configuradas"

Execute o setup de credenciais:
```bash
npx @justmpm/search-console auth --setup
```

### "Token expirado"

Os tokens são renovados automaticamente. Se houver problemas, re-autentique:
```bash
rm ~/.search-console/tokens.json
npx @justmpm/search-console auth
```

### "URL não encontrada"

Verifique se a URL está registrada exatamente como no Search Console:
- `https://example.com/` (com barra final)
- `sc-domain:example.com` (para domain properties)

### "Insufficient Permission" / 403

- Confirme que a conta autenticada tem acesso a propriedade
- Rode `list_sites` para validar se o site aparece para essa conta

### "API has not been used" / API desabilitada

- Habilite a Search Console API no projeto OAuth
- Aguarde 2-5 minutos e tente novamente

## Desenvolvimento

```bash
# Instalar dependências
npm install

# Build
npm run build

# Desenvolvimento
npm run dev

# Testar autenticação
npm run auth
```

## Licença

MIT © Koda AI Studio