Skip to main content

Integrations

CleanLibrary's job is to answer one question: "is this package safe to install — under our policy?" The verdict it returns is the same envelope, computed from the same source data, regardless of which developer surface asked. This page is about combining those surfaces.

1. The universal-checkpoint thesis​

Three places a developer encounters a package name:

  1. The editor. A hover over a package.json dependency, an autocomplete on an import statement, a requirements.txt line.
  2. An AI coding agent. "Add lodash to the project." "Bump log4js to 6.4.0."
  3. The terminal. npm install, pip install, cargo add, go get. The same name appears in CI pipelines, git hooks, Dockerfile RUN lines.

CleanLibrary surfaces a verdict at each of these — the VS Code extension, the MCP server, and the CLI respectively. All three call the same backend, return the same VerdictEnvelopeV1, and apply the same policy. A developer can switch from one to another and never see a contradiction.

That property — verdict identity across surfaces — is what we mean by "universal checkpoint."

2. Surface-by-surface​

SurfaceInstall mediumLatency profileBest fit
VS Code extensionMarketplace (cleanstart.cleanlibrary)Sub-second hover; cached after first lookupDaily editor use; reading existing code
MCP serverpip install cleanlib-mcp-serverSingle round-trip per agent tool call (~200ms warm)AI coding agents; chat-driven workflows
CLI`curlshinstaller orcargo install`Sub-second for cached verdicts; 1–5s for first-fetch

The extension is the right default for an interactive developer. The MCP server is the right default when the agent is the driver. The CLI is the right default for anything automation-shaped — pipelines, hooks, container builds.

You don't have to pick one. They share configuration; the same API key works across all three.

3. Mix-and-match patterns​

A few combinations we see in practice.

IDE + agent​

The extension surfaces verdicts on hover; the MCP server lets the agent reason about remediation, fetch advisories, or check exploitability for a CVE the developer noticed. Both pull from the same backend, so the agent's recommendation and the editor's hover never disagree.

CI + git hook​

Run cleanlib scan in the pre-commit hook (catches DENY before it ships) and again in CI (catches what local hooks miss — engineers can skip hooks). Both reads cost a fraction of a second per package and the audit log captures every decision.

CI + AI review​

Some teams run an agent against an inbound pull request to summarize risk. The MCP server gives that agent direct access to verdicts, advisories, and remediation. Use cleanlib_remediation to ask for upgrade paths on each DENY; use cleanlib_advisories to attach context for WARN.

Container build + verdict gate​

Pin the CLI in your base image; have the Dockerfile run cleanlib scan before the install step. A DENY fails the build with an actionable message, including the policy reason and (where one exists) a recommended_version.

4. Cross-surface envelope identity​

Every surface returns the same VerdictEnvelopeV1 shape — decision, reason_code, confidence, plus the rich-data fields described in Vulnerability Intelligence. The same envelope ID can be cross-referenced across surfaces, which means:

  • Audit logs from the editor, the agent, and CI all join on envelope_id
  • A developer can show a teammate a verdict they got in their editor and the teammate can fetch the exact same envelope from the CLI
  • The agent's cleanlib_fetch_verdict and the CLI's cleanlib verdict are interchangeable — same inputs, same output

If a surface ever returns a different envelope for the same (ecosystem, package, version) than another surface within the verdict freshness window, that's a bug — please report it.

5. SDK direct​

The three canonical surfaces cover the common cases. For anything else — custom internal tooling, a slack bot that pings on DENY, a Backstage plugin that surfaces verdicts on service catalog entries — the SDKs are the supported lower-level interface:

  • JavaScript / TypeScript: npm install @cleanstart/cleanlib-sdk
  • Python: pip install cleanstart-cleanlib-sdk
  • Go: see Getting Started for the canonical module path

All three SDKs implement the same DeriveStatus contract — given the same envelope, they return the same (status, reason_code). The Rust client used inside the CLI is a fourth implementation of the same contract.

6. Deployment patterns​

Single-user developer​

Install the extension; optionally install the CLI for terminal habits. One API key. No CI integration unless the developer's own scripts want it.

Team​

Extension on every developer's editor; CLI in CI for the merge gate; risk-acceptance rules reviewed by a designated owner. Audit log feeds the team's security review cadence. The same API key is provisioned per-developer; CI gets a separate scoped key.

Enterprise​

Add the agent surface (MCP server) so AI-assisted workflows go through CleanLibrary. Wire the audit log into the SIEM via cleanlib audit --output json. Use cleanlib config init to manage per-ecosystem proxy configuration through your existing config-management tooling rather than per-developer setup.

For air-gapped or partial-air-gapped environments, the CLI can run against an internal endpoint via CLEANLIB_ENRICH_BASE_URL — same contract, different host.

See also​