readme-proof MCP server
Commit Nov 6, 2026Analyzes README files for portability issues and command risks using static analysis and provides reviewable verification plans.
Also known as ruvnet/readme-proof
- Stars
- 6
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 6, 2026
- License
- MIT
What is readme-proof MCP?
readme-proof analyzes README files for portability issues and command risks using static analysis and provides reviewable verification plans.
Summary generated from the project's README
About readme-proof MCP server
Developers can verify documentation quality by checking README files for portability issues and command risks before publishing a package. This tool uses static analysis to identify target-dependent documentation problems and extract command blocks with risk annotations. It works locally via a CLI, a terminal view, or a browser-based UI, and it functions as a local stdio MCP server for integration with AI clients.
Users can choose between npm or GitHub targets to tailor the analysis to how the documentation will be displayed. The system provides line-numbered findings, including the specific rule, severity, and explanation for each issue. Because it relies on explicit local rules rather than an LLM to declare correctness, it provides a predictable way to inspect local documentation. No model API keys are required for the analysis, and the browser interface keeps README text local by not sending it to an external analysis API.
What you can do with it
- 1Identify documentation portability issuesAnalyze a Markdown file to find issues that depend on whether it is viewed on npm or GitHub.
- 2Generate a verification planCreate a reviewable plan to verify the contents of a README file.
- 3Audit command block risksScan documentation for potentially dangerous commands using static analysis.
- 4Export analysis reports for integrity checksSave analysis results into a JSON report or an RVF binary for later inspection.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableruvnet/readme-proof is public and reachablegithub.com/ruvnet/readme-proof ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-06github.com/ruvnet/readme-proof ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- 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 GitHubREADME Proof
Check README portability and command risks before publishing a package. Get line numbered findings and a reviewable verification plan through a CLI, terminal view, browser or MCP server.
Published prerelease: 0.1.0-next.1. Static analysis does not execute README commands or prove that an installation succeeds. No model API key is required.
Quick start
Install the published prerelease:
npx readme-proof@0.1.0-next.1 analyze README.md --target npm
npx readme-proof@0.1.0-next.1 tui README.md
npx readme-proof@0.1.0-next.1 plan README.md
From a source checkout:
npm ci
npm run build
node dist/main.mjs analyze README.md --target github
node dist/main.mjs ui
The UI command serves locally. Use the built CLI to inspect local documentation. See host setup for local plugin and MCP configuration.
What it checks
The analyzer inspects Markdown for target dependent documentation issues and extracts command blocks with risk annotations. Findings identify the rule, severity, source line and explanation. It uses explicit local rules; it does not use an LLM to declare documentation correct.
Choose npm when the README will be displayed outside its repository, or GitHub for repository presentation. File inventory can improve checks where supported. Review each finding in context before editing.
Browser
Watch the 28-second walkthrough, made from actual product footage with editable native graphics and an instrumental soundtrack.
Serve this repository as static files and open ui/. Paste or upload a README, select the publication target, inspect findings and download JSON. The browser imports the same analyzer as the CLI. README text stays in the browser; the UI does not send it to an analysis API. Opening the HTML directly through a file: URL may block JavaScript module imports, so use an HTTP static server.
MCP and skills
The local stdio MCP server exposes readme_analyze and readme_plan. Analysis receipts are addressable at ruv://readme-proof/evidence/{sha256}. A receipt records analysis; it does not certify successful execution.
This repository includes a reusable readme-proof skill, a portable Agent Plugins manifest, and Claude Code and Codex compatibility metadata. They are distributable source integrations, not marketplace listings or automatic installation into your account. Installation and limitations.
Evidence containers
Export a JSON report with readme-proof rvf REPORT.json OUT.rvf, then inspect it with readme-proof rvf-read OUT.rvf. The adapter uses @ruvector/rvf-wasm@0.1.9 to create a genuine RVF binary plus a mandatory OUT.rvf.receipt.json sidecar. Keep both files together. The binary stores a digest vector and the sidecar stores the report. Verification checks integrity, not authenticity, semantic similarity or correctness. Report-only CLI exports do not bind the original README bytes; their Markdown hash represents an empty input. MCP receipts generated from Markdown bind the supplied input bytes. An optional RVM deployment contract is described in the deployment notes; runtime execution requires separate validation.
Release verification
Registry installation passed on Node.js 20 and 24, and 16 tests passed at the published source revision. Both README SVG URLs returned HTTP 200 with image/svg+xml. Release receipt · GitHub release · public report.
Tests and benchmarks
Run npm test and npm run benchmark. One historical local run on October 11, 2026, before subsequent parser hardening, measured mean times of 16.64 ms uncached and 14.81 ms cached per 1,000 identical analyses across ten alternating samples: 10.99% lower mean time. The result is specific to repeated identical input and this run; it is not an algorithmic improvement or a general speed guarantee. Held out fixture equality checks passed. Raw samples and limitations.
The optional evolution module calls the real @metaharness/darwin@0.10.3 Pareto routine to compare supplied matched metrics. It returns proposals only. Autogenous integration is a contract representation, not an executed runtime. Synthetic tests and supplied metrics do not establish real reader usability or trusted performance evidence.
Why this exists
The first run experience is a real product surface. A public usability report on October 11, 2026 describes broken links and missing assumptions found by real users. README Proof automates a bounded set of mechanical checks. Human comprehension and actual installation testing remain separate. Design decision and sources. The factory also captured a live discovery sweep with source digests and a frozen candidate plan.
MIT licensed. See SECURITY.md before sharing reports or testing untrusted instructions.
readme-proof MCP questions
Does the tool execute commands found in the README?
No, the static analysis does not execute README commands or prove that an installation succeeds.
What MCP tools are available?
The local stdio MCP server provides readme_analyze and readme_plan tools.
Does the tool verify if an installation was successful?
No, the analysis receipts record the analysis performed but do not certify that the execution was successful.