USAGE.md•4.99 kB
# License Scanner MCP Server - Usage Guide
## Quick Start
1. **Install dependencies:**
```bash
./install.sh
```
2. **Test the server:**
```bash
source venv/bin/activate
python test_server.py
```
3. **Run the MCP server:**
```bash
source venv/bin/activate
python run_server.py
```
## Available Tools
### 1. `scan_dependencies(project_path: str)`
Scans a project directory for dependencies and fetches license information.
**Example:**
```json
{
"project_path": "/path/to/project",
"package_files": ["package.json", "requirements.txt"],
"dependencies": [
{
"name": "express",
"version": "^4.18.2",
"manager": "npm",
"license": "MIT",
"author": "TJ Holowaychuk",
"homepage": "https://expressjs.com/"
}
],
"total_dependencies": 5
}
```
### 2. `generate_license_report(project_path: str, output_file: str = None)`
Generates a comprehensive markdown license report.
**Example output:**
```markdown
# License Report
**Project:** /path/to/project
**Total Dependencies:** 12
**Package Files Found:** package.json, requirements.txt
## NPM Dependencies
| Package | Version | License | Author | Homepage |
|---------|---------|---------|--------|----------|
| express | ^4.18.2 | MIT | TJ Holowaychuk | https://expressjs.com/ |
## License Summary
| License | Count |
|---------|-------|
| MIT | 8 |
| Apache-2.0 | 3 |
| BSD-3-Clause | 1 |
```
### 3. `list_package_managers(project_path: str)`
Lists all detected package manager files in a project.
**Example:**
```json
{
"project_path": "/path/to/project",
"package_files": [
"package.json",
"requirements.txt",
"Cargo.toml"
],
"total_files": 3
}
```
## Supported Package Managers
| Package Manager | Files Detected | License Source |
|----------------|----------------|----------------|
| npm/yarn/pnpm | `package.json`, `yarn.lock`, `pnpm-lock.yaml` | npm registry API |
| Python pip | `requirements.txt`, `pyproject.toml`, `Pipfile` | PyPI JSON API |
| Rust cargo | `Cargo.toml`, `Cargo.lock` | crates.io API |
| PHP composer | `composer.json`, `composer.lock` | (Basic support) |
| Ruby bundler | `Gemfile`, `Gemfile.lock` | (Basic support) |
| Go modules | `go.mod`, `go.sum` | (Basic support) |
| Java Maven | `pom.xml` | (Basic support) |
| Java Gradle | `build.gradle`, `gradle.lockfile` | (Basic support) |
## Integration with Claude Desktop
Add this to your Claude Desktop configuration:
```json
{
"mcpServers": {
"license-scanner": {
"command": "python",
"args": ["/absolute/path/to/license_scanner.py"],
"cwd": "/absolute/path/to/project"
}
}
}
```
Then you can use natural language commands like:
- "Scan the dependencies in my project"
- "Generate a license report for this directory"
- "What package managers are used in this project?"
## Example Use Cases
### 1. Compliance Auditing
```bash
# Generate a comprehensive license report
python -c "
from license_scanner import generate_license_report
result = generate_license_report('/path/to/project', 'compliance_report.md')
print(result)
"
```
### 2. Dependency Analysis
```bash
# Get JSON data for further processing
python -c "
from license_scanner import scan_dependencies
import json
result = scan_dependencies('/path/to/project')
data = json.loads(result)
print(f'Found {data[\"total_dependencies\"]} dependencies')
"
```
### 3. Package Manager Detection
```bash
# Check what package managers are in use
python -c "
from license_scanner import list_package_managers
import json
result = list_package_managers('/path/to/project')
data = json.loads(result)
print(f'Package managers: {data[\"package_files\"]}')
"
```
## Error Handling
The server includes comprehensive error handling:
- Invalid project paths
- Network timeouts when fetching license data
- Malformed package files
- Missing dependencies
All errors are logged and returned in a structured format.
## Performance Features
- **Caching**: License information is cached to avoid repeated API calls
- **Timeout protection**: API requests have 10-second timeouts
- **Parallel processing**: Multiple package files are processed efficiently
## Customization
You can extend the server by:
1. Adding new package manager parsers in the `parse_*` functions
2. Adding new license sources in the `get_*_package_license` functions
3. Modifying the markdown report format in `generate_license_report_markdown`
## Troubleshooting
### Common Issues
1. **Module not found errors**: Make sure you're running in the virtual environment
```bash
source venv/bin/activate
```
2. **Network errors**: Check your internet connection for license API calls
3. **Permission errors**: Ensure the script has read access to project files
4. **Empty results**: Verify that package manager files exist in the target directory
### Debug Mode
For debugging, you can run the test script to see detailed output:
```bash
source venv/bin/activate
python test_server.py
```