PatchProof MCP

PatchProof is a focused Model Context Protocol server for local npm supply-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 from package-lock.json.
• audit_dependencies: dependency extraction with a deterministic mock vulnerability table.
• generate_evidence_report: an end-to-end JSON/HTML artifact combining SBOM components, 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 live currently uses the same deterministic mock data.
• scan_repository intentionally returns bounded repository statistics; vulnerability matching is handled by audit_dependencies.
• Reachability classification and verification command execution are not yet integrated into evidence reports.
• The browser demo uses a bundled fixture and does not inspect arbitrary remote repositories.
• 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.

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 calls the 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 from package-lock.json.

audit_dependencies

Input:

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

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

generate_evidence_report

Input:

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

Runs the implemented SBOM and deterministic dependency audit together. It returns findings and upgrade recommendations as JSON and, for html or both, 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    verified stdio and Streamable HTTP transports
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 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.

License

MIT. See LICENSE.