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,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
|
||||
|
||||
Reference in New Issue
Block a user