bd-skill — Black Duck SCA Skill for Claude Code

An MCP (Model Context Protocol) server that gives Claude Code access to your Black Duck instance. Ask natural-language questions about vulnerabilities, licenses, policy violations, and component risks — Claude handles the multi-step API navigation automatically.

Prerequisites

• Python 3.11+
• A Black Duck server with API access
• A Black Duck API token
• Claude Code CLI
• Java 17+ (required only for running Detect scans)

Installation

cd bd_skill
python -m venv .venv
source .venv/bin/activate
pip install -e .

This installs the bd-skill command into the virtualenv.

Registering with Claude Code

Register the MCP server so Claude Code can use the skill:

claude mcp add -s project \
  -e BLACKDUCK_BDSCA_URL=https://your-blackduck-server.com \
  -e BLACKDUCK_BDSCA_TOKEN=your-api-token \
  blackduck \
  -- /path/to/bd_skill/.venv/bin/bd-skill

Scope options:

Verify

claude mcp list

You should see blackduck listed. Start a new Claude Code session and the 16 tools will be available.

Environment Variables

Multi-Server Profiles

If you work with multiple Black Duck instances (e.g. production and staging), you can configure named profiles instead of using environment variables.

Setup

Create ~/.blackduck/profiles.yaml:

profiles:
  prod:
    url: https://bd-prod.example.com
    token: "your-prod-api-token"
    tls_verify: true       # optional, default: true
    timeout: 30            # optional, default: 30
    cache_ttl: 300         # optional, default: 300
  staging:
    url: https://bd-staging.example.com
    token: "your-staging-api-token"

default: prod   # optional — first profile is used if omitted

When a profiles file is present, environment variables are ignored. If no profiles file exists, the server falls back to BLACKDUCK_BDSCA_URL / BLACKDUCK_BDSCA_TOKEN environment variables (full backward compatibility).

Registration with Profiles

When using profiles, you don't need to pass credentials via -e flags:

claude mcp add -s project \
  blackduck \
  -- /path/to/bd_skill/.venv/bin/blackduck-assist

Profile Management Tools

Switching Profiles

Ask Claude naturally:

• "Switch to the staging profile"
• "Which Black Duck profile am I connected to?"
• "List my Black Duck profiles"

Available Tools

Navigation

Security & Compliance

Investigation

Detect Scanning

Advanced

Resources

MCP resources provide browsable data endpoints that LLMs can read via URI patterns. Unlike tools, resources don't consume tool-call tokens and are ideal for paginated data.

Project and version names support the same fuzzy matching as tools — if a name doesn't match exactly, the response includes suggestions.

Slash Commands

Quick-access commands for common operations. Type these directly in Claude Code:

Slash Command Examples

/list_projects              # show first 20 projects, with option to page through more
/list_projects payment       # search for projects matching "payment"
/project_risk my-app         # risk profile for my-app (auto-resolves latest version)
/project_vulns my-app critical  # only critical vulnerabilities
/policy_violations my-app    # policy violations grouped by rule

Installation

Copy the skill files to your Claude Code skills directory:

cp -r skills/list_projects  ~/.claude/skills/
cp -r skills/project_risk   ~/.claude/skills/
cp -r skills/project_vulns  ~/.claude/skills/
cp -r skills/policy_violations ~/.claude/skills/

Restart Claude Code for the commands to appear in /help.

Running Detect Scans

The MCP server can kick off Black Duck Detect scans directly. Detect is auto-downloaded on first use — no manual installation required (Java 17+ must be available).

How it works

1. run_detect_scan starts the scan asynchronously and returns a scan ID immediately
2. get_detect_scan_status polls for progress and retrieves log output
3. list_detect_scans shows all scans in the current session

Credentials (URL, token, TLS settings) are automatically injected from the active profile — you never need to pass them.

Parameters

Natural language examples

• "Scan the current project with Black Duck Detect"
• "Run a rapid scan on /path/to/my-app"
• "Kick off a Detect scan for my-app version 2.0"
• "Check the status of my Detect scan"

Detect script management

The Detect CLI script (detect10.sh) is automatically downloaded from https://detect.blackduck.com/detect10.sh to ~/.blackduck/detect/ on first use. Subsequent scans reuse the cached script.

Usage Examples

Once registered, just ask Claude naturally:

• "What critical vulnerabilities are in my-app?"
• "Show me the risk profile for payment-service"
• "Which projects are affected by CVE-2021-44228?"
• "Compare v2.0 and v3.0 of api-gateway"
• "What GPL-licensed components are in my-app?"
• "Run a Detect scan on this project"

Claude will automatically resolve project names (with fuzzy matching), navigate to the right version, and call the appropriate tools.

Development

Setting Up the Dev Environment

git clone <repo-url> && cd bd_skill
python -m venv .venv
source .venv/bin/activate
make dev    # installs the package in editable mode with dev deps + pre-commit hooks

This installs pytest, ruff, mypy, and pre-commit. The make dev target is equivalent to:

pip install -e ".[dev]"
pre-commit install

Running Tests

make test       # run all tests with coverage report

Tests use mocked API responses — no live Black Duck server is needed. The coverage threshold is 60%; the suite currently sits at ~63%.

Other useful commands:

make lint       # check lint + formatting (no modifications)
make format     # auto-fix lint issues and reformat
make typecheck  # run mypy type checking
make check      # run all three gates: lint → typecheck → tests

Project Structure

bd_skill/
├── .mcp.json                  # MCP server definition
├── pyproject.toml              # Package metadata, deps, and tool configs
├── Makefile                    # Dev task runner (test, lint, format, etc.)
├── .pre-commit-config.yaml     # Pre-commit hooks (ruff + mypy)
├── skills/
│   ├── blackduck/
│   │   └── SKILL.md            # Skill instructions and domain knowledge
│   ├── list_projects/
│   │   └── SKILL.md            # /list_projects slash command
│   ├── project_risk/
│   │   └── SKILL.md            # /project_risk slash command
│   ├── project_vulns/
│   │   └── SKILL.md            # /project_vulns slash command
│   └── policy_violations/
│       └── SKILL.md            # /policy_violations slash command
├── src/
│   └── bd_skill/
│       ├── server.py           # MCP server + tool definitions + resource endpoints
│       ├── client.py           # Async Black Duck API wrapper
│       ├── detect.py           # Detect CLI runner (download, execute, track scans)
│       ├── profiles.py         # Multi-profile configuration and registry
│       ├── models.py           # Pydantic response models
│       ├── cache.py            # Name and response caching
│       ├── resolver.py         # Fuzzy project/version name matching
│       └── throttle.py         # Rate limiting (5 RPS default)
└── tests/
    ├── conftest.py             # Shared fixtures (mock SDK client, sample data)
    ├── test_models.py          # Pydantic model construction and validation
    ├── test_cache.py           # ResponseCache and NameCache
    ├── test_resolver.py        # Fuzzy name matching
    ├── test_throttle.py        # Async rate limiter
    ├── test_profiles.py        # ProfileRegistry and YAML loading
    ├── test_client.py          # BlackDuckClient methods (mocked SDK)
    ├── test_detect.py          # DetectRunner and ScanRecord
    ├── test_server.py          # MCP tool functions (mocked client)
    └── test_resources.py       # MCP resource functions

Removing

claude mcp remove blackduck