cleanlib-mcp-server 0.2.0__py3-none-any.whl

cleanlib_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""CleanLibrary MCP server.
+
+Exposes CleanLibrary verdict-aware supply-chain risk assessment as MCP tools
+so MCP-capable clients (Claude Code, Claude Desktop, Cursor, GitHub Copilot,
+and other agents) can fetch package verdicts directly.
+"""
+
+__version__ = "0.2.0"

cleanlib_mcp/backend.py

@@ -0,0 +1,221 @@
+"""Verdict backend.
+
+When CLEANLIB_ENDPOINT + CLEANLIB_API_KEY are configured, fetches verdicts
+from the CleanLibrary App `GET /v1/customer/verdicts/{eco}/{pkg}/{ver}`.
+When unconfigured (or the endpoint is unreachable), returns bundled demo
+fixtures so MCP clients always receive useful output.
+"""
+
+from __future__ import annotations
+
+import os
+import secrets
+from dataclasses import asdict, dataclass
+from typing import Literal
+
+import httpx
+
+Decision = Literal["ALLOW", "DENY", "WARN"]
+
+
+@dataclass
+class Verdict:
+    """Mirrors the CleanLibrary App GET /v1/customer/verdicts response shape."""
+
+    verdict_id: str
+    ecosystem: str
+    package: str
+    version: str
+    decision: Decision
+    reasoning: str | None = None
+    confidence: float | None = None
+    source: str | None = None
+
+    def to_dict(self) -> dict:
+        return {k: v for k, v in asdict(self).items() if v is not None}
+
+
+# Bundled demo fixtures (cors-2.8.4 DENY / cors-2.8.5 ALLOW / helmet ALLOW /
+# dotenv ALLOW / oracledb WARN) used when no live backend is configured.
+_MOCK_FIXTURES: dict[str, dict] = {
+    "npm/cors/2.8.4": {
+        "decision": "DENY",
+        "reasoning": "Policy rule: cors-2.8.4 has known prototype pollution; upgrade to 2.8.5",
+        "confidence": 0.98,
+        "source": "VECTOR_VERDICT",
+    },
+    "npm/cors/2.8.5": {
+        "decision": "ALLOW",
+        "reasoning": "No findings; matches policy allowlist",
+        "confidence": 0.95,
+        "source": "ALLOWED_NO_FINDINGS",
+    },
+    "npm/helmet/8.0.0": {
+        "decision": "ALLOW",
+        "reasoning": "No findings; standard security middleware",
+        "confidence": 0.97,
+        "source": "ALLOWED_NO_FINDINGS",
+    },
+    "npm/dotenv/16.4.5": {
+        "decision": "ALLOW",
+        "reasoning": "No findings; widely-used config loader",
+        "confidence": 0.94,
+        "source": "ALLOWED_NO_FINDINGS",
+    },
+    "npm/oracledb/6.5.1": {
+        "decision": "WARN",
+        "reasoning": "Vendor-binary present; review supply-chain provenance before deploy",
+        "confidence": 0.70,
+        "source": "INSUFFICIENT_DATA",
+    },
+}
+
+
+async def fetch_verdict(ecosystem: str, package: str, version: str) -> Verdict:
+    """Fetch verdict for a package version.
+
+    Fixture-mode (default): returns a bundled demo fixture, or default-ALLOW
+    for unknown packages.
+
+    Live-mode (when CLEANLIB_ENDPOINT + CLEANLIB_API_KEY env set): queries the
+    CleanLibrary App customer-verdict endpoint, falling back to a fixture if
+    the endpoint is unreachable so the client always receives output.
+    """
+    endpoint = os.getenv("CLEANLIB_ENDPOINT", "").strip()
+    api_key = os.getenv("CLEANLIB_API_KEY", "").strip()
+
+    if endpoint and api_key:
+        try:
+            return await _live_fetch(endpoint, api_key, ecosystem, package, version)
+        except LiveBackendNotDeployed:
+            # Configured endpoint unreachable — fall back to a fixture so the
+            # client still receives useful output. The fallback verdict carries
+            # a reasoning string surfacing that the live backend was unavailable.
+            v = _mock_fetch(ecosystem, package, version)
+            v.reasoning = (
+                f"[live-mode fallback: CleanLibrary backend at {endpoint} unavailable] "
+                + (v.reasoning or "")
+            )
+            return v
+    return _mock_fetch(ecosystem, package, version)
+
+
+def _mock_fetch(ecosystem: str, package: str, version: str) -> Verdict:
+    key = f"{ecosystem}/{package}/{version}"
+    verdict_id = f"mock_{secrets.token_hex(4)}"
+    fixture = _MOCK_FIXTURES.get(key)
+    if fixture is not None:
+        return Verdict(
+            verdict_id=verdict_id,
+            ecosystem=ecosystem,
+            package=package,
+            version=version,
+            **fixture,
+        )
+    return Verdict(
+        verdict_id=verdict_id,
+        ecosystem=ecosystem,
+        package=package,
+        version=version,
+        decision="ALLOW",
+        reasoning="Default-ALLOW (no fixture matched; live App returned no verdict for this package version)",
+        confidence=0.5,
+        source="INSUFFICIENT_DATA",
+    )
+
+
+class LiveBackendNotDeployed(Exception):
+    """Raised when CLEANLIB_ENDPOINT is set but the verdict endpoint is
+    unreachable (empty-body 404). Distinguished from "package has no verdict"
+    (a structured-JSON 404) by response content-type. The tool layer treats
+    this as a degraded-mode signal and falls back to a fixture so clients
+    receive useful output even when the live backend is unavailable."""
+
+
+async def _live_fetch(
+    endpoint: str, api_key: str, ecosystem: str, package: str, version: str
+) -> Verdict:
+    """Live `GET /v1/customer/verdicts/{eco}/{pkg}/{ver}` call against the
+    configured CleanLibrary App.
+
+    A structured-JSON 404 means "verdict not found" for that package version;
+    an empty-body 404 means the endpoint is unreachable. The wrapper
+    distinguishes the two by response content-type and falls back to a
+    fixture in the unreachable case.
+    """
+    url = f"{endpoint.rstrip('/')}/v1/customer/verdicts/{ecosystem}/{package}/{version}"
+    headers = {
+        "authorization": f"Bearer {api_key}",
+        "accept": "application/json",
+        "user-agent": "cleanlib-mcp-server/0.2.0",
+    }
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        try:
+            resp = await client.get(url, headers=headers)
+        except httpx.HTTPError as e:
+            raise RuntimeError(f"live App transport failure: {e}") from e
+
+    if resp.status_code == 200:
+        data = resp.json()
+        return Verdict(
+            verdict_id=data.get("verdict_id", ""),
+            ecosystem=data.get("ecosystem", ecosystem),
+            package=data.get("package", package),
+            version=data.get("version", version),
+            decision=data.get("decision", "ALLOW"),
+            reasoning=data.get("reasoning"),
+            confidence=data.get("confidence"),
+            source=data.get("source"),
+        )
+
+    if resp.status_code == 404:
+        # Two cases: (a) endpoint reached but no verdict for this package
+        # (structured-JSON body); (b) endpoint unreachable (empty body or
+        # text/html). Distinguish via content-type.
+        content_type = resp.headers.get("content-type", "")
+        if "json" in content_type and resp.content:
+            # "Verdict not found" — return an INSUFFICIENT_DATA verdict.
+            return Verdict(
+                verdict_id=f"live_404_{secrets.token_hex(4)}",
+                ecosystem=ecosystem,
+                package=package,
+                version=version,
+                decision="ALLOW",
+                reasoning=f"No verdict on file for {ecosystem}/{package}@{version}",
+                confidence=None,
+                source="INSUFFICIENT_DATA",
+            )
+        raise LiveBackendNotDeployed(
+            f"CleanLibrary backend at {endpoint} did not return a verdict for "
+            f"/v1/customer/verdicts/{ecosystem}/{package}/{version}; "
+            f"returning fixture fallback."
+        )
+
+    if resp.status_code == 401 or resp.status_code == 403:
+        raise PermissionError(
+            f"App rejected Bearer (status={resp.status_code}); check CLEANLIB_API_KEY "
+            f"is valid for {endpoint}"
+        )
+
+    raise RuntimeError(f"App returned unexpected status {resp.status_code}: {resp.text[:200]}")
+
+
+async def _validate_live_endpoint_reachable(endpoint: str) -> bool:
+    """Reachability probe via /health (public; no auth required). Used by
+    `cleanlib_health_check` MCP tool to verify MCP→App transport works
+    end-to-end even when the verdict endpoint isn't yet deployed."""
+    try:
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            resp = await client.get(f"{endpoint.rstrip('/')}/health")
+            return resp.status_code == 200
+    except Exception:
+        return False
+
+
+async def live_health(endpoint: str) -> dict:
+    """Fetch the App's /health response (JSON) — used by the
+    `cleanlib_health_check` MCP tool. Public endpoint; no auth needed."""
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        resp = await client.get(f"{endpoint.rstrip('/')}/health")
+        resp.raise_for_status()
+        return resp.json()

cleanlib_mcp/server.py

@@ -0,0 +1,128 @@
+"""MCP server entry-point — registers CleanLibrary tools and serves over
+stdio transport. Compatible with any MCP-capable client (Claude Code,
+Claude Desktop, Cursor, GitHub Copilot, and other agents).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from .backend import fetch_verdict, live_health
+
+log = logging.getLogger("cleanlib-mcp-server")
+
+server: Server = Server("cleanlib-mcp-server")
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="cleanlib_fetch_verdict",
+            description=(
+                "Fetch the CleanLibrary verdict for a package version. Returns the "
+                "decision (ALLOW / DENY / WARN), reasoning, and confidence. Queries a "
+                "live CleanLibrary backend when CLEANLIB_ENDPOINT + CLEANLIB_API_KEY "
+                "are configured; otherwise returns bundled demo fixtures so the tool "
+                "always responds."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "ecosystem": {
+                        "type": "string",
+                        "enum": ["npm", "pypi", "go", "maven", "crates", "nuget", "rubygems"],
+                        "description": "Package ecosystem",
+                    },
+                    "package": {
+                        "type": "string",
+                        "description": "Package name (e.g. lodash, requests, github.com/spf13/cobra)",
+                    },
+                    "version": {
+                        "type": "string",
+                        "description": "Semantic version (e.g. 4.17.21)",
+                    },
+                },
+                "required": ["ecosystem", "package", "version"],
+            },
+        ),
+        Tool(
+            name="cleanlib_health_check",
+            description=(
+                "Verify MCP→App transport reachability via the public /health "
+                "endpoint. Returns the App's health JSON ({status, service, version, "
+                "ecosystems_mounted}). Requires CLEANLIB_ENDPOINT env var. Public "
+                "endpoint; no API key needed. Use this to confirm MCP server can "
+                "reach the deployed App before invoking verdict fetches."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {},
+                "required": [],
+            },
+        ),
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    if name == "cleanlib_fetch_verdict":
+        ecosystem = arguments.get("ecosystem", "")
+        package = arguments.get("package", "")
+        version = arguments.get("version", "")
+        if not (ecosystem and package and version):
+            return [TextContent(type="text", text="Error: ecosystem, package, and version are all required.")]
+        try:
+            verdict = await fetch_verdict(ecosystem, package, version)
+        except PermissionError as e:
+            return [TextContent(type="text", text=f"Auth error: {e}")]
+        except Exception as e:
+            return [TextContent(type="text", text=f"Verdict fetch failed: {e}")]
+        # Render as concise human-readable summary + JSON detail for agents.
+        icon = "✓" if verdict.decision == "ALLOW" else "✗" if verdict.decision == "DENY" else "⚠"
+        confidence_str = f"{verdict.confidence:.0%}" if verdict.confidence is not None else "n/a"
+        summary = (
+            f"{icon} {verdict.ecosystem}/{verdict.package}@{verdict.version} → "
+            f"{verdict.decision} (confidence {confidence_str})\n\n"
+            f"Reasoning: {verdict.reasoning or '(none)'}\n\n"
+            f"verdict_id: {verdict.verdict_id}"
+        )
+        return [TextContent(type="text", text=summary)]
+
+    if name == "cleanlib_health_check":
+        import os
+        endpoint = os.getenv("CLEANLIB_ENDPOINT", "").strip()
+        if not endpoint:
+            return [TextContent(type="text", text="CLEANLIB_ENDPOINT env var not set; cannot probe.")]
+        try:
+            data = await live_health(endpoint)
+        except Exception as e:
+            return [TextContent(type="text", text=f"Health probe failed against {endpoint}: {e}")]
+        return [TextContent(type="text", text=(
+            f"✓ CleanLibrary App reachable at {endpoint}\n\n"
+            f"status: {data.get('status')}\n"
+            f"service: {data.get('service')}\n"
+            f"version: {data.get('version')}\n"
+            f"ecosystems_mounted: {', '.join(data.get('ecosystems_mounted', []))}"
+        ))]
+
+    return [TextContent(type="text", text=f"Unknown tool: {name}")]
+
+
+async def serve() -> None:
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO)
+    asyncio.run(serve())
+
+
+if __name__ == "__main__":
+    main()

cleanlib_mcp_server-0.2.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: cleanlib-mcp-server
+Version: 0.2.0
+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
+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 — expose verdict-aware supply-chain risk assessment as MCP tools, so MCP-capable clients (Claude Code, Claude Desktop, Cursor, GitHub Copilot, and other agents) can fetch package verdicts directly inside the developer's workflow.
+
+Ask your AI assistant *"is cors@2.8.4 safe to install?"* and it queries CleanLibrary for an `ALLOW` / `DENY` / `WARN` verdict with reasoning and confidence — without leaving the editor.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `cleanlib_fetch_verdict(ecosystem, package, version)` | Fetch a verdict (`ALLOW` / `DENY` / `WARN`) with reasoning and confidence for a package version |
+| `cleanlib_health_check()` | Report server status + whether a live CleanLibrary backend is configured |
+
+## Install
+
+```bash
+pip install cleanlib-mcp-server
+```
+
+## 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.
+
+## MCP client integration
+
+The server speaks standard MCP over stdio, so it works with any MCP-capable client. Example configuration (Claude Desktop — `~/Library/Application Support/Claude/claude_desktop_config.json`; other clients use the same `mcpServers` shape):
+
+```json
+{
+  "mcpServers": {
+    "cleanlibrary": {
+      "command": "cleanlib-mcp-server"
+    }
+  }
+}
+```
+
+To connect a live CleanLibrary backend, add the endpoint + API key:
+
+```json
+{
+  "mcpServers": {
+    "cleanlibrary": {
+      "command": "cleanlib-mcp-server",
+      "env": {
+        "CLEANLIB_ENDPOINT": "https://cleanapp.clnstrt.dev",
+        "CLEANLIB_API_KEY": "clk_..."
+      }
+    }
+  }
+}
+```
+
+The same `command` + `env` pattern applies to Cursor, GitHub Copilot, and other MCP clients — consult your client's MCP server configuration docs for the exact file location.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+ruff check src tests
+pytest -v
+```
+
+## License
+
+Proprietary. See [LICENSE](./LICENSE) for terms. © 2026 CleanStart Inc.

cleanlib_mcp_server-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+cleanlib_mcp/__init__.py,sha256=LEStHhF9QeN8MrazrjqIBmXVYptoRPjNAU8RuHp46Ec,265
+cleanlib_mcp/backend.py,sha256=bcbVkHiyauesrh8hXl9hhwOXk_el_ER92XBz4RH08bw,8292
+cleanlib_mcp/server.py,sha256=qh8-hvV3aE72VPRDExqUVRS5RnRN9L_PZM6WYnb6o2Q,5124
+cleanlib_mcp_server-0.2.0.dist-info/licenses/LICENSE,sha256=-_ijBZ8qpgShm7v5vUkQOYYjiDnnjy1yVuqvNNxon6k,731
+cleanlib_mcp_server-0.2.0.dist-info/METADATA,sha256=wFBRMhC64LsufNi4d6x6pTzG_Y5GplooDtAQtCxTc4Y,3932
+cleanlib_mcp_server-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cleanlib_mcp_server-0.2.0.dist-info/entry_points.txt,sha256=i6VvagI03Lf-MAWyR3p_Cgf093Hvj_I1XgdlWdcPmeQ,65
+cleanlib_mcp_server-0.2.0.dist-info/top_level.txt,sha256=u8cHyffcPTv5xnmj7DPz-BSkorAHmNIJh8scb4o1ypk,13
+cleanlib_mcp_server-0.2.0.dist-info/RECORD,,

cleanlib_mcp_server-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cleanlib_mcp_server-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cleanlib-mcp-server = cleanlib_mcp.server:main

cleanlib_mcp_server-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+CleanStart Inc Proprietary License
+
+Copyright (c) 2026 CleanStart Inc. All rights reserved.
+
+This software is the proprietary property of CleanStart Inc. Use is permitted
+only under the terms of a separate commercial license agreement with CleanStart
+Inc. or its authorized distributors. Unauthorized use, modification, distribution,
+or reverse engineering is prohibited.
+
+For licensing inquiries: cto.office@cleanstart.com
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY.

cleanlib_mcp_server-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cleanlib_mcp