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.
