WellMarked

WellMarked MCP

Um servidor MCP autônomo extremamente leve para automação de raspagem web eficiente em tokens para agentes de IA, projetado para rodar localmente ou em servidores.

~98% menores snapshots de páginas web do que HTML bruto.

---

O oficial Model Context Protocol (MCP) para WellMarked.io. Dê aos seus agentes de IA a capacidade de transformar qualquer URL em Markdown limpo, extrair em lote lotes de páginas, rastrear sites inteiros, e pesquisar na web, tudo de dentro do Claude Desktop, Claude Code, Cursor, ou qualquer host MCP. Este MCP também suporta configurações locais.

É um adaptador fino sobre o wellmarked JavaScript SDK oficial, então ele herda a autenticação do SDK, erros tipados, dicas de repetição/back-off e polling polimórfico de trabalhos.

📖 Documentação MCP · Referência da API · Erros

Ferramentas

Ferramenta	O que faz
extract	Busca uma URL e retorna seu conteúdo principal como Markdown limpo + metadados.
bulk	Envia muitas URLs para extração concorrente. Bloqueia por resultados por padrão. Disponível em todos os planos; o plano limita URLs por trabalho (Free 5 · Pro 50 · Growth 200 · Enterprise ilimitado).
crawl	Rastreia um site BFS a partir de uma URL raiz até uma profundidade dada (Pro+). Retorna um trabalho assíncrono.
search	Pesquisa na web e retorna cada página de resultado como Markdown limpo, em uma única chamada. Disponível em todos os planos; o plano limita a contagem de resultados (Free 5 · Pro 10 · Growth 50 · Enterprise 200).
get_job	Consulta um trabalho em lote/rastreamento uma vez por id.
wait_for_job	Bloqueia até que um trabalho termine e retorna todos os resultados.
get_usage	Relata a cota do período de faturamento atual (plano, usado, limite, restante).

extract, bulk, crawl e search todos aceitam um format (markdown / json / chunks / html / links) e substituições de conformidade por solicitação (allow_domains / deny_patterns / respect_robots); extract, bulk e crawl também aceitam uma contagem de retry para timeouts de destino, e crawl um orçamento de max_pages.

Dois deles são restritos independentemente de qual ferramenta os carrega: render_js e os formatos json / chunks precisam de um plano Pro, Growth ou Enterprise. Portanto, uma chave Free pode chamar extract, bulk e search, mas pedir a qualquer um deles para renderizar JavaScript ou retornar blocos tipados resulta em plan_not_supported.

Saída estruturada

Cada ferramenta retorna seu payload como JSON no bloco de texto do resultado. Um agente lê status, completed, ok ou tokensSaved como campos reais em vez de fazer correspondência de padrões a partir de uma frase renderizada:

{
  "kind": "crawl",
  "jobId": "job_abc",
  "status": "done",
  "total": 12,
  "completed": 12,
  "done": true,
  "truncated": false,
  "results": [
    { "url": "https://example.com/a", "depth": 1, "ok": true, "markdown": "# A" },
    { "url": "https://example.com/b", "depth": 1, "ok": false, "error": "target_timeout" }
  ]
}

Não há renderização em prosa do resultado. Um payload composto de pares chave-valor viaja como pares chave-valor, e achatá-lo em um documento é exatamente o fardo de análise que este servidor existe para remover.

O payload viaja em content e deliberadamente não é duplicado em structuredContent. Os hosts expõem content ao modelo e vários ignoram structuredContent completamente, então um payload enviado apenas lá é invisível para o agente; enviá-lo em ambos os lugares dobra os tokens em cada resposta.

JSON como texto também é a forma mais estruturada que content pode carregar. Os blocos de conteúdo MCP são um conjunto fechado — text, image, audio, resource_link, resource — e nenhum deles contém um objeto bruto. Um tipo de bloco fora do padrão, como application/json, falha na validação de esquema no cliente e mata toda a chamada, então não é uma opção.

Erros são a exceção e carregam texto real — uma falha não tem forma tipada além do erro estável da API code, que já está na mensagem.

Não expostos como ferramentas: rotação de chave de API (/keys/rotate) e rotação de segredo de webhook (/webhook/rotate). Ambos são destrutivos e irreversíveis — a credencial antiga morre no instante em que a chamada retorna, sem fluxo de recuperação — o que é a forma errada para um agente autônomo. Rode a partir do painel ou do SDK.

Configuração

Existem duas maneiras de conectar, dependendo do seu host:

• Remoto (hospedado, OAuth) — para Claude.ai e outros hosts que suportam servidores MCP remotos. Sem chave de API para copiar; você faz login e autoriza no navegador. Veja Servidor remoto abaixo.
• Local (stdio, chave de API) — para Claude Desktop, Claude Code, Cursor e qualquer host que inicie um servidor local. Você fornece uma chave wm_... via ambiente. Gere uma em wellmarked.io.

Servidor remoto (hospedado — OAuth)

Adicione WellMarked como um conector personalizado e aponte para:

https://mcp.wellmarked.io

https://mcp.wellmarked.io/mcp também ainda funciona e sempre funcionará — conectores adicionados antes da raiz se tornar canônica continuam funcionando inalterados. Novos devem usar a raiz.

Seu host descobre o servidor de autorização automaticamente (via /.well-known/oauth-protected-resource), guia você pelo login no WellMarked e aprovação da conexão, e recebe um token com escopo e expiração — sem chave para colar. O conector pode extract, bulk, crawl e search; ele não pode emitir ou rotacionar credenciais.

No Claude.ai: Configurações → Conectores → Adicionar conector personalizado → cole a URL acima → siga os prompts de login e consentimento.

O servidor remoto fala MCP sobre HTTP Streamable e, internamente, chama as mesmas ferramentas que o servidor local — a superfície de ferramentas é idêntica (imposta pelo teste de paridade em test/).

Claude Desktop

Adicione a claude_desktop_config.json (Configurações → Desenvolvedor → Editar Config):

{
  "mcpServers": {
    "wellmarked": {
      "command": "npx",
      "args": ["-y", "wellmarked-mcp"],
      "env": {
        "WELLMARKED_API_KEY": "wm_your_key_here"
      }
    }
  }
}

Claude Code

claude mcp add wellmarked --env WELLMARKED_API_KEY=wm_your_key_here -- npx -y wellmarked-mcp

Cursor / outros hosts MCP

Qualquer host que inicie servidores MCP via stdio funciona — aponte para npx -y wellmarked-mcp com WELLMARKED_API_KEY no ambiente.

Variáveis de ambiente

Servidor local (stdio):

Variável	Obrigatório	Descrição
WELLMARKED_API_KEY	sim	Sua chave de API wm_....
WELLMARKED_TIMEOUT_MS	não	Timeout por solicitação em ms (padrão 30000).

Servidor remoto (HTTP Streamable) — apenas se você o auto-hospedar (npm run start:http):

Variável	Obrigatório	Descrição
PORT	não	Porta de escuta (padrão 3000; Railway define).
MCP_PUBLIC_URL	não	URL pública deste servidor, usada nos metadados de recurso protegido. Derivada do Host da solicitação se não definida.
WELLMARKED_TIMEOUT_MS	não	Timeout por solicitação em ms.

O servidor remoto não aceita nenhum WELLMARKED_API_KEY — cada solicitação autentica com seu próprio token de portador OAuth.

Desenvolver localmente

npm install
npm run build        # compile TypeScript to dist/
npm start            # run the compiled server on stdio
npm run start:http   # OR run the remote (Streamable HTTP) server
npm test             # tool-list parity across both entry points

# Inspect the stdio server interactively with the MCP Inspector:
WELLMARKED_API_KEY=wm_... npx @modelcontextprotocol/inspector node dist/index.js

Licença

MIT — veja LICENSE.