kaigo_mcp

일본 개호(介護)의 수급 데이터를 AI 에이전트가 사용할 수 있는 도구로 공개하는 MCP 서버.

Claude Code나 Claude Desktop에서 접속하면 "이 시(市)는 특별양호노인홈(特養)이 충분한가"를 공개 데이터에 기반해 답할 수 있게 된다.

상태: Phase 1(서버 본체)이 동작. 에이전트 본체와 eval은 미착수.

무엇을 하는 것인가

MCP(Model Context Protocol)는 LLM에 도구를 갖게 하기 위한 규격. 이 리포지토리가 만드는 것은 도구 쪽이며, LLM 그 자체는 포함하지 않는다. 서버 단독으로는 API를 전혀 호출하지 않으며, 과금도 발생하지 않는다.

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

도구

주요 지표는 요개호3 이상 인정자 100명당 특양 정원수(전국 24.6명·중앙값 26.7명). 정의와 출처는 kaigo_gap_analysis 쪽에 있다.

집계는 여기서 작성하지 않는다

데이터는 안4(kaigo_gap_analysis)가 export_web.py로 내보내고, 공개 대시보드가 배포하는 것과 동일한 insurers.json을 복사해서 사용한다. 여기서 나눗셈을 다시 작성하지 않는다.

지표의 정의를 두 곳에 두면, 에이전트의 답과 대시보드의 숫자가 어긋났을 때 어느 쪽이 올바른지 판정할 수 없게 된다. 안4의 dataset.py가 "정의는 한 곳"이라는 방침으로 작성되어 있으므로, 그것을 걸쳐 지키고 있다. 갱신은 python scripts/sync_data.py.

도구 설계에서 주의한 점

숫자만 반환해도 판단할 수 없다. "12.4"를 건네받아도 LLM은 높은지 낮은지 모르므로, 전국 순위와 도구의 설명문에 전국값을 포함하고 있다.

동명 자치체를 1건으로 고정하지 않는다. "후추시(府中市)"는 도쿄도와 히로시마현에 있다. 후보를 양쪽 모두 반환하고, 좁히기는 호출 측에 맡긴다.

특양 정원 0을 "전국 최하위"로 읽게 하지 않는다. 해당이 90 보험자 있으며, 전부가 동률 1위가 된다. 동률 건수를 반드시 첨부하고, 또한 "소규모 자치체에서는 드물지 않으며, 주민은 인근 자치체의 시설을 이용하고 있는 경우가 많다"는 주석을 붙인다. 이것이 없으면 rank_insurers의 결과에서 "신고촌(新郷村)은 전국 최악의 지역"이라는 잘못된 결론이 나온다.

도메인 지식을 도구의 응답에 심어 두지 않으면, 호출하는 쪽의 모델을 바꿀 때마다 같은 오독이 재발한다. 프롬프트가 아니라 도구 쪽에 두는 것은 그 때문이다.

사용법

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

Claude Code에서 사용하려면 이 디렉토리에서 기동하면 .mcp.json이 읽힌다. 다른 클라이언트에 등록할 때의 설정:

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

에이전트(Phase 2·동작 확인까지)

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

도구는 MCP 서버를 경유해 호출한다(함수를 직접 import하지 않는다). import로 끝내면 MCP를 통하지 않은 것이 되어, "MCP 서버를 만들었다"는 주장이 검증되지 않기 때문.

비교하는 4열

B와 C를 같은 Qwen 계열로 맞추고 있다. 그렇게 하면 B→C의 차이가 "모델 크기만의 효과", C→D가 "모델 계통의 차이", A→B가 "하드웨어와 세대의 효과"로 읽을 수 있다.

루프는 1개만 작성한다. 한쪽만 SDK의 도구 러너, 한쪽만 수기로 작성하면, 열 간의 차이가 모델의 차이인지 루프 구현의 차이인지 분리할 수 없게 된다. 백엔드는 이력 변환만 담당한다.

실측(열A·열B)

각 6회·python scripts/probe_tool_calling.py로 측정.

온도 0이 필요한 것은 7B 고유였다

qwen2.5:7b는 기본 온도에서는 <tool_call>의 시작 태그가 깨지고 (olith pering 같은 몇 글자가 앞에 붙는다), ollama의 파서가 인식하지 못해 호출이 본문 텍스트로 새어 나간다. 닫는 태그 </tool_call>만 남는 것이 표시. 온도 0으로 해소.

qwen3.5:9b에서는 기본 온도에서도 6/6. 이 깨짐은 로컬 실행 일반의 문제가 아니라, 이 모델의 세대·크기에 고유한 것이었다.

더 큰 차이는 "지시에 따르는가" 쪽

시스템 프롬프트는 "답하기 전에 get_national_baseline으로 전국 기준값을 확인할 것" 이라고 지시하고 있다. 9B는 6/6으로 따르고, 7B는 0/6으로 한 번도 따르지 않았다. 게다가 9B는 두 도구를 1스텝으로 병렬 호출한다.

7B가 올바른 답을 낼 수 있었던 것은, 도구의 설명문에 심어 둔 전국값(24.6)을 집어낸 것이며, 지시된 절차는 밟지 않았다. 안정성이 아니라 지시 추종의 차이이며, 도구가 늘어날수록 효과가 나타난다.

이 비교의 한계

A→B에서 하드웨어와 모델 세대가 동시에 바뀌고 있으므로, 개선이 GPU 때문인지 9B 때문인지 분리되어 있지 않다. 분리하려면 qwen2.5:7b를 GPU 머신에서도 실행한다(무료·수분).

초수(秒數)도, 최초의 모델 로드가 평균을 끌어올린다. 열A의 실측에서는 최초 102.6초·이후 7.6초(평균 23.4초)였다. 스크립트는 중앙값과 최초를 나눠 내도록 고쳤지만, 열B의 수치는 구(舊) 스크립트로 채취한 것이므로 재측정이 필요하다.

앞으로

• 열B 재측정(개량판 스크립트로 초수를 다시 채취)

• qwen2.5:7b를 GPU 머신에서 실행해, 하드웨어와 모델 세대의 효과를 분리

• 열C·D는 미실행(과금이 발생하므로 열이 갖춰진 뒤 1회만)

• Phase 3: eval 본체(복수 질문×복수 회에서의 정답률·완주율)

관련

• kaigo_matching — 개호 기록의 구조화 추출(안1)

• kaigo_gap_analysis — 보험자별 수급 갭 분석(안4·이 데이터의 출처)