Ranki.io SEO/AEO consultant

Ranki MCP — SEO, AEO, otimização de velocidade e imagens gratuito para Cursor, Claude Code, Windsurf e ChatGPT

O MCP que não apenas reporta — seu agente corrige. Audita qualquer URL para SEO e Otimização para Mecanismos de Resposta, mede Core Web Vitals reais via Google PageSpeed Insights e instrui seu agente a converter imagens para AVIF e WebP, reescrever tags <img> em <picture> responsivas com srcset e alt, inserir schema JSON-LD, gerar sitemap.xml / llms.txt / robots.txt, classificar páginas ocultas — e então reexecuta a auditoria para provar que a pontuação melhorou. Tudo dentro do Claude Code, Claude Desktop, Cursor, Windsurf e ChatGPT Desktop.

Instale em uma linha

npx @ranki.io/cli install

A CLI detecta automaticamente qual editor de IA você tem instalado (Claude Code, Claude Desktop, Cursor, Windsurf, ChatGPT Desktop), escreve a configuração MCP correta no lugar certo e baixa o arquivo Skill complementar do repositório ranki-seo-skills. Execute npx @ranki.io/cli update novamente mais tarde para atualizar a Skill; npx @ranki.io/cli check verifica a configuração.

Prefere o trecho JSON manual? Exemplos para cada editor estão na seção Instalação abaixo.

Duas implementações, mesmas ferramentas

Este repositório fornece o MCP em duas implementações equivalentes para que você possa escolher a que melhor se adapta à sua stack:

• server/ — referência PHP 8.4, a implantação de produção que alimenta o mcp.ranki.io. Hospedada, robusta, zero dependências, executada atrás do Cloudflare. É sobre isso que o mcp.ranki.io é construído.
• ts-server/ — referência Node / TypeScript, publicada como @ranki.io/seo-aeo-mcp no npm. Alternativa nativa em Node para desenvolvedores que preferem ferramentas JavaScript, instalável via npx -y @ranki.io/seo-aeo-mcp (stdio) ou npx @ranki.io/seo-aeo-mcp --serve (HTTP).

Ambas expõem as mesmas 22 ferramentas com a mesma saída JSON, proteção SSRF, semântica de limite de taxa e postura de segurança. A implementação TS executa as 15 ferramentas gratuitas nativamente no Node e faz proxy das 7 ferramentas de ponte pagas para a mesma API REST em app.ranki.io que o servidor PHP usa. Nenhuma delas abre um banco de dados — as ferramentas pagas passam pelo middleware ApiKeyAuth do Laravel e são limitadas aos dados do usuário solicitante.

O que ele realmente faz — 22 ferramentas

O servidor MCP expõe 22 ferramentas. Seu agente as chama como qualquer outra ferramenta MCP; elas retornam relatórios em Markdown que seu agente renderiza inline e então age — convertendo arquivos, reescrevendo HTML, gerando novos, commitando o resultado.

Auditoria

• audit_seo(url) — Scorecard de SEO on-page com 10 verificações: comprimento do título, meta description, unicidade do H1, canonical, viewport, HTTPS, completude do OpenGraph, cobertura de alt em imagens, contagem de links internos, presença de JSON-LD. Retorna pontuação de 0 a 100 com receitas de correção por falha.
• audit_aeo(url) — Scorecard de Otimização para Mecanismos de Resposta com 8 verificações: JSON-LD FAQPage / Article, introdução definitória com menos de 80 palavras, linha de autor, presença de llms.txt, robots.txt permite GPTBot / ClaudeBot / PerplexityBot, cabeçalhos H2/H3 em estilo de resposta, tabelas de comparação.
• audit_hidden_pages(urls, domain) — classifica cada caminho como robots-disallow, noindex, keep ou unsure com justificativa. Detecta rotas de admin, endpoints de API, rascunhos, páginas de login, painéis de conta, páginas de agradecimento, artefatos de build e URLs de resultados de busca. Retorna um bloco robots.txt pronto para colar.

Velocidade e imagens — esta é a parte que mais ninguém faz

• audit_speed(url, strategy) — pontuações reais do Lighthouse (Performance, Acessibilidade, SEO, Melhores Práticas) e Core Web Vitals (LCP, CLS, INP, FCP, TTFB) via Google PageSpeed Insights. Retorna oportunidades de imagem com bytes economizados por arquivo, JS / CSS bloqueadores de renderização e auditorias de SEO on-page com falha. A estratégia padrão é mobile (o Google classifica com foco em dispositivos móveis).
• audit_core_web_vitals(url) — um parágrafo por métrica com a receita literal de correção. "O elemento LCP é hero.png com 2,4 MB, converter para WebP economiza 1,8 MB → -1,1s no LCP." Extrai a URL do elemento LCP do Lighthouse para que o agente saiba exatamente qual arquivo otimizar.
• optimize_images(images, max_width) — para cada imagem: formato alvo (AVIF + WebP), larguras responsivas 1×/2×, sugestão de texto alternativo, os comandos literais sharp-cli / cwebp / avifenc e um bloco <picture> pronto para colar com srcset. Seu agente executa a conversão localmente no repositório e reescreve as tags <img>.

Gerar

• generate_sitemap_xml(urls) — constrói um sitemap.xml pronto para deploy a partir de uma lista de URLs com timestamps lastmod atuais.
• generate_llms_txt(site_name, summary, key_pages) — gera llms.txt, o padrão emergente para informar aos rastreadores de IA o que é seu site e quais páginas citar.
• generate_robots_txt(sitemap_url, allow_ai, disallow_paths) — constrói um robots.txt que permite ou nega explicitamente GPTBot, ChatGPT-User, ClaudeBot, anthropic-ai, PerplexityBot e Google-Extended.

Conteúdo e estratégia

• seo_starter_kit(domain) — retorna os quatro arquivos de base que a maioria dos sites criados por vibe-coding não possuem (robots.txt, sitemap.xml, llms.txt, JSON-LD) prontos para colar no seu repositório.
• find_topic_ideas(url) — lê sua página inicial, infere seu nicho e retorna um briefing estruturado para gerar 15 tópicos de artigos com intenção informacional, comercial e transacional, com critérios de priorização.
• find_keyword_gap(url, competitors) — retorna uma metodologia passo a passo para encontrar palavras-chave nas quais os concorrentes ranqueiam, mas você não. Se nenhum concorrente for informado, instrui seu editor a perguntar primeiro.
• propose_titles_metas(urls, focus_keyword) — extrai o título real, h1 e primeiro parágrafo de cada URL (ou aceita uma descrição em texto livre para páginas não publicadas) e retorna uma tabela Markdown com 5 candidatos a título e meta description por página em 5 ângulos (descritivo, focado em benefício, formato de pergunta, número específico, palavra-chave primeiro). Cada candidato é sinalizado quanto à conformidade de comprimento.
• explain_seo_terms(category) — glossário de referência com mais de 40 termos de SEO e AEO: SEO, AEO, GEO, JSON-LD, FAQPage, canonical, llms.txt, Core Web Vitals, E-E-A-T, atualização de conteúdo útil, doorway pages e mais. Filtre por categoria: básico, AEO, técnico, analytics, penalidade.

Instalar

• install_skill(agent) — retorna os comandos de instalação da Skill ranki-seo-skills para Claude Code, Claude Desktop, Cursor, Windsurf, Projetos web do Claude.ai e agentes AGENTS.md genéricos.

Sua conta Ranki.io — dados reais de ranqueamento dentro do seu IDE (chave de API paga)

• get_account() — whoami para sua chave de API: nome, e-mail, plano, limites diários e mensais, uso atual.
• list_projects() — lista projetos na sua conta Ranki.io.
• list_articles(project_id) — índice paginado de artigos em um projeto: nano_id, título, status, idioma, focus_keyword[], esboço do TOC, contagem de palavras, pontuação de SEO. Filtro de status opcional.
• get_article(article_id) — busca um único artigo pelo seu nano_id: título, HTML, palavras-chave de foco, índice, URLs de imagens incorporadas, pontuação de SEO.
• list_rank_tracking(project_id) — resumo do Google Search Console para um projeto: totais de 28 dias, top 20 palavras-chave por cliques, top 20 palavras-chave de oportunidade (posição > 10 com impressões — as vitórias fáceis).
• list_gsc_keywords(project_id) — lista completa e paginada de palavras-chave do GSC, ordenável por cliques / impressões / posição / CTR.
• ai_visibility(project_id) — snapshots registrados de citação por IA: quais dos seus tópicos rastreados apareceram nas SERPs do ChatGPT, Claude, Perplexity e Google AI Overviews no momento da captura.

Como é uma sessão típica

You:    audit my site speed and fix the slow images

Claude: → Calling ranki.audit_speed(url="https://myapp.dev")
        ← Lighthouse: 42 perf · LCP 4.8s · 3 images blocking the paint.
        → Calling ranki.optimize_images([hero.png, banner.jpg, card.png])…
        ← 3 files, recipes returned.
        → Running sharp-cli to convert hero.png → hero.avif + hero.webp + hero@2x.avif…
        → Editing app/page.tsx — rewriting <img> as <picture srcset>, adding alt text…
        → Calling ranki.audit_speed again to verify…
        ← Lighthouse: 96 perf · LCP 1.4s.

You:    now find pages that shouldn't be in Google

Claude: → Calling ranki.audit_hidden_pages(domain="https://myapp.dev")
        ← 8 robots-disallow, 12 noindex, 118 keep, 4 unsure.
        → Editing public/robots.txt to disallow /admin /dashboard /checkout /account…
        → Adding <meta name="robots" content="noindex"> to app/search/page.tsx…
        Done. Submit URL-removal requests in Search Console for the 8 admin pages.

O arquivo Skill (em ranki-seo-skills) informa ao seu agente quando chamar qual ferramenta, em qual ordem e onde no seu repositório aplicar cada correção.

Limites de taxa

Nível	Limite diário	Escopo	Ferramentas disponíveis
Sem chave	5 chamadas	por IP	15 ferramentas gratuitas (auditorias, geradores, velocidade, otimização de imagem, estratégia de conteúdo, instalação)
Chave de API Ranki.io	500 chamadas	por chave	Todas as 22 ferramentas, incluindo as 7 ferramentas de ponte que leem suas palavras-chave reais do GSC, rastreamento de ranqueamento, citações de IA, lista de projetos e biblioteca de artigos da sua conta Ranki.io

Obtenha uma chave em app.ranki.io/developer. X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset são retornados em cada resposta. As mensagens de erro do dispatcher incluem a contagem regressiva para reset e o caminho de upgrade.

---

Instalação

Claude Desktop / Claude Code (recomendado para a maioria dos vibe-coders)

Adicione ao ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ranki": {
      "command": "npx",
      "args": ["-y", "@ranki.io/mcp"],
      "env": { "RANKI_API_KEY": "rk_live_..." }
    }
  }
}

Reinicie o Claude Desktop. O indicador MCP deve mostrar ranki com 22 ferramentas.

Cursor (transporte HTTP, sem necessidade de npx)

.cursor/mcp.json no seu projeto:

{
  "mcpServers": {
    "ranki": {
      "url": "https://mcp.ranki.io",
      "headers": { "X-API-Key": "rk_live_..." }
    }
  }
}

ChatGPT Desktop, Continue.dev, Zed, qualquer coisa compatível com MCP

Se o cliente suportar MCP stdio, use o trecho do Claude Desktop. Se suportar MCP HTTP, use o trecho do Cursor.

Obtenha sua chave de API gratuita

Visite app.ranki.io/developer e clique em Reveal. Sua chave já existe — toda conta Ranki.io recebe uma criada automaticamente. As ferramentas de consultoria gratuitas funcionam sem chave (5 chamadas/IP/dia); as ferramentas de ponte list_projects e get_article exigem uma.

---

Como os vibe-coders usam

Cenário 1: "Acabei de publicar um site, o que eu faço?"

You: I just shipped my Next.js app at https://myapp.com. What SEO do I need?

Claude (via Ranki MCP):
  → Calling seo_starter_kit(domain="myapp.com")
  ← [Returns robots.txt + sitemap.xml + llms.txt + JSON-LD templates]
  → Writing public/robots.txt
  → Writing public/sitemap.xml (enumerating pages from app/ directory…)
  → Writing public/llms.txt
  → Adding JSON-LD <script> to app/layout.tsx
  → Calling audit_seo to verify…
  ← Score: 92/100. 🎉

Cenário 2: "Por que o ChatGPT não está citando meus documentos?"

You: Why doesn't ChatGPT cite my docs site?

Claude (via Ranki MCP):
  → Calling audit_aeo(url="https://docs.myproduct.com")
  ← Score 38/100. Failing: no FAQPage schema, no llms.txt, robots.txt blocks ClaudeBot.
  → Fixing each failure in your repo…
  ← Score 88/100. Re-deploy and ChatGPT should pick it up within 7-14 days.

Cenário 3: "Não sei quais posts de blog escrever"

You: I have a Stripe alternative landing page but the blog is empty. Help.

Claude (via Ranki MCP):
  → Calling find_topic_ideas(url="https://mystripe-alt.com")
  ← [Returns brief with topic generation methodology + 15-topic structure]
  → [Generates 15 topics organized by intent, picks top 3]
  ← Recommended first 3 articles:
     1. "How to switch payment processors without losing customers" (transactional)
     2. "Stripe vs us: side-by-side fee comparison for $10K/mo MRR" (commercial)
     3. "What is interchange-plus pricing and why most SaaSes overpay" (informational)

Cenário 4: "Quais palavras-chave de lacuna estou perdendo?"

You: My competitors are stripe.com and lemonsqueezy.com. What am I missing?

Claude (via Ranki MCP):
  → Calling find_keyword_gap(url="https://mystripe-alt.com",
                              competitors=["stripe.com","lemonsqueezy.com"])
  ← [Returns methodology + per-competitor analysis steps]
  → Crawling /blog on both competitors…
  → Cross-referencing against your sitemap…
  ← 5 high-value gaps found:
     - "PCI compliance for small SaaS" (covered by Stripe, not you)
     - "How to handle subscription dunning" (covered by both, not you)
     - … 3 more

---

Arquitetura

┌────────────────────────┐         ┌──────────────────────────┐
│  Claude / Cursor / etc │         │  mcp.ranki.io (PHP)      │
│                        │         │                          │
│  1. Sees 22 tools      │ JSON-RPC│  - 22 tool definitions   │
│  2. Decides to use one ├────────►│  - HTTP + stdio (npx)    │
│  3. Receives advice    │         │  - 5/IP or 500/key per   │
│  4. Acts on the repo   │         │    UTC day rate limit    │
│                        │         │  - REST API bridge       │
└────────────────────────┘         └────────────┬─────────────┘
                                                │ (only for keyed tools)
                                                ▼
                                   ┌──────────────────────────┐
                                   │  app.ranki.io REST API   │
                                   │  /api/v1/projects        │
                                   │  /api/v1/articles/...    │
                                   └──────────────────────────┘

Dois transportes

• stdio (Claude Desktop, Claude Code, maioria dos clientes MCP) — instale o pacote npm @ranki.io/mcp, que é um shim Node.js de 50 linhas que faz proxy de JSON-RPC stdio para https://mcp.ranki.io.
• HTTP (Cursor, clientes personalizados) — aponte diretamente para https://mcp.ranki.io. Não é necessária instalação do Node.

Layout do repositório

ranki-mcp/
├── server/                     # PHP MCP server (deployed to mcp.ranki.io)
│   ├── public/index.php        #   GET → marketing landing page (HTML)
│   ├── index.php               #   POST → JSON-RPC 2.0 dispatcher
│   ├── lib/
│   │   ├── jsonrpc.php         #   JSON-RPC reply helpers
│   │   ├── registry.php        #   Tool registry + REST API bridge
│   │   └── ratelimit.php       #   Per-IP rate limit (5/day for free tier)
│   └── tools/
│       ├── seo_starter_kit.php
│       ├── find_topic_ideas.php
│       ├── find_keyword_gap.php
│       ├── audit_aeo.php
│       ├── audit_seo.php
│       ├── generate_sitemap_xml.php
│       ├── generate_llms_txt.php
│       ├── generate_robots_txt.php
│       ├── list_projects.php
│       └── get_article.php
└── npx/                        # Node.js stdio shim (published as @ranki.io/mcp)
    ├── package.json
    ├── index.js                #   ~50 lines: stdin→POST→stdout
    └── README.md

---

SEO vs AEO — qual a diferença?

SEO (Search Engine Optimization) é fazer seu site ranquear nos 10 links azuis clássicos do Google. Os sinais: title tags, meta descriptions, H1, canonicals, sitemap, links internos, velocidade da página, compatibilidade com dispositivos móveis, HTTPS. Ferramentas como Ahrefs / SEMrush / SurferSEO pontuam isso.

AEO (Answer Engine Optimization) é fazer seu site ser citado quando ChatGPT, Claude, Perplexity ou Google AI Overviews respondem à pergunta de um usuário. Os sinais são diferentes:

• JSON-LD FAQPage — o maior sinal de citação.
• Introduções definitórias — o primeiro parágrafo é uma resposta concisa "X é …".
• Linha de autor + E-E-A-T — LLMs preferem fontes citadas com autores nomeados.
• llms.txt — convite explícito para LLMs usarem seu conteúdo.
• robots.txt permitindo bots de IA — GPTBot / ClaudeBot / PerplexityBot NÃO devem ser bloqueados.
• Cabeçalhos em estilo de resposta — H2/H3 formulados como perguntas ("O que é X?", "Como o X funciona?").
• Tabelas de comparação — o elemento HTML com maior taxa de citação nos AI Overviews.

O audit_aeo verifica todos esses 8 e diz à sua IA exatamente o que corrigir. A partir de 2026, o tráfego AEO é o canal de SEO de crescimento mais rápido e a maioria dos sites tem cobertura zero.

---

llms.txt — o padrão emergente de busca por IA

Inspirado pelo robots.txt, mas para LLMs. Um arquivo Markdown em /llms.txt informa aos rastreadores de IA:

• Sobre o que é seu site (em linguagem clara, não metadados).
• Quais páginas são mais importantes.
• Como citar você.

# Acme Corp

> Acme makes the SDK for shipping React Native apps faster.

## Key pages

- [Homepage](https://acme.dev/)
- [Documentation](https://acme.dev/docs)
- [Pricing](https://acme.dev/pricing)
- [Blog](https://acme.dev/blog)

## About

- Founded 2024, based in Berlin.
- Used by 12,000+ teams including Linear and Notion.
- Open source SDK on github.com/acme/sdk.

Use generate_llms_txt para criar um em 5 segundos.

---

Self-hosting

O servidor MCP é PHP 8.4 puro — sem framework, sem banco de dados, sem dependências do Composer. Coloque o diretório server/ atrás de um vhost Nginx servindo public/index.php e pronto.

server {
  server_name mcp.yourdomain.com;
  root /var/www/ranki-mcp/server/public;
  index index.php;
  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }
  location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.4-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
  }
}

O lib/ratelimit.php usa arquivos em /tmp/ para limitação de taxa por IP — funciona imediatamente. Para limitação de taxa com Redis em escala, troque a implementação.

---

Contribuindo

PRs são bem-vindos para novas ferramentas de consultoria. Para adicionar uma ferramenta:

1. Crie server/tools/your_tool.php retornando um function (array $args, string $apiKey): array chamável.
2. Retorne rk_mcp_text_content("...your structured advice...").
3. Registre a ferramenta em server/lib/registry.php sob rk_mcp_tool_definitions().

Nomenclatura de ferramentas: <verb>_<noun> snake_case (ex.: audit_aeo, find_topic_ideas).

Filosofia da ferramenta: retorne dados + instruções para a IA chamadora, nunca chame um LLM você mesmo.

---

Perguntas Frequentes

Isso custa dinheiro?

As ferramentas de consultoria (tudo exceto list_projects / get_article) são gratuitas — 5 chamadas por IP por dia UTC. Para remover esse limite, obtenha uma chave de API gratuita em app.ranki.io/developer. As ferramentas de ponte exigem uma chave porque acessam seus dados privados do Ranki.io.

O Ranki MCP usa meus créditos do Claude?

Sim — e apenas os seus. Nós nunca fazemos chamadas a LLMs. O servidor MCP retorna conselhos estruturados; seu Claude / Cursor avalia e age sobre eles usando seus próprios créditos.

Por onde os dados fluem?

• As ferramentas de consultoria (audit_*, generate_*, seo_starter_kit, find_*) buscam a URL que você passa (sem outras chamadas de rede).
• As ferramentas de ponte (list_projects, get_article) chamam app.ranki.io/api/v1/... via HTTPS com sua X-API-Key.
• Não registramos os corpos das requisições. Registramos IP + nome da ferramenta + status da resposta para limitação de taxa + depuração.

É código aberto?

Sim — licença MIT, código-fonte completo neste repositório.

Posso executá-lo dentro do VPC da minha empresa?

Sim — server/ é PHP puro, sem dependências de serviços externos, exceto app.ranki.io para as ferramentas de ponte (que você pode desabilitar removendo esses arquivos de ferramenta).

Como isso é diferente de concorrentes como Surfer / Frase / Outrank?

Esses são painéis SaaS que auditam uma URL por vez e recomendam mudanças. O Ranki MCP é uma camada de protocolo que permite que sua IA use essas auditorias em linha enquanto escreve código no seu IDE. Formato diferente, preço diferente (gratuito), público diferente (vibe-coders, não profissionais de SEO).

Sou um vibe-coder e não tenho ideia do que AEO significa.

É literalmente para você. Comece com seo_starter_kit("yourdomain.com") — seu Claude irá guiá-lo por tudo.

Vocês treinarão IA com meus dados?

Nós não treinamos modelos. Nós não temos modelos. Somos uma fina camada de consultoria sobre verificações determinísticas.

---

Licença

MIT. Veja LICENSE.

Construído com cuidado por Ranki.io — automação de AI SEO + AEO para fundadores, agências e criadores.