# Ferramentas SEO — OpenSEO

Motor único do SEO Descomplicar®. Substituiu integralmente o stack anterior.
UI: `https://seo.descomplicar.pt` · Projecto default: `1e5ad4d6-a285-4fd3-9633-339abef4b6af`

---

## 1. Migração — o que morreu e o que o substitui

O stack antigo desta skill (v2.1.0) apontava para quatro dependências. **Nenhuma está operacional** (verificado 30-07-2026):

| Dependência antiga | Estado real | Substituto OpenSEO |
|---|---|---|
| **SEO Tools API** `localhost:3000` | `~/mcp-servers/seo-tools-api/` **não existe em disco** | ver tabela abaixo |
| **Ahrefs MCP** | nunca esteve em nenhuma config MCP | `get_backlinks_*`, `get_domain_overview`, `get_keyword_metrics` |
| **GSC MCP** | em `disabledServers` | `get_search_console_performance`, `inspect_urls` |
| **Lighthouse MCP** | em `disabledServers` | `run_site_audit` (`runLighthouse`) ou `chrome-devtools` |

### Endpoint a endpoint

| Antigo | Novo | Nota |
|---|---|---|
| `/seo-audit` | `run_site_audit` + `get_audit_issues` | Atenção ao `maxPages` |
| `/page-speed-analyzer` | `run_site_audit` com `runLighthouse: true` | Amostra até 20 páginas |
| `/content-optimization` | `get_audit_issues` (`thin-content`, `title-*`, `meta-description-*`) | |
| `/internal-linking` | `get_audit_issues` (`orphan-page`, `broken-internal-link`, `no-outgoing-links`) | |
| `/backlink-checker` | `get_backlinks_overview` | |
| `/rank-checker` | `get_rank_tracker` (grátis) ou `get_ranked_keywords` (pago) | |
| `/competitor-analysis` | `find_serp_competitors` + `get_domain_overview` | |
| `/sitemap-generator` | **sem equivalente** | Usar plugin WP ou gerar à mão |
| Ahrefs `keyword_generator` | `research_keywords` (novas) / `get_keyword_metrics` (conhecidas) | |
| Ahrefs `get_backlinks_list` | `get_backlinks_profile` | |
| Ahrefs `get_traffic` | `get_domain_overview` | Estimado |
| Lighthouse `run_audit` | `chrome-devtools → lighthouse_audit` | Por página |
| Lighthouse `get_core_web_vitals` | `chrome-devtools → performance_start_trace` | LCP/INP/CLS reais |
| GSC `get_search_analytics` | `get_search_console_performance` | |
| GSC `check_indexing_issues` | `inspect_urls` | Até 10 URLs por chamada |
| GSC `get_sitemaps` | **sem equivalente** | Ver na UI do Search Console |

---

## 2. Inventário OpenSEO (24 ferramentas)

### Grátis — não tocam no DataForSEO

| Ferramenta | Função |
|---|---|
| `whoami` | Utilizador, org, modo, scopes. **Não mostra saldo em self-hosted** |
| `list_projects` | Projectos + `projectId` + mercado default |
| `create_project` | Novo projecto (nome, domínio, mercado) |
| `run_site_audit` | Crawl same-origin, robots-aware. `maxPages` **default 50** |
| `get_audit_status` | Progresso (fase, páginas, Lighthouse) |
| `get_audit_issues` | Relatório priorizado. Filtros `severity`/`issueType` |
| `get_audit_pages` | Páginas crawladas com dados SEO por página |
| `get_search_console_performance` | Search Analytics: cliques, impressões, CTR, posição |
| `inspect_urls` | URL Inspection do GSC (até 10 URLs): indexação, canónico |
| `get_rank_tracker` | Configs de rank tracking + último snapshot |
| `save_keywords` | Guardar keywords no projecto (idempotente) |
| `list_saved_keywords` | Keywords guardadas + métricas em cache |

### Pagas — consomem créditos

| Ferramenta | Custo aprox. | Função |
|---|---|---|
| `get_keyword_metrics` | lote | **Até 700 keywords/chamada**: volume, KD, intenção, CPC, tendência |
| `research_keywords` | ~30-100/seed | 1-5 seeds → ideias novas + métricas |
| `get_serp_results` | ~30-60/keyword | Google orgânico ao vivo, 1-10 keywords |
| `find_serp_competitors` | pago | Domínios que competem num conjunto de keywords |
| `get_ranked_keywords` | pago | Keywords onde um domínio posiciona, por mercado |
| `get_domain_overview` | pago | Tráfego orgânico, nº keywords, backlinks, ref. domains |
| `get_domain_keyword_suggestions` | pago | Lista detalhada de keywords de um domínio |
| `get_backlinks_overview` | ~50/domínio, ~25/página | Resumo do perfil de backlinks |
| `get_backlinks_profile` | pago | Linhas detalhadas: anchors, dofollow, spam, lost/broken |
| `get_local_serp_results` | pago | Google Maps / Local Finder junto a coordenadas |
| `search_local_businesses` | pago | Negócios locais perto de coordenadas |
| `get_google_business_questions` | pago | Q&A de Google Business Profile |

---

## 3. Mercados

| Mercado | `locationCode` | `languageCode` |
|---|---|---|
| **Portugal** | `2620` | `pt` |
| EUA (default do projecto) | `2840` | `en` |

`2620` = Portugal, confirmado empiricamente (SERP devolve domínios `.pt`). **Não inventar códigos** — validar sempre por uma query de teste. Referência oficial: `dataforseo.com/help-center/locations`.

**Aviso:** alguns países são servidos por dados do Google Ads — volume/CPC funcionam, mas KD, intenção e analytics de domínio não estão disponíveis.

---

## 4. Limitações conhecidas (verificadas, não presumidas)

1. **Issues sem URL.** `get_audit_issues` e `get_audit_pages` devolvem só contagens agregadas via bridge MCP. As linhas por URL vivem em `structuredContent.issues`, que a bridge não entrega. `get_audit_pages` trunca em ~25 linhas mesmo com `limit: 1000`.
   → Contorno: `details.mcpMeta.url` traz o link do relatório na UI.

2. **Sem medidor de créditos.** `whoami` em self-hosted devolve o mesmo output antes e depois de chamadas pagas. Os custos documentados são estimativas do schema. O contador real está na conta DataForSEO.

3. **`maxPages` default 50.** A causa mais comum de auditorias falsamente limpas.

4. **GSC anonimiza queries.** Totais por query são sempre inferiores aos totais por página. Usar a vista por página para números globais.

5. **GSC não filtra por posição.** Striking distance filtra-se do lado do cliente.

6. **Lag do GSC:** os últimos ~3 dias podem estar incompletos. Datas em Pacific Time. Máximo 16 meses de histórico.

---

## 5. Propriedades Search Console disponíveis

```
sc-domain:descomplicar.pt
https://emanuelalmeida.pt/
https://carstuff.pt/
https://solarfvengenharia.com/
https://aquisevende.pt/
https://alojadamaria.com/
https://e-commerce.descomplicar.pt/
```

---

**Actualizado:** 30-07-2026 | Substitui a versão baseada em SEO Tools API + Ahrefs + GSC/Lighthouse MCP