Python Code Validator

Python 代码验证器

一个 MCP 服务，可根据 Python 代码应满足的示例对其进行验证、修复和运行——通过 HTTP 在 https://api.statemind.ai/mcp 提供 validate_python、repair_python 和 execute_python，提供免费密钥，无需账户。

这是一项托管服务，可证明 AI 生成的 Python 代码确实实现了你的要求。说明意图——断言或 doctest 行——代码便会在无网络、只读文件系统的容器中据此运行；只有所有示例都通过，才会返回修复结果。在 QuixBugs 缺陷集上，41% 的缺陷得到修复，77% 的代码因未实现其声称的功能而被拒绝；对修正后的程序没有误报——而 ruff 和 mypy 对其中任何缺陷都没有报错（具体数据）。

无需说明意图的检查也已包含：语法和 lint 诊断、AST 安全策略（还能捕获隐藏在动态导入和运行时属性查找背后的调用）、bandit 检查、凭据扫描和确定性修复——最终给出一个判定和评分。同一问题在十分钟内重复询问时，会直接返回首次答复且不收费（x-msvc-repeat: 1）。

此仓库包含客户端部分：MCP 配置、CI 脚本和 pre-commit 钩子。服务本身运行在 https://api.statemind.ai，因此无需安装或托管任何内容。

无需账户即可获取密钥

curl -s -X POST https://api.statemind.ai/v1/keys
# {"api_key": "msvc_free_…", "tier": "free", "calls_per_day": 25, "modes": ["static"]}

每天可进行 25 次静态检查，按 UTC 日期计量，每个地址可获取少量密钥：足以试用并在小型项目中运行，但不适合大量使用。每个答复都会附带额度状态（x-quota-remaining、x-quota-reset），客户端可以在额度用尽前降低请求频率。

MCP

已在官方 MCP 注册表中注册为 ai.statemind/python-code-validator；该名称通过提供服务的域名验证，而非 GitHub 账户。任何 MCP 客户端都可以添加以下代码块：

{
  "mcpServers": {
    "python-code-validator": {
      "type": "http",
      "url": "https://api.statemind.ai/mcp",
      "headers": { "Authorization": "Bearer msvc_free_…" }
    }
  }
}

• Claude Code：claude mcp add --transport http python-code-validator https://api.statemind.ai/mcp --header "Authorization: Bearer msvc_free_…"
• Cursor：~/.cursor/mcp.json，使用相同的代码块。
• VS Code / Copilot：在 "servers" 下配置 .vscode/mcp.json。

只能启动命令的客户端则使用此仓库中的 stdio 桥接程序，它会通过 HTTPS 转发相同的工具：

{
  "mcpServers": {
    "python-code-validator": {
      "command": "python3",
      "args": ["/path/to/python-code-validator/mcp_stdio.py"]
    }
  }
}

也可以使用容器；此处的 Dockerfile 可构建该容器：

docker build -t python-code-validator .
docker run -i --rm -e VALIDATOR_API_KEY python-code-validator

Gemini CLI 可将相同的桥接程序安装为扩展，并附带让它实际投入使用的指令文件：

gemini extensions install jkanselaar/python-code-validator

三个工具，名称体现了它们对代码的操作：

工具	运行代码	密钥
validate_python	否	免费
repair_python — 也会返回 fixed_code	否	付费
execute_python — 也会在沙盒中运行代码	是	付费

旧版单一工具 python_code_validator 及其 mode 参数仍会响应已配置该工具的客户端，但已不再列出。

说明代码原本应实现的功能

上述所有检查都可能在函数计算结果错误时通过。能发现这类问题的只有意图，而提出代码请求的 Agent 是唯一知道意图的一方——因此请将意图一并传入：

{"code": "def bitcount(n): …", "mode": "execute",
 "options": {"examples": "assert bitcount(127) == 7"}}

Doctest 行（>>> bitcount(127) 接着是 7）同样适用，源码中已有的 >>> 示例也一样。execute_python 会在沙盒中运行这些示例：未通过的示例会产生 python:example-mismatch 错误；只有所有示例都通过，修复搜索才会返回修复结果。在 QuixBugs 缺陷集上——其中包含真实缺陷，正确性由隐藏测试输入决定——41% 的缺陷得到修复，77% 的代码因未实现其声称的功能而被拒绝，且对修正后的程序没有误报。

重复调用不收费：相同密钥针对相同问题——相同模式、代码和示例——会直接返回已有答复，并标记 x-msvc-repeat: 1。因此，逐步检查自身工作的 Agent 不会因那些不可能发生变化的判定而被收费。

Claude Code 插件

指令可能会被忽略；钩子不会。插件会在 Claude Code 写入或编辑 Python 文件的同一轮中检查每个文件，并将错误反馈给模型，而不是交给你：

/plugin marketplace add jkanselaar/python-code-validator
/plugin install python-code-validator@statemind

无需配置：首次使用时，它会自行生成并保存一个免费的密钥。通过检查的文件不会有任何提示；未通过的文件会指出问题行并中止当前轮次；相同的文件不会被重复检查。它不会因自身问题而结束会话——如果服务无法访问或免费额度用完，会让当前轮次继续，并说明如何提高额度。

设置 VALIDATOR_API_KEY，即可使用付费密钥代替免费层级；设置 VALIDATOR_URL，即可指向你自己的部署。插件还附带 validate-python 技能，用于完成钩子无法做到的部分：将预期行为编写成示例，并针对示例运行代码。

Cursor 钩子

同一脚本已接入 Cursor 的 postToolUse。检查结果会作为对话上下文返回，而不是通过退出码返回：

mkdir -p .cursor/hooks
base=https://raw.githubusercontent.com/jkanselaar/python-code-validator/main
curl -sf $base/plugin/hooks/validate_written.py -o .cursor/hooks/validate_written.py
curl -sf $base/cursor/hooks.json -o .cursor/hooks.json

项目钩子从项目根目录运行，因此 cursor/hooks.json 中的命令是相对于项目根目录的路径。如果要让钩子应用于所有项目，请将脚本放在 ~/.cursor/hooks/ 中，并将同一代码块放入 ~/.cursor/hooks.json，其中的命令为 python3 ./hooks/validate_written.py --cursor。

让 Agent 使用它

配置服务并不会让它被调用；起作用的是指令文件。本仓库中的 AGENTS.md 就是该文件，其中的文本可以按客户端读取的任意文件名放入任何项目：

mkdir -p .github
curl -sf https://raw.githubusercontent.com/jkanselaar/python-code-validator/main/AGENTS.md \
  | tee AGENTS.md CLAUDE.md GEMINI.md .github/copilot-instructions.md >/dev/null

Cursor 使用带 front matter 的规则，因此需要单独的文件——将 .cursor/rules/python-code-validator.mdc 复制到项目的 .cursor/rules/ 目录中。

如果你更愿意在现有指令中添加一行，简而言之：

编写代码前，先用 assert 示例写明代码应实现的功能，并将这些示例传入 options.examples。每次编辑后调用 validate_python；函数完成后调用一次 execute_python，此后只有在函数行为发生变化时才再次调用。调用返回 fixed_code 时，请采用它——服务已使用你的示例运行了代码。不要展示返回 valid: false 的代码。

CI

服务会提供客户端，因此工作流无需检出本仓库，也不需要密钥：

- run: |
    curl -sf https://api.statemind.ai/v1/client -o validate.py
    python3 validate.py --changed-against "origin/${{ github.base_ref }}"

或者作为操作从 Marketplace 使用：

permissions:
  contents: read
  pull-requests: write   # so the run can comment its result on the pull request
steps:
  - uses: jkanselaar/[email protected]
    with:
      api-key: ${{ secrets.VALIDATOR_API_KEY }}   # optional; free tier without it

修改过的 Python 代码会经过验证，问题行会在差异中标注；遇到语法错误和不安全模式时，作业会失败。对于服务直接拒绝的文件（超过 200 kB 限制），会跳过并发出警告，而不会导致运行失败。

运行还会在拉取请求中留下一条评论；之后有新的推送时，会就地编辑这条评论，而不会重复添加。评论会说明哪些内容通过了检查、哪些内容已修复，以及当天还剩多少额度。如果没有 pull-requests: write 权限，则不会写入任何内容，作业也不受影响；设置 comment: "false" 可关闭评论。

在免费层级中，操作会将密钥保存在工作流缓存中，每个仓库每天一个，因此额度归仓库所有，而不是归某次运行所有。设置 api-key 后，将跳过缓存。

Pre-commit

repos:
  - repo: https://github.com/jkanselaar/python-code-validator
    rev: v1.22.0
    hooks:
      - id: python-code-validator

客户端本身

validate.py 仅使用标准库，因此也可以在 Makefile、git 钩子或容器中通过 python validate.py file.py 运行：

$ python3 validate.py service.py
::error file=service.py,line=88,title=SyntaxError::invalid syntax
FAIL service.py score=0.66

0/1 files accepted

设置 VALIDATOR_API_KEY 时会使用该密钥；否则，客户端会生成一个免费密钥——如果 VALIDATOR_KEY_FILE 指定了路径，就将密钥保存在该路径中，这样一系列运行可以共用同一份额度。VALIDATOR_URL 用于将客户端指向另一个部署。VALIDATOR_SOURCE 用于指定调用方，该值只会被计数：在工作流内运行时，会自动将调用方记为 github-action。

徽章

每次拉取请求都会检查 Python 代码的仓库可以这样说明：

[![Python validated](https://img.shields.io/badge/python-validated-2ea44f?logo=python&logoColor=white)](https://api.statemind.ai/?src=badge)

HTTP

curl -s https://api.statemind.ai/v1/validate \
  -H "Authorization: Bearer $VALIDATOR_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"code": "def f(:\n    pass\n", "mode": "static"}'

mode 可以是 static、repair 或 execute；repair 和 execute 需要配置密钥。提交的代码不会被记录。

被拒绝的调用会说明应如何处理，让没有可询问运维人员的调用方也能自行解决：

{"error": "payment_required",
 "remedy": {"action": "upgrade_key", "hint": "A free key covers static only. …"}}

为调用付费

免费密钥每天可进行 25 次静态检查，而每个地址每天只能获得几个密钥，因此这项额度是试用额度，而非长期供应。超出额度后，密钥会附带额度点数：静态检查消耗 1 点，修复消耗 3 点，沙盒运行消耗 10 点；十分钟内重复提交的相同调用会使用首次调用的结果免费响应。

可以使用银行卡购买额度点数，无需发票，也无需联系任何人：

curl -s -X POST https://api.statemind.ai/v1/keys/checkout \
  -H 'content-type: application/json' \
  -d '{"api_key": "'"$VALIDATOR_API_KEY"'", "credits": 500}'

该接口会返回一个 Stripe Checkout 页面；银行卡扣款成功后几秒钟，额度点数就会添加到密钥上（500 点额度为 €10）。持有 Gnosis 钱包的 Agent 也可以直接使用 xDAI 付款，无需浏览器——GET /v1/pricing 会说明这两种方式。

示例

examples/ 目录包含三个文件，以及用于发送这些文件的客户端：一个通过所有检查却仍返回错误数字的文件，一个被安全策略拒绝的文件，还有一个从沙盒返回并获准的文件。

许可证

MIT。