ealmeida/claude-plugins
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

marketing: migra superfície SEO para OpenSEO (motor único)

Browse Source 
As skills de SEO assentavam em quatro dependências, nenhuma operacional:
SEO Tools API (localhost:3000, pasta inexistente em disco), Ahrefs MCP
(nunca esteve em config), gsc e lighthouse (em disabledServers). Os seis
passos da /seo-audit e o workflow inteiro da /seo-report apontavam para
tooling morto — não eram executáveis.

- seo-audit v3.0: ordem por custo (grátis → lote pago → unitário pago),
  gate de mercado (PT = 2620/pt) e gate de maxPages
- seo-report v3.0: cobertura de crawl obrigatória no entregável
- ferramentas-api.md: inventário das 24 ferramentas OpenSEO + tabela de
  migração endpoint a endpoint
- implementacao-tecnica.md: striking distance, desperdício e filtro de
  ruído do GSC em código
- seo-specialist v3.0: primary_mcps [openseo], bloco de MCPs desligados,
  FID → INP nos Core Web Vitals

maxPages tem default 50: descomplicar.pt auditado com o default deu 25
URLs e 92 issues sem críticos; com maxPages 600 deu 1337 issues e 9
críticos. Documentado como gate — a fase Search Console dimensiona o crawl.

Limitações declaradas nas skills: get_audit_issues devolve contagens sem
URLs pela bridge MCP (structuredContent.issues não é entregue) e o whoami
não expõe saldo de créditos em self-hosted.
This commit is contained in:
ealmeida
2026-07-30 22:39:40 +01:00
parent f90ba6ec76
commit 2d05873642
9 changed files with 545 additions and 497 deletions
Download Patch File Download Diff File Expand all files Collapse all files
marketing/skills/seo-audit/references/ferramentas-api.md
+94 -64
View File
@@ -1,75 +1,113 @@
# Ferramentas e APIs - SEO Audit
# Ferramentas SEO — OpenSEO
## 1. SEO Tools API (http://localhost:3000)
Motor único do SEO Descomplicar®. Substituiu integralmente o stack anterior.
UI: `https://seo.descomplicar.pt` · Projecto default: `1e5ad4d6-a285-4fd3-9633-339abef4b6af`
```bash
# Auditoria basica
curl "http://localhost:3000/seo-audit?url=URL"
---
# Velocidade PageSpeed Insights style
curl "http://localhost:3000/page-speed-analyzer?url=URL"
## 1. Migração — o que morreu e o que o substitui
# Backlinks + DR/UR
curl "http://localhost:3000/backlink-checker?url=URL"
O stack antigo desta skill (v2.1.0) apontava para quatro dependências. **Nenhuma está operacional** (verificado 30-07-2026):
# Rankings para keywords
curl "http://localhost:3000/rank-checker?url=URL&keywords=keyword1,keyword2"
| 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` |
# Optimizacao conteudo on-page
curl "http://localhost:3000/content-optimization?url=URL"
### Endpoint a endpoint
# Internal linking structure
curl "http://localhost:3000/internal-linking?url=URL"
| 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 |
# Sitemap XML generator
curl "http://localhost:3000/sitemap-generator?url=URL"
---
# Analise concorrencia
curl "http://localhost:3000/competitor-analysis?url=URL&competitors=site1.com,site2.com"
```
## 2. Inventário OpenSEO (24 ferramentas)
## 2. Lighthouse MCP
### Grátis — não tocam no DataForSEO
| Tool | Funcao | Output |
|------|--------|--------|
| `run_audit(url)` | Auditoria completa | Performance, SEO, A11y, Best Practices |
| `get_performance_score(url)` | Score performance | 0-100 |
| `get_core_web_vitals(url)` | LCP, INP, CLS | Mobile + Desktop |
| `get_accessibility_score(url)` | Acessibilidade | 0-100 + issues |
| `get_seo_analysis(url)` | Analise SEO tecnico | Meta, headings, indexabilidade |
| `get_security_audit(url)` | Seguranca | HTTPS, mixed content, headers |
| `compare_mobile_desktop(url)` | Comparacao | Diferencas performance |
| `get_lcp_opportunities(url)` | Optimizacoes LCP | Preload, lazy load |
| `find_unused_javascript(url)` | JS nao usado | Tamanhos, % savings |
| 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 |
## 3. SEO Ahrefs MCP (via API)
### Pagas — consomem créditos
| Tool | Funcao | Dados |
|------|--------|-------|
| `get_backlinks_list(domain)` | Lista backlinks | DR, UR, anchor text |
| `keyword_generator(keyword, country)` | Ideias keywords | Volume, KD, CPC |
| `get_traffic(domain)` | Trafego estimado | Visitas mensais, keywords |
| `keyword_difficulty(keyword)` | Dificuldade keyword | 0-100 (KD score) |
| 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 |
## 4. Google Search Console MCP
---
| Tool | Funcao | Dados Reais |
|------|--------|-------------|
| `list_properties` | Listar sites verificados | URLs properties |
| `get_search_analytics(site, period)` | Queries, cliques, CTR | Ultimos 16 meses |
| `inspect_url_enhanced(site, url)` | Inspeccionar URL | Indexacao, mobile usability |
| `check_indexing_issues(site, urls)` | Problemas indexacao | Erros, avisos |
| `get_sitemaps(site)` | Listar sitemaps | Status, URLs submetidos |
## 3. Mercados
## 5. Google Analytics MCP
| Mercado | `locationCode` | `languageCode` |
|---|---|---|
| **Portugal** | `2620` | `pt` |
| EUA (default do projecto) | `2840` | `en` |
| Tool | Funcao | Metricas |
|------|--------|----------|
| `get_account_summaries` | Listar contas | Properties disponiveis |
| `run_report(property, metrics, dimensions)` | Relatorio custom | Sessions, users, bounce rate |
| `run_realtime_report(property)` | Tempo real | Utilizadores activos now |
`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`.
## Propriedades GSC Disponiveis
**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
@@ -81,14 +119,6 @@ https://alojadamaria.com/
https://e-commerce.descomplicar.pt/
```
## Requisitos
---
- **SEO Tools API** deve estar a correr: `~/mcp-servers/seo-tools-api/start.sh`
- **GSC** requer autenticacao OAuth na primeira utilizacao
- **GA** requer ADC credentials configuradas (`gcloud auth application-default login`)
## Limitacoes
- Ahrefs API tem rate limiting (100 req/day free tier)
- GSC data maximo: 16 meses historico
- Lighthouse scores variam +/- 5 pontos entre execucoes (network dependent)
**Actualizado:** 30-07-2026 | Substitui a versão baseada em SEO Tools API + Ahrefs + GSC/Lighthouse MCP
marketing/skills/seo-audit/references/template-relatorio-auditoria.md
+8 -5
View File
@@ -183,11 +183,14 @@ H1: [Texto] OK
---
## Ferramentas Utilizadas
- SEO Tools API (localhost:3000)
- Lighthouse MCP
- SEO Ahrefs MCP
- Google Search Console MCP
- Google Analytics MCP (opcional)
- OpenSEO — crawl e issues (`run_site_audit`, `get_audit_issues`)
- OpenSEO — Search Console (`get_search_console_performance`)
- OpenSEO — keywords e SERP (`get_keyword_metrics`, `get_serp_results`)
- OpenSEO — autoridade (`get_backlinks_overview`, `get_domain_overview`)
- chrome-devtools — Core Web Vitals por página (opcional)
**Cobertura do crawl**: [N páginas crawladas] de [M páginas com impressões no GSC]
**Chamadas pagas**: [listar] — custo estimado, não medido (OpenSEO não expõe saldo)
---