mcp-retrieval

Qué es

mcp-retrieval es un servidor Model Context Protocol escrito en Go. Expone capacidades de recuperación web a cualquier cliente compatible con MCP (Claude Desktop, agentes de IDE, aplicaciones LLM personalizadas) como tres herramientas de solo lectura. Internamente utiliza la librería retrieval-go para buscar en la web y obtener páginas, devolviendo resultados como Markdown limpio listo para entregar a un modelo.

La librería no necesita claves API: la búsqueda web pasa por DuckDuckGo Lite, la búsqueda de imágenes por Bing Images, y la obtención de páginas ejecuta el HTML a través de un extractor de legibilidad antes de convertirlo a Markdown. Para mantenerse fiable contra la protección de bots, suplanta a navegadores reales a nivel de TLS y puede rotar tanto huellas de navegador como proxies — ver Motor de recuperación.

Ambos transportes que soporta el SDK de MCP están disponibles y exponen el mismo conjunto de herramientas:

• stdio — el cliente lanza el binario y habla por stdin/stdout (el predeterminado, ideal para clientes de escritorio).

• http — un servidor HTTP transmisible de larga duración (útil para despliegues remotos/compartidos).

Related MCP server: mcp-web-calc

Herramientas

Las tres están anotadas como de solo lectura. Cada herramienta devuelve una carga JSON estructurada que coincide con su esquema de salida; el SDK refleja el mismo JSON en el bloque de contenido de texto para clientes que no leen structuredContent.

web_search

web_search_images

web_scrape

Tanto las listas queries/urls están limitadas a max_queries (10) elementos por llamada. Las consultas deben tener ≤ 512 caracteres; las URLs ≤ 2048 caracteres y solo http/https.

Resultados y recuentos

Cada llamada se distribuye en la lista de entrada y devuelve una entrada por consulta/URL, cada una con su propio status — success, failed o timeout — de modo que un fallo parcial aún devuelve los elementos que sí funcionaron.

count es el número de elementos realmente devueltos, y puede ser menor que el max_results / max_images solicitado: los duplicados dentro de los resultados de una sola consulta se eliminan antes de aplicar el límite, y el proveedor puede simplemente tener menos elementos para dar. Un count más pequeño es un resultado normal, no un error.

La deduplicación es por consulta, no entre consultas. Cada entrada se deduplica por sí misma, por lo que un enlace encontrado por dos de las consultas en la misma llamada aparece en ambas entradas — deduplica la unión tú mismo si lo necesitas.

Errores

Los fallos a nivel de solicitud se devuelven como resultado de herramienta con isError: true y un mensaje de texto plano, no como un error JSON-RPC — el modelo lee el mensaje y puede corregir la llamada por sí mismo. Los fallos por elemento nunca hacen esto; permanecen dentro de la carga como status: "failed" / "timeout".

Una llamada falla por completo solo cuando la entrada se rechaza antes de que comience cualquier trabajo, o cuando todos los elementos de la misma fallan:

Los mensajes de fallo total deliberadamente no distinguen los tiempos de espera de otras causas: un lote mixto puede fallar por varias razones a la vez, y el status por elemento ya lleva ese detalle siempre que al menos un elemento sobreviva.

Limitaciones conocidas

• web_scrape solo maneja HTML. Las páginas pasan por un extractor de legibilidad, que necesita marcado de artículo, por lo que las respuestas text/plain no producen nada y vuelven como status: "failed". Los hosts de archivos crudos son el caso común: raw.githubusercontent.com, github.com/.../raw/..., cdn.jsdelivr.net. Extrae la página renderizada en lugar del archivo crudo.

• La relevancia de web_search_images no está garantizada. Para algunas consultas, Bing Images sirve una página que no es un conjunto de resultados, y se analiza como si lo fuera — la herramienta entonces devuelve imágenes no relacionadas con status: "success". Trata los resultados de imágenes como de mejor esfuerzo y verifícalos antes de mostrarlos a un usuario.

• Sin JavaScript. Las páginas se obtienen tal cual; el contenido renderizado en el lado del cliente es invisible para el extractor.

Inicio rápido

Instalación

Elige la que mejor se adapte — todas dan el mismo servidor.

Contenedor (sin necesidad de toolchain de Go):

docker pull ghcr.io/role1776/mcp-retrieval:latest

Binario precompilado — descarga el archivo para tu plataforma desde la última versión, descomprímelo y pon mcp-retrieval en tu PATH.

Paquete MCP — para clientes que instalan archivos .mcpb, descarga mcp-retrieval_<version>_<os>_<arch>.mcpb desde la última versión y ábrelo con tu cliente. El paquete lleva el binario compilado, por lo que no necesita ni Docker ni Go. Elige el archivo que coincida con tu sistema operativo y arquitectura de CPU: un paquete contiene un binario nativo.

Desde el código fuente:

go install github.com/Role1776/mcp-retrieval/app/cmd/mcp-retrieval@latest   # needs Go 1.25.5+

O construye el binario en el lugar (el módulo Go vive en app/):

make build          # -> bin/mcp-retrieval

Ejecutar

# defaults: stdio transport, no configuration needed
./bin/mcp-retrieval

# with an explicit env file
./bin/mcp-retrieval -env /absolute/path/to/.env

La única bandera es opcional:

Conectar un cliente MCP (stdio)

Apunta tu cliente al binario compilado. Ejemplo de configuración de Claude Desktop:

{
  "mcpServers": {
    "retrieval": {
      "command": "/absolute/path/to/mcp-retrieval",
      "env": {
        "MAX_RESULTS": "20"
      }
    }
  }
}

El bloque env es opcional: "command" por sí solo es suficiente.

Conexión de un cliente MCP (contenedor)

Ejecuta la imagen en stdio. La configuración sigue viajando a través del bloque env, pero Docker necesita que cada variable se nombre en la línea de comandos con -e para que llegue al proceso:

{
  "mcpServers": {
    "retrieval": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MAX_RESULTS",
        "-e", "DEFAULT_TIMEOUT_MS",
        "ghcr.io/role1776/mcp-retrieval:latest"
      ],
      "env": {
        "MAX_RESULTS": "20",
        "DEFAULT_TIMEOUT_MS": "5000"
      }
    }
  }
}

-i es obligatorio: sin él, el contenedor no recibe stdin y el cliente ve morir al servidor de inmediato. Los clientes que se instalan desde el MCP Registry construyen esta invocación por sí mismos y solicitan las variables declaradas en server.json.

Ejecución sobre HTTP

Establece MCP_TRANSPORT=http y el servidor escucha en SERVER_PORT en MCP_PATH (por defecto http://localhost:8080/mcp).

Configuración

Todo se configura mediante variables de entorno, y cada valor se valida antes del arranque: un valor no numérico o no positivo es un error de arranque. Las relaciones entre límites no se comprueban en el arranque; consulta Límites. Las variables ya presentes en el entorno tienen prioridad sobre un archivo .env, por lo que el bloque env de un cliente MCP siempre tiene efecto. Cada campo tiene un valor predeterminado sensato, de modo que el servidor se ejecuta sin configuración alguna (transporte stdio).

Consulta .env.example para ver la lista completa con sus valores predeterminados, lista para copiar a .env.

Servidor MCP

La versión anunciada a los clientes no es configurable: se graba en el binario en tiempo de compilación a partir de la etiqueta git.

Servidor HTTP (solo transporte http)

Cliente HTTP y proxy

Cuando se configura un proxy, cada solicitud saliente recibe un identificador de sesión único añadido al inicio de sesión, de modo que el proveedor upstream rota la IP de salida por solicitud.

Límites

Cada valor se comprueba por separado: debe ser mayor que cero, pero los tríos DEFAULT_*, MIN_* y MAX_* no se verifican entre sí en el arranque. Un conjunto incoherente no detiene el servidor; se reconcilia por solicitud en su lugar:

• un valor que el llamante omite, o pasa como cero o negativo, recurre al DEFAULT_* correspondiente;

• el resultado se limita luego a [MIN_*, MAX_*], de modo que un DEFAULT_* mayor que su MAX_* simplemente produce MAX_*;

• si MIN_* supera a MAX_*, gana el máximo.

Por lo tanto, el límite efectivo siempre está dentro del máximo configurado, y una mala configuración degrada a un servidor funcional en lugar de un arranque fallido. La contrapartida es que degrada silenciosamente: un error tipográfico como MAX_RESULTS=2 en lugar de 20 no produce ninguna advertencia, solo respuestas discretamente más pequeñas. Vale la pena revisar estos valores cuando los resultados parecen truncados.

Registro

Arquitectura

El proyecto sigue una estructura limpia y en capas. Las dependencias apuntan hacia adentro, hacia el dominio, y cada capa se comunica con la siguiente a través de interfaces.

app/                       the Go module: sources plus its build files
                           (Dockerfile, .dockerignore, .goreleaser.yaml)

cmd/mcp-retrieval/main.go  entry point: parse flags, load config, run app

internal/
  app/                     wiring + lifecycle (build server, run, graceful shutdown)
  config/                  config loading (.env → env vars → validate)
  domain/                  core types (Query, Link, Document, Snippet, Image) and errors
  dto/web/                 request/response shapes for the MCP tools
  transport/mcp/           MCP layer
    router/                registers every tool group on the MCP server
    web/                   tool handlers
    utils/                 schema helpers and error → tool-result mapping
  usecase/web/             business logic: validation, parallelism, timeouts, dedupe/limit/rerank
  adapter/web/             retrieval-go client wiring (search, images, scrape, proxy)
  pkg/                     reusable building blocks (mcpserver, server, logger, validator)

Flujo de solicitud para una llamada de herramienta:

MCP client → transport/mcp/web (handler) → usecase/web → adapter/web → retrieval-go → the web
                     ↑ maps errors               ↑ validates, fans out, limits results

Tanto la búsqueda como el raspado se distribuyen en paralelo a través de la lista de entrada y agregan resultados por elemento, cada uno con su propio estado (success, failed, timeout). Una llamada solo falla por completo cuando todos los elementos de ella fallan.

Motor de recuperación

Todo el trabajo de red se delega en retrieval-go, configurado en app/internal/adapter/web. Vale la pena saber:

• Fuentes. La búsqueda web usa DuckDuckGo Lite; la búsqueda de imágenes usa Bing Images; la obtención de páginas procesa el HTML sin procesar mediante un extractor de legibilidad y convierte el artículo principal a Markdown (tablas incluidas). No se requieren claves de API de motores de búsqueda.

• Suplantación de navegador. El adaptador habilita WithBrowserRotation(), por lo que cada solicitud se envía desde uno de ~11 perfiles de navegador reales elegidos al azar. Cada perfil combina una huella TLS/JA3 genuina (mediante uTLS) con un User-Agent y encabezados de sugerencia de cliente coincidentes: Chrome 133/131/120 (Windows/macOS/Linux), Edge 131, Firefox 120 (Windows/macOS), Safari 18.4 (macOS) y Safari de iOS 18.4. Esto hace que el tráfico parezca de navegadores ordinarios en lugar de un cliente HTTP de Go, que es lo que mantiene accesibles las fuentes gratuitas.

• Rotación de proxy. Cuando se configura PROXY_HOST, el adaptador instala una fábrica de proxies que añade un session-<id> único al nombre de usuario del proxy en cada solicitud. Con un proveedor de proxy residencial/rotatorio basado en sesiones, esto produce una IP de salida nueva por solicitud, distribuyendo la carga y evitando límites de velocidad. Sin proxy, las solicitudes salen directamente.

• Manejo de respuestas. Las respuestas se descomprimen de forma transparente (gzip, br, zstd, deflate), y keep-alive está deshabilitado (WithDisableKeepAlive()) para que las conexiones agrupadas no fijen una sola huella/IP entre solicitudes.

Nada de esto necesita configuración para funcionar: los valores predeterminados anteriores se aplican automáticamente. Solo las credenciales del proxy son extras opcionales.

Desarrollo

Todo lo relacionado con Go vive en app/, así que usa el makefile desde la raíz del repositorio o pasa -C app a la cadena de herramientas:

make build          # compile the binary
make test           # run tests

go -C app build ./...      # compile everything
go -C app test ./...       # run tests
go -C app vet ./...        # static checks

Consulta CONTRIBUTING.md para las pautas de solicitudes de extracción.

Licencia

Publicado bajo la Licencia MIT.