An AI code judge for Python that detects hallucinations, unverified facts, and unpinned dependencies to ensure reliable model-generated code.
Also known as malikabyl/proven, proven-judge
- Stars
- 1
- Tools
- 3
- Downloads, 30 days
- 271
- Latest version
- 0.2.0
- Last commit
- Nov 3, 2026
- License
- MIT
What is Proven MCP?
Proven is an AI code judge for Python that detects hallucinations, unverified facts, and unpinned dependencies to ensure reliable model-generated code. It exposes 3 tools, such as proven_check, proven_explain, proven_rules.
Summary generated from the project's README
About Proven MCP server
Proven acts as a specialized judge for Python code generated by artificial intelligence. It focuses on identifying hallucinations, unverified facts, and unpinned dependencies to ensure that model-produced scripts are reliable and safe for use. The tool operates by enforcing six specific rules that check for real imports, existing function calls, dated sources for facts, and the presence of tests for public functions.
Developers can integrate this server into their workflows using various methods, including a command line interface, pre-commit hooks, or GitHub Actions. When used as an MCP server with clients like Claude Desktop or Cursor, it provides tools such as proven_check, proven_explain, and proven_rules. It can be run in a local environment using uvx or by installing the proven-judge package via pip to allow the judge to inspect the project's specific virtual environment and installed packages.
What you can do with it
- 1Verifying factual data in codeA developer can ensure that hardcoded numbers or legal references include a source and a date.
Written from the project's README. Every use case is checked against a quote from it.
How to install Proven MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Proven MCP in Claude Code
$ claude mcp add proven -- uvx proven-judge mcp --no-installed-checkInstall Proven MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"proven": {
"command": "uvx",
"args": [
"proven-judge",
"mcp",
"--no-installed-check"
]
}
}
}Install Proven MCP in VS Code
.vscode/mcp.json
{
"servers": {
"proven": {
"type": "stdio",
"command": "uvx",
"args": [
"proven-judge",
"mcp",
"--no-installed-check"
]
}
}
}Install Proven MCP in VS Code CLI
$ code --add-mcp '{"name":"proven","type":"stdio","command":"uvx","args":["proven-judge","mcp","--no-installed-check"]}'Install Proven MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"proven": {
"command": "uvx",
"args": [
"proven-judge",
"mcp",
"--no-installed-check"
]
}
}
}Install Proven MCP in Codex
$ codex mcp add proven -- uvx proven-judge mcp --no-installed-checkInstall Proven MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.proven] command = "uvx" args = ["proven-judge", "mcp", "--no-installed-check"]
Install Proven MCP in Gemini CLI
$ gemini mcp add -s user proven uvx -- proven-judge mcp --no-installed-checkInstall Proven MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"proven": {
"command": "uvx",
"args": [
"proven-judge",
"mcp",
"--no-installed-check"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for proven-judge 0.2.0 in an isolated container with no network and no keys. It answered and listed 3 tools.
Proven MCP tools 3
Read from the server with tools/listproven_checkRead-onlyJudge Python code written by AI against hallucinations: invented packages and calls, facts typed from memory, unverified model output, swallowed errors, code without tests. Returns every issue with the rule and how to fix it. Call it after writing or editing Python code and fix every issue until the code is accepted. Note: to check names inside installed packages, Proven imports them (rule P2).
proven_explainRead-onlyExplain one Proven rule (P0-P6): what it requires and how to fix a violation.
proven_rulesRead-onlyList all Proven rules with their codes and titles.
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablemalikabyl/proven is public and reachablegithub.com/malikabyl/proven ↗Pass
- Package names this repository as its sourceproven-judge names malikabyl/proven as sourcepypi.org/project/proven-judge/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for proven-judgepypi.org/project/proven-judge/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-03github.com/malikabyl/proven ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from proven-judgePass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubProven
A judge for code written by AI. The syntax is plain Python. The rules are against hallucinations.
The core principle: nothing exists until it is proven. A package exists if it is pinned in requirements. A function exists if it is in the installed version. A fact exists if it has a source and a date. A model's answer exists for the user once it has passed a check. A function works if a test proves it.
Why
AI models write more code than people can read. The languages that win are the ones where the compiler acts as a reviewer: TypeScript became the #1 language on GitHub in 2025 (GitHub Octoverse 2025), and GitHub links this to typed languages making AI-assisted code more reliable. A new language is not the answer — models barely know new languages. What helps is the old language that models know best, with a strict judge on top of it. That is how TypeScript grew on top of JavaScript.
Proven does the same for Python, but it catches hallucinations rather than type errors.
Six rules
| Code | Rule | What it catches |
|---|---|---|
| P1 | Imports are real | Invented packages, unpinned versions, modules that are not installed |
| P2 | Calls are real | Functions, classes, attributes and modules that do not exist |
| P3 | No facts from memory | Official figures, tax rates, law article numbers and URLs typed into code by hand; outdated facts |
| P4 | Model output is verified | A model's answer goes to a user or a database without a check; a forged check |
| P5 | Errors are not swallowed | Bare except, silent except: pass |
| P6 | Functions are proven by tests | A public function with no test; a test that checks nothing |
Every rule in detail: SPEC.md.
What it looks like
The code in examples/bad/bot.py is how an AI model writes when nobody checks it — a legal-answers bot for Kazakhstan:
import anthropik # a typo
MRP = 3932 # Kazakhstan's monthly index, the 2025 value "from memory"
def handle(phone, question):
raw = llm(question)
answer = f"{raw}\n\nLegal basis: Article 46 of the Labour Code"
try:
json.loadz(answer)
except:
pass
send(phone, answer)
The judge:
$ python proven.py check examples/bad
Proven 0.2.0 · root: /path/to/proven/examples · python: /usr/bin/python3 3.12.3 · requirements: requirements.txt · packages from: the judge's own
bad/bot.py:4:1 P1 package "anthropik" is not in requirements.txt — it may be invented
bad/bot.py:5:1 P1 version of "requests" is not pinned with == (now: ">=2.31")
bad/bot.py:7:1 P3 "MRP" is a number typed from memory — it needs a dated source
bad/bot.py:9:10 P3 address "adilet.zan.kz" typed by hand — move it to a config or allowed_url_hosts
bad/bot.py:12:1 P6 function "llm" is not called in any test
bad/bot.py:16:5 P4 public function "llm" returns unverified model output — annotate it "-> Unverified" or return verify(...)
bad/bot.py:19:1 P6 function "send" is not called in any test
bad/bot.py:23:1 P6 function "handle" is not called in any test
bad/bot.py:25:14 P3 law article number typed by hand: "Article 46" — take it from the database
bad/bot.py:27:9 P2 module "json" has no name "loadz"
bad/bot.py:28:5 P5 bare except catches everything, even Ctrl+C and program exit
bad/bot.py:30:5 P4 unverified model output goes into "send"
How to fix:
P1 Imports are real — Check the exact package name on PyPI, add a name==version line ...
...
Proven: 12 issue(s) in 1 file(s). Code rejected.
The same bot fixed according to the rules — examples/good/bot.py:
MRP = Fact(4325, source='Law of the Republic of Kazakhstan "On the Republican Budget '
'for 2026–2028" No. 239-VIII',
date="2026-01-01")
def ask_model(question, llm) -> Unverified:
return unverified(llm(question))
def answer(question, llm, checker, send):
raw = ask_model(question, llm)
send(verify(raw, checker)) # the user only gets what has been verified
$ python proven.py check examples/good
Proven: no issues. Code accepted.
Quick start
Python 3.11+. No dependencies — the standard library only.
pip install proven-judge # the package is "proven-judge", the command is "proven"
proven init # create proven.toml
proven check # check the project
Exit code: 0 — code accepted, 1 — there are issues. For machines there is --json.
proven rules # list the rules
proven explain P4 # explain a rule
In your code, from proven_types import Fact, Unverified, unverified, verify, and add proven-judge==0.2.0 to requirements.txt (P1 applies to Proven too).
No installation at all: copy proven.py and proven_types.py into your project and run python proven.py check.
pre-commit
# .pre-commit-config.yaml
repos:
- repo: https://github.com/malikabyl/proven
rev: v0.2.0
hooks:
- id: proven
The hook checks the whole project, not only the changed files: P6 needs to see the tests.
GitHub Actions
- uses: actions/checkout@v4
- uses: malikabyl/proven@v0.2.0
Issues show up as annotations on the lines of the pull request and in the job summary. Inputs: path (the folder to run in), args (extra arguments for proven check), python (the interpreter with your dependencies installed, so P1 and P2 can see them; by default python3). Outside the action, proven check --github gives the same annotations.
MCP server
Proven is also an MCP server, so an AI agent can call the judge itself: tools proven_check, proven_explain and proven_rules. It needs no extra packages.
Claude Code:
claude mcp add proven -- uvx proven-judge mcp --no-installed-check
Other clients (Claude Desktop, Cursor and others):
{
"mcpServers": {
"proven": {
"command": "uvx",
"args": ["proven-judge", "mcp", "--no-installed-check"]
}
}
}
uvx runs the server in its own environment, where your project's packages are not installed, hence --no-installed-check. To check that packages are installed too (P1), run the server from your project's environment instead: pip install proven-judge, then proven mcp. Pass the agent an absolute path to the project.
The loop with an AI model
Proven works like a compiler for an AI model: the model writes code, the judge says what is wrong and how to fix it, the model fixes it. The judge's messages are written so they can be handed to a model as they are.
Claude Code. The repository already has .claude/settings.json: after every edit of a .py file the judge checks it, and if there are issues, Claude sees the report and fixes them. Copy the .claude folder into your project.
Rules in the prompt. A cheat sheet for a system prompt or CLAUDE.md is in PROMPT.md. The model then follows the rules from the first try, and the judge catches the rest.
GitHub. The workflow .github/workflows/proven.yml runs the judge and the tests on every push and pull request.
An existing project
On old code the judge will find many issues at once. To avoid fixing everything in one day:
python proven.py baseline
The current issues are written to .proven-baseline.json as old debt. From then on the judge skips them but rejects any new issue. Pay the debt off gradually and rewrite the baseline.
Run the judge with the project's Python. P1 and P2 look at installed packages. The first line of every report says what the judge measured with: the project root, the Python, the requirements file and the environments it read. Without proven.toml the root is the nearest folder with pyproject.toml, requirements.txt or .git. If the judge runs in its own environment, it also reads the project's .venv (or venv, env, $VIRTUAL_ENV): packages there count as installed, and names in them are checked by reading their code, without importing it.
A project with no tests at all gets one P6 issue instead of one per function. Until there are tests, disable = ["P6"] keeps the report readable.
Waivers
The human has the final say. A rule can be switched off for one line — but only with a reason:
MRP = 3932 # proven: allow P3: computing an archived 2025 fine
A waiver without a reason is itself an issue (P0). The comment goes on the same line or on the line above. For P5 it can also go inside the handler, where the explanation usually is:
except OSError:
pass # proven: allow P5: logging a call must not break the answer to the client
A plain comment is not enough on purpose: a model can write "# intentional" as easily as "pass". The Russian keyword works too: # proven: разрешить P3: reason.
Honest limits
The judge catches what is invented, not what is wrong:
- P3 checks that a fact has a source and a recent date, not that the value matches the law. Comparing it with the source is up to a person or to the check in
verify(). - P2 checks names in modules and classes. Methods on objects (
response.jsonn()) cannot be checked statically — tests catch them (P6). - P2 imports packages installed in the judge's own environment to look inside, which runs their import code; packages from the project's
.venvare read, not imported. Turn it off withcheck_attributes = false. - P4 follows data inside a file and through functions by name. It is cautious: when in doubt, it treats data as unverified. A public function that returns model output must say so with
-> Unverified. A model client created in another file is only recognised if its function name is listed insources. - P6 matches functions and tests by name, not by module.
- Logic that is wrong but consistent will not be caught by any static judge. Tests and your final word catch it.
Layout
proven.py the judge (CLI)
proven_types.py Unverified, Verified, verify(), Fact
proven.toml settings (the judge checks itself)
SPEC.md the rules in detail and every setting
CHANGELOG.md what changed in each version
PROMPT.md a cheat sheet for an AI model
examples/bad code with hallucinations
examples/good the same code following the rules
tests/ the judge's tests
pyproject.toml the proven-judge package
action.yml the GitHub Action
server.json the MCP Registry entry
.pre-commit-hooks.yaml the pre-commit hook
.claude/settings.json the hook for Claude Code
.github/workflows/ the check on GitHub and the release to PyPI
Releasing: bump VERSION in proven.py, then publish a GitHub release with the tag vX.Y.Z. The release workflow checks that the tag, VERSION and server.json agree, builds the package, publishes it to PyPI and then to the MCP Registry. Update the two versions in server.json together with VERSION.
Check the judge itself:
pip install -r requirements-dev.txt
python proven.py check # the judge accepts itself
python -m pytest
The values in the examples (Kazakhstan's MRP and others) were checked against the source on 3 November 2026 and serve as illustrations. In live code, check them against adilet.zan.kz, Kazakhstan's official legal database.
License
MIT, see LICENSE.
Proven MCP questions
How do I add Proven MCP to Claude Code?
Run claude mcp add proven -- uvx proven-judge mcp --no-installed-check in your terminal. Add --scope user to make it available in every project.
How do I add Proven MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Proven MCP provide?
It exposes 3 tools, including proven_check, proven_explain, proven_rules.
How can I use Proven with an AI agent?
Proven is an MCP server that provides tools like proven_check, proven_explain, and proven_rules for AI agents to call directly.
Does Proven require any dependencies?
No, it only requires Python 3.11+ and uses the standard library only.
Can I skip existing issues in an old project?
Yes, you can run python proven.py baseline to write current issues to a baseline file, allowing the judge to only reject new issues.