Insurance Claim Estimator (KR + US)

insurance-claim-mcp

薬袋・診療費領収書の情報（KCD 疾病コード、処置、診療費）を加入保険の約款と照合し、予想保険金を案内する MCP（Model Context Protocol）サービスです。

情報提供を目的とした予想額です。実際の支払いの可否と金額は、保険会社の審査によって異なります。

mcp-name: io.github.seothief/insurance-claim-mcp

クイックスタート（インストール型 MCP サーバー）

uvがあれば、インストールせずにすぐ実行できます。データは PC 内の~/.insurance-claim-mcp/（SQLite）にのみ保存されます。

{
  "mcpServers": {
    "insurance-claim": { "command": "uvx", "args": ["insurance-claim-mcp"] }
  }
}

Claude Code: claude mcp add insurance-claim -- uvx insurance-claim-mcp PostgreSQLを使用する場合は、uvx --from "insurance-claim-mcp[postgres]" insurance-claim-mcpを実行し、DATABASE_URLを指定します。 エージェント向けの使用手順はskills/insurance-claim-mcp/SKILL.md、マーケットへの登録手順はdocs/PUBLISHING.mdを参照してください。

英語（米国の補足保険プラン）

病院の請求書に記載されたプランの給付一覧と ICD-10-CM コードに基づいて、米国の入院給付、傷害、重大疾病プランの給付額を推定します。計算は決定論的なフェイルクローズ型ルールエンジンで行います。給付一覧で確認できない給付は推測せず、NOT_EVALUATEDを返します。

claude mcp add insurance-claim -- uvx insurance-claim-mcp

対応する給付：入院時給付、入院日額給付（日数上限、免責期間）、ICU 日数、重大疾病一時金（ICD-10-CM のプレフィックス、保険金額に対する割合）、傷害骨折給付一覧、救急外来受診。エージェント向けの手順はskills/us-supplemental-claims/SKILL.mdを参照してください。データはローカル（~/.insurance-claim-mcp/）に保存されます。あくまで予想額であり、保険金請求に関する決定ではありません。

主な設計とアーキテクチャ

• LLM 推論と決定論的（Deterministic）ルールエンジンの分離
  • 非構造化データ（保険証券・病院の領収書画像）の読み取りとユーザーとの対話は AI クライアントが担い、ハルシネーションがあってはならない約款との照合と予想保険金の計算は、サーバーのルールエンジンが専任で処理します。
  • フェイルクローズの安全対策：約款原文の検証（verified=true）が完了していない、または保険証券（POLICY_CERTIFICATE）の出典が確認されていない特約は、推測で計算せずNOT_EVALUATED（0ウォン）として返します。
• MCP の3つの構成要素（Tools・Resources・Prompts）を標準実装
  • Tools（11個）：ユーザー登録（register_user）、保険の登録・更新（register_user_policy）、未マッピングの特約に関する再照会の確定（resolve_user_rider）、予想保険金の計算（evaluate_claim）など、状態の変更と処理を実行します。
  • Resources（3個）：オンボーディングガイド（insurance://guide/onboarding）、標準保障ルールカタログ（insurance://rules/standard）、保険会社の公式書類の依頼方法を案内する動的テンプレート（insurance://guide/document-request/{policy_type}/{product_name}）
• Prompts（1個）：段階的な保険登録と領収書の評価を促す標準 AI アシスタント手順（insurance_assistant_prompt）と、ai_follow_up_promptに基づく追加質問のオーケストレーション
• MCP 専用インターフェースとサーバーレス環境への最適化
  • 保険関連の機能は**FastMCP（Streamable HTTP /mcpおよびローカルのstdio）**でのみ提供します。Cloud Run の状態確認用の/api/health、/api/versionを除き、REST API、OpenAPI スキーマ、Web ブリッジ、紹介ページは提供しません。
  • Cloud Run のサーバーレススケーリング環境に対応するため、stateless_http=Trueとcombine_lifespansを適用しています。また、リバースプロキシの背後で/mcpが307リダイレクトされる際に発生する HTTPS から HTTP へのダウングレードを、ASGI ミドルウェアによるパスの正規化で解決しています。

利用ガイド

エンドユーザー（保険加入者）と設定担当者・運用担当者向けの総合的な使用方法は利用ガイドを参照してください。

ローカルでの実行

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.lock.txt
.\.venv\Scripts\python.exe -m uvicorn claim_service.main:app --app-dir src --port 8080

• 状態確認：GET /api/health、GET /api/version（認証不要）
• インストールに失敗する場合、またはpipがない場合（No module named pip、pip._vendorの欠落）：ローカル開発環境のセットアップ
• MCP エンドポイント（Streamable HTTP）：POST /mcp（または/mcp/）
• MCP のローカル実行（stdio）：.\.venv\Scripts\python.exe -m claim_service.mcp.server

データベースとセキュリティ

• デフォルト：ローカル SQLite（claim_service.db。プロジェクトのルートに作成され、.gitignoreによってコミット対象から除外されます）
• クラウド：環境変数DATABASE_URLに PostgreSQL の URL を指定します（例：postgresql+psycopg://...）
• 評価リクエスト（疾病コード、診療費）は保存せず、計算結果のみを返します。
• MCP HTTP アクセスは、ユーザーごとの API キー（X-User-KeyヘッダーまたはBearer）で認証します。キーの原文は発行時に一度だけ表示され、サーバーには SHA-256 ハッシュのみが保存されます。キー認証により、リクエストは所有ユーザーに紐付けられます（PIN の入力に代わります）。PIN で保護されたアカウントでは、PBKDF2-HMAC-SHA256（120,000回の反復）ハッシュによる検証を継続します。キーの発行・失効についてはユーザーごとの API/MCP キーガイド、接続設定についてはクライアント接続ガイド、総合的な使用方法については利用ガイドを参照してください。

テストと静的解析

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check src tests scripts
.\.venv\Scripts\python.exe -m mypy src

デプロイ

mainに CI を通過した変更をマージすると、GitHub Actions が Cloud Run に自動でデプロイし、 /api/health、/api/versionを確認します。手動デプロイは GitHub の Actions → Deploy to Cloud Run → Run workflowを選択するだけで実行できます。 初回設定に必要な GitHub の変数、Workload Identity Federation、権限については、 デプロイ設定ガイドを参照してください。運用環境へのデプロイは、このローカル環境からは実行しません。

진행 현황

STATUS.md

라이선스

MIT