# mcp-semclone - Model Context Protocol Server for SEMCL.ONE

[![Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP 1.0+](https://img.shields.io/badge/MCP-1.0+-purple.svg)](https://modelcontextprotocol.io/)

MCP (Model Context Protocol) server that provides LLMs with comprehensive OSS compliance and vulnerability analysis capabilities through the SEMCL.ONE toolchain.

## Overview

mcp-semclone integrates the complete SEMCL.ONE toolchain to provide LLMs with powerful software composition analysis capabilities:

- **License Detection & Compliance**: Scan codebases for licenses and validate against policies
- **Binary Analysis**: Analyze compiled binaries (APK, EXE, DLL, SO, JAR) for OSS components and licenses
- **Vulnerability Assessment**: Query multiple vulnerability databases for security issues
- **Package Discovery**: Identify packages from source code and generate PURLs
- **SBOM Generation**: Create Software Bill of Materials in CycloneDX format
- **Policy Validation**: Check license compatibility and organizational compliance

## Features

### Tools

**Analysis & Scanning:**
- `scan_directory` - Comprehensive directory scanning for packages, licenses, and vulnerabilities
- `scan_binary` - Analyze compiled binaries (APK, EXE, DLL, SO, JAR) for OSS components
- `check_package` - Check specific packages for licenses and vulnerabilities
- `download_and_scan_package` - Download package source from registries and perform deep license/copyright scanning

**Legal Notices & Documentation:**
- `generate_legal_notices` - Generate legal notices by scanning source code directly (fast, recommended)
- `generate_legal_notices_from_purls` - Generate legal notices from PURL list (downloads from registries)
- `generate_sbom` - Generate Software Bill of Materials in CycloneDX format

**License & Policy Validation:**
- `validate_policy` - Validate licenses against organizational policies
- `validate_license_list` - Quick license safety validation for distribution types
- `get_license_obligations` - Get detailed compliance requirements for licenses
- `check_license_compatibility` - Check if two licenses can be mixed
- `get_license_details` - Get comprehensive license information including full text
- `analyze_commercial_risk` - Assess commercial distribution risks

**Complete Workflows:**
- `run_compliance_check` - Universal one-shot compliance workflow for any project type

### Resources
- `license_database` - Access license compatibility information
- `policy_templates` - Get pre-configured policy templates

### Prompts
- `compliance_check` - Guided workflow for license compliance checking
- `vulnerability_assessment` - Guided workflow for security assessment

## Installation

### Single Command Installation

```bash
pip install mcp-semclone
```

This automatically installs all required SEMCL.ONE tools:
- **purl2notices** - Comprehensive package detection and license extraction
- **osslili** - License detection from archives (used by check_package)
- **binarysniffer** - Binary analysis for OSS components
- **ospac** - Policy validation engine
- **vulnq** - Vulnerability database queries
- **upmex** - Package metadata extraction (used by check_package)

### Pipx Installation (Recommended for Global Access)

[pipx](https://pipx.pypa.io/) installs the package in an isolated environment while making the CLI tools globally available. This is ideal for avoiding dependency conflicts with other Python packages on your system.

```bash
# Install pipx if you don't have it
pip install pipx
pipx ensurepath

# Install mcp-semclone
pipx install mcp-semclone

# IMPORTANT: Inject all SEMCL.ONE tool dependencies into the same isolated environment
# This ensures all tools are available both as libraries and CLI commands
# Required by some agents that need direct CLI tool access
# Use --include-apps to make CLI commands globally available
pipx inject mcp-semclone purl2notices purl2src osslili binarysniffer ospac vulnq upmex --include-apps
```

**Benefits of pipx:**
- ✅ Isolated environment prevents dependency conflicts
- ✅ All tools globally accessible in PATH
- ✅ Easy to update: `pipx upgrade mcp-semclone`
- ✅ Clean uninstall: `pipx uninstall mcp-semclone`


**For detailed setup instructions including:**
- IDE-specific configurations (Cursor, Cline, Kiro, VS Code, JetBrains)
- Auto-approve settings
- pip vs pipx configurations
- Configuration templates
- Troubleshooting

**See the [IDE Integration Guide](https://community.semcl.one/user_guides/mcp-semclone-ide-integration-guide/)**

### Environment Variables

Optional environment variables for enhanced functionality:

```bash
# API Keys (optional, for higher rate limits)
export GITHUB_TOKEN="your_github_token"
export NVD_API_KEY="your_nvd_api_key"

# Tool paths (optional, only if tools are not in PATH)
# Tools are auto-detected by default using shutil.which()
export PURL2NOTICES_PATH="/custom/path/to/purl2notices"
export OSSLILI_PATH="/custom/path/to/osslili"
export BINARYSNIFFER_PATH="/custom/path/to/binarysniffer"
export VULNQ_PATH="/custom/path/to/vulnq"
export OSPAC_PATH="/custom/path/to/ospac"
export UPMEX_PATH="/custom/path/to/upmex"
```

**Note:** Tools are automatically detected in your PATH. Environment variables are only needed for custom installation locations.

## Usage Examples

### With MCP Clients

Once configured, you can ask your LLM:

- "Scan /path/to/project for license compliance issues"
- "Analyze this Android APK file for OSS components and licenses"
- "Check if this project has any critical vulnerabilities"
- "Generate an SBOM for my project"
- "What licenses are in this compiled binary?"
- "Validate these licenses against our commercial distribution policy"
- "Find all GPL-licensed dependencies in this codebase"


## Workflows

### License Compliance Check

1. **Scan the project** to identify all packages and licenses
2. **Load or create a policy** defining allowed/denied licenses
3. **Validate licenses** against the policy
4. **Generate compliance report** with violations and recommendations

### Vulnerability Assessment

1. **Discover packages** in the codebase
2. **Query vulnerability databases** for each package
3. **Prioritize by severity** (CRITICAL > HIGH > MEDIUM > LOW)
4. **Identify available fixes** and upgrade paths
5. **Generate security report** with remediation steps

### SBOM Generation

1. **Scan project structure** to identify components
2. **Extract metadata** for each component
3. **Detect licenses** and copyright information
4. **Format as SBOM** (CycloneDX 1.4 JSON)
5. **Validate completeness** of the SBOM


## Examples

### Basic MCP Client Usage

See [`examples/basic_usage.py`](examples/basic_usage.py) for simple examples of calling MCP tools directly.

### Strands Agent with Ollama

A complete autonomous agent example demonstrating OSS compliance analysis using local LLM (Ollama) with MCP integration.

**Location**: `examples/strands-agent-ollama/`

**Features:**
- Autonomous decision-making (plan → execute → interpret → report)
- Local LLM inference via Ollama (llama3, gemma3, deepseek-r1)
- Interactive and batch analysis modes
- Custom policy enforcement
- Complete privacy (no external API calls)

**Quick Start:**
```bash
cd examples/strands-agent-ollama
./quickstart.sh
python agent.py interactive
```

**Documentation:**
- [README.md](examples/strands-agent-ollama/README.md) - Complete usage guide
- [TUNING.md](examples/strands-agent-ollama/TUNING.md) - Optimization guide
- [OVERVIEW.md](examples/strands-agent-ollama/OVERVIEW.md) - Architecture reference

**Use Cases:**
- Mobile app compliance (APK/IPA analysis)
- Embedded/IoT firmware scanning
- CI/CD integration
- Interactive compliance queries

See the [example directory](examples/strands-agent-ollama/) for full details.


## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

mcp-semclone is released under the Apache License 2.0. See [LICENSE](LICENSE) for details.

## Support

- **Issues**: [GitHub Issues](https://github.com/SemClone/mcp-semclone/issues)
- **Discussions**: [GitHub Discussions](https://github.com/SemClone/mcp-semclone/discussions)
- **Security**: Report vulnerabilities to security@semcl.one

---

*Part of the [SEMCL.ONE](https://github.com/SemClone/semcl.one) Software Composition Analysis toolchain*