rigor-mcp

rigor

为 AI Agent 提供经验证的统计推断。

大模型擅长复述统计知识，却不擅长可靠地实际执行统计分析——t 统计量或所需样本量，是从训练数据中回忆出的数字，而不是计算并核验得出的结果。rigor 提供了另一种选择：经典假设检验（参数和非参数）、相关与回归、效应量、检验效能／样本量计算、多重比较校正，以及适用于结果在最终确定前被多次检查的始终有效序贯检验，所有结果都从头计算，并以附带引文、经过假设核验的答案形式返回；此外还提供帮助选择合适工具的决策助手，以及可一次运行／校正多项比较的批处理工具，因为“我到底该用哪种检验”“我忘了校正多重比较”和“我看了仪表板后提前停止”都是常见的独立失误，并非只是把某个公式算错。

一个具体示例。 人人都只记得个大概的样本量数字，是 Cohen（1988）亲自给出的示例：d=0.5，alpha=.05，power=.80 -> 每组 n≈64。它出现在每本教材和每份幻灯片中，因此遇到看起来相似的问题时，人们也会套用这个答案。换成 d=0.46、power=.85 呢——这是适度且现实的调整，并非陷阱：

$ rigor power ttest-2samp --effect-size 0.46 --power 0.85
Required n per group = 84.86 (round up: 85)

结果是 85，而不是“差不多 64”——相比那个半记半忘的数字，招募人数要多三分之一。问题看起来和那个著名示例相似。公式本身并不难（power.py 用几行代码就能在两个方向上运行相同的二分搜索）；失误之处在于，回忆一个看起来相近的答案，感觉和算出正确答案毫无区别，直到发现数字错了。

第二个具体示例。 Agent（或人）盯着实时实验仪表板，每次有新数据就检查 p 值，一旦低于 0.05 就立刻停止，这是教科书级的自我欺骗方式——无论是否采用固定样本量设计，这都是人们监控进行中实验的默认方式：

$ rigor sequential peeking-inflation --n-looks 10
Naive repeated peeking, 10 looks, nominal alpha=0.05
  estimated true alpha = 0.1918 (+/- 0.0028 MC SE, 20000 trials)

在名义显著性水平为 5% 时检查 10 次，实际运行的显著性水平更接近 19%——即使真实效应为零，约五分之一的“显著”结果也只是噪声。rigor sequential proportion / rigor sequential mean 会改为计算始终有效的 p 值（mSPRT，Johari 等人，2017 年）：每次有新观测值后都可以检查，同时将假阳性率保持在名义水平，无需预先承诺样本量，也无需校正“我看了多少次”。

它以 MCP 服务的形式构建：对当前 MCP 生态进行扫描后发现，统计学／实验设计是 Agent 常见需求中少数尚未有人覆盖的领域之一（生态中已有用于编程文档的 Context7、多个物理／工程／化学／地理领域服务，甚至还有 Bentley 的 STAAD 集成）。

统计分析本身（rigor/distributions.py、inference.py、nonparametric.py、correlation.py、regression.py、effect_size.py、power.py、corrections.py，以及 advisor.py 和 batch.py 中的决策／批处理助手）仅使用标准库，没有依赖项。整个软件包确实依赖官方的 mcp SDK，因为 MCP 服务是它提供的核心组成部分，而非附加组件——请参阅安装。

安装

pip install rigor-mcp

（PyPI 发行包名为 rigor-mcp，因为单独的 rigor 已被一个无关的软件包占用；可导入的软件包和 CLI 命令仍然都叫 rigor。）这会同时安装两个控制台命令：rigor（CLI）和 rigor-mcp（MCP 服务）——特意采用单次安装，无需另外配置额外依赖，因为 uvx rigor-mcp（大多数 MCP 客户端实际调用它的方式）无法指定额外依赖项。

包含内容

• rigor/distributions.py — 基于标准库从头实现 t、卡方和 F 分布（正则化不完全伽马函数／贝塔函数），并通过精确闭式恒等式验证（t(1) = Cauchy、chi2(2) = 缩放指数分布、t² = F(1, df)），而非依赖未经核验的转录结果。
• rigor/inference.py — 单样本／双样本和配对 t 检验、单比例／双比例 z 检验、卡方拟合优度检验和独立性检验、Fisher 精确检验（2x2，通过超几何分布精确计算——小样本替代方法；chi_square_independence 自身的低期望计数警告会指向它）、McNemar 检验和 McNemar 精确检验（2x2，用于配对比例——例如同一批受试者的前后回答；two_proportion_z_test 的独立组假设不适用于此情形；精确版本通过对不一致配对使用二项分布计算，与 Fisher 精确检验相对于 chi_square_independence 的小样本关系相同）、单因素方差分析，以及用于检验方差相等性的 Levene（Brown-Forsythe）检验。每项检验都返回一个 TestResult：统计量、自由度、双尾 p 值、置信区间、引用文献和假设警告（例如依赖小样本正态性、期望单元格计数过低）。
• rigor/nonparametric.py — Mann-Whitney U、Wilcoxon 符号秩和 Kruskal-Wallis 检验：分别是 two_sample_t_test／paired_t_test／one_way_anova 的非参数替代方案，适用于参数检验自身的假设警告表明结果可能不可靠的情况。基于秩并校正并列值；同样返回 TestResult。
• rigor/correlation.py — Pearson（线性）和 Spearman（单调，通过秩计算）相关分析，每项都以 TestResult 返回（H0：无关联），并通过 Fisher z 变换给出置信区间。
• rigor/regression.py — 简单（单预测变量）普通最小二乘回归：斜率、截距、R²，以及斜率的显著性检验和置信区间。
• rigor/effect_size.py — Cohen's d、Hedges' g、Cohen's h、Cramér's V、eta²/omega²（用于 one_way_anova），以及秩双列相关（用于 mann_whitney_u）。
• rigor/power.py — 单样本／双样本 t 检验和双比例 z 检验的检验效能与所需样本量（单样本公式也适用于 paired_t_test，因为配对 t 检验就是对差值进行的单样本 t 检验）。两种方向（给定 n，求检验效能；给定检验效能，求 n）通过构造实现精确的数值互逆（对同一个底层检验效能函数使用二分法），并使用 Cohen（1988）的 d=0.5/α=.05/power=.80 教科书参考案例（n≈64）进行合理性检查。
• rigor/corrections.py — Bonferroni 和 Benjamini-Hochberg（FDR）多重比较校正。
• rigor/advisor.py — recommend_test：这是决策辅助工具，而非统计量。回答数据／问题的若干特征（连续型／比例／分类型／有序型、组数、是否配对、样本是否少或偏斜、关注关联而非差异、是否重复检查），即可获得应调用的工具、当该检验的假设看起来不可靠时可改用什么，以及应同时运行什么。它将其他各模块文档字符串中已有的交叉引用汇总为一个可调用的答案，让 Agent 无需事先读完所有文档即可找到相关检验。checked_repeatedly=True 会在有相应工具时转到 sequential_* 工具（适用于两独立组、连续型或比例数据）；否则会明确说明情况，而不是悄悄忽略该标志。
• rigor/batch.py — pairwise_group_comparisons：一次性对 2 个或更多组进行所有成对比较（可选择 two_sample_t_test 或 mann_whitney_u），并对整批比较应用 Bonferroni／BH 校正。这样就无需 Agent 手动编排 k*(k-1)/2 次单独调用和一次校正调用，从而避免忘记校正步骤。显著结果返回后，后续自然可进行的 one_way_anova／kruskal_wallis 已在各自的文档字符串中给出建议。
• rigor/sequential.py — 通过混合序贯概率比检验（mSPRT）进行始终有效（可安全窥视）的序贯检验：本包中的其他检验都假设样本量预先固定且只检查一次；此检验专为每次获得新观测后重新检查而设计（例如实时 A/B 测试仪表板），不会像在每次检查时天真地重复运行固定样本检验那样抬高假阳性率。采用闭式公式（Robbins 1970；Johari、Koomen、Pekelis 和 Walsh 2017），覆盖双样本均值和双比例，另提供 naive_peeking_inflation——通过固定随机种子的 Monte Carlo 演示，展示该方法旨在避免的确切失效模式。tests/test_sequential.py 中通过模拟检查始终有效这一保证本身（而不仅是单个 p 值的正确性）。有一个刻意违背直觉的选择：当 n 很小时出现完全分离（例如 0/5 对 5/5），结果会报告没有可用于决策的证据（p=1），而不是报告一次性 Fisher 精确检验会给出的最强证据——因为该检验会在每次观测后检查，而小样本下的完全分离在零假设成立时纯粹由偶然造成的频率足够高（每组 n=1 时约为 ~40%），若将其视为证明，反而会破坏始终有效这一保证。开发期间通过保证模拟发现了这一点，而非通过代码审查发现。
• rigor/cli.py — 提供以上所有功能的 CLI（仓库根目录下的 rigor.py 是一个轻量封装，因此即使未安装任何内容，也能在普通检出目录中运行 python3 rigor.py ...）。
• rigor/mcp_server.py — 一个 MCP 工具封装，向任何 MCP 客户端（Claude Code、Claude Desktop 等）公开全部 37 项操作。已通过 stdio 与真实客户端进行端到端冒烟测试：工具发现以及代表性调用均对照已知参考值进行了核验，包括完整往返流程仍得出 Cohen（1988）案例中的 n=63，以及 Fisher 最初的“品茶女士”案例中的 p≈0.4857。

用法

安装后使用 CLI：

rigor ttest one-sample --data 5.1,4.9,5.3,5.0,4.8,5.2 --mu0 5.0
rigor corr pearson --x 1,2,3,4,5 --y 2,4,5,4,5
rigor regress --x 1,2,3,4,5 --y 3,5,7,9,11
rigor nonparam mann-whitney --a 1,2,3 --b 4,5,6
rigor power ttest-2samp --effect-size 0.5 --power 0.8
rigor recommend --outcome-type continuous --n-groups 3   # which test fits?
rigor posthoc --groups "1,2,3|4,5,6|7,8,9" --labels A,B,C  # pairwise + correction
rigor mcnemar --table "794,86;150,570"    # paired proportions, e.g. before/after
rigor sequential proportion --successes1 55 --n1 500 --successes2 40 --n2 500 --tau 0.05
                # ^ peeking-safe -- rerun as n1/n2 grow, no correction needed
rigor sequential peeking-inflation --n-looks 10   # ...vs. naively checking 10 times
rigor --help   # full list of subcommands (ttest, ztest, chi2, fisher, mcnemar,
                # mcnemar-exact, anova, levene, nonparam, corr, regress,
                # effect-size, power, correct, recommend, posthoc, sequential)

也可以直接从检出目录运行，无需安装：

python3 rigor.py ttest one-sample --data 5.1,4.9,5.3,5.0,4.8,5.2 --mu0 5.0

通过 stdio 运行 MCP 服务（Claude Code 等本地客户端所使用的传输方式）：

pip install rigor-mcp
rigor-mcp

也可以从检出目录运行：pip install mcp && python3 -m rigor.mcp_server。

在 Claude Code 中注册：

claude mcp add rigor -- rigor-mcp

（或者，从检出目录运行：claude mcp add rigor -- python3 -m rigor.mcp_server，在此仓库的根目录下运行，或使用绝对模块路径）。使用 MCP Inspector 进行交互式试用时，请将其作为脚本运行，而不是使用已安装的命令——这意味着必须手动将包根目录添加到路径中，因为 Inspector 会直接导入该文件：

pip install "mcp[cli]"
PYTHONPATH=. mcp dev rigor/mcp_server.py

已处理的传输层边缘情况

对于零方差样本，cohens_d 会按其自身文档约定正确返回 +inf/-inf，但非有限浮点数通过 MCP 的结构化内容序列化为 JSON 时会变成 null，这过去会导致工具自身的数值类型输出架构校验失败并使调用崩溃。现在，MCP cohens_d 工具返回 {"value": float | null, "warnings": [...]}，而非单独的浮点数，因此会明确报告这种情况（空值，并附上指出方向的警告），而不会崩溃。此修复仅适用于输出架构为裸标量的工具——已通过真实 stdio 确认，所有返回字典的工具（所有基于 TestResult 的工具，以及 simple_linear_regression）都能将非有限字段直接作为 JSON 的非标准 Infinity 传递，因为通用字典返回值不会受到严格的逐字段数值架构约束。在返回裸浮点数的工具中，只有 cohens_d 可能实际产生非有限值。

测试

python3 -m unittest discover -s tests -v

共 203 项测试：182 项直接测试统计/决策逻辑（其中，针对 sequential.py，包括一项模拟测试，验证反复查看数据时始终有效的保证本身成立，而不仅仅是验证单个 p 值是否正确；开发期间还有一项模拟测试捕获了一个真实错误：早期草案将小样本的完全分离视为最强证据，而不是通常情况下的小样本噪声，从而破坏了同一项保证）；18 项会启动 mcp_server.py，模拟真实 MCP 客户端并通过连接检查结果（如果未安装 mcp，则会自动跳过）；3 项会检查 server.json 的元数据（版本、描述长度、名称长度）是否符合 pyproject.toml 或 MCP Registry 自身的限制（这两个文件没有其他关联——参见 test_release_metadata.py）。

许可证

MIT——详见 LICENSE。