# Job Helper — Servidor MCP

Servidor [MCP](https://modelcontextprotocol.io) que expone la funcionalidad de [Job Helper](https://job-helper-adrianmnd.vercel.app) como herramientas invocables desde cualquier cliente compatible (Claude Desktop, Claude Code...). Permite gestionar candidaturas en lenguaje natural: *"busca ofertas de backend en Sevilla y crea candidaturas de las 2 mejores"*, *"genera un CV para la candidatura de Acme"*, *"resume mis métricas"*.

## Herramientas expuestas

| Herramienta | Qué hace | Coste / riesgo |
|---|---|---|
| `search_jobs` | Busca ofertas reales via Adzuna (con traducción automática del término) | Ninguno |
| `list_applications` | Lista todas las candidaturas del usuario | Ninguno |
| `create_application` | Crea una candidatura nueva (estado inicial "Guardada") | Ninguno |
| `generate_document` | Genera CV/carta adaptados via Gemini | **Llamada real a Gemini, con coste de API** |
| `delete_application` | Elimina una candidatura y todo su historial | **Irreversible** |
| `get_metrics` | Devuelve el embudo de conversión y tiempos medios | Ninguno |

Las dos herramientas marcadas usan las anotaciones `destructiveHint`/`openWorldHint` del SDK de MCP para que el cliente las trate con más cautela — pero la responsabilidad última de confirmar cada llamada es de quien usa el cliente, no de este servidor.

## Stack

- TypeScript + `@modelcontextprotocol/sdk` (v1.x — la v2 del SDK, alineada con la revisión de spec 2026-07-28, aún se está asentando en el momento de construir esto)
- Zod para la validación de parámetros de cada herramienta
- Transporte stdio (el servidor corre como proceso local, invocado directamente por el cliente MCP — no se despliega a ningún servidor remoto)

## Setup

```bash
npm install
```

No requiere `.env` — a diferencia de los otros repos de Job Helper, las credenciales de autenticación no las lee este proyecto de un archivo propio, sino que las inyecta el cliente MCP (ver más abajo).

## Probarlo con el MCP Inspector

Antes de conectar cualquier cliente real, verifica el servidor de forma aislada:

```bash
# macOS / Linux
JOB_HELPER_EMAIL=tu-email JOB_HELPER_PASSWORD=tu-contrasena npx @modelcontextprotocol/inspector npx tsx src/index.ts

# Windows (PowerShell)
$env:JOB_HELPER_EMAIL="tu-email"; $env:JOB_HELPER_PASSWORD="tu-contrasena"; npx @modelcontextprotocol/inspector npx tsx src/index.ts
```

Abre la UI local del Inspector y dispara cada herramienta a mano antes de fiarte de ningún cliente.

## Conectarlo a Claude Desktop

Desde la propia app: **Settings → Developer → Edit Config**, y añade una entrada dentro de `mcpServers`:

```json
{
  "mcpServers": {
    "job-helper": {
      "command": "npx",
      "args": ["tsx", "/ruta/absoluta/a/job-helper-mcp/src/index.ts"],
      "env": {
        "JOB_HELPER_EMAIL": "tu-email",
        "JOB_HELPER_PASSWORD": "tu-contrasena"
      }
    }
  }
}
```

Reinicia Claude Desktop por completo (no solo la ventana) tras guardar. Verifica la conexión en **Settings → Connectors** — los servidores locales aparecen etiquetados como "DESKTOP" ahí, no necesariamente con un icono en la caja de chat (varía según la versión de la app).

## Consideraciones de seguridad

- **Ninguna credencial vive en este repositorio.** El email/contraseña de tu cuenta de Job Helper se configuran en el cliente MCP (`claude_desktop_config.json`), que está fuera de este proyecto y nunca se versiona.
- **`generate_document` dispara una llamada real y con coste a Gemini** cada vez que se invoca — trátala con la misma cautela que tendrías generando un documento desde la propia app web.
- **`delete_application` es irreversible.** El cliente MCP debería pedir confirmación antes de ejecutarla (comportamiento estándar), pero no dependas únicamente de eso si te preocupa un borrado accidental.
- Usa una cuenta de prueba de Job Helper para experimentar con este servidor, no tu cuenta principal, mientras estés aprendiendo el protocolo.

## Repositorios relacionados

- [job-helper-backend](https://github.com/AdrianMnd/job-helper-backend) — API que este servidor consume
- [job-helper-frontend](https://github.com/AdrianMnd/job-helper-frontend) — Aplicación web
- [job-helper-extension](https://github.com/AdrianMnd/job-helper-extension) — Extensión de navegador
- [job-helper-android](https://github.com/AdrianMnd/job-helper-android) — Versión Android (TWA)

## Licencia

ISC — ver [LICENSE](./LICENSE)