job-search-mcp

Servidor MCP local que gestiona una busqueda de empleo sobre archivos Markdown.

El servidor no razona. El usuario habla con Claude, y Claude usa este servidor para leer y escribir sus archivos con una estructura fija. El cerebro es el cliente; esto es la memoria y las manos.

De un solo usuario, sin red, sin base de datos.

---

Concepto central: dos archivos separados

Es la idea que sostiene todo lo demas.

• perfil-skills.md es lo que YA se tiene. Todo a nivel [solido] o [parcial], nunca huecos. Un termino entra aqui solo cuando el usuario confirma que lo tiene.
• radar-huecos.md es lo que el mercado pide y no se tiene, cada termino con un contador de cuantas ofertas objetivo lo han pedido. Ordenado por contador: lo de arriba es lo mas urgente de aprender.

Ciclo de vida de una skill: nace como hueco cuando una oferta la pide, su contador sube cada vez que otra oferta la vuelve a pedir, y se gradua cuando el usuario confirma que la ha adquirido: sale del radar y entra en el perfil con su nivel. Ese es el unico camino de hueco a perfil.

---

Modelo de datos

Todo vive en DATA_DIR, un directorio que es a la vez una boveda de Obsidian. El MCP escribe los .md y Obsidian los renderiza: la misma carpeta, cero conflicto.

DATA_DIR/
  perfil/
    perfil-skills.md    - [solido|parcial] Termino (nota)          bajo '## Categoria'
    radar-huecos.md     - [contador: N] Termino (Categoria). Fuentes: a; b
    criterios.md        prosa libre: que hace que una oferta merezca el tiempo
    cv.md               CV en Markdown, fuente de la evidencia concreta
  ofertas/
    AAAA-MM-empresa.md  frontmatter YAML + analisis + registro de estados + notas

Estados de una oferta: analizada -> solicitada -> entrevista -> oferta -> aceptada, con dos salidas laterales desde cualquier punto: denegada y descartada.

El servidor nunca regenera un archivo

Parsea solo las lineas que reconoce y edita esa linea concreta, dejando el resto de bytes intactos. El discriminador es el patron (- [contador: N] ), no la posicion: por eso una seccion ## Reglas llena de vinietas normales convive sin problema con las lineas de datos.

Esto es deliberado. Los archivos los edita tambien un humano en Obsidian, asi que el formato es del usuario, no del servidor.

---

Superficie MCP

Resources (solo lectura, los adjunta el usuario)

URI	Contenido
profile://skills	perfil-skills.md
profile://gaps	radar-huecos.md, ordenado por contador al servir
profile://cv	cv.md
profile://criteria	criterios.md
offers://list	tabla del pipeline: estado, empresa, puesto, score
offers://{id}	una oferta entera: analisis, estados y notas

Tools (escriben, los invoca el modelo)

Tool	Que hace
record_gap(term, category, source)	Sube el contador en 1 y anade la fuente. Si no existe, lo crea con 1. Nunca duplica.
list_gaps()	Huecos ordenados por contador descendente.
confirm_skill(term, level, evidence, category?)	La graduacion: saca del radar y mete en el perfil. Descarta las fuentes: al perfil solo viaja la evidencia.
update_skill_level(term, level)	Cambia solido/parcial de algo que ya esta en el perfil.
save_offer(id, title, company, markdown, score?, salario?, url?, tags?)	Crea o actualiza una oferta. Al actualizar conserva estado y notas.
set_offer_status(id, status)	Mueve por el ciclo de vida y lo anota con fecha.
add_offer_note(id, note)	Nota fechada en "Notas de entrevista".
ping()	Diagnostico: responde y dice sobre que DATA_DIR trabaja.

Prompt (lo invoca el usuario)

analyze_offer devuelve la plantilla de analisis rellenada con perfil, CV y criterios leidos del disco en ese instante, mas las instrucciones de guardar la oferta con save_offer y registrar cada hueco con record_gap. Debajo se pega el texto de la oferta.

---

Instalacion

Requiere Node >= 18 (probado con 24).

npm install
npm run build

Configuracion: una unica variable de entorno.

Variable	Por defecto
JOB_MCP_DATA_DIR	~/Desktop/Productivo/Trabajo/Perfil

Comprobar que arranca (imprime la ruta de datos y se queda esperando en stdio):

$env:JOB_MCP_DATA_DIR="<ruta a la boveda>"
node build/index.js

Registrarlo en un cliente

Es un servidor stdio: el cliente lo lanza como proceso hijo. La declaracion tiene siempre esta forma:

{
  "command": "node",
  "args": ["<ruta al repo>/build/index.js"],
  "env": { "JOB_MCP_DATA_DIR": "<ruta a la boveda>" }
}

• Claude Code: ~/.claude.json, o claude mcp add job-search --scope user -- node <ruta>/build/index.js.
• Claude Desktop: bloque mcpServers en claude_desktop_config.json. Usa la ruta absoluta del ejecutable de node: Desktop se lanza desde el explorador y no hereda el PATH.

Las rutas concretas de esta maquina estan en SETUP.local.md, fuera de git.

---

La regla que mas tiempo cuesta aprender

Cada npm run build obliga a reiniciar el cliente.

Un servidor MCP por stdio se lanza una vez, cuando arranca el cliente, y ese proceso se queda vivo. No hay recarga en caliente. Cerrar la ventana de Claude Desktop no basta: hay que salir desde el icono de la bandeja del sistema.

Sintoma tipico: pides un tool nuevo y el cliente jura que no existe.

---

Desarrollo

npm run build     # tsc -> build/
npm test          # tsc + node --test "build/**/*.test.js"   (40 tests)
npm run watch     # recompilar al guardar

src/
  index.ts          solo cablea: resources + tools + prompts + transporte stdio
  config.ts         DATA_DIR y rutas derivadas
  resources.ts      los 6 resources
  tools.ts          los 8 tools, con sus esquemas Zod
  prompts.ts        analyze_offer
  lib/
    markdown.ts     primitivas por linea: cabeceras, secciones, EOL, normalize
    skills.ts       perfil-skills.md
    radar.ts        radar-huecos.md y los contadores
    offers.ts       frontmatter, estados y notas
    graduate.ts     confirm_skill: la operacion que cruza los dos archivos
    files.ts        el UNICO modulo con I/O

src/lib/* son funciones puras con la forma (contenido, args) -> { contenido, changed, message }. Por eso los tests no tocan el disco y corren en 100 ms.

graduate.ts devuelve los dos contenidos nuevos sin escribir: quien llama persiste ambos o ninguno. Es lo mas cerca de una transaccion que tiene sentido aqui.

Nunca uses console.log en el servidor. stdout es el canal JSON-RPC y escribir ahi rompe el protocolo. Los logs van a console.error (stderr).

Probar el servidor sin ningun cliente, hablandole JSON-RPC crudo:

$msgs = @(
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"m","version":"0"}}}'
'{"jsonrpc":"2.0","method":"notifications/initialized"}'
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
)
$msgs | node build/index.js

---

Donde aparece cada primitivo en el cliente

Los tres primitivos tienen puntos de entrada distintos, segun quien decide usarlos:

Primitivo	Quien lo invoca	Donde aparece
Prompt	el usuario	menu /
Tool	el modelo	no se invoca desde un menu: se pide hablando
Resource	el usuario	menu de adjuntar

---

Obsidian

El DATA_DIR es una boveda. Dos plugins, y de momento solo estos:

• Dataview: tabla viva del radar ordenada por contador, y tabla de ofertas filtrada por estado, apoyada en el frontmatter YAML.
• Kanban: el pipeline de ofertas como tablero por estado.

La vista de grafo y los [[enlaces]] salen gratis.

---

Fuera de alcance

Sin base de datos (son Markdown a proposito, legibles y versionables a mano), sin interfaz web, sin scraping de portales, sin multiusuario, sin nube. Corre local.

Las mejoras aparcadas estan en IDEAS.md.