mcp-chainladder

mcp-chainladder

为 Claude 提供精算链梯法准备金计算。 一个 Model Context Protocol 服务，为 Claude 提供计算 IBNR、预测最终赔付额、运行 Mack （1993）随机误差估计、检查 Mack（1994）模型 假设，以及从 CSV 解析损失三角形的工具——所有操作都可通过自然语言 对话完成。

仅用于计算——不构成精算建议。 这是一个机械式的 链梯法计算器。数据、因子、尾部因子和 排除项的选择，以及对随机误差指标的解释， 都需要专业的精算判断。

---

功能

通过 MCP 提供八种工具。提出问题时，Claude 会选择合适的工具； 你无需按名称调用它们。

工具	Claude 会在何时使用
compute_chain_ladder	“这个三角形的 IBNR 是多少？”——核心工具
project_triangle	“完整的预测三角形是什么样的？”
mack_stochastic	“总准备金的不确定性有多大？”
mack_diagnostics	“有没有异常值或趋势问题？”
parse_csv_triangle	“对这个 CSV 文件运行链梯法”
to_incremental	“显示增量发展模式”
to_cumulative	“将这些增量值累加”
sample_triangle	“给我看一个可运行的示例”——快速演示

所有数值约定均与 Mack 1993 和 Mack 1994 论文一致；在教科书中的 10×10 三角形上，计算结果与 手动计算的差异稳定在约 1e-12 以内。

---

安装

pipx install mcp-chainladder
# or, to run on demand without installing:
uvx mcp-chainladder

需要 Python 3.10 或更高版本；除官方 MCP SDK 外，没有其他运行时依赖。

接入 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

退出并重新打开 Claude Desktop。每个对话中的 🔌 图标下都会显示三角形工具。

对于 Cursor / Cline / Continue / Zed——使用相同的 mcpServers 配置块，每个应用 的配置文件位置不同（相关文档会介绍具体操作步骤）。

---

示例

对 CSV 运行链梯法

Me: I have a paid-loss triangle at ~/Desktop/motor_2026Q1.csv.
    Run the chain ladder and tell me the IBNR.

Claude: [calls parse_csv_triangle, then compute_chain_ladder]
        Loaded a 10×10 cumulative triangle. Using volume-weighted
        factors:
          • Total paid to date: 49,458,000 USD
          • Total ultimate:     65,883,400 USD
          • Total IBNR:         16,425,400 USD
        Selected factors trend from 1.879 at the front of the
        triangle down to 1.002 at the tail.

检查是否需要担心模型假设

Me: Same triangle — any reason not to trust the projection?

Claude: [calls mack_diagnostics]
        Three flags worth a look:
        • Inflation trend: slope 0.053, p ≈ 1e-12 — STRONG evidence
          link ratios are drifting upward across accident years.
          This violates Mack's homogeneity assumption; consider
          weighting recent years more.
        • Calendar-year: Z = 0.0, p = 1.0 — no diagonal effect.
        • Independence: Z = -0.35, p = 0.73 — no obvious dependence
          across development columns.
        • Outliers: 0 cells exceed |2σ|.

        The inflation finding is the one to act on.

排除异常值后重新运行

Me: Drop the link ratio at AY 3, dev period 2→3. What changes?

Claude: [calls compute_chain_ladder with excluded=[[2, 1]]]
        Excluding (AY 3, 2→3):
          • Volume factor at 2→3 moves from 1.331 to 1.328
          • Total IBNR moves from 16,425 to 16,389 (−36)
          • Mack SE total moves from ±354.6 to ±348.2
        Net: small enough to be a "robustness check passes" rather
        than a finding.

---

工具参考

每种工具都会返回一个 JSON 对象（project_triangle/to_incremental/to_cumulative 返回 二维列表）。Claude 会直接读取服务端的说明和类型——你无需 记住这些数据结构——不过这里提供了一份速查表。

compute_chain_ladder(triangle, selected_factors?, tail?, excluded?)

端到端的链梯法计算。

返回字段	含义
volume_factors[j]	转换 j→j+1 的全年度加权平均年龄发展因子
simple_factors[j]	各个链接比率的非加权平均值
selected_factors[j]	实际用于预测的因子集（默认为 volume）
individual_factors[i][j]	每行的链接比率 C[i,j+1] / C[i,j]；如果这对数据未被观测到，则为 null
cdf[j]	累计发展因子，直至最终赔付额；cdf[-1] == tail
latest_diagonal[i]	每个 AY 最近一次观测值
ultimates[i]	每个 AY 的预测最终赔付额
ibnr[i]	每个 AY 的最终赔付额 − 最新值
total_*	上述三项的总和
n_acc、n_dev	三角形维度

mack_stochastic(triangle, selected_factors, excluded?)

Mack（1993）无分布假设标准误。返回每个发展期的 σ̂²_j（仅有一个观测值时使用尾部规则回填）、每行的 SE 和 CV，以及根据公式 5.15 纳入行间协方差后的 SE_total / CV_total。

mack_diagnostics(triangle, selected_factors, excluded?, outlier_threshold?)

返回标准化残差、异常值（|r| > threshold，默认值为 2.0）、日历年符号检验、相邻发展列间的 Spearman 独立性检验，以及对数链接比均值相对于事故年索引的通胀斜率。

将 p 值区间翻译为通俗表述：

p < 0.005 → strong evidence
p < 0.05  → significant
p < 0.10  → borderline
p ≥ 0.10  → no evidence

parse_csv_triangle(path)

从磁盘读取 CSV，将空白 / NA / NaN / N/A / − 单元格视为未观测值，去除嵌入的千位分隔逗号，并跳过表头 / 元数据行。返回三角形 + 维度 + 读取文件的绝对路径（可用于让助手确认加载了哪个文件）。

project_triangle(triangle, selected_factors)

使用链梯法投影填充三角形的右下部分。返回完整的矩形 list[list[float]]（不含 null）。对于没有可用于向前投影的观测值的行，返回 NaN。

to_incremental(cumulative) / to_cumulative(incremental)

两种转换。未观测单元格保持未观测；对已观测单元格进行反向转换可得到精确结果。

sample_triangle()

返回教科书中的 10×10 累计赔付三角形。可用于自检：将其传给 compute_chain_ladder，应得到 赔付 49,458 / 最终赔付 65,883 / IBNR 16,425。

---

三角形格式

[
    # AY 1 — fully developed
    [1000, 1855, 2423, 2988, 3335, 3483, 3552, 3603, 3624, 3631],
    # AY 2 — observed through dev 9
    [1113, 2103, 2774, 3422, 3844, 4010, 4090, 4148, 4172, None],
    # …
    # AY 10 — only the first observation
    [2640, None, None, None, None, None, None, None, None, None]
]

• 外层索引 = 事故年，按从早到晚排列
• 内层索引 = 发展期，0 = 第一个账龄
• 未观测单元格使用 None（或 JSON null）
• 所有行的长度必须相同 — 在末尾补充 null

---

测试

pipx install --editable mcp-chainladder
pytest -q

测试会将每个公开工具的结果与该教科书三角形的知名基准值进行比对，精度约为 1e-9。

Pro 版

<< 审核中 — 即将推出 >>

免费版包含上面列出的全部 8 个工具。Pro 可解锁更多方法 + 批量工作流，需通过本地许可证文件授权，文件位于 ~/.chainladder/license（或 $CHAINLADDER_LICENSE_FILE 指定的位置）。

**Pro 许可证目前仅用于内部和测试用途，不向公众开放。**目前尚无购买渠道。下方列出 Pro 工具供参考；面向外部用户时，这些工具会继续返回 pro_license_required。

Pro 工具	功能
pro_license_status	查看当前许可证状态（可免费调用）
interpret_diagnostics	Mack 检验，附带结论标签 + 通俗易懂的摘要 + 建议采取的行动
sensitivity_analysis	每次剔除一个链接比率，并按 IBNR 影响进行排序
tail_extrapolation	拟合指数 + 反幂尾部模型，并推荐最佳拟合
bornhuetter_ferguson	BF 计提方法，并与 CL 并列比较
compare_methods	一次调用运行 CL + BF，报告差异 + 最大偏差
generate_pdf_report (即将于 v1.2 推出)	完整的 5 页精算 PDF — 封面 / 三角形 / 因子 / 结果 / 3D 损失曲面
batch_csv_processing (即将于 v1.2 推出)	对目录中的 CSV 三角形执行链梯法
cape_cod、mack_bf (即将于 v1.3 推出)	更多计提方法，均会返回并列比较结果

许可证文件格式

{
  "product":  "mcp-chainladder-pro",
  "owner":    "[email protected]",
  "expires":  null,
  "key":      "CL-PRO-1A2B3C4D",
  "signature": "…"
}

将文件放在 ~/.chainladder/license 中（文件所在目录必须已存在；服务不会创建该目录）。下次 Claude 调用 Pro 工具时，工具会立即解锁并响应。

如果许可证缺失或已过期，每个 Pro 工具都会返回 {"error": "pro_license_required", "status": {...}}，而不是执行计算 — Claude 会读取状态并指引你前往升级 URL。无论许可证状态如何，免费版工具始终可用。

许可证

MIT。参见 LICENSE。