Insurance Claim Estimator (KR + US)

insurance-claim-mcp

一款 MCP（Model Context Protocol）服务，可将药袋和医疗费用收据中的信息（KCD 疾病代码、处置、医疗费用）与已投保的保险条款进行对照，提供预估保险金。

仅提供参考性估算。实际是否赔付及赔付金额取决于保险公司的审核。

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

快速开始（安装型 MCP 服务）

如果已安装 uv，无需安装即可直接运行。数据仅存储在本机的 ~/.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。 Agent 使用说明请参阅 skills/insurance-claim-mcp/SKILL.md，市场发布流程请参阅 docs/PUBLISHING.md。

English (US supplemental plans)

根据计划的福利明细和医院账单上的 ICD-10-CM 代码，估算美国住院津贴、意外伤害和重大疾病计划的赔付金额。计算由确定性、故障关闭的规则引擎执行：明细未确认的福利会返回 NOT_EVALUATED，绝不猜测。

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

支持的福利：住院、每日住院津贴（最长天数、免赔期）、ICU 天数、重大疾病一次性给付（ICD-10-CM 前缀、保额百分比）、意外骨折赔付明细，以及急诊就诊。Agent 使用说明：skills/us-supplemental-claims/SKILL.md。数据保留在本地（~/.insurance-claim-mcp/）。仅为估算，不代表理赔决定。

核心设计与架构

• 分离大模型推理与确定性规则引擎
  • 非结构化数据（保险单、医院收据图片）的读取和用户对话由 AI 客户端处理；不会产生幻觉的条款比对和预估保险金计算则由服务器规则引擎负责。
  • 故障关闭安全措施：若未完成保险条款原文验证（verified=true），或无法确认附加险的保险单（POLICY_CERTIFICATE）来源，则不进行猜测计算，而是返回 NOT_EVALUATED（0 韩元）。
• 标准实现 MCP 三大组成部分（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；并通过 ASGI 中间件路径规范化，解决反向代理后访问 /mcp 时发生 307 重定向导致 HTTPS→HTTP 降级的问题。

使用指南

最终用户（保险投保人）及设置人员、运营人员的完整使用说明，请参阅使用指南。

本地运行

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

部署

将通过 CI 的变更合并到 main 后，GitHub Actions 会自动部署到 Cloud Run，并检查 /api/health、/api/version。也可以在 GitHub 中点击 Actions → Deploy to Cloud Run → Run workflow 手动部署。 首次设置所需的 GitHub 变量、Workload Identity Federation 和权限，请参阅 部署设置指南。此本地任务不会执行生产部署。

진행 현황

STATUS.md

라이선스

MIT