Metadata-Version: 2.4
Name: blackduck-sca-mcp
Version: 0.9.1
Summary: A agentic tool for handling and orchestrating Black Duck SCA products.
Author-email: Bogdan Mihaila <bmihaila@blackduck.com>, Matti Siipola <matti@blackduck.com>, Jussi Polet <polet@blackduck.com>
License-Expression: Apache-2.0
Keywords: agent,LLM,AI,agentic AI,MCP,blackduck,SCA,BDSCA,BDBA,scan,results,helpers
Classifier: Programming Language :: Python
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: structlog>=20.1.0
Requires-Dist: typer>=0.12.5
Requires-Dist: rich>=13.8.1
Requires-Dist: requests<3,>=2
Requires-Dist: requests-toolbelt>=1.0.0
Requires-Dist: fastmcp>=3.0.0
Requires-Dist: pydantic<3,>=2.13.3
Requires-Dist: PyYAML>=6.0
Requires-Dist: blackduck-sca-api-client==0.3.1
Dynamic: license-file

# Black Duck SCA — MCP Server

Connect your AI coding assistant to the Black Duck Software Composition Analysis (SCA) products.
The MCP server exposes your Black Duck SCA instance as a set of tools that any
MCP-compatible AI harness can call to perform actions such as: 
investigate your software's security posture and vulnerabilities, triage findings, 
generate vulnerability reports and SBOMs.

[Black Duck Website](https://www.blackduck.com/) 

## Capabilities

These are the MCP tool areas currently available.

| Area | Available Features | Related Tool Names |
|------|--------------------|--------------------|
| Dashboard | View instance-wide security posture, activity trends, and vulnerability breakdowns | get_dashboard_summary |
| Projects | Find projects and versions, inspect BOM contents, and review project-level vulnerabilities | search_projects_versions<br>fetch_project_components<br>fetch_project_vulnerabilities |
| Components | Search components across projects and see where specific versions are used | search_components |
| Vulnerabilities | Search the global vulnerability dataset and update remediation/triage status | search_vulnerabilities<br>update_vulnerability_remediation |
| Policies | Check policy violation status and compliance at project version level | fetch_policy_violation_status |
| Scanning | Run scans for source, binary, container, and SBOM inputs; check scan status and results; match code snippets | scan<br>search_scans<br>get_scan_status<br>match_code_snippet |
| Reports | Generate SBOM, VEX/CSAF, and Notices reports | create_report |
| Connectivity | Validate backend connectivity and credential health | check_connectivity |


## Prerequisites

- **Black Duck SCA instance** with a user account and API token
- **Python 3.13 or later+**
- **[uv](https://docs.astral.sh/uv/getting-started/installation/)** — Python package manager
- **Java 11+** _(optional)_ — required only for source scanning via Detect

## Installation

### Claude Code

```bash
claude mcp add blackduck-bdsca-mcp \
  --env BLACKDUCK_BDSCA_URL=https://<your-instance-url> \
  --env BLACKDUCK_BDSCA_TOKEN=<api-token> \
  -- uvx \
  --managed-python --python 3.13 \
  --from 'blackduck-sca-mcp' bdsca \
  --transport stdio
```

### Claude Desktop/Cowork

Add via UI and make sure the config file has similar values afterward.

```json
{
    "managedMcpServers": [
    {
      "name": "blackduck-bdsca-mcp",
      "source": "user",
      "transport": "stdio",
      "command": "/bin/uvx",
      "args": [
        "--managed-python",
        "--python", "3.13",
        "--from", "blackduck-sca-mcp", "bdsca",
        "--transport", "stdio"
      ],
      "env": {
        "BLACKDUCK_BDSCA_URL": "https://<your-instance-url>",
        "BLACKDUCK_BDSCA_TOKEN": "<api-token>"
      }
    }
  ]
}

```

###  VS Code

Add to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "blackduck-bdsca-mcp": {
      "command": "uvx",
      "args": [
        "--managed-python",
        "--python", "3.13",
        "--from", "blackduck-sca-mcp", "bdsca",
        "--transport", "stdio"
      ],
      "env": {
        "BLACKDUCK_BDSCA_URL": "https://<your-instance-url>",
        "BLACKDUCK_BDSCA_TOKEN": "<api-token>"
      }
    }
  }
}
```

###  Copilot CLI

Copilot CLI currently does not implement the full  
MCP spec, it is missing handling of MCP resources. To work around that, we can expose those resources as tools 
by specifying the `BLACKDUCK_MCP_ENABLE_RESOURCES_AS_TOOLS=true` environment variable.

```bash
copilot mcp add blackduck-bdsca-mcp \
  --env BLACKDUCK_BDSCA_URL=https://<your-instance-url> \
  --env BLACKDUCK_BDSCA_TOKEN=<api-token> \
  --env BLACKDUCK_MCP_ENABLE_RESOURCES_AS_TOOLS=true \
  -- uvx \
  --managed-python --python 3.13 \
  --from 'blackduck-sca-mcp' bdsca \ 
  --transport stdio
```

```json
{
  "servers": {
    "blackduck-bdsca-mcp": {
      "command": "uvx",
      "args": [
        "--managed-python",
        "--python", "3.13",
        "--from", "blackduck-sca-mcp", "bdsca",
        "--transport", "stdio"
      ],
      "env": {
        "BLACKDUCK_BDSCA_URL": "https://<your-instance-url>",
        "BLACKDUCK_BDSCA_TOKEN": "<api-token>"
      }
    }
  }
}
```

#### Roo Code

Use the same `.vscode/mcp.json` configuration as GitHub Copilot above.

### SSL/TLS

If your instance uses a self-signed certificate, either add it to your system's
trusted certificate store or set below for the MCP to allow it to connect:

```bash
export BLACKDUCK_BDSCA_SSL_VERIFY=false
```

## Security

API tokens inherit the full permissions of the associated user account.
If you provide a token with write access, the AI assistant can modify
data in your Black Duck SCA instance — including updating vulnerability
remediation status and policy overrides.

We recommend creating a dedicated service account with the minimum
permissions required for your use case. See the [Role and Permission Matrix](https://documentation.blackduck.com/bundle/bd-hub/page/UsersAndGroups/RoleMatrix.html) for details.


## Support

- [Black Duck Website](https://www.blackduck.com/)
- [Community Portal](https://community.blackduck.com)
- [Email](support@blackduck.com)
