PatchProof MCP

PatchProof is a focused Model Context Protocol server for npm supply-chain inspection. Four tools implement one end-to-end chain:

lockfile -> CycloneDX SBOM -> OSV vulnerability -> source reachability
         -> remediation plan -> allowlisted verification -> evidence report

Current Status

The complete public tool set is implemented and covered by focused tests:

• scan_repository: authorized-root repository traversal with bounded file and byte counting plus explicit truncation diagnostics.

• generate_sbom: deterministic CycloneDX-shaped SBOM generation from package-lock.json.

• audit_dependencies: dependency extraction with live OSV queries, timeout/retry/cache controls, and an explicit deterministic fallback.

• generate_evidence_report: an end-to-end JSON/HTML artifact combining SBOM components, matched vulnerabilities, transparent risk scores, import-based reachability, ranked upgrades, and optional verification results.

Important limitations:

• Only npm package-lock.json repositories are supported.

• Live OSV sends only npm package names and versions to api.osv.dev; no repository source is transmitted.

• scan_repository intentionally returns bounded repository statistics; vulnerability matching is handled by audit_dependencies.

• Reachability is static import evidence, not runtime code-path proof.

• Verification is disabled by default and can execute only npm run typecheck, npm test, and npm run build with shell: false.

• The browser demo uses a bundled fixture and does not inspect arbitrary remote repositories.

• Missing, malformed, and unreadable lockfiles are reported explicitly rather than being presented as clean dependency results.

• Both the local CLI and Vercel deployment use the official stateless Streamable HTTP transport.

The Vercel demo exposes a stateless Streamable HTTP endpoint at /api/mcp. For safety, every public tool call is locked to the bundled demo fixture; it does not accept arbitrary server filesystem paths. The landing page calls the endpoint directly and lets reviewers run all four tools without installing an MCP client.

Committed, reproducible report artifacts are available at examples/demo-report.json and examples/demo-report.html. GitHub Actions rebuilds them and fails if the committed evidence becomes stale. Five additional golden scenarios under examples/golden/ cover safe, vulnerable, dev/transitive, malformed-lockfile, and missing-lockfile behavior.

Related MCP server: pkgtruth

Agent Workflows

Three machine-readable workflows demonstrate how AI coding agents compose the four MCP tools:

• security-triage

• release-gate

• evidence-review

Validate them offline:

npm run workflow:validate

Execute one against a running MCP endpoint:

npm run workflow:run -- release-gate http://127.0.0.1:8765/mcp

Client setup guides for Claude Code, Codex, and GitHub Copilot live in examples/agent-workflows/. CyOps session-to-repository provenance is documented in docs/cyops-provenance.md.

Requirements

• Node.js 20

• npm 10

Install And Verify

npm ci
npm run lint
npm run typecheck
npm test
npm run coverage
npm run build

The suite contains 82 tests covering core tools, live OSV normalization and caching, CVSS v3.1, reachability, remediation, verification security, transports, risk scoring, and five scenario fixtures. CI enforces at least 85% line, statement, and function coverage and 80% branch coverage. The current verified coverage values are generated by npm run coverage and enforced in CI.

Run

Build first, then start the stdio MCP server:

npm run build
npm run start:stdio

Deploy The Live Demo

Import this GitHub repository into Vercel and deploy with the default settings. The deployment provides:

• / - a static project and tool overview;

• /api/mcp - the stateless MCP Streamable HTTP endpoint;

• a bundled npm fixture supporting deterministic and live OSV demonstrations.

Verify the deployment:

curl -X POST https://YOUR-DEPLOYMENT.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tool Summary

scan_repository

Input:

{
  "repoRoot": "/authorized/repository",
  "includeHidden": false,
  "followSymlinks": false
}

Returns the resolved repository root, files scanned, bytes read, duration, ignored directories, the current findings array, and truncated with a reason when a resource limit stops traversal. Any repoRoot override must remain inside the root authorized by the MCP host.

generate_sbom

Input:

{
  "repoRoot": "/authorized/repository",
  "format": "cyclonedx"
}

Returns a deterministic CycloneDX 1.5-shaped component list derived from package-lock.json, including an explicit lockfileStatus.

audit_dependencies

Input:

{
  "repoRoot": "/authorized/repository",
  "osvMode": "live",
  "fallbackToMock": true,
  "ecosystem": "npm"
}

Returns dependencies and package-linked vulnerabilities with source set to live, mock, or mock-fallback. Live requests use a five-second timeout, two bounded retries, eight-request concurrency, and a one-hour in-memory cache. OSV CVSS v3 vectors are converted to reproducible base scores.

generate_evidence_report

Input:

{
  "repoRoot": "/authorized/repository",
  "format": "both",
  "osvMode": "live",
  "fallbackToMock": true,
  "verify": false
}

Runs SBOM, OSV auditing, static import reachability, remediation planning, and optional allowlisted verification. It returns JSON and a self-contained HTML report. Set verify=true only in a trusted local checkout.

Risk Model

PatchProof ranks each vulnerability with a deterministic 0–100 score:

severity-or-CVSS
× production/dev factor
× direct/transitive factor
× fix-availability factor

The report preserves every factor and a human-readable explanation. The model does not use hidden weights or network data, so identical lockfiles always produce identical ranking. See src/risk/scorer.ts, tests/unit/risk-scorer.test.ts, and docs/acceptance-evidence.md.

Architecture

src/server       MCP registration and CLI
src/tools        four public MCP tool definitions
src/scanners     bounded repository traversal
src/parsers      npm lockfile parsing
src/sbom         deterministic SBOM assembly
src/osv          live OSV client, CVSS v3.1, cache, retry, and mock fallback
src/reachability static import evidence with file and line locations
src/remediation  semver-aware, reachability-informed upgrade planning
src/verification shell-free allowlisted npm verification
src/reporting    end-to-end JSON and HTML evidence assembly
src/risk         transparent deterministic risk scoring
src/security     path, resource, error, and redaction utilities
src/transport    verified stdio and Streamable HTTP transports
tests/unit       infrastructure and focused core-tool tests
fixtures/scenarios safe, vulnerable, dev/transitive, malformed, and missing cases

Business logic is kept outside the MCP registry so it can be tested directly.

Security Notes

• Callers must provide or authorize a repository root.

• Repository traversal is bounded by file, byte, depth, and time limits.

• Common generated directories such as .git, node_modules, dist, build, and coverage are ignored.

• Live OSV receives only { package: { ecosystem, name }, version }.

• Live network failures are explicit and can fall back to deterministic mode.

• Verification never uses a shell and rejects every command outside a fixed allowlist.

This is a focused security evidence tool, not a runtime exploitability oracle. Do not rely on it as the sole source for vulnerability or secret detection.

CyOps Arena

The repository was scaffolded and iterated with CyOps Humanize using MiniMax M3. The Git history and planning documents retain the generated implementation evidence. Manual verification confirmed:

• strict TypeScript typecheck passes;

• the Vitest suite passes;

• the production TypeScript build passes.

• an integration test starts the HTTP server on an ephemeral port and verifies the complete four-tool MCP surface through JSON-RPC;

• GitHub Actions independently repeats those checks on Node.js 20 and verifies that the committed demo evidence is reproducible.

• Three agent workflows are machine-validated and can be executed over MCP JSON-RPC with scripts/run-agent-workflow.mjs.

License

MIT. See LICENSE.