joblet-mcp-grok

Servidor MCP independiente que expone la búsqueda de empleo de joblet.ai en modo de solo lectura a Grok y a cualquier otro host de MCP que cumpla con los estándares. Despliegue independiente — no comparte infraestructura, rama ni tren de lanzamientos con los otros conectores de Joblet.

Dos herramientas, ambas de solo lectura (readOnlyHint: true):

• search_jobs — búsqueda por palabras clave con un filtro de ubicación real del upstream, filtrado de relevancia en la capa MCP (coincidencia de tokens en título/categoría/industria/rol; se rechazan las coincidencias solo en la descripción), deduplicación de expVer/casi duplicados y un tope máximo de 8 resultados. Incluye texto + structuredContent, además de un widget de tarjeta de empleo de MCP Apps para los hosts que lo rendericen.

• get_job_details — oferta completa (descripción, requisitos, responsabilidades, salario y lugar de trabajo cuando se conocen, enlace de solicitud) por id de empleo.

Las URLs de solicitud se pasan byte a byte, sin modificación (se conserva el seguimiento de Joveo, sin proxy ni redirección). El tipo de empleo no se expone ni se filtra intencionadamente: la búsqueda del upstream no proporciona un campo autoritativo.

Requisitos

• Node.js 18+ (desarrollado y probado en Node 24)

• No se requieren claves API ni secretos — la API upstream de joblet.ai es pública

Configuración local

npm ci
npm run build        # bundles the widget to dist/mcp-app.html (required before start)
PORT=3010 npm start  # MCP endpoint at http://localhost:3010/mcp

Comprobación de salud:

# GET /health  ->  {"status":"ok","version":"1.1.0"}

Endpoint MCP: POST /mcp — Streamable HTTP, respuestas JSON, sin estado (sin ids de sesión). Requiere la cabecera estándar de la especificación Accept: application/json, text/event-stream. GET / devuelve un banner de servicio.

Verificar el contrato MCP localmente

MCP_URL="http://localhost:3010/mcp" node test_client.mjs
MCP_URL="http://localhost:3010/mcp" node test_widget.mjs

O de forma interactiva: npm run inspect (MCP Inspector → Streamable HTTP → la URL /mcp).

Desarrollo

npm run typecheck    # server + widget/tests configs
npm test             # vitest suites (server pipeline, widget, a11y, logging)
npm run build        # production widget bundle

Configuración

Ver .env.example. Todo es opcional; los valores predeterminados son adecuados para producción. MCP_REQUEST_LOG=1 activa un registro depurado por llamada (solo hashes/longitudes/recuentos — nunca el texto sin procesar de las consultas, ubicaciones, URLs de solicitud ni credenciales).

Notas sobre el widget

El widget de tarjeta de empleo informa al host de su propia altura intrínseca mediante la notificación sendSizeChanged de MCP Apps (solo la altura, medida después de requestAnimationFrame, con detección de cambios para evitar bucles de redimensionado) y respeta una altura fija del contenedor del host cuando se declara una.

Que el host redimensione el iframe en consecuencia es comportamiento del host.

El CTA «Ver y solicitar» utiliza la petición ui/open-link conforme a los estándares, con un respaldo visible y accesible dentro de la tarjeta (enlace

• acción de copiar) siempre que el host la rechace o no la admita — nunca falla en silencio.