Agentes de IA - MCP, REST e OpenAPI

Ligue o Claude Desktop, o Claude Code, o claude.ai, o ChatGPT ou o seu próprio agente ao Arachnide - três vias, 25 ferramentas, o prompt de sistema sugerido e o modelo de segurança.

Três vias, um só conjunto de ferramentas

Desde a 3.13, o Arachnide foi concebido para ser conduzido por um agente de IA: o seu, ou qualquer assistente que fale MCP (Claude) ou OpenAPI (Actions do ChatGPT, LangChain, n8n, Make…). O agente lê a auditoria que tem aberta, inicia rastreios que aparecem em direto na aplicação, explora páginas, obtém o plano de ação priorizado e o relatório de preparação GEO e, com a sua aprovação, corrige o site através dos conectores CMS. Tudo corre na sua máquina ou no seu servidor; nada é enviado a terceiros, exceto o que o modelo do seu próprio agente recebe.

Esta tabela é gerada a partir do repositório e só existe em inglês.

O token é criado no primeiro arranque do Arachnide e vive em ~/.arachnide/agent.json (modo 0600). Leia-o, copie-o ou renove-o em Definições → Agentes de IA; num servidor, defina antes ARACHNIDE_AGENT_TOKEN. O mesmo ecrã mostra as últimas chamadas recebidas dos agentes, os URLs MCP e OpenAPI, um campo de URL público para os túneis e excertos prontos a colar. As ferramentas são idênticas nas três vias: vêm de um único registo, src/agent/tools.mjs. crawl_id: "current" designa sempre o rastreio aberto na aplicação Arachnide.

Claude Desktop e Claude Code (local, stdio)

claude mcp add arachnide -- node /caminho/para/arachnide-seo-spider/src/mcp.mjs
# com um segredo para um site:
claude mcp add arachnide -e ARACHNIDE_WP_APP_PASSWORD="xxxx xxxx xxxx xxxx" -- node /caminho/para/arachnide-seo-spider/src/mcp.mjs

Claude Desktop: Settings → Developer → Edit Config, depois adicione o servidor e reinicie o Claude Desktop:

{
  "mcpServers": {
    "arachnide": {
      "command": "node",
      "args": ["C:\\Users\\you\\arachnide-seo-spider\\src\\mcp.mjs"],
      "env": { "ARACHNIDE_WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx", "ARACHNIDE_LANG": "pt" }
    }
  }
}

Depois basta pedir: «Audita www.o-meu-site.pt e corrige os títulos, as descrições e os textos alternativos em falta das páginas mais importantes.», ou use o prompt optimize_site. Com a aplicação em execução, pode também usar a via HTTP a partir do Claude Desktop: Definições → Agentes de IA → Copiar a configuração do Claude Desktop dá { "mcpServers": { "arachnide": { "url": "http://127.0.0.1:4000/mcp", "headers": { "Authorization": "Bearer ara_…" } } } }.

Variáveis de ambiente do servidor MCP: ARACHNIDE_LANG (etiquetas: en, fr, de, es, it, pt), ARACHNIDE_HOME (configuração e diário, por predefinição ~/.arachnide), ARACHNIDE_CONFIG (ficheiro de sites), ARACHNIDE_CRAWLS (pasta de rastreios, partilhada com a aplicação web por predefinição).

Conector personalizado claude.ai e agentes alojados (HTTP)

O claude.ai só alcança servidores na internet pública por HTTPS. Exponha a aplicação:

npm start                                        # Arachnide em http://localhost:4000
cloudflared tunnel --url http://localhost:4000   # ou: ngrok http 4000 · tailscale funnel 4000

No Arachnide → Definições → Agentes de IA, cole o URL público (por exemplo https://xyz.trycloudflare.com). No claude.ai → Settings → Connectors → Add custom connector: URL https://xyz.trycloudflare.com/mcp, e o token como bearer token. O token é a sua chave: nunca o partilhe. Para um agente alojado construído com o Claude Agent SDK ou a Messages API, adicione o servidor como servidor MCP com o mesmo URL e o cabeçalho Authorization, ou chame diretamente a via REST.

ChatGPT (GPT Actions) e agentes OpenAI

No construtor de GPT → Actions → Import from URL: https://<anfitrião>/openapi.json. Autenticação: API Key, tipo de autenticação Bearer, cole o token. Cada ferramenta torna-se uma ação (arachnide_get_summary, arachnide_action_plan…); as ferramentas só de leitura são marcadas como não consequentes, as ferramentas de escrita (aplicar, reverter, configurar) pedem confirmação. Com a OpenAI Agents / Responses API, aponte uma ferramenta MCP alojada para https://<anfitrião>/mcp com o cabeçalho bearer, ou envolva os endpoints REST como funções a partir da especificação OpenAPI.

As 25 ferramentas

Esta tabela é gerada a partir do repositório e só existe em inglês.

Todas as ferramentas de leitura (arachnide_get_summary, arachnide_list_issues, arachnide_get_issue, arachnide_action_plan, arachnide_search_pages, arachnide_geo_readiness) aceitam segment. Google Analytics 4: passe ga4_key_file (e ga4_property) ou ga4_csv às ferramentas de rastreio. Modo lista (3.21): mode: "list" com urls ou sitemap_url, max_pages até 200 000. GET /api/agent/tools devolve a mesma lista com o JSON Schema de cada entrada.

Preparação GEO

arachnide_geo_readiness pontua um rastreio em 100 para a visibilidade nas respostas de IA: crawlers de IA permitidos ou bloqueados no robots.txt (GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot, Google-Extended…), llms.txt, cobertura de dados estruturados e tipos orientados para respostas, profundidade do conteúdo e páginas pobres, duplicados, higiene dos títulos / descrições / H1 / Open Graph, com uma pontuação por parte e recomendações ordenadas. Os mesmos sinais aparecem no separador Robots, IA e sitemaps da aplicação.

Prompt de sistema sugerido

Cole isto no prompt de sistema do seu agente (instruções do projeto Claude, instruções do GPT, system do Agent SDK):

You are an SEO and GEO (generative engine optimisation) consultant. You work with Arachnide SEO Spider through its tools.
- When the user mentions "the audit", "the site" or "the crawl", use crawl_id "current": it is what they see in the Arachnide app. Call arachnide_list_crawls if unsure.
- Start every analysis with arachnide_get_summary, then arachnide_action_plan (what to do first) and arachnide_geo_readiness (visibility in AI answers). Explain in plain language, cite numbers, never invent data that is not in the tool results.
- To explore, use arachnide_search_pages (sorted by Link Score) and arachnide_get_page; to write content, read the real page with arachnide_fetch_page first.
- A new crawl: arachnide_start_crawl, then poll arachnide_crawl_status every 15-30 s; the user can watch it in the app.
- Changes to the live site: arachnide_suggest_fixes → write the values yourself (same language as the site, natural, unique, within pixel limits) → arachnide_preview_changes → show a before/after table → wait for an explicit "yes" → arachnide_apply_changes → arachnide_verify_changes. Small batches (10-30), most important pages first. Every batch can be undone with arachnide_rollback_changes.
- Never ask the user to paste passwords or API keys in the chat: configure sites with "env:VARIABLE" references.

Ligar um site (servidor MCP)

Os sites vivem em ~/.arachnide/sites.json. O agente cria a entrada com arachnide_configure_site; os segredos nunca passam pelo chat: o ficheiro guarda env:VARIABLE e o valor vem do ambiente do servidor MCP. Campos que o agente pode alterar: título SEO, meta description, H1, canonical, noindex, texto alternativo das imagens, redirecionamentos 301.

{
  "sites": {
    "my-blog": {
      "url": "https://www.my-blog.com",
      "connector": "wordpress",
      "user": "admin",
      "appPassword": "env:ARACHNIDE_WP_APP_PASSWORD",
      "policy": { "allowedFields": ["seo_title", "meta_description", "image_alt"], "maxChangesPerBatch": 30 }
    }
  }
}

As definições e os pré-requisitos dos conectores estão listados em Corrigir em 1 clique.

Modelo de segurança

• O token é obrigatório em /mcp e /api/agent/*; /openapi.json é público (não contém nenhum segredo) para que os construtores de GPT o possam importar. /api/agent/settings (token, registo) só responde à interface local.
• Os pedidos são limitados (240 por minuto e por IP) e as últimas 50 chamadas são mostradas na aplicação.
• Desative os agentes a qualquer momento com o interruptor em Definições → Agentes de IA; renove o token se ele for divulgado.
• Exponha o Arachnide apenas por HTTPS (túnel ou proxy inverso). Atrás de um proxy, encaminhe X-Forwarded-Proto / X-Forwarded-Host ou defina o URL público na aplicação (ARACHNIDE_PUBLIC_URL).
• As ferramentas de escrita passam pela mesma política que o servidor MCP: campos permitidos por site, tamanho dos lotes, modo só de leitura, diário e reversão. As ferramentas de aplicação e de reversão estão assinaladas como destrutivas, pelo que o Claude Code e o Claude Desktop pedem permissão. Só o anfitrião do próprio site é aceite.

Exemplos

# resumo da auditoria aberta na aplicação
curl -X POST https://<anfitrião>/api/agent/arachnide_get_summary -H "Authorization: Bearer ara_…" -H "Content-Type: application/json" -d '{}'
# as 10 páginas com o Link Score mais alto em /blog/
curl -X POST https://<anfitrião>/api/agent/arachnide_search_pages -H "Authorization: Bearer ara_…" -H "Content-Type: application/json" -d '{"folder":"/blog/","limit":10}'
# preparação GEO de um rastreio guardado
curl -X POST https://<anfitrião>/api/agent/arachnide_geo_readiness -H "Authorization: Bearer ara_…" -H "Content-Type: application/json" -d '{"crawl_id":"www.example.com_2026-10-19T09-00-00"}'

Os erros são JSON: 400 argumentos inválidos (com o caminho do campo), 401 token em falta ou inválido, 404 ferramenta, rastreio, problema ou página desconhecidos, 409 já há um rastreio em curso.