The PatchProof MCP server provides tools for npm supply-chain security inspection, taking you from a lockfile through to a verified evidence report.
scan_repository – Traverse a repository root in a bounded, safe manner (configurable file count, byte, and depth limits) to parse manifests and package-lock.json, returning typed findings such as vulnerabilities, secrets, and malformed inputs. Supports options to include hidden files or follow symlinks.
generate_sbom – Generate a deterministic CycloneDX 1.5 Software Bill of Materials (SBOM) from package-lock.json, including component name, version, purl, and declared licenses. Output is validated against the official CycloneDX schema.
audit_dependencies – Audit dependencies against the OSV vulnerability database (api.osv.dev) in live mode (with timeout, caching, retries, and rate limiting) or deterministic mock mode (no network). Returns the full dependency list with matched vulnerabilities and CVSS v3.1 scores.
generate_evidence_report – Assemble a final report in JSON, HTML, or both formats, consolidating SBOM components, OSV vulnerability matches, static import reachability, remediation plans (ranked upgrades), transparent risk scoring (0–100), and optional allowlisted verification results.
The server is designed to be composed by AI coding agents for security-triage, release-gate, and evidence-review workflows.
Provides tools for inspecting npm supply chain, including scanning repositories, generating SBOMs, auditing dependencies, and creating evidence reports.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PatchProof MCP scan the repository at ./my-project for dependency vulnerabilities"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 reportThe 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: npm-mcp
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:validateExecute one against a running MCP endpoint:
npm run workflow:run -- release-gate http://127.0.0.1:8765/mcpClient 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.
Node.js 20
npm 10
npm ci
npm run lint
npm run typecheck
npm test
npm run coverage
npm run buildThe 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.
Build first, then start the stdio MCP server:
npm run build
npm run start:stdioImport 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"}'scan_repositoryInput:
{
"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_sbomInput:
{
"repoRoot": "/authorized/repository",
"format": "cyclonedx"
}Returns a deterministic CycloneDX 1.5-shaped component list derived from
package-lock.json, including an explicit lockfileStatus.
audit_dependenciesInput:
{
"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_reportInput:
{
"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.
PatchProof ranks each vulnerability with a deterministic 0–100 score:
severity-or-CVSS
× production/dev factor
× direct/transitive factor
× fix-availability factorThe 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.
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 casesBusiness logic is kept outside the MCP registry so it can be tested directly.
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.
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.
MIT. See LICENSE.
Audit the repository dependencies against OSV (api.osv.dev). Supports a deterministic mock adapter (default, no network) and a live adapter (timeout, bounded retry, TTL cache, sliding-window rate limit). Returns the dependency list and the matched vulnerabilities.
| Name | Required | Description | Default |
|---|---|---|---|
| repoRoot | No | ||
| osvMode | No | mock | |
| ecosystem | No | npm |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes mock vs live adapter behavior (network, retry, cache, rate limits) and return value, compensating for missing annotations. Does not cover authentication or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no fluff, front-loaded with main action and key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers adapters and return but lacks explanation of repoRoot path requirements, ecosystem options, and output format. Adequate for simplicity but gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning to osvMode by explaining mock/live behavior; ecosystem and repoRoot are not described. With 0% schema coverage, description partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool audits repository dependencies against OSV and lists adapters and outputs. It distinguishes from siblings by context, though not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like scan_repository or generate_sbom. Missing prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assemble the final evidence report. The JSON form carries schemaVersion, generatedAt, inputs, findings, reachability, remediation, verification, limitations, and redactions. The HTML form is self-contained (no external assets, inline CSS/JS, accessible markup) and renders a stable layout suitable for review and audit.
| Name | Required | Description | Default |
|---|---|---|---|
| repoRoot | No | ||
| format | No | both | |
| includeHtmlPreview | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description effectively discloses output behavior: JSON content fields and HTML self-contained features. It does not mention destructive actions or side effects, but for a report generation tool this is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loaded with the core purpose. However, the second sentence is dense with details that could be more structured. Still, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and zero parameter descriptions, the description leaves significant gaps. It provides output details but not input semantics or process context, making it only partially complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any parameters (repoRoot, format, includeHtmlPreview). Agents must infer or rely on parameter names alone, which is insufficient for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose ('Assemble the final evidence report') and distinguishes it from sibling tools (audit_dependencies, generate_sbom, scan_repository) by specifying that it produces the final report with detailed content descriptions for JSON and HTML forms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the final step ('final evidence report') but provides no explicit guidance on when to use it versus alternatives or prerequisites. It does not mention that this tool should be used after other scanning/auditing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build a CycloneDX 1.5 SBOM for the repository. Components include name, version, purl, and declared licenses when available. Output is validated against the official CycloneDX JS schema before being returned.
| Name | Required | Description | Default |
|---|---|---|---|
| repoRoot | No | ||
| format | No | cyclonedx |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses output format (CycloneDX 1.5), included fields, and validation step. Lacks details on potential network access, performance impact, or any side effects, but adequate for a read-only generation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with main action, no redundant words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing explicit return value or output format (e.g., JSON/XML). No output schema to compensate. Does not explain repoRoot parameter's role or constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No description adds meaning to the two parameters. Schema provides type/enum only; repoRoot has no explanation of its purpose or semantics. With 0% coverage, description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Build' and resource 'CycloneDX 1.5 SBOM for the repository' with specific format and component details. Distinct from siblings like audit_dependencies and scan_repository.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when needing an SBOM, but no explicit guidance on when to use this vs. alternatives like audit_dependencies or scan_repository. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Walk a repository root, parse its manifest and lockfile, and return a typed set of findings (vulnerabilities, secrets, malformed inputs). Safe by default: paths are resolved through security/paths.ts and the run is bounded by ResourceGovernor.
| Name | Required | Description | Default |
|---|---|---|---|
| repoRoot | No | ||
| includeHidden | No | ||
| followSymlinks | No | ||
| maxFiles | No | ||
| maxBytes | No | ||
| maxDepth | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions safety features (path resolution via security/paths.ts, bounded by ResourceGovernor) and return type (typed findings). However, it does not disclose potential side effects, error behavior, or destructive nature beyond the safe-by-default claim.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loaded with the core action. However, the lack of parameter details makes it feel incomplete, slightly reducing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (6 parameters, no output schema, no annotations), the description is insufficient. It covers purpose and safety but omits parameter semantics, return value structure, and usage guidelines, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. Despite six parameters including 'repoRoot', 'includeHidden', 'maxFiles', etc., the description provides no explanation of their meaning, defaults, or valid values. This leaves the AI agent without the information needed to set parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (walk, parse, return) and resource (repository root) and specifies three types of findings (vulnerabilities, secrets, malformed inputs). It distinguishes the tool from siblings like audit_dependencies and generate_sbom.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for general repository scanning but does not explicitly state when to use it vs alternatives or provide exclusion criteria. Lacks guidance on prerequisites or context-specific usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0audit_dependenciesgenerate_evidence_reportgenerate_sbomscan_repositoryTools have distinct purposes: audit_dependencies focuses on known vulnerabilities from OSV, scan_repository is broader (vulnerabilities, secrets, malformed inputs), generate_sbom creates SBOMs, and generate_evidence_report produces reports. Some overlap between audit and scan, but descriptions clarify differences.
All tool names follow a consistent verb_noun pattern with snake_case: audit_dependencies, generate_evidence_report, generate_sbom, scan_repository. No deviations.
4 tools is perfectly scoped for a security/audit server covering dependency auditing, SBOM generation, repository scanning, and evidence reporting. Neither too few nor too many.
The toolset covers the core lifecycle: scan repository, audit dependencies, generate SBOM, and assemble evidence report. No obvious missing operations for the stated domain of repository security and compliance.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Detect malicious or vulnerable npm packages: registry search, OSV.dev and GitHub advisory lookups
Generate SBOMs, scan vulnerabilities, and analyze dependencies from local projects or Git repos.
Supply chain risk scoring for npm, PyPI, Cargo, and Go. 9 tools. Behavioral signals.
Provide AI-powered real-time analysis and intelligence on NPM packages, including security, depend…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/eaglebooth/patchproof-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
