Readeck MCP

Un servidor MCP que convierte una biblioteca de Readeck en una base de conocimiento de lectura/escritura para agentes de IA: los agentes pueden enviar el HTML que generan directamente a Readeck (auto-etiquetado por un LLM) y después recuperar y leer esos documentos. Construido con FastMCP — el mismo código se ejecuta como servidor local stdio o como servidor remoto HTTP detrás de un proxy inverso.

A diferencia de los MCP de Readeck existentes (que son asistentes de solo lectura), este ingiere HTML generado por agentes y lo auto-etiqueta con un LLM a partir de una taxonomía fija.

Herramientas

readeck_save utiliza la API de creación JSON de Readeck con el campo html de HTML sin procesar (base64/data-URI no funcionan). Envía un User-Agent de navegador para que un WAF (p. ej. el error 1010 de Cloudflare) no lo bloquee, y hace un breve sondeo para devolver el id, word_count y reading_url del nuevo marcador.

Related MCP server: Doc Monitor MCP

Auto-etiquetado

Cuando se llama a readeck_save sin labels, un LLM clasifica el documento. Es resistente a inyecciones por diseño: el modelo solo puede elegir entre una taxonomía fija (LABEL_TAXONOMY), y el resultado se cruza con esa lista en el lado del servidor, por lo que es imposible tener etiquetas fuera del vocabulario. Una etiqueta de origen (ORIGIN_LABEL, por defecto propio) siempre la añade el menú, nunca el LLM.

Independiente del proveedor (compatible con OpenAI o Anthropic). Funciona con planes gratuitos como Groq — para modelos de razonamiento como gpt-oss configura un LLM_MAX_TOKENS generoso y el servidor envía reasoning_effort: low automáticamente.

Salvaguardas

• Autenticación HTTP de bloqueo ante fallos: mediante autorización de transporte HTTP, cada tool en invoca requiere Authorization: Bearer $MCP_AUTH_TOKEN (comparación de tiempo constante).

• Validación de entradas: límite de tamaño de HTML, rechazo de no-HTML, lista de permitidos de esquemas de URL, saneamiento y comprobación de límites de etiquetas.

• Limitación de ritmo tipo token-bucket por proceso.

• Las llamadas LLM se reintentan en 429/5xx con retroceso y se degradan correctamente (el etiquetado es de mejor esfuerzo; un error nunca bloquea el guardado).

Configuración (entorno)

Local (stdio)

READECK_TOKEN=... uv run --script server.py --selftest   # smoke test

Regístrate con un cliente MCP (mcpServers), por ejemplo:

{
  "mcpServers": {
    "readeck": {
      "command": "uv",
      "args": ["run", "--script", "/path/to/readeck-mcp/server.py"],
      "env": { "READECK_URL": "https://readeck.example.com", "READECK_TOKEN": "..." }
    }
  }
}

Remoto (HTTP / Docker)

Ejecútalo con READECK_MCP_TRANSPORT=http (ver Dockerfile). Colócalo detrás de tu proxy inverso o túnel, por ejemplo en https://mcp-readeck.example.com. Cuando se ejecute junto a Readeck, define READECK_URL=http://readeck:8000 para evitar el doble viaje público. Apunta los clientes al endpoint:

{
  "mcpServers": {
    "readeck": {
      "type": "http",
      "url": "https://mcp-readeck.example.com/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

Nota: usa la ruta del endpoint sin barra final (/mcp, no /mcp/): algunos proxies convierten la redirección de la barra final en un 307 que rompe los clientes streamable-HTTP.

Define siempre un MCP_AUTH_TOKEN robusto antes de exponer el endpoint: ese token concede acceso de escritura a tu biblioteca.

Licencia

MIT