gristmill-mcp

一个 MCP 服务器，用于检查 AI 生成的代码，并返回确定性的结构和安全违规列表，以便 AI 编码代理在代码落地前修复自己的输出。

Grist 是送入磨坊研磨的谷物。AI 输出就是 grist——真正有价值的原材料，但未经加工。磨坊赋予它结构。

AI 写出 grist。Gristmill 让它成为可以交付的代码。

为什么是 MCP 服务器，而不是技能

技能是加载到模型上下文中的文本——它改变模型知道的内容。MCP 服务器是模型执行的程序——它改变模型能做什么。

风格指导（"优先使用类而非松散函数"）属于技能。验证（"此文件在第 12、40、66 行有 7 个顶级函数"）需要对文件运行代码。模型阅读自己的输出并推理"这看起来函数太多了"是一种伪装成观察的猜测——它没有关于"太多"在这个文件中意味着什么的真实依据，也没有可靠的计数方法。Gristmill 解析 AST 并进行计数。指令与执行之间的这种区别，就是为什么它作为一个服务器存在，而不是一段建议文本。

该服务器从不调用 LLM，在相同输入上运行结果从不变化，也从不输出置信度分数。相同输入 → 每次字节相同的输出。这种确定性就是整个产品的价值所在。AI 层位于此服务器之上，消费其发现结果并决定如何处理——服务器的工作止于报告带有行号的事实。

Related MCP server: code-verify-mcp

安装

git clone <this repo> gristmill-mcp
cd gristmill-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

Claude Code

通过 CLI 注册它，指向虚拟环境的控制台脚本：

claude mcp add gristmill -- /absolute/path/to/gristmill-mcp/.venv/bin/gristmill-mcp

或者直接将其添加到你的 MCP 配置中（项目中的 .mcp.json，或全局 Claude Code 配置）：

{
  "mcpServers": {
    "gristmill": {
      "command": "/absolute/path/to/gristmill-mcp/.venv/bin/gristmill-mcp"
    }
  }
}

其他 MCP 客户端

任何基于 stdio 的 MCP 客户端都可以启动相同的二进制文件——gristmill-mcp（或虚拟环境中的 python3 -m gristmill.server）使用标准 MCP stdio 传输协议，无需客户端特定配置。

命令行（无 MCP 客户端）

用于本地测试，或复现下面的工作示例，一个轻量级 CLI 封装了相同的引擎：

.venv/bin/gristmill-verify path/to/file_or_dir [--checks secrets structure comment_slop] [--severity-floor warning] [--json]

工作示例

demo/billing.py，一个 Stripe 计费助手的未经编辑的初稿：

import stripe

# I've added this as you requested — sets up the Stripe client
STRIPE_SECRET_KEY = None  # was a literal sk_live_... key — see note below

stripe.api_key = STRIPE_SECRET_KEY


def customer_create(config):
    return stripe.Customer.create(**config)


def customer_delete(config):
    return stripe.Customer.delete(config["id"])


def customer_find(config):
    return stripe.Customer.retrieve(config["id"])


def customer_update(config):
    return stripe.Customer.modify(config["id"], **config)

.venv/bin/gristmill-verify demo/billing.py

输出，其中包含一个真实的 Stripe 活动密钥形状的字面量（替换了上面的 None）：

gristmill: 1 files scanned, 0 skipped (2 error, 4 warning, 0 info) in 1ms
  [WARNING] STR002  billing.py:1  4 top-level functions share the prefix `customer_` — consider a `Customer` class or module
  [WARNING] STR003  billing.py:1  4 top-level functions take a first parameter named `config` — consider making it instance state
  [WARNING] CMT001  billing.py:3  Comment addresses the reader conversationally ('as you requested')
  [ERROR  ] SEC006  billing.py:4:22  Stripe live key assigned to `STRIPE_SECRET_KEY`
  [ERROR  ] SEC010  billing.py:4:22  String literal assigned to `STRIPE_SECRET_KEY`, which looks credential-shaped
  [WARNING] SEC011  billing.py:4:22  High-entropy string literal (5.1 bits/char) assigned to `STRIPE_SECRET_KEY`

（文件路径相对于最近的 .gristmill.toml 显示——demo/ 目录携带了自己的配置，因此此示例的输出独立于顶层项目配置保持稳定。）

注意： GitHub 的推送保护会阻止任何包含真实格式密钥的推送文件——包括在注释或 Markdown 代码块中，本 README 也不例外。demo/billing.py 当前已将密钥替换为 None 以解除初始推送的阻塞；这是一个 TODO，需要恢复（通过允许列表中的密钥扫描例外）以使演示重新生效。

--json 标志（或 verify MCP 工具，两者都返回）提供完整的结构化形式——文件、行、列、静态建议字符串，以及经过脱敏处理的 evidence 字段（sk_l… (49 chars)，绝不包含密钥本身）。

工具

verify

检查源文件中的密钥、结构问题和低质量注释。返回带有文件路径和行号的确定性发现结果。在生成或编辑代码后、将其作为完成品呈现之前调用此工具。

输入：paths（文件或目录，必填），checks（可选的 secrets/structure/comment_slop 子集，默认为全部），severity_floor（可选，默认为 info）。

输出：一个紧凑的人类可读摘要，后跟完整的结构化 JSON——文件、行、列、消息、脱敏证据，以及每个规则的静态建议字符串。发现结果始终按 path、line、rule_id 排序——这种稳定性使运行结果字节相同，并让模型能够直接导航到问题所在。

explain_rule

接受一个 rule_id（例如 SEC001）并返回其原理、捕获内容、遗漏内容以及如何抑制它——与 docs/RULES.md 相同的内容，按需提供，以便 verify 输出保持简洁。

规则

每个规则的完整原理、假阴性说明和抑制说明：docs/RULES.md。

配置

项目根目录下的 .gristmill.toml，所有键均为可选：

[checks]
enabled = ["secrets", "structure", "comment_slop"]

[structure]
max_top_level_functions = 5
max_function_lines = 60

[secrets]
entropy_threshold = 4.5

[ignore]
paths = ["legacy/**", "vendor/**"]
rules = ["CMT003"]

.gristmillignore 文件（gitignore 语法）与 [ignore] paths 配合使用。在标记行或其上一行也支持内联抑制：

SUPPRESSED = "ghp_" + "..."  # gristmill: ignore SEC003

// gristmill: ignore SEC003
const suppressed = "ghp_" + "...";

语言支持

• Python — 完全支持（stdlib ast 和 tokenize）。

• JavaScript/TypeScript — 完全支持，通过 tree-sitter 及编译后的 tree-sitter-javascript 和 tree-sitter-typescript 语法实现，而非调用基于 Node 的解析器。这以编译后的 Python 依赖为代价，换取了独立于主机是否安装 Node 的独立性——无论 node 是否在 PATH 上，structure 和 comment_slop 都能以相同方式工作，并且提供真正的 AST 而非纯文本回退。

• 其他语言 — secrets 检查仍然运行（基于正则表达式且与语言无关）；对于该文件，structure 和 comment_slop 被跳过，并在 skipped_paths 中报告。

局限性

在信任此工具超出其应得范围之前，请阅读以下内容：

• secrets 仅捕获有形状或高熵的字符串。 像 hunter2 这样的低熵人类密码永远不会被标记——没有可靠的方法将其与普通短字符串区分开来。在运行时拼装的凭据（字符串拼接、os.environ.get(...) or "fallback"、base64 解码的片段）对静态文本的正则表达式/熵检查是不可见的。

• 跨文件的结构性问题不可见。 structure 一次只查看一个文件；应该跨文件拆分的类，或两个不同模块中的重复逻辑，不在范围内。

• comment_slop 的 CMT002 故意设置得很窄。 它是该集合中假阳性风险最高的规则，因此实现上偏向于保持沉默——它遗漏真实叙述的频率远高于过度标记。确切的子集匹配规则请参见 docs/RULES.md。

• Python 和 JS/TS 之外的语言仅获得 secrets 覆盖。 v1 版本中不对 Go、Rust、Ruby 等语言进行结构或注释分析。

• 这不是一个 Git 历史密钥扫描器。 它按给定方式检查工作树。已提交但后来从当前文件中删除的密钥不是此工具的关注点（Git 历史扫描器是一个不同的、互补的工具）。

• 无自动修复。 Gristmill 报告；调用模型决定更改什么以及如何更改。这种分离是有意为之（参见上面的"为什么是 MCP 服务器，而不是技能"），但这意味着单独的 verify 调用永远不会修复任何问题。

一个夸大其覆盖范围的工具，比一个坦诚说明其盲点的工具更糟糕——在这里，沉默胜过虚假的信心，就像它胜过嘈杂的发现一样。

路线图

v1 明确不在范围内，按大致优先级排序：

• 自动修复/补丁生成（目前由调用模型使用 verify 发现结果完成）

• 依赖新鲜度和 CVE 检查（需要网络调用包注册表——自然的 v2 功能）

• Python 和 JavaScript/TypeScript 之外的语言支持

• 对已提交但后来删除的密钥进行 Git 历史扫描

• 托管服务、Web UI 或仪表板

开发

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest tests/ -q

编辑 src/gristmill/rules.py 后重新生成 docs/RULES.md：

.venv/bin/python3 scripts/generate_rules_doc.py

测试覆盖（tests/）：已知脏数据的黄金文件输出、有并行和无并行情况下的 10 倍确定性、必须产生零发现的假阳性语料库、脱敏处理（原始密钥绝不进入任何输出字段）、以及健壮性（语法无效、二进制、空文件和超大文件永远不会导致运行崩溃）。

许可证

MIT — 参见 LICENSE。