PatchProof MCP

PatchProof MCP

PatchProof is a focused Model Context Protocol server for local npmsupply-chain inspection. The MVP exposes four tools with deterministic,offline-friendly behavior.

Current Status

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

• scan_repository: bounded repository file and byte counting.
• generate_sbom: deterministic CycloneDX-shaped SBOM generation frompackage-lock.json.
• audit_dependencies: dependency extraction with a deterministic mockvulnerability table.
• generate_evidence_report: an end-to-end JSON/HTML artifact combining SBOMcomponents, matched vulnerabilities, and upgrade recommendations.

Important limitations:

• Only npm package-lock.json repositories are supported.
• audit_dependencies does not yet query the live OSV API. Selecting livecurrently uses the same deterministic mock data.
• scan_repository currently returns repository statistics; vulnerability andsecret findings are not yet integrated into its result.
• Reachability classification and verification command execution are not yetintegrated into evidence reports.
• The browser demo uses a bundled fixture and does not inspect arbitrary remoterepositories.
• Streamable HTTP is scaffolded and should not yet be treated as a verifiedproduction transport when using the local CLI.

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; itdoes not accept arbitrary server filesystem paths.

Committed, reproducible report artifacts are available atexamples/demo-report.json and examples/demo-report.html. GitHub Actionsrebuilds them and fails if the committed evidence becomes stale.

Requirements

• Node.js 20
• npm 10

Install And Verify

npm ci
npm run typecheck
npm test
npm run build

The focused core-tool test suite creates a temporary npm repository and callsthe four implemented tools directly.

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 containing deterministic mock vulnerabilities.

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, and the current findings array.

generate_sbom

Input:

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

Returns a deterministic CycloneDX 1.5-shaped component list derived frompackage-lock.json.

audit_dependencies

Input:

{
  "repoRoot": "/authorized/repository",
  "osvMode": "mock",
  "ecosystem": "npm"
}

Returns parsed dependencies and matching entries from the local deterministicmock vulnerability table.

generate_evidence_report

Input:

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

Runs the implemented SBOM and deterministic dependency audit together. Itreturns findings and upgrade recommendations as JSON and, for html orboth, a self-contained HTML report with summary metrics.

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          deterministic mock dependency audit
src/reporting    end-to-end JSON and HTML evidence assembly
src/security     path, resource, error, and redaction utilities
src/transport    stdio and HTTP transport scaffolding
tests/unit       infrastructure and focused core-tool tests

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.
• The implemented dependency audit is local and deterministic.

This is an MVP, not a completed security product. Do not rely on it as the solesource for vulnerability or secret detection.

CyOps Arena

The repository was scaffolded and iterated with CyOps Humanize using MiniMaxM3. The Git history and planning documents retain the generated implementationevidence. Manual verification confirmed:

• strict TypeScript typecheck passes;
• the Vitest suite passes;
• the production TypeScript build passes.
• GitHub Actions independently repeats those checks on Node.js 20 and verifiesthat the committed demo evidence is reproducible.

License

MIT. See LICENSE.