# mcp-semclone - Model Context Protocol Server for SEMCL.ONE
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.python.org/downloads/)
[](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`
### Development Installation
```bash
git clone https://github.com/SemClone/mcp-semclone.git
cd mcp-semclone
pip install -e .[dev]
```
## Configuration
### MCP Client Integration
**Quick Start - Basic Configuration:**
Add to your MCP client configuration file (e.g., `.cursor/mcp.json`, Cline settings, `.kiro/settings/mcp.json`):
```json
{
"mcpServers": {
"semclone": {
"command": "/path/to/your/.local/pipx/venvs/mcp-semclone/bin/python3",
"args": ["-m", "mcp_semclone.server"],
"env": {}
}
}
}
```
**Find your pipx Python path:**
```bash
# macOS/Linux
echo "$HOME/.local/pipx/venvs/mcp-semclone/bin/python3"
# Or locate automatically
pipx list --include-injected | grep mcp-semclone -A 3
```
**📖 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](guides/IDE_INTEGRATION_GUIDE.md)**
### 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"
### Direct MCP Client Usage
```python
from mcp import Client
import asyncio
async def main():
async with Client("mcp-semclone") as client:
# Scan a directory
result = await client.call_tool(
"scan_directory",
{
"path": "/path/to/project",
"check_vulnerabilities": True,
"check_licenses": True
}
)
print(f"Found {result['metadata']['total_packages']} packages")
print(f"Found {result['metadata']['total_vulnerabilities']} vulnerabilities")
# Scan a binary file
binary_result = await client.call_tool(
"scan_binary",
{
"path": "/path/to/app.apk",
"analysis_mode": "deep",
"check_compatibility": True
}
)
print(f"Found {binary_result['metadata']['component_count']} components")
print(f"Licenses: {binary_result['licenses']}")
# Check a specific package
package_result = await client.call_tool(
"check_package",
{"identifier": "pkg:npm/express@4.17.1"}
)
print(f"Vulnerabilities: {package_result['vulnerabilities']}")
asyncio.run(main())
```
## 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
## Architecture
```
┌─────────────────┐
│ LLM Client │
│ (MCP Client) │
└────────┬────────┘
│ MCP Protocol
┌────────▼────────┐
│ mcp-semclone │
│ MCP Server │
└────────┬────────┘
│ Subprocess calls
┌────────▼──────────────────────────┐
│ SEMCL.ONE Toolchain │
├────────────────────────────────────┤
│ purl2notices │ Package + License │
│ osslili │ Archive scanning │
│ binarysniffer│ Binary analysis │
│ vulnq │ Vulnerability DB │
│ ospac │ Policy engine │
│ upmex │ Metadata extract │
└────────────────────────────────────┘
```
## Server Instructions for LLMs
The MCP server includes comprehensive instructions that help LLMs understand how to use the tools effectively. These instructions are automatically injected into the LLM's context when using the server, providing:
### Workflow Patterns
- **License-first approach**: The server prioritizes license detection before package identification or vulnerability scanning
- **Efficient execution order**: Tools are orchestrated in an optimal sequence (licenses → packages → vulnerabilities → policy validation)
- **Smart dependency handling**: Package identification is only performed when needed for vulnerability checks or detailed SBOMs
### Tool Selection Guidance
- When to use `scan_directory` (comprehensive analysis) vs `check_package` (single package lookup)
- How tools interact (e.g., `generate_sbom` automatically calls `scan_directory` internally)
- Specialized tools for specific scenarios (e.g., `analyze_commercial_risk` for mobile/commercial distribution)
### Performance Optimization
- Vulnerability scanning is limited to the first 10 packages to avoid timeouts
- Recursive scanning depth limits: 10 for licenses, 5 for package identification
- 120-second timeout per tool invocation
- Guidance for handling large codebases
### Common Usage Patterns
The server provides ready-to-use workflow examples:
1. **Basic compliance check**: License inventory without package identification
2. **Full security assessment**: Complete vulnerability analysis with package discovery
3. **Policy validation**: Automated license compliance checking
4. **Commercial risk analysis**: Copyleft detection for mobile/commercial use
5. **SBOM generation**: Supply chain transparency documentation
This enables LLMs to automatically choose the right tool combination, optimize performance, and follow best practices without requiring user expertise in OSS compliance workflows.
## Tool Integration
The MCP server orchestrates multiple SEMCL.ONE tools:
1. **purl2notices**: Comprehensive package detection, license scanning, and copyright extraction (primary scanning tool)
2. **osslili**: License detection in archives and compressed files (used by check_package)
3. **binarysniffer**: Binary analysis for compiled artifacts (APK, EXE, DLL, SO, JAR)
4. **vulnq**: Queries vulnerability databases (OSV, GitHub, NVD)
5. **ospac**: Validates licenses against policies
6. **upmex**: Extracts package metadata from manifests (used by check_package)
## 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.
## IDE Integration
Use SEMCL.ONE tools directly within your AI-powered IDE for seamless OSS compliance analysis during development.
### Supported IDEs
- **Cursor IDE** - AI-first code editor
- **Cline** - AI coding extension for VS Code
- **Kiro IDE** - Amazon's agentic AI IDE
- **VS Code** - With MCP extension
- **JetBrains IDEs** - With AI plugin
### Quick Setup
1. **Install mcp-semclone** with pipx (recommended):
```bash
pipx install mcp-semclone
pipx inject mcp-semclone purl2notices osslili binarysniffer ospac vulnq upmex
```
2. **Configure your IDE** - Add MCP server configuration (see guide for IDE-specific paths)
3. **Restart your IDE**
### Use Cases in IDEs
Once integrated, ask your IDE's AI:
- "Check this project for license compliance issues"
- "What licenses are used in my dependencies?"
- "Is this package safe for commercial distribution?"
- "Generate SBOM for this release"
- "Create NOTICE file for mobile app"
**📖 Complete documentation**: See [IDE Integration Guide](guides/IDE_INTEGRATION_GUIDE.md)
## Development
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=mcp_semclone tests/
# Run specific test
pytest tests/test_server.py -v
```
### Building
```bash
# Build package
python -m build
# Install locally for testing
pip install -e .
```
## Troubleshooting
### Common Issues
1. **Tools not found**: Ensure all SEMCL.ONE tools are installed and in PATH
2. **API rate limits**: Add API keys to environment variables
3. **Permission errors**: Check file/directory permissions
4. **Large codebases**: Use recursive=False or limit scan depth
### Debug Mode
Enable debug logging:
```bash
export MCP_LOG_LEVEL=DEBUG
python -m mcp_semclone.server
```
## Security Considerations
- API keys are optional but recommended for production use
- The server runs tools via subprocess with user permissions
- Vulnerability data is fetched from public APIs
- No data is sent to external services without explicit tool calls
## 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*
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-semclone",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, llm, compliance, license, vulnerability, sbom, sca, oss",
"author": null,
"author_email": "\"Oscar Valenzuela B.\" <oscar.valenzuela.b@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/5e/e6/b9a5c9abf5a1178f44950779da9cf483f82c4ab78c9816e54bb969c3dc00/mcp_semclone-1.6.1.tar.gz",
"platform": null,
"description": "# mcp-semclone - Model Context Protocol Server for SEMCL.ONE\n\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://www.python.org/downloads/)\n[](https://modelcontextprotocol.io/)\n\nMCP (Model Context Protocol) server that provides LLMs with comprehensive OSS compliance and vulnerability analysis capabilities through the SEMCL.ONE toolchain.\n\n## Overview\n\nmcp-semclone integrates the complete SEMCL.ONE toolchain to provide LLMs with powerful software composition analysis capabilities:\n\n- **License Detection & Compliance**: Scan codebases for licenses and validate against policies\n- **Binary Analysis**: Analyze compiled binaries (APK, EXE, DLL, SO, JAR) for OSS components and licenses\n- **Vulnerability Assessment**: Query multiple vulnerability databases for security issues\n- **Package Discovery**: Identify packages from source code and generate PURLs\n- **SBOM Generation**: Create Software Bill of Materials in CycloneDX format\n- **Policy Validation**: Check license compatibility and organizational compliance\n\n## Features\n\n### Tools\n\n**Analysis & Scanning:**\n- `scan_directory` - Comprehensive directory scanning for packages, licenses, and vulnerabilities\n- `scan_binary` - Analyze compiled binaries (APK, EXE, DLL, SO, JAR) for OSS components\n- `check_package` - Check specific packages for licenses and vulnerabilities\n- `download_and_scan_package` - Download package source from registries and perform deep license/copyright scanning\n\n**Legal Notices & Documentation:**\n- `generate_legal_notices` - Generate legal notices by scanning source code directly (fast, recommended)\n- `generate_legal_notices_from_purls` - Generate legal notices from PURL list (downloads from registries)\n- `generate_sbom` - Generate Software Bill of Materials in CycloneDX format\n\n**License & Policy Validation:**\n- `validate_policy` - Validate licenses against organizational policies\n- `validate_license_list` - Quick license safety validation for distribution types\n- `get_license_obligations` - Get detailed compliance requirements for licenses\n- `check_license_compatibility` - Check if two licenses can be mixed\n- `get_license_details` - Get comprehensive license information including full text\n- `analyze_commercial_risk` - Assess commercial distribution risks\n\n**Complete Workflows:**\n- `run_compliance_check` - Universal one-shot compliance workflow for any project type\n\n### Resources\n- `license_database` - Access license compatibility information\n- `policy_templates` - Get pre-configured policy templates\n\n### Prompts\n- `compliance_check` - Guided workflow for license compliance checking\n- `vulnerability_assessment` - Guided workflow for security assessment\n\n## Installation\n\n### Single Command Installation\n\n```bash\npip install mcp-semclone\n```\n\nThis automatically installs all required SEMCL.ONE tools:\n- **purl2notices** - Comprehensive package detection and license extraction\n- **osslili** - License detection from archives (used by check_package)\n- **binarysniffer** - Binary analysis for OSS components\n- **ospac** - Policy validation engine\n- **vulnq** - Vulnerability database queries\n- **upmex** - Package metadata extraction (used by check_package)\n\n### Pipx Installation (Recommended for Global Access)\n\n[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.\n\n```bash\n# Install pipx if you don't have it\npip install pipx\npipx ensurepath\n\n# Install mcp-semclone\npipx install mcp-semclone\n\n# IMPORTANT: Inject all SEMCL.ONE tool dependencies into the same isolated environment\n# This ensures all tools are available both as libraries and CLI commands\n# Required by some agents that need direct CLI tool access\n# Use --include-apps to make CLI commands globally available\npipx inject mcp-semclone purl2notices purl2src osslili binarysniffer ospac vulnq upmex --include-apps\n```\n\n**Benefits of pipx:**\n- \u2705 Isolated environment prevents dependency conflicts\n- \u2705 All tools globally accessible in PATH\n- \u2705 Easy to update: `pipx upgrade mcp-semclone`\n- \u2705 Clean uninstall: `pipx uninstall mcp-semclone`\n\n### Development Installation\n\n```bash\ngit clone https://github.com/SemClone/mcp-semclone.git\ncd mcp-semclone\npip install -e .[dev]\n```\n\n## Configuration\n\n### MCP Client Integration\n\n**Quick Start - Basic Configuration:**\n\nAdd to your MCP client configuration file (e.g., `.cursor/mcp.json`, Cline settings, `.kiro/settings/mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"semclone\": {\n \"command\": \"/path/to/your/.local/pipx/venvs/mcp-semclone/bin/python3\",\n \"args\": [\"-m\", \"mcp_semclone.server\"],\n \"env\": {}\n }\n }\n}\n```\n\n**Find your pipx Python path:**\n```bash\n# macOS/Linux\necho \"$HOME/.local/pipx/venvs/mcp-semclone/bin/python3\"\n\n# Or locate automatically\npipx list --include-injected | grep mcp-semclone -A 3\n```\n\n**\ud83d\udcd6 For detailed setup instructions including:**\n- IDE-specific configurations (Cursor, Cline, Kiro, VS Code, JetBrains)\n- Auto-approve settings\n- pip vs pipx configurations\n- Configuration templates\n- Troubleshooting\n\n**See the [IDE Integration Guide](guides/IDE_INTEGRATION_GUIDE.md)**\n\n### Environment Variables\n\nOptional environment variables for enhanced functionality:\n\n```bash\n# API Keys (optional, for higher rate limits)\nexport GITHUB_TOKEN=\"your_github_token\"\nexport NVD_API_KEY=\"your_nvd_api_key\"\n\n# Tool paths (optional, only if tools are not in PATH)\n# Tools are auto-detected by default using shutil.which()\nexport PURL2NOTICES_PATH=\"/custom/path/to/purl2notices\"\nexport OSSLILI_PATH=\"/custom/path/to/osslili\"\nexport BINARYSNIFFER_PATH=\"/custom/path/to/binarysniffer\"\nexport VULNQ_PATH=\"/custom/path/to/vulnq\"\nexport OSPAC_PATH=\"/custom/path/to/ospac\"\nexport UPMEX_PATH=\"/custom/path/to/upmex\"\n```\n\n**Note:** Tools are automatically detected in your PATH. Environment variables are only needed for custom installation locations.\n\n## Usage Examples\n\n### With MCP Clients\n\nOnce configured, you can ask your LLM:\n\n- \"Scan /path/to/project for license compliance issues\"\n- \"Analyze this Android APK file for OSS components and licenses\"\n- \"Check if this project has any critical vulnerabilities\"\n- \"Generate an SBOM for my project\"\n- \"What licenses are in this compiled binary?\"\n- \"Validate these licenses against our commercial distribution policy\"\n- \"Find all GPL-licensed dependencies in this codebase\"\n\n### Direct MCP Client Usage\n\n```python\nfrom mcp import Client\nimport asyncio\n\nasync def main():\n async with Client(\"mcp-semclone\") as client:\n # Scan a directory\n result = await client.call_tool(\n \"scan_directory\",\n {\n \"path\": \"/path/to/project\",\n \"check_vulnerabilities\": True,\n \"check_licenses\": True\n }\n )\n print(f\"Found {result['metadata']['total_packages']} packages\")\n print(f\"Found {result['metadata']['total_vulnerabilities']} vulnerabilities\")\n\n # Scan a binary file\n binary_result = await client.call_tool(\n \"scan_binary\",\n {\n \"path\": \"/path/to/app.apk\",\n \"analysis_mode\": \"deep\",\n \"check_compatibility\": True\n }\n )\n print(f\"Found {binary_result['metadata']['component_count']} components\")\n print(f\"Licenses: {binary_result['licenses']}\")\n\n # Check a specific package\n package_result = await client.call_tool(\n \"check_package\",\n {\"identifier\": \"pkg:npm/express@4.17.1\"}\n )\n print(f\"Vulnerabilities: {package_result['vulnerabilities']}\")\n\nasyncio.run(main())\n```\n\n## Workflows\n\n### License Compliance Check\n\n1. **Scan the project** to identify all packages and licenses\n2. **Load or create a policy** defining allowed/denied licenses\n3. **Validate licenses** against the policy\n4. **Generate compliance report** with violations and recommendations\n\n### Vulnerability Assessment\n\n1. **Discover packages** in the codebase\n2. **Query vulnerability databases** for each package\n3. **Prioritize by severity** (CRITICAL > HIGH > MEDIUM > LOW)\n4. **Identify available fixes** and upgrade paths\n5. **Generate security report** with remediation steps\n\n### SBOM Generation\n\n1. **Scan project structure** to identify components\n2. **Extract metadata** for each component\n3. **Detect licenses** and copyright information\n4. **Format as SBOM** (CycloneDX 1.4 JSON)\n5. **Validate completeness** of the SBOM\n\n## Architecture\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 LLM Client \u2502\n\u2502 (MCP Client) \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502 MCP Protocol\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 mcp-semclone \u2502\n\u2502 MCP Server \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502 Subprocess calls\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 SEMCL.ONE Toolchain \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 purl2notices \u2502 Package + License \u2502\n\u2502 osslili \u2502 Archive scanning \u2502\n\u2502 binarysniffer\u2502 Binary analysis \u2502\n\u2502 vulnq \u2502 Vulnerability DB \u2502\n\u2502 ospac \u2502 Policy engine \u2502\n\u2502 upmex \u2502 Metadata extract \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## Server Instructions for LLMs\n\nThe MCP server includes comprehensive instructions that help LLMs understand how to use the tools effectively. These instructions are automatically injected into the LLM's context when using the server, providing:\n\n### Workflow Patterns\n- **License-first approach**: The server prioritizes license detection before package identification or vulnerability scanning\n- **Efficient execution order**: Tools are orchestrated in an optimal sequence (licenses \u2192 packages \u2192 vulnerabilities \u2192 policy validation)\n- **Smart dependency handling**: Package identification is only performed when needed for vulnerability checks or detailed SBOMs\n\n### Tool Selection Guidance\n- When to use `scan_directory` (comprehensive analysis) vs `check_package` (single package lookup)\n- How tools interact (e.g., `generate_sbom` automatically calls `scan_directory` internally)\n- Specialized tools for specific scenarios (e.g., `analyze_commercial_risk` for mobile/commercial distribution)\n\n### Performance Optimization\n- Vulnerability scanning is limited to the first 10 packages to avoid timeouts\n- Recursive scanning depth limits: 10 for licenses, 5 for package identification\n- 120-second timeout per tool invocation\n- Guidance for handling large codebases\n\n### Common Usage Patterns\nThe server provides ready-to-use workflow examples:\n1. **Basic compliance check**: License inventory without package identification\n2. **Full security assessment**: Complete vulnerability analysis with package discovery\n3. **Policy validation**: Automated license compliance checking\n4. **Commercial risk analysis**: Copyleft detection for mobile/commercial use\n5. **SBOM generation**: Supply chain transparency documentation\n\nThis enables LLMs to automatically choose the right tool combination, optimize performance, and follow best practices without requiring user expertise in OSS compliance workflows.\n\n## Tool Integration\n\nThe MCP server orchestrates multiple SEMCL.ONE tools:\n\n1. **purl2notices**: Comprehensive package detection, license scanning, and copyright extraction (primary scanning tool)\n2. **osslili**: License detection in archives and compressed files (used by check_package)\n3. **binarysniffer**: Binary analysis for compiled artifacts (APK, EXE, DLL, SO, JAR)\n4. **vulnq**: Queries vulnerability databases (OSV, GitHub, NVD)\n5. **ospac**: Validates licenses against policies\n6. **upmex**: Extracts package metadata from manifests (used by check_package)\n\n## Examples\n\n### Basic MCP Client Usage\n\nSee [`examples/basic_usage.py`](examples/basic_usage.py) for simple examples of calling MCP tools directly.\n\n### Strands Agent with Ollama\n\nA complete autonomous agent example demonstrating OSS compliance analysis using local LLM (Ollama) with MCP integration.\n\n**Location**: `examples/strands-agent-ollama/`\n\n**Features:**\n- Autonomous decision-making (plan \u2192 execute \u2192 interpret \u2192 report)\n- Local LLM inference via Ollama (llama3, gemma3, deepseek-r1)\n- Interactive and batch analysis modes\n- Custom policy enforcement\n- Complete privacy (no external API calls)\n\n**Quick Start:**\n```bash\ncd examples/strands-agent-ollama\n./quickstart.sh\npython agent.py interactive\n```\n\n**Documentation:**\n- [README.md](examples/strands-agent-ollama/README.md) - Complete usage guide\n- [TUNING.md](examples/strands-agent-ollama/TUNING.md) - Optimization guide\n- [OVERVIEW.md](examples/strands-agent-ollama/OVERVIEW.md) - Architecture reference\n\n**Use Cases:**\n- Mobile app compliance (APK/IPA analysis)\n- Embedded/IoT firmware scanning\n- CI/CD integration\n- Interactive compliance queries\n\nSee the [example directory](examples/strands-agent-ollama/) for full details.\n\n## IDE Integration\n\nUse SEMCL.ONE tools directly within your AI-powered IDE for seamless OSS compliance analysis during development.\n\n### Supported IDEs\n\n- **Cursor IDE** - AI-first code editor\n- **Cline** - AI coding extension for VS Code\n- **Kiro IDE** - Amazon's agentic AI IDE\n- **VS Code** - With MCP extension\n- **JetBrains IDEs** - With AI plugin\n\n### Quick Setup\n\n1. **Install mcp-semclone** with pipx (recommended):\n ```bash\n pipx install mcp-semclone\n pipx inject mcp-semclone purl2notices osslili binarysniffer ospac vulnq upmex\n ```\n\n2. **Configure your IDE** - Add MCP server configuration (see guide for IDE-specific paths)\n\n3. **Restart your IDE**\n\n### Use Cases in IDEs\n\nOnce integrated, ask your IDE's AI:\n- \"Check this project for license compliance issues\"\n- \"What licenses are used in my dependencies?\"\n- \"Is this package safe for commercial distribution?\"\n- \"Generate SBOM for this release\"\n- \"Create NOTICE file for mobile app\"\n\n**\ud83d\udcd6 Complete documentation**: See [IDE Integration Guide](guides/IDE_INTEGRATION_GUIDE.md)\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=mcp_semclone tests/\n\n# Run specific test\npytest tests/test_server.py -v\n```\n\n### Building\n\n```bash\n# Build package\npython -m build\n\n# Install locally for testing\npip install -e .\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Tools not found**: Ensure all SEMCL.ONE tools are installed and in PATH\n2. **API rate limits**: Add API keys to environment variables\n3. **Permission errors**: Check file/directory permissions\n4. **Large codebases**: Use recursive=False or limit scan depth\n\n### Debug Mode\n\nEnable debug logging:\n\n```bash\nexport MCP_LOG_LEVEL=DEBUG\npython -m mcp_semclone.server\n```\n\n## Security Considerations\n\n- API keys are optional but recommended for production use\n- The server runs tools via subprocess with user permissions\n- Vulnerability data is fetched from public APIs\n- No data is sent to external services without explicit tool calls\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## License\n\nmcp-semclone is released under the Apache License 2.0. See [LICENSE](LICENSE) for details.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/SemClone/mcp-semclone/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/SemClone/mcp-semclone/discussions)\n- **Security**: Report vulnerabilities to security@semcl.one\n\n---\n\n*Part of the [SEMCL.ONE](https://github.com/SemClone/semcl.one) Software Composition Analysis toolchain*\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Model Context Protocol server for SEMCL.ONE OSS compliance toolchain",
"version": "1.6.1",
"project_urls": {
"Bug Reports": "https://github.com/SemClone/mcp-semclone/issues",
"Homepage": "https://github.com/SemClone/mcp-semclone",
"Source": "https://github.com/SemClone/mcp-semclone"
},
"split_keywords": [
"mcp",
" llm",
" compliance",
" license",
" vulnerability",
" sbom",
" sca",
" oss"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "88b12d479fbf156d43b2a623bec06c57db061a782ca5d7b71943975c1a158160",
"md5": "a92633b35b1177c412ab436241312963",
"sha256": "ce5e2f6e2a7fbde316f932a7903297b5306b33287fc0ba1a12e7675e9cefa7bb"
},
"downloads": -1,
"filename": "mcp_semclone-1.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a92633b35b1177c412ab436241312963",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 45078,
"upload_time": "2025-11-14T06:33:52",
"upload_time_iso_8601": "2025-11-14T06:33:52.875102Z",
"url": "https://files.pythonhosted.org/packages/88/b1/2d479fbf156d43b2a623bec06c57db061a782ca5d7b71943975c1a158160/mcp_semclone-1.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5ee6b9a5c9abf5a1178f44950779da9cf483f82c4ab78c9816e54bb969c3dc00",
"md5": "dc73539a397b0225277a4ff198c95280",
"sha256": "bcf72ae6c6d36618765835a06908bade7b28721abbcb0410d2b7c61f4665560b"
},
"downloads": -1,
"filename": "mcp_semclone-1.6.1.tar.gz",
"has_sig": false,
"md5_digest": "dc73539a397b0225277a4ff198c95280",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 110310,
"upload_time": "2025-11-14T06:33:54",
"upload_time_iso_8601": "2025-11-14T06:33:54.553363Z",
"url": "https://files.pythonhosted.org/packages/5e/e6/b9a5c9abf5a1178f44950779da9cf483f82c4ab78c9816e54bb969c3dc00/mcp_semclone-1.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-14 06:33:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SemClone",
"github_project": "mcp-semclone",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "mcp-semclone"
}
JSON
