marketing: migra superfície SEO para OpenSEO (motor único)
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:
@@ -1,30 +1,13 @@
|
||||
---
|
||||
name: seo-report
|
||||
description: Relatorio de auditoria SEO completo com Lighthouse, Google Search Console e exportacao para Google Docs. Analisa Core Web Vitals, desempenho, SEO on-page e gera recomendacoes accionaveis.
|
||||
description: Relatório SEO completo com dados reais via OpenSEO (Search Console, crawl, Core Web Vitals, backlinks) e exportação para Google Docs. Prioriza por retorno e gera plano de acção. Usar quando "relatório SEO", "seo report", "relatório cliente SEO", "auditoria para cliente".
|
||||
---
|
||||
|
||||
# Skill: /seo-report
|
||||
|
||||
Gera relatorio SEO completo com dados de multiplas fontes e exporta automaticamente para Google Docs.
|
||||
Relatório SEO para cliente, com dados reais do **OpenSEO**, exportado para Google Docs.
|
||||
|
||||
---
|
||||
|
||||
## Contexto NotebookLM
|
||||
|
||||
ANTES de executar, consultar notebook para contexto especializado:
|
||||
|
||||
| Notebook | ID | Consultar quando |
|
||||
|----------|-----|-----------------|
|
||||
| Marketing Digital PT | `4c595973` | Sempre |
|
||||
|
||||
```
|
||||
mcp__notebooklm__notebook_query({
|
||||
notebook_id: "4c595973-ba10-420a-a3bf-e4389e424ad3",
|
||||
query: "<adaptar ao contexto — ex: auditoria SEO, relatorio performance, recomendacoes tecnicas>"
|
||||
})
|
||||
```
|
||||
|
||||
**Procedimento relacionado:** `PROC-DMARC-Email-Entregabilidade.md` -- consultar quando o relatorio envolve email deliverability.
|
||||
Diferença face a `/seo-audit`: a auditoria é o **diagnóstico técnico interno**; o report é o **entregável ao cliente** — mesma recolha, apresentação orientada a decisão e a orçamento.
|
||||
|
||||
---
|
||||
|
||||
@@ -32,127 +15,115 @@ mcp__notebooklm__notebook_query({
|
||||
|
||||
`/seo-report <url>` ou `/seo-report <url> <email_destino>`
|
||||
|
||||
---
|
||||
|
||||
## Exemplos
|
||||
|
||||
```bash
|
||||
# Relatorio basico (envia para emanuelalmeidaa@gmail.com)
|
||||
/seo-report https://descomplicar.pt
|
||||
|
||||
# Relatorio para cliente especifico
|
||||
/seo-report https://cliente.pt cliente@email.com
|
||||
|
||||
# Relatorio com analise concorrencia
|
||||
/seo-report https://site.pt --competitors=concorrente1.pt,concorrente2.pt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Fontes de Dados
|
||||
## Fontes de dados
|
||||
|
||||
| Fonte | Dados Recolhidos | Tempo |
|
||||
|-------|------------------|-------|
|
||||
| **Lighthouse (Desktop)** | Performance, SEO, Accessibility, Best Practices | ~30s |
|
||||
| **Lighthouse (Mobile)** | Core Web Vitals, INP, comparacao mobile/desktop | ~30s |
|
||||
| **Lighthouse (Optimizacoes)** | Oportunidades LCP, JS nao usado, images optimization | ~15s |
|
||||
| **GSC** | Cliques, impressoes, CTR, posicao media, top queries, tendencia 90 dias | ~10s |
|
||||
| **SEO Tools API** | Meta tags, imagens, alt text, links internos/externos, estrutura HTML | ~5s |
|
||||
| **Ahrefs (opcional)** | DR, UR, backlinks, referring domains | ~10s |
|
||||
| Fonte | Ferramenta | Dados | Custo |
|
||||
|---|---|---|---|
|
||||
| **Search Console** | `get_search_console_performance` | Cliques, impressões, CTR, posição, por query e por página | grátis |
|
||||
| **Indexação** | `inspect_urls` | Estado de indexação (até 10 URLs) | grátis |
|
||||
| **Crawl técnico** | `run_site_audit` → `get_audit_issues` | Issues por severidade, Lighthouse em amostra | grátis |
|
||||
| **Core Web Vitals** | `chrome-devtools → performance_start_trace` | LCP, INP, CLS por página | grátis |
|
||||
| **Keywords** | `get_keyword_metrics` | Volume, KD, intenção (até 700/chamada) | pago |
|
||||
| **Autoridade** | `get_backlinks_overview`, `get_domain_overview` | Backlinks, ref. domains, tráfego estimado | pago |
|
||||
| **Concorrência** | `find_serp_competitors`, `get_serp_results` | Quem ocupa a SERP | pago |
|
||||
|
||||
**Tempo Total:** ~1m40s (sem concorrencia) | ~3m (com 2 concorrentes)
|
||||
**Tempo:** ~5-10 min (crawl de 600 páginas demora ~4 min). Não é instantâneo — avisar o cliente.
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Validar URL de entrada
|
||||
2. Verificar se site esta no GSC (skip se nao)
|
||||
3. Executar auditorias em paralelo:
|
||||
- Lighthouse Desktop + Mobile
|
||||
- Core Web Vitals
|
||||
- SEO Tools API
|
||||
- GSC Analytics (se disponivel)
|
||||
- Ahrefs (se habilitado)
|
||||
4. Processar e formatar dados
|
||||
5. Gerar relatorio Markdown
|
||||
6. Criar Google Doc e partilhar
|
||||
7. Retornar link do documento
|
||||
|
||||
---
|
||||
|
||||
## Estrutura do Relatorio
|
||||
|
||||
O relatorio final tem 8 seccoes:
|
||||
|
||||
1. **Sumario Executivo** -- Top 5 descobertas + accao imediata recomendada
|
||||
2. **Pontuacoes Globais** -- Desktop vs Mobile (Performance, SEO, A11y, Best Practices)
|
||||
3. **Core Web Vitals** -- LCP, INP, CLS com oportunidades de optimizacao
|
||||
4. **GSC Analytics** -- Performance overview, top queries, oportunidades CTR (ultimos 90 dias)
|
||||
5. **Analise On-Page** -- Meta tags, imagens SEO, internal linking
|
||||
6. **Backlinks e Autoridade** -- DR, UR, top backlinks, estrategia
|
||||
7. **Plano de Accao** -- Priorizado (critico/importante/melhoria) com impacto e esforco
|
||||
8. **Roadmap Trimestral** -- Fundacao tecnica -> Conteudo e autoridade -> Consolidacao
|
||||
|
||||
---
|
||||
|
||||
## Propriedades GSC Disponiveis
|
||||
|
||||
```
|
||||
sc-domain:descomplicar.pt
|
||||
https://emanuelalmeida.pt/
|
||||
https://carstuff.pt/
|
||||
https://solarfvengenharia.com/
|
||||
https://aquisevende.pt/
|
||||
https://alojadamaria.com/
|
||||
https://e-commerce.descomplicar.pt/
|
||||
1. whoami + list_projects → projectId e mercado (GATE: PT = 2620/pt)
|
||||
2. GSC por query + por página → paginar até esgotar
|
||||
3. Dimensionar o crawl → maxPages ≥ nº páginas com impressões + 25%
|
||||
4. run_site_audit → poll get_audit_status até "completed"
|
||||
5. get_audit_issues → critical → warning → info
|
||||
6. Cruzar fase 2 com fase 5 → páginas com procura E com defeito = lista de trabalho
|
||||
7. [pago, opcional] keywords, backlinks, SERP
|
||||
8. Gerar Markdown → Google Doc → partilhar
|
||||
```
|
||||
|
||||
**Os passos 1-6 são grátis e produzem o grosso do relatório.** O passo 7 só se o cliente pagar análise competitiva.
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
## Estrutura do relatório (8 secções)
|
||||
|
||||
1. **Sumário executivo** — 5 descobertas + a acção imediata. Más notícias primeiro.
|
||||
2. **Realidade actual** — cliques, impressões, CTR global, distribuição por posição, branded vs não-branded.
|
||||
3. **Onde está o retorno** — striking distance (pos 4-20, ≥25 impressões) e desperdício (pos >40 com procura alta).
|
||||
4. **Estado técnico** — issues por severidade, com **cobertura do crawl declarada**.
|
||||
5. **Core Web Vitals** — LCP / INP / CLS nas páginas que importam (não em todas).
|
||||
6. **Autoridade** — backlinks e ref. domains, se contratado.
|
||||
7. **Plano de acção** — prioridade (crítico/importante/melhoria) × esforço × impacto estimado.
|
||||
8. **Roadmap trimestral** — fundação técnica → conteúdo → consolidação.
|
||||
|
||||
---
|
||||
|
||||
## Regras de honestidade do relatório
|
||||
|
||||
Um relatório SEO é um documento comercial. Isso torna a precisão **mais** importante, não menos.
|
||||
|
||||
- **Declarar sempre a cobertura do crawl.** "1337 issues em 600 páginas crawladas de ~640 com impressões." Sem isto, o número de issues não significa nada.
|
||||
- **Não apresentar contagens como URLs verificados.** Se a bridge só deu contagens, dizê-lo e anexar o link da UI.
|
||||
- **Custos são estimativas.** O OpenSEO não expõe saldo — nunca escrever "gastámos X créditos" como facto.
|
||||
- **Separar medido de inferido.** Marcar as inferências. Um cliente que descobre uma inferência apresentada como facto deixa de confiar no resto.
|
||||
- **CTR baixo em posição alta não é problema de ranking.** É título/meta. Dizer isso — é a recomendação mais barata e de maior retorno que existe.
|
||||
|
||||
---
|
||||
|
||||
## Notas técnicas
|
||||
|
||||
### Requisitos
|
||||
- SEO Tools API a correr: `~/mcp-servers/seo-tools-api/start.sh`
|
||||
- Google Workspace MCP configurado
|
||||
- GSC authentication (OAuth primeira vez)
|
||||
- OpenSEO acessível (`whoami` responde)
|
||||
- Propriedade ligada ao Search Console (senão, relatório sem fase GSC — declarar)
|
||||
- `google-workspace` MCP para o Google Doc
|
||||
|
||||
### Erros Comuns
|
||||
- **Site nao em GSC:** Relatorio gerado sem dados GSC (aviso incluido)
|
||||
- **Lighthouse timeout:** Retry automatico (3x)
|
||||
- **Ahrefs rate limit:** Skip backlinks, aviso no relatorio
|
||||
### Erros comuns
|
||||
| Erro | Sintoma | Solução |
|
||||
|---|---|---|
|
||||
| **`maxPages` por omissão** | Relatório limpo demais, poucos issues | Redimensionar pelo nº de páginas do GSC e relançar |
|
||||
| Site fora do GSC | Fase 2 vazia | Gerar sem GSC, com aviso destacado |
|
||||
| Mercado errado | Dados de keywords em inglês/EUA | `locationCode: 2620`, `languageCode: "pt"` |
|
||||
| Crawl a demorar | `get_audit_status` em `crawling` | Normal — 600 páginas ≈ 4 min. Fazer poll, não cancelar |
|
||||
|
||||
---
|
||||
|
||||
## References (conteudo detalhado)
|
||||
## References
|
||||
|
||||
| Ficheiro | Conteudo |
|
||||
|----------|----------|
|
||||
| `references/template-relatorio.md` | Template completo do relatorio com todas as tabelas e seccoes |
|
||||
| `references/implementacao-tecnica.md` | Workflow mermaid, codigo JS, funcoes GSC, notas tecnicas |
|
||||
| Ficheiro | Conteúdo |
|
||||
|---|---|
|
||||
| `references/template-relatorio.md` | Template completo com tabelas e secções |
|
||||
| `references/implementacao-tecnica.md` | Workflow, chamadas OpenSEO, processamento |
|
||||
|
||||
Inventário completo das ferramentas e tabela de migração: `../seo-audit/references/ferramentas-api.md`
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
## Anti-patterns
|
||||
|
||||
- Gerar relatorio sem dados reais (sempre usar MCPs)
|
||||
- Ignorar gap mobile/desktop
|
||||
- Nao priorizar recomendacoes (tudo parece igual)
|
||||
- Esquecer de verificar se site esta no GSC antes de tentar recolher dados
|
||||
- Relatorio sem accoes concretas e estimativas de impacto
|
||||
- Gerar relatório sem dados reais.
|
||||
- Omitir a cobertura do crawl (faz o relatório parecer melhor do que é).
|
||||
- Listar issues por contagem em vez de por impacto.
|
||||
- Apresentar estimativas de custo ou de tráfego como medições.
|
||||
- Recomendações sem esforço e impacto estimados.
|
||||
- Correr as fases pagas antes das grátis.
|
||||
|
||||
---
|
||||
|
||||
**Versao:** 2.1.0 | **Autor:** Descomplicar
|
||||
|
||||
---
|
||||
**Versão:** 3.0.0 | **Autor:** Descomplicar® | **Motor:** OpenSEO
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
{"date":"2026-07-30","issue":"Skill dependia de SEO Tools API (localhost:3000), Lighthouse MCP, GSC MCP e Ahrefs — nenhum operacional. Workflow inteiro não executável.","fix":"Reescrita sobre OpenSEO; fases grátis antes das pagas; cobertura de crawl obrigatória no relatório.","source":"auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
|
||||
@@ -1,144 +1,169 @@
|
||||
# Implementacao Tecnica - SEO Report
|
||||
# Implementação Técnica — SEO Report (OpenSEO)
|
||||
|
||||
## Workflow Tecnico
|
||||
## Workflow
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Input: URL] --> B{Site em GSC?}
|
||||
B -->|Sim| C[Recolher dados GSC]
|
||||
B -->|Nao| D[Skip GSC, aviso]
|
||||
graph TD
|
||||
A[Input: URL] --> B[whoami + list_projects]
|
||||
B --> C{Mercado correcto?}
|
||||
C -->|Não| C2[Passar locationCode 2620 + languageCode pt]
|
||||
C -->|Sim| D[GSC: dimensions query]
|
||||
C2 --> D
|
||||
|
||||
C --> E[Lighthouse Desktop]
|
||||
D --> E
|
||||
D --> E[GSC: dimensions page]
|
||||
E --> F[Dimensionar crawl:<br/>maxPages = páginas GSC + 25%]
|
||||
|
||||
E --> F[Lighthouse Mobile]
|
||||
F --> G[Core Web Vitals]
|
||||
G --> H[SEO Tools API]
|
||||
H --> I{Ahrefs habilitado?}
|
||||
F --> G[run_site_audit]
|
||||
G --> H[poll get_audit_status]
|
||||
H -->|running| H
|
||||
H -->|completed| I[get_audit_issues por severidade]
|
||||
|
||||
I -->|Sim| J[Recolher DR/UR]
|
||||
I -->|Nao| K[Skip Ahrefs]
|
||||
I --> J[Cruzar: páginas com procura<br/>E com defeito]
|
||||
J --> K{Fases pagas contratadas?}
|
||||
|
||||
J --> L[Processar dados]
|
||||
K --> L
|
||||
K -->|Sim| L[get_keyword_metrics<br/>get_backlinks_overview<br/>get_serp_results]
|
||||
K -->|Não| M[Saltar fases pagas]
|
||||
|
||||
L --> M[Gerar relatorio Markdown]
|
||||
M --> N[Criar Google Doc]
|
||||
N --> O[Partilhar com email]
|
||||
|
||||
O --> P[Retornar link]
|
||||
L --> N[Processar]
|
||||
M --> N
|
||||
N --> O[Markdown] --> P[Google Doc] --> Q[Partilhar]
|
||||
```
|
||||
|
||||
## Implementacao
|
||||
**O ponto crítico é o nó F.** Dimensionar o crawl a partir do GSC é o que distingue um relatório verdadeiro de um relatório limpo e falso.
|
||||
|
||||
---
|
||||
|
||||
## Sequência de chamadas
|
||||
|
||||
```javascript
|
||||
async function generateSEOReport(url, options = {}) {
|
||||
const {
|
||||
email = 'emanuelalmeidaa@gmail.com',
|
||||
competitors = [],
|
||||
includeAhrefs = true
|
||||
} = options;
|
||||
// 1. Contexto e mercado
|
||||
const me = await openseo.whoami();
|
||||
const projs = await openseo.list_projects();
|
||||
const projectId = projs[0].id;
|
||||
const MARKET = { locationCode: 2620, languageCode: 'pt' }; // Portugal
|
||||
|
||||
// 1. Validar URL
|
||||
if (!isValidURL(url)) {
|
||||
throw new Error('URL invalido');
|
||||
// 2. Search Console — paginar até esgotar (grátis)
|
||||
async function gscAll(dimensions) {
|
||||
const rows = [];
|
||||
let startRow = 0;
|
||||
while (true) {
|
||||
const r = await openseo.get_search_console_performance({
|
||||
projectId, dimensions, dateRange: 'last_3_months',
|
||||
rowLimit: 1000, startRow
|
||||
});
|
||||
const parsed = parseRows(r.text);
|
||||
rows.push(...parsed);
|
||||
if (!r.text.split('\n')[0].includes('more available') || !parsed.length) break;
|
||||
startRow += 1000;
|
||||
}
|
||||
return rows;
|
||||
}
|
||||
|
||||
// 2. Recolher dados em paralelo (melhor performance)
|
||||
const [
|
||||
lighthouseDesktop,
|
||||
lighthouseMobile,
|
||||
coreWebVitals,
|
||||
seoToolsData,
|
||||
gscData,
|
||||
ahrefsData
|
||||
] = await Promise.allSettled([
|
||||
mcp__lighthouse__run_audit(url, 'desktop'),
|
||||
mcp__lighthouse__run_audit(url, 'mobile'),
|
||||
mcp__lighthouse__get_core_web_vitals(url),
|
||||
fetch(`http://localhost:3000/seo-audit?url=${url}`).then(r => r.json()),
|
||||
getGSCData(url),
|
||||
includeAhrefs ? getAhrefsData(url) : null
|
||||
]);
|
||||
const byQuery = await gscAll(['query']);
|
||||
const byPage = await gscAll(['page']);
|
||||
|
||||
// 3. Processar e formatar
|
||||
const reportData = {
|
||||
url,
|
||||
date: new Date().toISOString().split('T')[0],
|
||||
scores: extractScores(lighthouseDesktop, lighthouseMobile),
|
||||
cwv: processCoreWebVitals(coreWebVitals),
|
||||
gsc: processGSCData(gscData),
|
||||
onPage: processOnPageData(seoToolsData),
|
||||
backlinks: processBacklinks(ahrefsData),
|
||||
recommendations: generateRecommendations(/* all data */)
|
||||
};
|
||||
// 3. Dimensionar o crawl a partir da realidade, não de um default
|
||||
const maxPages = Math.ceil(byPage.length * 1.25);
|
||||
|
||||
// 4. Gerar documento Markdown
|
||||
const markdown = generateReportMarkdown(reportData);
|
||||
// 4. Crawl (grátis) — assíncrono, exige poll
|
||||
const audit = await openseo.run_site_audit({
|
||||
projectId, url, maxPages, runLighthouse: true
|
||||
});
|
||||
let status;
|
||||
do {
|
||||
await sleep(30_000);
|
||||
status = await openseo.get_audit_status({ projectId, auditId: audit.id });
|
||||
} while (!status.text.includes('completed'));
|
||||
|
||||
// 5. Criar Google Doc
|
||||
const docResult = await mcp__google-workspace__create_doc({
|
||||
title: `Relatorio SEO - ${extractDomain(url)} - ${reportData.date}`,
|
||||
body_content: markdown,
|
||||
user_google_email: email
|
||||
// 5. Issues por severidade (grátis)
|
||||
const critical = await openseo.get_audit_issues({ projectId, auditId: audit.id, severity: 'critical' });
|
||||
const warning = await openseo.get_audit_issues({ projectId, auditId: audit.id, severity: 'warning' });
|
||||
|
||||
// 6. Fases pagas — so se contratadas
|
||||
if (options.paid) {
|
||||
const kw = await openseo.get_keyword_metrics({
|
||||
projectId, keywords: strikingDistance(byQuery).map(r => r.key), ...MARKET
|
||||
});
|
||||
|
||||
// 6. Retornar link
|
||||
return {
|
||||
success: true,
|
||||
doc_url: docResult.url,
|
||||
summary: reportData.recommendations.slice(0, 5)
|
||||
};
|
||||
const bl = await openseo.get_backlinks_overview({ projectId, target: domain });
|
||||
}
|
||||
```
|
||||
|
||||
## Propriedades GSC Disponiveis
|
||||
---
|
||||
|
||||
## Processamento — as funções que importam
|
||||
|
||||
```javascript
|
||||
const GSC_PROPERTIES = [
|
||||
'sc-domain:descomplicar.pt',
|
||||
'https://emanuelalmeida.pt/',
|
||||
'https://carstuff.pt/',
|
||||
'https://solarfvengenharia.com/',
|
||||
'https://aquisevende.pt/',
|
||||
'https://alojadamaria.com/',
|
||||
'https://e-commerce.descomplicar.pt/'
|
||||
];
|
||||
// GSC anonimiza queries: totais por query < totais por página.
|
||||
// Para números globais usar SEMPRE a vista por página.
|
||||
const globals = {
|
||||
clicks: sum(byPage, 'clicks'),
|
||||
impressions: sum(byPage, 'impressions'),
|
||||
ctr: sum(byPage, 'clicks') / sum(byPage, 'impressions')
|
||||
};
|
||||
|
||||
async function getGSCData(url) {
|
||||
const domain = extractDomain(url);
|
||||
const property = GSC_PROPERTIES.find(p => p.includes(domain));
|
||||
// O GSC não filtra por posição — filtrar do lado do cliente.
|
||||
const strikingDistance = rows => rows
|
||||
.filter(r => r.position >= 4 && r.position <= 20 && r.impressions >= 25)
|
||||
.sort((a, b) => b.impressions - a.impressions);
|
||||
|
||||
if (!property) {
|
||||
console.warn(`Site ${domain} nao esta no GSC. Dados GSC nao disponiveis.`);
|
||||
return null;
|
||||
}
|
||||
// Páginas com procura real enterradas fora das primeiras 4 páginas.
|
||||
const waste = rows => rows
|
||||
.filter(r => r.position > 40 && r.impressions >= 300)
|
||||
.sort((a, b) => b.impressions - a.impressions);
|
||||
|
||||
const analytics = await mcp__gsc__get_search_analytics({
|
||||
site_url: property,
|
||||
start_date: daysAgo(90),
|
||||
end_date: 'today',
|
||||
dimensions: ['query'],
|
||||
row_limit: 100
|
||||
});
|
||||
// O sinal mais accionável: primeira página, CTR nulo.
|
||||
// Não é ranking — é título e meta description.
|
||||
const titleProblem = rows => rows
|
||||
.filter(r => r.position <= 10 && r.impressions >= 200 && r.ctr < 0.005);
|
||||
|
||||
return analytics;
|
||||
}
|
||||
// Lixo nas queries do GSC (colagens do Google Ads, operadores site:).
|
||||
const isNoise = k =>
|
||||
(k.includes('ativado') && k.includes('correspond')) ||
|
||||
k.startsWith('-site:') || k.startsWith('=') ||
|
||||
k.length > 90 || k.includes('0,00');
|
||||
```
|
||||
|
||||
## Notas Tecnicas
|
||||
---
|
||||
|
||||
## Entrega
|
||||
|
||||
```javascript
|
||||
const doc = await googleWorkspace.docs_create_document({
|
||||
title: `Relatório SEO — ${domain} — ${today}`,
|
||||
user_google_email: email
|
||||
});
|
||||
await googleWorkspace.docs_append_text({ document_id: doc.id, text: markdown });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas técnicas
|
||||
|
||||
### Requisitos
|
||||
- SEO Tools API a correr: `~/mcp-servers/seo-tools-api/start.sh`
|
||||
- Google Workspace MCP configurado
|
||||
- GSC authentication (OAuth primeira vez)
|
||||
- OpenSEO acessível (`whoami` responde)
|
||||
- Propriedade ligada ao Search Console
|
||||
- `google-workspace` MCP para o documento
|
||||
|
||||
### Performance
|
||||
- Execucao paralela de tools (1m40s total)
|
||||
- Cache Lighthouse results (5 min TTL)
|
||||
- Rate limiting Ahrefs API (100 req/day free)
|
||||
### Tempos reais (medidos, descomplicar.pt, 07-2026)
|
||||
| Fase | Duração |
|
||||
|---|---|
|
||||
| GSC (2 dimensões, ~1700+474 linhas) | ~10s |
|
||||
| Crawl 600 páginas + Lighthouse 20 | ~4 min |
|
||||
| `get_audit_issues` | instantâneo |
|
||||
|
||||
### Erros Comuns
|
||||
- **Site nao em GSC:** Relatorio gerado sem dados GSC
|
||||
- **Lighthouse timeout:** Retry automatico (3x)
|
||||
- **Ahrefs rate limit:** Skip backlinks, aviso no relatorio
|
||||
### Limitações
|
||||
- **Issues sem URL:** `get_audit_issues` / `get_audit_pages` devolvem só contagens pela bridge MCP; `structuredContent.issues` não é entregue e `get_audit_pages` trunca em ~25 linhas. Usar `details.mcpMeta.url` para o link da UI.
|
||||
- **Sem medidor de créditos:** `whoami` não muda depois de chamadas pagas. Custos são estimativas.
|
||||
- **Lag do GSC:** últimos ~3 dias incompletos; datas em Pacific Time; máx. 16 meses.
|
||||
|
||||
### Erros comuns
|
||||
| Erro | Sintoma | Solução |
|
||||
|---|---|---|
|
||||
| `maxPages` por omissão (50) | Poucos issues, relatório "limpo" | Redimensionar pelo GSC, relançar |
|
||||
| Site fora do GSC | Fase GSC vazia | Gerar sem GSC, aviso destacado |
|
||||
| Mercado errado | Keywords em inglês/EUA | `locationCode: 2620`, `languageCode: "pt"` |
|
||||
| Cancelar o crawl cedo demais | Sem `auditId` utilizável | Fazer poll; 600 páginas ≈ 4 min |
|
||||
|
||||
---
|
||||
|
||||
**Actualizado:** 30-07-2026 | Substitui a implementação baseada em Lighthouse MCP + SEO Tools API + Ahrefs
|
||||
|
||||
@@ -203,13 +203,17 @@ Data: YYYY-MM-DD | Versao 2.0 (2026 Standards)
|
||||
## Anexos
|
||||
|
||||
### A. Metodologia
|
||||
- Lighthouse: 3 runs, mediana reportada
|
||||
- GSC: Ultimos 90 dias completos
|
||||
- Motor: OpenSEO (crawl same-origin, robots-aware) + Search Console
|
||||
- Crawl: [N] páginas de [M] com impressões no GSC — **declarar sempre a cobertura**
|
||||
- Search Console: últimos 3 meses; vista por página para totais (o GSC anonimiza queries)
|
||||
- Core Web Vitals: Lighthouse em amostra; páginas individuais via chrome-devtools
|
||||
- Thresholds: Google 2026 Standards
|
||||
- Custos de chamadas pagas: estimativas do schema, não medições
|
||||
|
||||
### B. Glossario
|
||||
- **DR**: Domain Rating (Ahrefs)
|
||||
- **INP**: Interaction to Next Paint (substitui FID em 2026)
|
||||
### B. Glossário
|
||||
- **Striking distance**: posição 4-20 com impressões relevantes — onde está o retorno
|
||||
- **KD**: Keyword Difficulty
|
||||
- **INP**: Interaction to Next Paint (substituiu o FID em 2026)
|
||||
- **E-E-A-T**: Experience, Expertise, Authoritativeness, Trust
|
||||
- **CTR**: Click-Through Rate
|
||||
|
||||
|
||||
Reference in New Issue
Block a user