kaigo_mcp

Un servidor MCP que expone los datos de oferta y demanda de cuidados de larga duración en Japón como una herramienta utilizable por agentes de IA.

Al conectarse desde Claude Code o Claude Desktop, permite responder a preguntas como «¿esta ciudad tiene suficientes residencias de cuidados especiales?» basándose en datos públicos.

Estado: Fase 1 (el servidor en sí) en funcionamiento. El agente en sí y la evaluación aún no se han abordado.

Qué hace

MCP (Model Context Protocol) es un estándar para dotar a los LLM de herramientas. Este repositorio crea el lado de las herramientas; no incluye el LLM en sí. El servidor por sí solo no realiza ninguna llamada a API y no genera costes.

[考える側]                    [このリポジトリ]
Claude Code / 自作エージェント  ←stdio→  kaigo-gap サーバー
「どの道具を使うか」を判断              呼ばれたらデータを返す

Herramientas

El indicador principal es el número de plazas en residencias de cuidados especiales por cada 100 personas certificadas con nivel de cuidados 3 o superior (nacional: 24,6; mediana: 26,7). La definición y las fuentes están en kaigo_gap_analysis.

No reescribimos los cálculos aquí

Los datos los genera la propuesta 4 (kaigo_gap_analysis) mediante export_web.py, y se utiliza el mismo insurers.json que distribuye el panel público, copiándolo. Aquí no se reescribe la división.

Si la definición del indicador estuviera en dos sitios, cuando las respuestas del agente y las cifras del panel discreparan, no se podría determinar cuál es la correcta. El dataset.py de la propuesta 4 sigue la política de «una sola definición», y la mantenemos a través de él. La actualización se hace con python scripts/sync_data.py.

Consideraciones de diseño de las herramientas

Devolver solo números no permite juzgar. Si se le pasa «12,4», el LLM no sabe si es alto o bajo, por lo que se incluyen el rango nacional y el valor nacional en la descripción de la herramienta.

No se asume un único municipio con el mismo nombre. «Fuchu» existe en Tokio y en Hiroshima. Se devuelven ambos candidatos y se deja que el llamador decida.

No se hace que un valor de 0 plazas en residencias de cuidados especiales se lea como «el peor del país». Hay 90 aseguradoras afectadas, y todas quedarían empatadas en el primer puesto. Siempre se indica el número de empates y se añade la nota: «No es raro en municipios pequeños; los residentes suelen utilizar instalaciones de municipios vecinos». Sin esto, el resultado de rank_insurers llevaría a la conclusión errónea de que «Shingo es la peor región del país».

Si no se incorpora el conocimiento de dominio en las respuestas de las herramientas, cada vez que se cambie el modelo que las llama, se repetirá la misma mala interpretación. Por eso se coloca en el lado de la herramienta, no en el prompt.

Uso

pip install -r requirements.txt
python scripts/sync_data.py     # 案4からデータを取り込む
python scripts/smoke_test.py    # 通信の疎通確認

Para usarlo desde Claude Code, basta con iniciarlo en este directorio; se leerá .mcp.json. Configuración para registrarlo en otros clientes:

{
  "mcpServers": {
    "kaigo-gap": {
      "command": "python",
      "args": ["-m", "kaigo_mcp"],
      "cwd": "C:\projects\kaigo_mcp"
    }
  }
}

Agente (Fase 2 · hasta la verificación de funcionamiento)

python -m kaigo_mcp.agent --list
python -m kaigo_mcp.agent "尼崎市は特養が足りてる？" --verbose

Las herramientas se llaman a través del servidor MCP (no se importan las funciones directamente). Si se hiciera con import, no se estaría usando MCP y no se verificaría la afirmación de «hemos creado un servidor MCP».

Las 4 columnas a comparar

B y C están alineados con la misma familia Qwen. Así, la diferencia B→C se lee como «efecto solo del tamaño del modelo», C→D como «diferencia de familia de modelos» y A→B como «efecto del hardware y la generación».

Solo se escribe un bucle. Si uno usa el ejecutor de herramientas del SDK y el otro está escrito a mano, no se puede separar si la diferencia entre columnas se debe al modelo o a la implementación del bucle. El backend solo se encarga de convertir el historial.

Mediciones reales (columnas A y B)

6 ejecuciones cada una, medidas con python scripts/probe_tool_calling.py.

La necesidad de temperatura 0 era específica del 7B

Con qwen2.5:7b, a la temperatura por defecto, la etiqueta de apertura de <tool_call> se rompe (aparecen unos pocos caracteres como olith o pering al principio), el analizador de ollama no la reconoce y la llamada se filtra al texto del cuerpo. La señal es que solo queda la etiqueta de cierre </tool_call>. Se resuelve con temperatura 0.

Con qwen3.5:9b, incluso a la temperatura por defecto, 6/6. Esta rotura no es un problema general de la ejecución local, sino específico de la generación y el tamaño de este modelo.

La diferencia mayor está en «si sigue las instrucciones»

El prompt del sistema indica: «Antes de responder, consulta el valor de referencia nacional con get_national_baseline». El 9B lo cumple 6/6; el 7B no lo cumple ni una vez (0/6). Además, el 9B llama a las dos herramientas en paralelo en un solo paso.

El 7B pudo dar la respuesta correcta porque tomó el valor nacional (24,6) incrustado en la descripción de la herramienta, pero no siguió el procedimiento indicado. No es una diferencia de estabilidad, sino de seguimiento de instrucciones, y se nota más cuantas más herramientas haya.

Limitaciones de esta comparación

En A→B, cambian a la vez el hardware y la generación del modelo, por lo que no se puede separar si la mejora se debe a la GPU o al 9B. Para separarlo, habría que ejecutar qwen2.5:7b también en la máquina con GPU (gratis, unos minutos).

Los segundos también se ven afectados por la carga inicial del modelo, que eleva la media. En la medición de la columna A, la primera ejecución fue de 102,6 s y las siguientes de 7,6 s (media de 23,4 s). El script se ha corregido para que muestre la mediana y la primera ejecución por separado, pero los valores de la columna B se tomaron con el script antiguo, por lo que hay que volver a medirlos.

Próximos pasos

• Re-medición de la columna B (volver a tomar los segundos con el script mejorado)

• Ejecutar qwen2.5:7b en la máquina con GPU para separar los efectos del hardware y de la generación del modelo

• Columnas C y D sin ejecutar (como generan costes, solo una vez cuando estén todas las columnas)

• Fase 3: evaluación en sí (tasa de respuestas correctas y tasa de finalización con varias preguntas × varias ejecuciones)

Relacionados

• kaigo_matching — Extracción estructurada de registros de cuidados (propuesta 1)

• kaigo_gap_analysis — Análisis de brechas de oferta y demanda por aseguradora (propuesta 4 · origen de estos datos)