cleanlib-mcp-server 0.2.0__tar.gz

cleanlib_mcp_server-0.2.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,74 @@
+# 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/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cleanlib-mcp-server"
+version = "0.2.0"
+description = "CleanLibrary MCP server — exposes verdict-aware supply-chain risk assessment as Model Context Protocol tools for AI agent workflows"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.11"
+license = { text = "CleanStart Inc Proprietary" }
+authors = [{ name = "CleanStart Inc", email = "cto.office@cleanstart.com" }]
+maintainers = [{ name = "CleanStart Inc", email = "cto.office@cleanstart.com" }]
+keywords = ["cleanlibrary", "mcp", "model-context-protocol", "cleanstart", "supply-chain-security", "verdict", "policy-evaluation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: Other/Proprietary License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Software Distribution",
+]
+
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.7.0",
+]
+
+[project.urls]
+Homepage = "https://cleanlibrary.clnstrt.dev"
+Documentation = "https://cleanlibrary.clnstrt.dev"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.6.0",
+]
+
+[project.scripts]
+cleanlib-mcp-server = "cleanlib_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

cleanlib_mcp_server-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cleanlib_mcp_server-0.2.0/src/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_server-0.2.0/src/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-0.2.0/src/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/src/cleanlib_mcp_server.egg-info/PKG-INFO

@@ -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/src/cleanlib_mcp_server.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/cleanlib_mcp/__init__.py
+src/cleanlib_mcp/backend.py
+src/cleanlib_mcp/server.py
+src/cleanlib_mcp_server.egg-info/PKG-INFO
+src/cleanlib_mcp_server.egg-info/SOURCES.txt
+src/cleanlib_mcp_server.egg-info/dependency_links.txt
+src/cleanlib_mcp_server.egg-info/entry_points.txt
+src/cleanlib_mcp_server.egg-info/requires.txt
+src/cleanlib_mcp_server.egg-info/top_level.txt
+tests/test_backend.py

cleanlib_mcp_server-0.2.0/src/cleanlib_mcp_server.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cleanlib_mcp_server-0.2.0/src/cleanlib_mcp_server.egg-info/entry_points.txt

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

cleanlib_mcp_server-0.2.0/src/cleanlib_mcp_server.egg-info/requires.txt

@@ -0,0 +1,8 @@
+mcp>=1.0.0
+httpx>=0.27.0
+pydantic>=2.7.0
+
+[dev]
+pytest>=8.0.0
+pytest-asyncio>=0.23.0
+ruff>=0.6.0

cleanlib_mcp_server-0.2.0/src/cleanlib_mcp_server.egg-info/top_level.txt

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

cleanlib_mcp_server-0.2.0/tests/test_backend.py

@@ -0,0 +1,195 @@
+"""Substrate-mode backend tests — mock backend behavior with cycle-4 §D.7
+demo fixtures."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from cleanlib_mcp.backend import fetch_verdict
+
+
+@pytest.fixture(autouse=True)
+def _clear_live_env(monkeypatch):
+    """Force mock-mode by clearing live-backend env vars per test."""
+    monkeypatch.delenv("CLEANLIB_ENDPOINT", raising=False)
+    monkeypatch.delenv("CLEANLIB_API_KEY", raising=False)
+
+
+async def test_cors_2_8_4_returns_deny():
+    v = await fetch_verdict("npm", "cors", "2.8.4")
+    assert v.decision == "DENY"
+    assert v.reasoning and ("prototype pollution" in v.reasoning or "2.8.5" in v.reasoning)
+
+
+async def test_cors_2_8_5_returns_allow():
+    v = await fetch_verdict("npm", "cors", "2.8.5")
+    assert v.decision == "ALLOW"
+
+
+async def test_helmet_returns_allow():
+    v = await fetch_verdict("npm", "helmet", "8.0.0")
+    assert v.decision == "ALLOW"
+
+
+async def test_dotenv_returns_allow():
+    v = await fetch_verdict("npm", "dotenv", "16.4.5")
+    assert v.decision == "ALLOW"
+
+
+async def test_oracledb_returns_warn():
+    v = await fetch_verdict("npm", "oracledb", "6.5.1")
+    assert v.decision == "WARN"
+    assert v.reasoning and ("vendor-binary" in v.reasoning.lower() or "supply-chain" in v.reasoning.lower())
+
+
+async def test_unknown_pkg_default_allow():
+    v = await fetch_verdict("npm", "some-unknown-pkg", "1.0.0")
+    assert v.decision == "ALLOW"
+    assert v.reasoning and "default-allow" in v.reasoning.lower()
+
+
+async def test_verdict_id_unique_per_call():
+    a = await fetch_verdict("npm", "lodash", "4.17.21")
+    b = await fetch_verdict("npm", "lodash", "4.17.21")
+    assert a.verdict_id != b.verdict_id
+
+
+async def test_verdict_carries_input_eco_pkg_ver():
+    v = await fetch_verdict("pypi", "requests", "2.32.0")
+    assert v.ecosystem == "pypi"
+    assert v.package == "requests"
+    assert v.version == "2.32.0"
+
+
+async def test_verdict_to_dict_drops_none_values():
+    v = await fetch_verdict("npm", "helmet", "8.0.0")
+    d = v.to_dict()
+    # None values should be dropped from serialization
+    assert all(value is not None for value in d.values())
+    assert d["decision"] == "ALLOW"
+    assert d["package"] == "helmet"
+
+
+def _mock_transport(handler):
+    """Helper: build an httpx.MockTransport from a request-handler callable."""
+    import httpx
+    return httpx.MockTransport(handler)
+
+
+async def test_live_fetch_200_returns_canonical_verdict(monkeypatch):
+    """When App's Rev 4 §9.3 endpoint returns 200 + valid JSON, MCP parses
+    it into the canonical Verdict dataclass."""
+    import httpx
+    from cleanlib_mcp import backend as b
+
+    def handler(request):
+        assert request.url.path == "/v1/customer/verdicts/npm/lodash/4.17.21"
+        assert request.headers["authorization"] == "Bearer test-key"
+        return httpx.Response(200, json={
+            "verdict_id": "vrd_test123",
+            "ecosystem": "npm",
+            "package": "lodash",
+            "version": "4.17.21",
+            "decision": "ALLOW",
+            "reasoning": "no findings",
+            "confidence": 0.95,
+            "source": "ALLOWED_NO_FINDINGS",
+        })
+
+    _orig = httpx.AsyncClient
+    monkeypatch.setattr(b.httpx, "AsyncClient", lambda **kw: _orig(transport=_mock_transport(handler), **{k: v for k, v in kw.items() if k != "transport"}))
+    v = await b._live_fetch("https://app.test", "test-key", "npm", "lodash", "4.17.21")
+    assert v.verdict_id == "vrd_test123"
+    assert v.decision == "ALLOW"
+    assert v.confidence == 0.95
+
+
+async def test_live_fetch_404_no_json_raises_live_backend_not_deployed(monkeypatch):
+    """When App's endpoint returns 404 with empty/non-JSON body, MCP raises
+    LiveBackendNotDeployed so the wrapper can fall back to mock."""
+    import httpx
+    from cleanlib_mcp import backend as b
+
+    def handler(request):
+        return httpx.Response(404, content=b"<html>404 Not Found</html>", headers={"content-type": "text/html"})
+
+    _orig = httpx.AsyncClient
+    monkeypatch.setattr(b.httpx, "AsyncClient", lambda **kw: _orig(transport=_mock_transport(handler), **{k: v for k, v in kw.items() if k != "transport"}))
+    with pytest.raises(b.LiveBackendNotDeployed) as exc:
+        await b._live_fetch("https://app.test", "test-key", "npm", "lodash", "4.17.21")
+    assert "did not return a verdict" in str(exc.value)
+
+
+async def test_live_fetch_404_json_returns_no_verdict_substrate(monkeypatch):
+    """When the endpoint returns 404 with a JSON body (reached, but no verdict
+    for this package), the backend returns a Verdict with INSUFFICIENT_DATA
+    source."""
+    import httpx
+    from cleanlib_mcp import backend as b
+
+    def handler(request):
+        return httpx.Response(404, json={"error": "verdict not found"}, headers={"content-type": "application/json"})
+
+    _orig = httpx.AsyncClient
+    monkeypatch.setattr(b.httpx, "AsyncClient", lambda **kw: _orig(transport=_mock_transport(handler), **{k: v for k, v in kw.items() if k != "transport"}))
+    v = await b._live_fetch("https://app.test", "test-key", "npm", "missing", "1.0.0")
+    assert v.decision == "ALLOW"
+    assert v.source == "INSUFFICIENT_DATA"
+    assert "No verdict on file" in (v.reasoning or "")
+
+
+async def test_live_fetch_401_raises_permission_error(monkeypatch):
+    """Bad bearer → 401 → PermissionError."""
+    import httpx
+    from cleanlib_mcp import backend as b
+
+    def handler(request):
+        return httpx.Response(401, content=b"unauthorized")
+
+    _orig = httpx.AsyncClient
+    monkeypatch.setattr(b.httpx, "AsyncClient", lambda **kw: _orig(transport=_mock_transport(handler), **{k: v for k, v in kw.items() if k != "transport"}))
+    with pytest.raises(PermissionError) as exc:
+        await b._live_fetch("https://app.test", "bad-key", "npm", "lodash", "4.17.21")
+    assert "401" in str(exc.value)
+
+
+async def test_fetch_verdict_falls_back_to_mock_when_endpoint_not_deployed(monkeypatch):
+    """End-to-end: live env set, App returns 404-not-deployed, fetch_verdict
+    falls back to mock fixture + annotates reasoning."""
+    import httpx
+    from cleanlib_mcp import backend as b
+
+    monkeypatch.setenv("CLEANLIB_ENDPOINT", "https://app.test")
+    monkeypatch.setenv("CLEANLIB_API_KEY", "test-key")
+
+    def handler(request):
+        return httpx.Response(404, content=b"<html>404</html>", headers={"content-type": "text/html"})
+
+    _orig = httpx.AsyncClient
+    monkeypatch.setattr(b.httpx, "AsyncClient", lambda **kw: _orig(transport=_mock_transport(handler), **{k: v for k, v in kw.items() if k != "transport"}))
+    v = await b.fetch_verdict("npm", "cors", "2.8.4")
+    assert v.decision == "DENY"  # cors-2.8.4 fixture is DENY
+    assert "live-mode fallback" in (v.reasoning or "")
+
+
+async def test_live_health_returns_app_health_json(monkeypatch):
+    """live_health probes /health and returns the JSON body."""
+    import httpx
+    from cleanlib_mcp import backend as b
+
+    def handler(request):
+        assert request.url.path == "/health"
+        return httpx.Response(200, json={
+            "status": "ok",
+            "service": "cleanlib-app",
+            "version": "0.1.0",
+            "ecosystems_mounted": ["npm", "pypi", "go", "maven", "crates", "nuget", "rubygems"],
+        })
+
+    _orig = httpx.AsyncClient
+    monkeypatch.setattr(b.httpx, "AsyncClient", lambda **kw: _orig(transport=_mock_transport(handler), **{k: v for k, v in kw.items() if k != "transport"}))
+    data = await b.live_health("https://app.test")
+    assert data["status"] == "ok"
+    assert "npm" in data["ecosystems_mounted"]