WellMarked

¡Convierte cualquier URL a Markdown limpio! ¡Ahorra hasta >99% en tokens y memoria en comparación con HTML crudo!

Documentación

WellMarked MCP

Un servidor MCP independiente extremadamente ligero para automatización de web scraping eficiente en tokens para agentes de IA, diseñado para ejecutarse localmente o en servidores.

~98% de instantáneas de páginas web más pequeñas que el HTML sin procesar.

NPM Version

El servidor oficial de Model Context Protocol (MCP) para WellMarked.io. Dale a tus agentes de IA la capacidad de convertir cualquier URL en Markdown limpio, extraer por lotes páginas, rastrear sitios completos y buscar en la web, todo desde Claude Desktop, Claude Code, Cursor o cualquier host MCP. Este MCP también admite configuraciones locales.

Es un adaptador delgado sobre el oficial wellmarked SDK de JavaScript, por lo que hereda la autenticación del SDK, errores tipados, sugerencias de reintento/back-off y sondeo de trabajos polimórfico.

📖 documentación de MCP · referencia de API · Errores

Herramientas

Herramienta	Qué hace
`extract`	Obtiene una URL y devuelve su contenido principal como Markdown limpio + metadatos.
`bulk`	Envía muchas URL para extracción concurrente. Bloquea los resultados por defecto. Disponible en todos los planes; el plan limita las URL por trabajo (Free 5 · Pro 50 · Growth 200 · Enterprise ilimitado).
`crawl`	Rastrea un sitio BFS desde una URL raíz hasta una profundidad dada (Pro+). Devuelve un trabajo asíncrono.
`search`	Busca en la web y devuelve cada página de resultados como Markdown limpio, en una sola llamada. Disponible en todos los planes; el plan limita el número de resultados (Free 5 · Pro 10 · Growth 50 · Enterprise 200).
`get_job`	Consulta un trabajo de lote/rastreo una vez por id.
`wait_for_job`	Bloquea hasta que un trabajo termine y luego devuelve todos los resultados.
`get_usage`	Informa la cuota del período de facturación actual (plan, usado, límite, restante).

extract, bulk, crawl y search aceptan todos un format (markdown / json / chunks / html / links) y anulaciones de cumplimiento por solicitud (allow_domains / deny_patterns / respect_robots); extract, bulk y crawl también aceptan un recuento de retry para tiempos de espera objetivo, y crawl un presupuesto de max_pages.

Dos de esos están restringidos independientemente de la herramienta que los lleve: render_js y los formatos json / chunks necesitan un plan Pro, Growth o Enterprise. Así que una clave Free puede llamar a extract, bulk y search, pero pedir a cualquiera de ellos que renderice JavaScript o devuelva bloques tipados devuelve plan_not_supported.

Salida estructurada

Cada herramienta devuelve su carga útil como JSON en el bloque de texto del resultado. Un agente lee status, completed, ok o tokensSaved como campos reales en lugar de hacer coincidir patrones a partir de una oración 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" }
  ]
}

No hay representación en prosa del resultado. Una carga útil compuesta de pares clave-valor viaja como pares clave-valor, y aplanarla en un documento es exactamente la carga de análisis que este servidor existe para eliminar.

La carga útil viaja en content y deliberadamente no se duplica en structuredContent. Los hosts exponen content al modelo y varios ignoran structuredContent por completo, por lo que una carga útil enviada solo allí es invisible para el agente; enviarla en ambos lugares duplica los tokens en cada respuesta.

JSON como texto es también la forma más estructurada que content puede transportar. Los bloques de contenido MCP son un conjunto cerrado — text, image, audio, resource_link, resource — y ninguno de ellos contiene un objeto sin procesar. Un tipo de bloque fuera de especificación como application/json falla la validación de esquema en el cliente y mata toda la llamada, por lo que no es una opción.

Los errores son la excepción y llevan texto real: un fallo no tiene forma tipada más allá del error estable de la API code, que ya está en el mensaje.

No expuestos como herramientas: rotación de clave API (/keys/rotate) y rotación de secreto de webhook (/webhook/rotate). Ambos son destructivos e irreversibles: la credencial anterior muere en el instante en que la llamada regresa, sin flujo de recuperación, lo cual es la forma incorrecta para un agente autónomo. Rote desde el panel o el SDK.

Configuración

Hay dos formas de conectarse, según tu host:

Remoto (alojado, OAuth) — para Claude.ai y otros hosts que admiten servidores MCP remotos. No hay clave API que copiar; inicias sesión y autorizas en el navegador. Ver Servidor remoto a continuación.
Local (stdio, clave API) — para Claude Desktop, Claude Code, Cursor y cualquier host que lance un servidor local. Proporcionas una clave wm_... a través del entorno. Genera una en wellmarked.io.

Servidor remoto (alojado — OAuth)

Agrega WellMarked como conector personalizado y apúntalo a:

https://mcp.wellmarked.io

https://mcp.wellmarked.io/mcp también sigue funcionando y siempre lo hará: los conectores agregados antes de que la raíz se volviera canónica siguen funcionando sin cambios. Los nuevos deben usar la raíz.

Tu host descubre el servidor de autorización automáticamente (a través de /.well-known/oauth-protected-resource), te guía para iniciar sesión en WellMarked y aprobar la conexión, y recibe un token con alcance y expiración: no hay clave que pegar. El conector puede extract, bulk, crawl y search; no puede emitir ni rotar credenciales.

En Claude.ai: Configuración → Conectores → Agregar conector personalizado → pega la URL anterior → sigue los avisos de inicio de sesión y consentimiento.

El servidor remoto habla MCP sobre Streamable HTTP y, internamente, llama a las mismas herramientas que el servidor local: la superficie de herramientas es idéntica (garantizada por la prueba de paridad en test/).

Claude Desktop

Agrega a claude_desktop_config.json (Configuración → Desarrollador → Editar configuración):

{
  "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 / otros hosts MCP

Cualquier host que lance servidores MCP sobre stdio funciona: apúntalo a npx -y wellmarked-mcp con WELLMARKED_API_KEY en el entorno.

Variables de entorno

Servidor local (stdio):

Variable	Requerido	Descripción
`WELLMARKED_API_KEY`	sí	Tu clave API de `wm_...`.
`WELLMARKED_TIMEOUT_MS`	no	Tiempo de espera por solicitud en ms (predeterminado `30000`).

Servidor remoto (Streamable HTTP) — solo si lo autoalojas (npm run start:http):

Variable	Requerido	Descripción
`PORT`	no	Puerto de escucha (predeterminado `3000`; Railway lo establece).
`MCP_PUBLIC_URL`	no	La URL pública de este servidor, utilizada en los metadatos de recursos protegidos. Derivada del Host de la solicitud si no se establece.
`WELLMARKED_TIMEOUT_MS`	no	Tiempo de espera por solicitud en ms.

El servidor remoto no toma ninguna WELLMARKED_API_KEY: cada solicitud se autentica con su propio token de portador OAuth.

Desarrollar 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

Licencia

MIT — ver LICENSE.