Agent Ready

agent-ready-mcp

Servidor MCP para Agent Ready — verifica qualquer URL quanto à legibilidade para agentes de IA de acordo com a Especificação de Legibilidade para Agentes da Vercel, o padrão llmstxt.org e manifestos de protocolo de agentes (cartões de servidor MCP, A2A, agents.json, agent-permissions.json, UCP, x402, NLWeb). 72 verificações em quatro famílias de especificações — 40 verificações de site e página (15 em todo o site + 25 por página), 10 contra llmstxt.org e 22 contra manifestos de protocolo de agentes — cada uma com orientação de correção por verificação, além de uma subpontuação separada de acessibilidade proveniente de 23 verificações de WCAG 2.2 / estabilidade de layout.

Hospedado em https://agent-ready.dev/api/v1/mcp (HTTP Streamable); este pacote é um wrapper stdio fino em torno dos mesmos endpoints REST, distribuído via npm para clientes MCP locais (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf).

Recursos

• scan_site — nova verificação de legibilidade para agentes em qualquer URL. Funciona sem chave no nível gratuito anônimo (3 verificações/30 dias por IP, profundidade de 25 páginas, síncrono); com uma chave Pro, verifica até 250 páginas, consultando a API hospedada por até 60s.
• get_scan — recupera uma verificação executada anteriormente pelo id (chave Pro necessária — o histórico de verificações é limitado à conta).
• ask — busca em linguagem natural (NLWeb) sobre a própria metodologia, verificações e especificações do Agent Ready. Pública, sem necessidade de chave de API; retorna resultados tipados com Schema.org.
• validate_structured_data — valida o JSON-LD de uma página (ou colado) contra as verificações de dados estruturados do Agent Ready. Pública, sem necessidade de chave de API; o modo de colagem não requer rede, então um agente pode verificar JSON-LD que acabou de criar.
• Três prompts de descoberta — scan, interpret_scan, remediation_plan. Fluxos de trabalho de ponta a ponta, de URL → pontuação → plano de correção.
• SKILL.md — descritor de Skill da Claude incluído em skills/agent-ready/ para roteamento de ativação.

Configuração

Nenhuma chave é necessária para começar: scan_site, ask e validate_structured_data funcionam anonimamente prontos para uso (scan_site na cota anônima gratuita — 3 verificações por 30 dias por IP, com profundidade de 25 páginas). Uma chave de API Pro do Agent Ready desbloqueia 50 verificações/mês, profundidade de 250 páginas, histórico de verificações (get_scan) e monitoramento semanal — cadastre-se em agent-ready.dev e emita uma chave no painel. O bloco env nas configurações abaixo é opcional; omita-o para executar sem chave.

Claude Desktop

Adicione a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "agent-ready": {
      "command": "npx",
      "args": ["-y", "agent-ready-mcp@latest"],
      "env": {
        "AGENT_READY_API_KEY": "ar_live_..."
      }
    }
  }
}

Claude Code

claude mcp add agent-ready \
  -e AGENT_READY_API_KEY=ar_live_... \
  -- npx -y agent-ready-mcp@latest

Cursor / VS Code / Windsurf

.cursor/mcp.json, .vscode/mcp.json ou ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "agent-ready": {
      "command": "npx",
      "args": ["-y", "agent-ready-mcp@latest"],
      "env": {
        "AGENT_READY_API_KEY": "ar_live_..."
      }
    }
  }
}

Variáveis de ambiente

Variável	Obrigatória	Padrão	Finalidade
AGENT_READY_API_KEY	Não	—	Token Bearer Pro do painel do Agent Ready. Sem ele, scan_site usa o nível gratuito anônimo e get_scan fica indisponível.
AGENT_READY_API_URL	Não	https://agent-ready.dev	Substituição para implantações auto-hospedadas ou de staging.
AGENT_READY_SCAN_TIMEOUT_MS	Não	60000	Por quanto tempo scan_site consulta antes de retornar um placeholder running.
AGENT_READY_GET_TIMEOUT_MS	Não	5000	Tempo limite para get_scan e buscas por consulta.

Ferramentas

Ferramenta	Entradas	Retorna
scan_site	url (string, obrigatória), pageLimit (número, opcional, máx. 2000 — limitado pelo seu plano; fixo em 25 sem chave)	Objeto de verificação: pontuação Vercel 0–100, subpontuação llms.txt 0–100, descobertas por verificação com strings howToFix. Execuções sem chave usam o nível gratuito anônimo (3 verificações/30 dias por IP) e retornam de forma síncrona; com chave Pro, retorna o placeholder { id, status: "running" } se a verificação exceder o prazo de consulta.
get_scan	id (string, id da verificação de uma chamada scan_site anterior)	Mesmo objeto de verificação que scan_site, ou not_found se o id for desconhecido ou não pertencer ao usuário autenticado. Chave Pro necessária.
ask	q (string, obrigatória), itemType (filtro de corpus opcional), mode (opcional, list ou summarize)	/ask NLWeb sobre a metodologia, verificações e especificações do Agent Ready. Pública — sem necessidade de chave de API. Objetos de resultado tipados com Schema.org.
validate_structured_data	exatamente um de url (string) ou jsonld (string)	Resultado de dados estruturados da série D: mode, url, descobertas por verificação e um veredito summary. Pública — sem necessidade de chave de API. Valida lint de esquema + coerência de agente que os validadores de primeira parte não validam.

Prompts

Prompt	Argumentos	O que faz
scan	url	Nova verificação + resumo de alto nível (pontuação, classificação, 3–5 principais falhas, próximo passo).
interpret_scan	id	Explicação em linguagem simples das descobertas de uma verificação anterior, agrupadas por categoria.
remediation_plan	id, focus opcional ("seo" ou "agents")	Documento de correção priorizado com grupos Agora/Próximo/Depois e ids de verificação por correção.

Exemplo de fluxo de trabalho

You: Use agent-ready to scan https://my-saas.com
Claude: [calls scan_site] Your site scored 78/100 (Good) on the Vercel Agent
        Readability Spec. The top 3 fixes: …
You: Can you build me a remediation plan?
Claude: [calls remediation_plan with the scan id] Here's the prioritised list…

Skill (Anthropic Claude Skills)

Um SKILL.md está em skills/agent-ready/SKILL.md dentro do pacote. Para usá-lo no Claude Desktop / Claude Code, copie o diretório skills/agent-ready/ para ~/.claude/skills/.

A skill descreve quando ativar (URL + intenção de auditoria de legibilidade), qual ferramenta escolher, como apresentar os resultados da verificação sem despejar JSON bruto e quando adiar para outras ferramentas (SEO geral, perfil de desempenho, edição de código).

Como funciona

Este pacote é um wrapper fino stdio→HTTPS:

MCP client (stdio) ↔ agent-ready-mcp ↔ HTTPS ↔ agent-ready.dev/api/v1/scans

Toda a execução de verificação, persistência e aplicação de cota do nível Pro acontecem no servidor hospedado. O pacote npm apenas traduz entre MCP JSON-RPC via stdio e a API REST.

Se preferir usar o servidor MCP hospedado diretamente (transporte HTTP Streamable, sem instalação local), aponte seu cliente MCP para https://agent-ready.dev/api/v1/mcp com Authorization: Bearer ar_live_....

Metodologia

As 72 verificações, seus pesos e a fórmula de pontuação estão documentados em agent-ready.dev/methodology. Tanto manifest.json quanto server.json neste repositório estão em conformidade com os esquemas de registro relevantes (Glama Marketplace v0.3 e registro MCP 2025-12-11, respectivamente).

Desenvolvimento

npm install
npm run build       # → dist/mcp-server.mjs
npm test
npm run typecheck

Lançamento

Consulte RELEASE.md. É a fonte da verdade para superfícies de versão, verificações locais, envio de tags, o fluxo de trabalho de lançamento do GitHub Actions e as etapas manuais pós-lançamento.

Licença

MIT — consulte LICENSE.