bob-sps-helper

MCP server for IBM Verify SaaS SPS security issue management and migration helper. This tool helps automate the analysis, categorization, and remediation of security issues during sprint cycles.

What This Server Does

The bob-sps-helper MCP server provides automated tools for managing security issues in the IBM Verify SaaS SPS migration process. It connects to GitHub Enterprise and JIRA to:

• Analyze and categorize security issues by severity and fix complexity with detailed vulnerability information
• Provide interactive workflows through IBM Bob with progress tracking and guided issue resolution
• Display comprehensive vulnerability tables including CVSS scores, CWE IDs, affected files, and remediation steps
• Create JIRA deviation requests for issues that cannot be fixed
• Suggest fixes with code snippets, configuration examples, and effort estimates
• Track component security health and sprint readiness
• Automate end-to-end sprint processing workflows

Key Features

📊 Enhanced Vulnerability Analysis

• Detailed tables with CVSS scores, package names, CWE IDs, and affected files
• Impact analysis showing how vulnerabilities affect your codebase
• Remediation guidance with specific version upgrades and fix steps
• Effort estimates for planning sprint work

🎯 Interactive Workflow

• Guided issue resolution with step-by-step options
• Progress tracking showing reviewed, in-progress, and pending issues
• Flexible navigation to skip, go back, or batch process issues
• Smart categorization identifying quick-fixes vs complex issues

🔧 Automation

• Batch operations for creating deviations or fixes
• Automatic file analysis to identify affected code
• Integration with GitHub and JIRA for seamless workflow

Quick Start

The primary way to use this server is via npx with global VS Code settings (no cloning required).

Prerequisites

• Node.js 18 or higher
• GitHub Enterprise personal access token (repo, read:org scopes)
• JIRA personal access token
• IBM VPN connection (for GitHub Enterprise and JIRA access)

1. Create Required Tokens

GitHub Token:

1. Go to https://github.ibm.com/settings/tokens
2. Click "Generate new token" → "Generate new token (classic)"
3. Select scopes: repo, read:org
4. Generate and copy the token

JIRA Token:

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Copy the token

2. Set Environment Variables

Add these to your shell profile (~/.zshrc for zsh or ~/.bashrc for bash):

export GITHUB_REPO_ACCESS_TOKEN="your_github_token_here"
export GITHUB_BASE_URL="https://github.ibm.com/api/v3"
export JIRA_PAT="your_jira_token_here"
export JIRA_BASE_URL="https://jsw.ibm.com"
export JIRA_USERNAME="[email protected]"

Then reload your shell:

source ~/.zshrc  # or source ~/.bashrc

Important: After setting environment variables, you must fully quit and relaunch VS Code (Cmd+Q → reopen) for it to pick up the new values.

3. Add to VS Code Settings

Open VS Code User Settings (JSON):

• Press Cmd+Shift+P
• Type "Open User Settings (JSON)"
• Add this configuration:

{
  "mcp": {
    "servers": {
      "bob-sps-helper": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "bob-sps-helper"],
        "env": {
          "GITHUB_REPO_ACCESS_TOKEN": "${env:GITHUB_REPO_ACCESS_TOKEN}",
          "GITHUB_BASE_URL": "${env:GITHUB_BASE_URL}",
          "JIRA_PAT": "${env:JIRA_PAT}",
          "JIRA_BASE_URL": "${env:JIRA_BASE_URL}",
          "JIRA_USERNAME": "${env:JIRA_USERNAME}"
        }
      }
    }
  }
}

Important: Add this to your User Settings (JSON), NOT to a workspace .vscode/settings.json file. The global settings ensure the server works from any project.

4. Reload VS Code

After adding the configuration, reload VS Code:

• Press Cmd+Shift+P
• Type "Developer: Reload Window"

5. Verify Setup

In IBM Bob, type:

Use the bob-sps-helper MCP server to check setup

You should see a report showing all prerequisites passed.

How to Invoke in IBM Bob

Critical: You must explicitly mention the server name in your requests to IBM Bob. Without this, Bob may answer from general knowledge instead of using the MCP tools.

Working Pattern

Use the bob-sps-helper MCP server to <action>

Why This Matters

IBM Bob doesn't yet support @server-name mentions or /slash-commands autocomplete. By explicitly saying "Use the bob-sps-helper MCP server to...", you ensure Bob routes your request to the correct MCP server instead of answering from its general knowledge base.

Bob will ask you for any missing details interactively - you don't need to provide everything upfront.

Example Invocations

Check setup:

Use the bob-sps-helper MCP server to check setup

Analyze component issues:

Use the bob-sps-helper MCP server to analyze security issues for component agent-bridge-supsvc sprint 158

Create deviation requests:

Use the bob-sps-helper MCP server to create deviation requests for issues 59200, 59169 in component saml sprint 158

Get component health:

Use the bob-sps-helper MCP server to check the security health of component notification

Suggest a fix:

Use the bob-sps-helper MCP server to suggest a fix for issue 59200

Batch process sprint:

Use the bob-sps-helper MCP server to batch process sprint 158 for component workflow in standalone mode

IBM Bob Limitations

| Feature | IBM Bob Support | Workaround | | -------------------------------- | -------------------- | -------------------------------------------------------------- | | /slash-commands | ❌ Not yet supported | Use explicit "Use the bob-sps-helper MCP server to..." pattern | | @server-name mentions | ❌ Not yet supported | Use explicit "Use the bob-sps-helper MCP server to..." pattern | | Natural language requests | ✅ Fully supported | Works great with explicit server name | | Interactive parameter collection | ✅ Fully supported | Bob asks for missing details |

Note: Slash commands ARE registered in the server and will work automatically in IBM Bob once IBM Bob adds support - no server code changes needed.

Slash Commands

These slash commands work in VS Code Copilot Chat and Cline (not yet in IBM Bob):

| Command | Description | Arguments | | ------------------------------------- | --------------------------------------- | ---------------------------- | | /bob-sps-helper:check-setup | Run prerequisites check | None (zero-argument) | | /bob-sps-helper:analyze-component | Analyze security issues for a component | None - AI asks interactively | | /bob-sps-helper:create-deviations | Create JIRA deviation requests | None - AI asks interactively | | /bob-sps-helper:component-health | Check component security health | None - AI asks interactively | | /bob-sps-helper:batch-process | Complete sprint issue processing | None - AI asks interactively |

All slash commands take zero arguments - the AI will ask you for required details interactively.

Tool Reference

For advanced users who want to call tools directly:

| Tool | Description | Required Inputs | | ---------------------------- | --------------------------------- | -------------------------------- | | check_setup | Verify prerequisites | None | | analyze_all_issues | Analyze and categorize issues | component, sprint | | create_deviation_request | Create JIRA deviations | issue_numbers, component | | suggest_fix | Get fix recommendations | issue_number | | create_fix_pr | Create PR with fixes | issue_numbers, component | | get_component_health | Get security health report | component | | batch_process_sprint | End-to-end sprint processing | component, sprint, mode | | manage_component_mapping | Manage component-to-repo mappings | action |

Enhanced Features

Action Classification Logic

The server automatically determines the recommended action for each security issue based on several factors:

Action Types

| Action | Icon | Description | When Applied | |--------|------|-------------|--------------| | Fix | ✅ | Regular code fix | Issue has fix-available label AND is not OS/base image related | | Fix (OS) | ⚠️ | OS/base image fix | Issue has fix-available label AND is OS/base image related | | Deviate | 📋 | Deviation recommended | No fix-available label OR OS dependency without fix | | Review | 🔍 | Manual review needed | Edge cases requiring human assessment |

Decision Flow

1. Check if issue has "fix-available" label
   ├─ YES → Check if OS/base image related
   │         ├─ YES → ⚠️ Fix (OS) - Requires base image update
   │         └─ NO  → ✅ Fix - Standard code fix
   │
   └─ NO  → Check if OS/base image related
             ├─ YES → 📋 Deviate - OS dependency, no fix available
             └─ NO  → 📋 Deviate - No fix available

2. OS/Base Image Detection:
   - Dependency Type contains "OS"
   - Base Image Vulnerability flag is true
   - Package is from system libraries (openssl-libs, glibc, zlib, etc.)

Why This Matters

OS/Base Image Issues (⚠️ Fix (OS)):

• These vulnerabilities come from the Docker base image or OS packages
• Even when a fix is available, it requires updating the base image
• Cannot be fixed by just updating application dependencies
• Requires coordination with infrastructure/DevOps teams
• Example: openssl-libs vulnerability needs base image rebuild

Regular Fixes (✅ Fix):

• Application-level dependencies that can be updated directly
• Can be fixed by updating go.mod, package.json, etc.
• No infrastructure changes required
• Example: Go standard library vulnerability fixed by Go version upgrade

Deviations (📋 Deviate):

• No fix is currently available from the vendor
• OS/base image issue without an available fix
• Risk accepted through formal deviation process
• Tracked in JIRA for future resolution

Example Scenarios

Scenario 1: Go Standard Library Vulnerability

• Package: crypto/tls
• Has fix-available label: Yes
• OS/Base Image: No
• Action: ✅ Fix - Upgrade Go version

Scenario 2: OpenSSL in Base Image

• Package: openssl-libs
• Has fix-available label: Yes
• OS/Base Image: Yes
• Action: ⚠️ Fix (OS) - Update base image

Scenario 3: Glibc with No Fix

• Package: glibc
• Has fix-available label: No
• OS/Base Image: Yes
• Action: 📋 Deviate - No fix available, OS dependency

Scenario 4: Application Dependency

• Package: express (Node.js)
• Has fix-available label: Yes
• OS/Base Image: No
• Action: ✅ Fix - Update package.json

Vulnerability Table Format

When you analyze issues, you'll see comprehensive tables like this:

| Issue # | CVE | CVSS | Package | CWE | References | Affected Files | Impact | Fix | Effort | Status | |---------|-----|------|---------|-----|------------|---------------|--------|-----|--------|--------| | #50915 | CVE-2025-68121 | 🔴 10.0 | crypto/tls | CWE-119 | NVD | 3 files | Direct code | v1.26.0-rc.3 | 4-8h | 🔄 Pending |

Table Columns:

• Issue # - Clickable GitHub link
• CVE - CVE identifier
• CVSS - Severity score with visual indicator
• Package - Affected package name
• CWE - Common Weakness Enumeration
• References - Links to NVD and security advisories
• Affected Files - Number of files impacted in your codebase
• Impact - How it affects your code
• Fix - Version to upgrade to
• Effort - Estimated time to fix
• Status - Progress indicator (🔄 Pending, ✅ Reviewed, 🚀 Fixed)

Interactive Workflow Example

Step 1: Analyze issues

Use the bob-sps-helper MCP server to analyze security issues for component agent-bridge-svc sprint 163

Step 2: Bob presents options

• Fix the 1 critical issue
• Fix all 3 critical + high priority issues
• Fix quick-win issues
• Create deviation requests for low severity issues

Step 3: Select an option, Bob shows detailed vulnerability info

Step 4: Choose action (create PR, deviation, mark reviewed, skip)

Step 5: Bob tracks progress and moves to next issue

Usage Examples

Example 1: Analyze Component Issues with Interactive Workflow

IBM Bob:

Use the bob-sps-helper MCP server to analyze security issues for agent-bridge-supsvc sprint 158

VS Code Copilot Chat / Cline:

/bob-sps-helper:analyze-component

Then provide: component = "agent-bridge-supsvc", sprint = 158

Result:

• Detailed vulnerability tables with CVSS, CWE, affected files
• Interactive options to fix, deviate, or review issues
• Progress tracking throughout the workflow
• Guided resolution with effort estimates

Example 2: Create Deviation Requests

IBM Bob:

Use the bob-sps-helper MCP server to create deviation requests for issues 59200 and 59169 in component saml sprint 158

VS Code Copilot Chat / Cline:

/bob-sps-helper:create-deviations

Then provide the issue numbers, component, and sprint.

Result: JIRA deviation requests created and linked back to GitHub issues.

Example 3: Check Component Health

IBM Bob:

Use the bob-sps-helper MCP server to check the security health of notification component

VS Code Copilot Chat / Cline:

/bob-sps-helper:component-health

Then provide: component = "notification"

Result: Health report with severity breakdown, sprint readiness score, and recommendations.

Component Mapping

The server uses a user-local configuration file to map component names to GitHub repositories. This file is automatically created at ~/.bob-sps-helper/component-mapping.json when you first use the server.

Initial Setup

On first use, the server creates an empty configuration file. You need to add your component mappings:

Option 1: Use the manage_component_mapping tool

Use the bob-sps-helper MCP server to add component mapping for agent-bridge-svc pointing to sec-ci/agent-bridge-svc

Option 2: Edit the file directly

Edit ~/.bob-sps-helper/component-mapping.json:

{
  "agent-bridge-svc": "sec-ci/agent-bridge-svc",
  "notification": "sec-ci/notification",
  "saml": "sec-ci/saml"
}

View Current Mappings

Use the bob-sps-helper MCP server to list all component mappings

Validate a Mapping

Use the bob-sps-helper MCP server to validate component mapping for agent-bridge-svc

This checks if the repository exists and is accessible.

Update or Delete Mappings

Use the bob-sps-helper MCP server to update component mapping for saml to point to sec-ci/saml-new

Use the bob-sps-helper MCP server to delete component mapping for old-component

Note: Changes take effect immediately - no need to restart VS Code.

Enhanced Deviation Request Tool

The create_deviation_request tool has been significantly enhanced to match and exceed the capabilities of the bash script (deviation-request.sh). It now provides comprehensive deviation request management with intelligent validation, label management, and dry-run capabilities.

Key Features

1. 🔍 Search Before Create - Automatically searches for existing JIRA tickets to avoid duplicates
2. 🏷️ Comprehensive Label Management - Intelligently manages all assess labels, sprint labels, and exempt flags
3. 📋 Custom Fields Support - Sets vulnerability ID, application URL, and type model fields in JIRA
4. 🛡️ Epic/CI Story Validation - Ensures PMO has completed CI Story before allowing deviations
5. 📅 Milestone Validation - Enforces sprint rules for medium/low severity issues
6. 🔄 Sprint Auto-Calculation - Automatically calculates current sprint if not provided
7. 👁️ Dry-Run Mode - Preview all changes before executing
8. 🔄 Update Existing Tickets - Updates existing JIRA tickets instead of creating duplicates
9. 📊 Detailed Reporting - Comprehensive output with success, warnings, errors, and skipped items

Basic Usage

Simplest form - auto-calculates sprint, uses defaults:

Use the bob-sps-helper MCP server to create deviation requests for issues 59200, 59169 in component saml

With dry-run - preview changes without executing:

Use the bob-sps-helper MCP server to create deviation requests for issue 59200 in component saml with dry run enabled

False positive deviation:

Use the bob-sps-helper MCP server to create false positive deviation for issue 59200 in component saml

Parameters

Required:

• issue_numbers - GitHub issue numbers to process (e.g., [59200, 59169])
• component - Component name (e.g., "saml", "workflow")

Optional:

• sprint - Sprint number (default: auto-calculated from current date)
• deviation_type - Type: "assess:false-positive" or "assess:resolution-not-avail" (default)
• auto_label - Automatically manage GitHub labels (default: true)
• validate_epic - Check if CI Story is Done in epic VDEV-185839 (default: true)
• validate_milestone - Validate milestone for medium/low severity (default: true)
• update_existing - Update existing JIRA ticket if found (default: true)
• dry_run - Preview changes without executing (default: false)

Deviation Types

assess:resolution-not-avail (Default)

• Use when no fix is available from the vendor
• Issue is in base image/OS (outside your control)
• Fix requires significant architectural changes

Labels Added: isv-deviate, assess:resolution-not-avail, assess-sprint:XXX

assess:false-positive

• Use when vulnerability doesn't apply to your use case
• Issue is incorrectly flagged by the scanner
• Configuration prevents exploitation

Labels Added: isv-deviate, assess:false-positive, assess-sprint:XXX, exempt

Label Management

The tool intelligently manages GitHub labels:

Labels Added:

• isv-deviate - Marks issue as having a deviation request
• assess-sprint:XXX - Tracks which sprint the deviation was created
• assess:false-positive OR assess:resolution-not-avail - Deviation type
• exempt - Added only for false positives

Labels Removed:

• Old assess-sprint:* labels (keeps only current sprint)
• Conflicting assess:* labels (keeps only selected type)
• exempt label (removed if not false positive)

Validation Rules

Epic/CI Story Validation:

• Checks if component has a "Done" Story under epic VDEV-185839
• Prevents deviation creation before PMO setup is complete
• To bypass: Set validate_epic: false (not recommended)

Milestone Validation:

• For critical/high severity: Always allowed ✅
• For medium/low severity: Milestone must be ≤ current sprint
• Prevents deviating future sprint issues
• To bypass: Set validate_milestone: false (not recommended)

Sprint Auto-Calculation

If you don't provide a sprint number, it's automatically calculated:

• Base Sprint: 150 (ended 2025-05-28)
• Sprint Length: 21 days
• Current Sprint = Base + (days since base end / 21)

JIRA Custom Fields

The tool automatically sets these JIRA custom fields:

| Field | Custom Field ID | Description | Example | |-------|----------------|-------------|---------| | Vulnerability ID | customfield_26402 | CVE or vulnerability identifier | CVE-2024-1234 | | Application URL | customfield_24410 | Link to GitHub issue | https://github.ibm.com/... | | Type Model | customfield_14800 | Whether fix is available | "Has Fix: Y" or "" |

Best Practices

✅ Do:

1. Always use dry-run first for new components
2. Let sprint auto-calculate unless you have a specific reason
3. Keep validations enabled for safety
4. Use appropriate deviation type

❌ Don't:

1. Don't bypass validations without good reason
2. Don't disable label management unless necessary
3. Don't create deviations for unsupported tools (mend-sast, mend, detect-secrets, peer-review)

Troubleshooting

"Component Not Ready"

• Cause: CI Story not Done in epic VDEV-185839
• Solution: Contact PMO (Ady/Jess) or temporarily bypass with validate_epic: false

"Milestone validation failed"

• Cause: Medium/Low severity issue with future milestone
• Solution: Wait for the milestone sprint, change issue milestone, or bypass with validate_milestone: false

"Tool requires manual JIRA deviation"

• Cause: Tool not in supported list (twistlock, owasp-zap, owasp-zap-ui only)
• Solution: Create JIRA deviation manually

What to Expect in VS Code

MCP Output Panel

All MCP server log messages appear in VS Code's MCP output panel. Important: VS Code labels ALL MCP logs as "errors" - this is cosmetic and expected behavior.

MCP servers must write logs to stderr (stdout is reserved for the JSON-RPC protocol). If you see "✅ All checks passed" in the output, the server is working correctly regardless of the "error" labels.

How to View Logs

1. Open VS Code Output panel (View → Output)
2. Select "MCP: bob-sps-helper" from the dropdown
3. Look for the "✅ All checks passed" message

Troubleshooting

All MCP logs show as "errors"

This is normal! MCP servers write to stderr, which VS Code displays with error styling. If you see "✅ All checks passed", the server is healthy.

IBM Bob doesn't show slash commands or @server-name autocomplete

This is expected. IBM Bob doesn't yet support these features. Use the workaround:

Use the bob-sps-helper MCP server to <action>

The slash commands ARE registered and will work automatically once IBM Bob adds support.

Token not set

Check that environment variables are set:

echo $GITHUB_REPO_ACCESS_TOKEN
echo $JIRA_PAT

If empty, add them to your shell profile and reload. Then fully quit and relaunch VS Code (Cmd+Q → reopen).

401 Unauthorized

• Verify tokens are valid and not expired
• Check token scopes (GitHub needs repo, read:org)
• Ensure you're connected to IBM VPN

npx fails or uses old version

Clear npx cache:

npx clear-npx-cache

Or force latest version:

npx bob-sps-helper@latest

Token expired

Tokens expire periodically. Generate new tokens and update your shell profile, then restart VS Code.

For Contributors

If you're contributing to this MCP server, you'll want to test local changes:

Clone and Build

git clone https://github.ibm.com/himanshu-sao-ibm/bob-sps-helper
cd bob-sps-helper
npm install
npm run build

Local Testing

The project includes .vscode/mcp.json and .bob/mcp.json configs that use node dist/index.js (not npx). These override global settings only when this project is open in VS Code.

When you open this project in VS Code:

1. Your local build is used automatically
2. Changes take effect after npm run build
3. Other projects still use the published npx version

Making Changes

1. Edit source files in src/
2. Run npm run build
3. Test in IBM Bob (with this project open in VS Code)
4. Commit and push changes

Publishing a New Version

First-Time Setup

npm login

Use your npm account credentials.

Publish

Use the included publish.sh script:

# Patch version (0.0.1 → 0.0.2)
./publish.sh patch

# Minor version (0.0.1 → 0.1.0)
./publish.sh minor

# Major version (0.0.1 → 1.0.0)
./publish.sh major

# Publish without version bump
./publish.sh --no-bump

# With 2FA OTP
./publish.sh patch --otp=123456

Verify Publication

npm view bob-sps-helper version
npm view bob-sps-helper dist-tags

Common Issues

E403 with 2FA:

• Use --otp=XXXXXX flag
• Or create a Granular Access Token at npmjs.com

Semver + latest tag pitfall: If you publish version 0.0.5 after publishing 0.1.0, npm won't update the latest tag. Always publish in ascending order, or manually fix the tag:

npm dist-tag add [email protected] latest

Teammate Updates

Teammates get updates automatically via npx on each VS Code launch. No action needed on their part.

To force an immediate update:

npx clear-npx-cache

Then reload VS Code.

License

MIT