Metadata-Version: 2.4
Name: cleanlib-mcp-server
Version: 0.5.2
Summary: CleanLibrary MCP server — exposes verdict-aware supply-chain risk assessment as Model Context Protocol tools for AI agent workflows
Author-email: CleanStart Inc <cto.office@cleanstart.com>
Maintainer-email: CleanStart Inc <cto.office@cleanstart.com>
License: CleanStart Inc Proprietary
Project-URL: Homepage, https://cleanlibrary.clnstrt.dev
Project-URL: Documentation, https://cleanlibrary.clnstrt.dev
Keywords: cleanlibrary,mcp,model-context-protocol,cleanstart,supply-chain-security,verdict,policy-evaluation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: cleanlib-sdk>=0.4.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Dynamic: license-file

# cleanlib-mcp-server

CleanLibrary MCP (Model Context Protocol) server — gives AI agents (Claude Code, Claude Desktop, Cursor, etc.) read access to CleanLibrary's library-verdict + vulnerability-intelligence APIs. Your agent can call `cleanlib_fetch_verdict` to ask *"should we use `lodash@4.17.20`?"* and get a structured response with verdict tier (`ALLOW` / `WARN` / `DENY`), CVE references, fix recommendations, and KMS-signed attestation.

## Install

```bash
pip install cleanlib-mcp-server
```

Latest: **0.5.x** on PyPI. 14 tools covering verdict / advisories / exploitability / EPSS / KEV / remediation / Vector / bulk operations.

## Configure

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "cleanlib": {
      "command": "cleanlib-mcp-server",
      "env": {
        "CLEANLIB_ENDPOINT": "https://cleanapp.clnstrt.dev",
        "CLEANLIB_API_KEY": "clk_YOUR_BEARER_HERE",
        "CLEANLIB_ENRICH_BEARER": "clk_YOUR_BEARER_HERE"
      }
    }
  }
}
```

Restart Claude Desktop. The 14 tools should appear in the tool picker.

### Claude Code

In your `.claude/settings.json` or via the `claude mcp add` command:

```bash
claude mcp add cleanlib \
  --command cleanlib-mcp-server \
  --env CLEANLIB_ENDPOINT=https://cleanapp.clnstrt.dev \
  --env CLEANLIB_API_KEY=clk_YOUR_BEARER_HERE \
  --env CLEANLIB_ENRICH_BEARER=clk_YOUR_BEARER_HERE
```

### Cursor / other MCP clients

The server speaks standard MCP over stdio. The same `command` + `env` pattern applies — consult your client's MCP server configuration docs for the exact file location.

## Bearer provisioning

CleanLibrary uses two bearer scopes:

| Bearer | Scope | What it accesses |
|---|---|---|
| `CLEANLIB_API_KEY` | App-side (`cleanapp.clnstrt.dev`) | `cleanlib_fetch_verdict` + `cleanlib_health_check` |
| `CLEANLIB_ENRICH_BEARER` | Tricorder substrate (`cleanlib-enrich.clnstrt.dev`) | 12 enrichment tools (advisories, exploitability, EPSS, KEV, remediation, Vector, CVE-enrich, bulk operations) |

For most customers these are the same bearer with both scopes; your design-partner / pilot agreement will spell out the tier.

### Tier shape

| Tier | Sustained | Burst | Typical use case |
|---|---|---|---|
| Free / evaluation | 60 req/min | 10 | Single-developer exploratory probing |
| Standard | 600 req/min | 60 | CI/CD pipelines + typical team usage |
| Enterprise | 6000 req/min | 600 | Large-org CI fleet + bulk operations |

On rate-limit hit: HTTP 429 + `Retry-After: <seconds>` header. Honor it.

### Provisioning flow

1. **Request bearer** via your CleanLibrary design-partner / pilot contact at <cto@cleanstart.com>
2. **Receive** a token of the form `clk_<random>_<tier>` (e.g. `clk_abc...xyz_001` for standard-tier-pilot)
3. **Store** in your local config file (above) or a secret manager:
   - macOS: Keychain (recommended) or `~/.config/cleanlib/bearer`
   - Linux: `~/.config/cleanlib/bearer` or your customer-side secret store
   - Cloud/CI: GitHub Actions Secret / GitLab CI variable / AWS SSM / GCP Secret Manager
4. **Never commit** bearer tokens to a repository. Keep them in environment variables or secret managers.

## Tool reference

14 tools post v0.5.0:

| Tool | What it does | Tier |
|---|---|---|
| `cleanlib_health_check` | App health + backend honesty block | Any |
| `cleanlib_fetch_verdict` | Get verdict envelope for a (ecosystem, package, version) | Any |
| `cleanlib_advisories` | List CVE advisories for a package | Any |
| `cleanlib_remediation` | Get recommended upgrade-version + remediation paths | Any |
| `cleanlib_exploitability` | Per-CVE exploitability assessment | Any |
| `cleanlib_epss` | Per-CVE EPSS score (exploitation likelihood) | Any |
| `cleanlib_kev` | ⚠ **Deprecated / fallback** — per-CVE CISA KEV listing (wraps the now-410-deprecated `/kev/:cve`); prefer `cleanlib_kev_package` or `cleanlib_exploitability` | Fallback |
| `cleanlib_cve_enrich` | Multi-source CVE enrichment | Gated |
| `cleanlib_enrich_package` | Full enrichment for a package (cycles all sources) | Standard+ |
| `cleanlib_epss_package` | EPSS for all known CVEs on a package | Standard+ |
| `cleanlib_kev_package` | KEV rollup for a package | Standard+ |
| `cleanlib_vector_verdict` | Tricorder Vector triage verdict | Standard+ |
| `cleanlib_exploitability_bulk` | Bulk exploitability for many CVEs | Standard+ |
| `cleanlib_packages_check_bulk` | Bulk verdict check for many packages | Standard+ |

## Verify it works

In Claude Code or Claude Desktop, ask:

> *"What's the CleanLibrary verdict for `npm/lodash/4.17.20`?"*

The agent should invoke `cleanlib_fetch_verdict` and return something like:

> The verdict is **DENY** (verdict source: `VECTOR_VERDICT`, severity HIGH, composite score 81). 5 CVEs affect this version. Top: CVE-2026-4800 (HIGH, CVSS 8.1, fixed in 4.18.0). Recommended action: upgrade to 4.17.21+ to address all 5 CVEs, or to 4.18.0+ for the cleanest path.

If you get `AUTH_ERROR` or `bearer required`: double-check the `env` block in your config file.

If every package returns `ALLOW_BY_ABSENCE`: your `CLEANLIB_ENRICH_BEARER` may be missing or scoped wrong. Run `cleanlib_health_check` — it returns the backend's honest state.

## Sample agent prompts

These work across Claude Code / Claude Desktop:

- *"Check `requirements.txt` packages against CleanLibrary and flag any DENY."*
- *"What CVEs affect `npm/express/4.17.1`?"*
- *"Should I upgrade `lodash` from `4.17.20`? Show me the upgrade journey."*
- *"Cross-check `python-cryptography/3.4.7` for KEV and EPSS data."*

## What ships today

- ✅ **Rate-limit enforcement** — per-minute quotas (above) with HTTP 429 + `Retry-After` header
- ✅ **App-layer caching** — vulnerability cross-reference TTL cache (5-min default) with `as_of` honesty (cache-hit responses carry the original substrate-fetch time, not cache-read time)
- ✅ **Observability foundation** — Cloud Monitoring custom-metrics + `availability.degraded_stale` honesty signal on verdict envelope
- ✅ **KMS-signed attestation** — every verdict carries an externally-verifiable ECDSA-P256 signature anchored at `cleanlibrary-prod` KMS

## What's NOT shipped yet (honest gaps)

- **Per-route SLA differentiation** — single Cloud Run service handles all routes today; per-route quotas land cycle-16
- **Full availability block population** — schema present + `degraded_stale` live; `kev` / `epss` / `exploitation_fusion` sub-fields land cycle-16
- **Multi-region** — single `us-central1`; EU sovereign deployment is a BD-trigger
- **Self-hosted enrich-api offering** — hosted-only today; air-gap customers contact <cto@cleanstart.com>

## Run

```bash
cleanlib-mcp-server   # stdio transport (per MCP spec)
```

## Backend modes

- **Connected** — when `CLEANLIB_ENDPOINT` + `CLEANLIB_API_KEY` are set, the server queries your CleanLibrary deployment for live verdicts.
- **Local fixtures** — when no endpoint is configured (or the configured endpoint is unreachable), the server returns bundled demo fixtures so MCP clients always receive useful output during local development.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `Extension 'cleanstart.cleanlibrary' not found` in Cursor | Open VSX republish pending; Cursor uses Open VSX | Install via direct `.vsix` from VS Code Marketplace |
| `ALLOW_BY_ABSENCE` for every package | Tricorder substrate gap for that package set | Cross-check via `cleanlib_advisories` separately; verdict is honest "no findings on file" not "verified clean" |
| `Internal error during session validation` 500 | Stale auth middleware (pre-2026-06-06) | Update to latest `cleanlib-mcp-server` 0.5.x |
| Timeout on `cleanlib_fetch_verdict` | Upstream Tricorder degraded | Check `cleanlib_health_check` for `backend.vector_client` state |
| `HTTP 429 / rate_limit_exceeded` | Hit tier's per-minute quota | Honor the `Retry-After` header (seconds-until-token-refill); see "Tier shape" above |

## Development

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ruff check src tests
pytest -v
```

## Feedback / contact

- Issues / questions: <cto@cleanstart.com>
- Source: https://bitbucket.org/triamsec/cleanlib-mcp-server

## License

Proprietary. See [LICENSE](./LICENSE) for terms. © 2026 CleanStart Inc.
