Skip to content

AIML-83: Improve README documentation structure #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

AIML-83: Improve README documentation structure #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4a8902e
Improve README: feature VS Code one-click install prominently
ChrisEdwards Oct 7, 2025
a40d9e9
Format security warning as GitHub callout block
ChrisEdwards Oct 7, 2025
8612e35
Use input variables for VS Code install credentials
ChrisEdwards Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 36 additions & 13 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,10 @@ This is an MCP (Model Context Protocol) server for Contrast Security that enable

### Building the Project
- **Build**: `mvn clean install` or `./mvnw clean install`
- **Package without tests**: `mvn clean package -DskipTests`
- **Test**: `mvn test` or `./mvnw test`
- **Run locally**: `java -jar target/mcp-contrast-0.0.11.jar --CONTRAST_HOST_NAME=<host> --CONTRAST_API_KEY=<key> --CONTRAST_SERVICE_KEY=<key> --CONTRAST_USERNAME=<user> --CONTRAST_ORG_ID=<org>`
- **Run single test**: `mvn test -Dtest=HintGeneratorTest` or `mvn test -Dtest=HintGeneratorTest#specificTestMethod`
- **Run locally**: `java -jar target/mcp-contrast-0.0.12-SNAPSHOT.jar --CONTRAST_HOST_NAME=<host> --CONTRAST_API_KEY=<key> --CONTRAST_SERVICE_KEY=<key> --CONTRAST_USERNAME=<user> --CONTRAST_ORG_ID=<org>`

### Docker Commands
- **Build Docker image**: `docker build -t mcp-contrast .`
Expand All @@ -28,17 +30,19 @@ This is an MCP (Model Context Protocol) server for Contrast Security that enable

**Main Application**: `McpContrastApplication.java` - Spring Boot application that registers MCP tools from all service classes.

**Service Layer**: Each service handles a specific aspect of Contrast Security data:
**Service Layer**: Each service handles a specific aspect of Contrast Security data and exposes `@Tool` annotated methods:
- `AssessService` - Vulnerability analysis and trace data
- `SastService` - Static application security testing data
- `SCAService` - Software composition analysis (library vulnerabilities)
- `ADRService` - Attack detection and response events
- `RouteCoverageService` - Route coverage analysis
- `PromptService` - AI prompt management

**SDK Extensions**: Located in `sdkexstension/` package, these extend the Contrast SDK with enhanced data models and helper methods for better AI integration.
**SDK Extensions**: Located in `sdkexstension/` package:
- `SDKExtension.java` - Extends Contrast SDK API with additional endpoints not in standard SDK (library observations, route details, session metadata, etc.)
- `SDKHelper.java` - Utility methods for hostname protocol handling and common operations
- `data/` subpackages - Enhanced data models with AI-friendly representations organized by domain (application, adr, routecoverage, sca, traces, sessionmetadata)

**Data Models**: Comprehensive POJOs in `data/` package representing vulnerability information, library data, applications, and attack events.
**Data Models**: Comprehensive POJOs in `data/` package representing vulnerability information, library data, applications, and attack events used by service layer.

**Hint System**: `hints/` package provides context-aware security guidance for vulnerability remediation.

Expand All @@ -58,19 +62,24 @@ Required environment variables/arguments:

### Technology Stack

- **Framework**: Spring Boot 3.4.5 with Spring AI 1.0.0-RC1
- **Framework**: Spring Boot 3.4.5 with Spring AI 1.0.1
- **MCP Integration**: Spring AI MCP Server starter
- **Contrast Integration**: Contrast SDK Java 3.4.2
- **Testing**: JUnit 5
- **Build Tool**: Maven with wrapper
- **JSON Processing**: Gson (via Contrast SDK)
- **Testing**: JUnit 5 with Spring Boot Test
- **Build Tool**: Maven 3.6+ with wrapper
- **Packaging**: Executable JAR and Docker container

### Development Patterns

1. **MCP Tools**: Services expose methods via `@Tool` annotation for AI agent consumption
2. **SDK Extension Pattern**: Enhanced data models extend base SDK classes with AI-friendly representations
3. **Hint Generation**: Rule-based system provides contextual security guidance
4. **Defensive Design**: All external API calls include error handling and logging
1. **MCP Tools**: Services expose methods via `@Tool` annotation for AI agent consumption. Register new services in `McpContrastApplication.tools()` bean.
2. **SDK Extension Pattern**:
- Use `SDKExtension` to add new Contrast API endpoints not in the standard SDK
- Use `SDKHelper` for common utility operations (hostname handling, etc.)
- Enhanced data models in `sdkexstension/data/` provide AI-friendly JSON representations
3. **Hint Generation**: Rule-based system in `hints/` package provides contextual security guidance for vulnerability remediation
4. **Defensive Design**: All external API calls include proper resource management (try-with-resources), error handling, and logging
5. **Pagination Handling**: SDK extension methods handle pagination automatically (see `getLibraryObservations` for pattern)

### Security Considerations

Expand All @@ -80,4 +89,18 @@ This codebase handles sensitive vulnerability data. The README contains critical

- Default log location: `/tmp/mcp-contrast.log`
- Debug logging: Add `--logging.level.root=DEBUG` to startup arguments
- Console logging is minimal by design for MCP protocol compatibility
- Console logging is minimal by design for MCP protocol compatibility
- Debug mode buffers API responses for logging (memory impact with large datasets)

### Troubleshooting

For common issues (SSL certificates, proxy configuration, debug logging), see the "Common Issues" and "Proxy Configuration" sections in [README.md](README.md).

### Adding New MCP Tools

To add a new tool/service:
1. Create a new `@Service` class with methods annotated with `@Tool(description="...")`
2. Inject dependencies (ContrastSDK, SDKExtension) via constructor
3. Register the service in `McpContrastApplication.tools()` bean method
4. Use `SDKExtension` to add new API endpoints if needed
5. Create enhanced data models in appropriate `sdkexstension/data/` subpackage
88 changes: 56 additions & 32 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,67 @@
# Contrast MCP Server

⚠️ CRITICAL SECURITY WARNING: EXPOSING YOUR CONTRAST VULNERABILITY DATA TO A LLM THAT TRAINS ON YOUR DATA CAN POTENTIALLY EXPOSE YOUR VULNERABILITY DATA TO THE OUTSIDE WORLD. Thus, do not use mcp-contrast functions which pull sensitive data with a LLM that trains on your data.
[![Java CI with Maven](https://github.com/Contrast-Labs/mcp-contrast/actions/workflows/build.yml/badge.svg)](https://github.com/Contrast-Labs/mcp-contrast/actions/workflows/build.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

Verify AI Data Privacy: Before sending vulnerability data to an AI, you must confirm that your service agreement guarantees your data will not be used for model training.

UNSAFE: Public consumer websites (e.g., the free versions of ChatGPT, Gemini, Claude). These services often use your input for training.
The Contrast MCP Server allow you to connect Contrast Security to your AI coding agent to automatically remediate vulnerabilities, update insecure libraries, and analyze security coverage—all through natural language prompts.

POTENTIALLY-SAFE: Enterprise-grade services (e.g. Google Cloud AI, AWS Bedrock, Azure OpenAI) or paid plans that contractually ensure data privacy and prevent model training on your prompts, verify with your information security teams.

<br/><br/>
![output.gif](images/output.gif)

[![Java CI with Maven](https://github.com/Contrast-Labs/mcp-contrast/actions/workflows/build.yml/badge.svg)](https://github.com/Contrast-Labs/mcp-contrast/actions/workflows/build.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Maven Central](https://img.shields.io/maven-central/v/com.contrast.labs/mcp-contrast.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.contrast.labs%22%20AND%20a:%22mcp-contrast%22)
[![Install in VS Code Docker](https://img.shields.io/badge/VS_Code-docker-0098FF?style=flat-square&logo=githubcopilot&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=contrastmcp&config=%7B%22command%22:%22docker%22,%22args%22:%5B%22run%22,%20%22-e%22,%22CONTRAST_HOST_NAME%22,%20%22-e%22,%22CONTRAST_API_KEY%22,%20%22-e%22,%22CONTRAST_SERVICE_KEY%22,%20%22-e%22,%22CONTRAST_USERNAME%22,%20%22-e%22,%22CONTRAST_ORG_ID%22,%20%20%22-i%22,%20%22--rm%22,%20%22contrast/mcp-contrast:latest%22,%20%22-t%22,%20%22stdio%22%5D,%22env%22:%7B%22CONTRAST_HOST_NAME%22:%22example.contrastsecurity.com%22,%22CONTRAST_API_KEY%22:%22example%22,%22CONTRAST_SERVICE_KEY%22:%22example%22,%22CONTRAST_USERNAME%22:%[email protected]%22,%22CONTRAST_ORG_ID%22:%22example%22%7D%7D)
## Quick Install

Contrast's MCP server allows you as a developer or security professional to quickly remediate vulnerabilities found by Contrast products. By combining the abilities of a LLM and Coding Agent of your choice and Contrast's unique vulnerability data it is possible to easily remediate vulnerabilities in your code or 3rd party libraries.
![output.gif](images/output.gif)
**VS Code (One-Click Install):**

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_contrast--mcp-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=ffffff)](vscode:mcp/install?%7B%22name%22%3A%22contrast-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-e%22%2C%22CONTRAST_HOST_NAME%22%2C%22-e%22%2C%22CONTRAST_API_KEY%22%2C%22-e%22%2C%22CONTRAST_SERVICE_KEY%22%2C%22-e%22%2C%22CONTRAST_USERNAME%22%2C%22-e%22%2C%22CONTRAST_ORG_ID%22%2C%22-i%22%2C%22--rm%22%2C%22contrast%2Fmcp-contrast%3Alatest%22%2C%22-t%22%2C%22stdio%22%5D%2C%22env%22%3A%7B%22CONTRAST_HOST_NAME%22%3A%22%24%7Binput%3Acontrast_host_name%7D%22%2C%22CONTRAST_ORG_ID%22%3A%22%24%7Binput%3Acontrast_org_id%7D%22%2C%22CONTRAST_USERNAME%22%3A%22%24%7Binput%3Acontrast_username%7D%22%2C%22CONTRAST_API_KEY%22%3A%22%24%7Binput%3Acontrast_api_key%7D%22%2C%22CONTRAST_SERVICE_KEY%22%3A%22%24%7Binput%3Acontrast_service_key%7D%22%7D%7D)

**Other Clients:** See [Installation Guide](#docker) below

---

> [!WARNING]
> **CRITICAL SECURITY WARNING:**
> EXPOSING YOUR CONTRAST VULNERABILITY DATA TO A LLM THAT TRAINS ON YOUR DATA CAN POTENTIALLY EXPOSE YOUR VULNERABILITY DATA TO THE OUTSIDE WORLD.
> Thus, do not use mcp-contrast functions which pull sensitive data with a LLM that trains on your data.
>
> **Verify AI Data Privacy:** Before sending vulnerability data to an AI, you must confirm that your service agreement guarantees your data will not be used for model training.
>
> **UNSAFE:** Public consumer websites (e.g., the free versions of ChatGPT, Gemini, Claude). These services often use your input for training.
>
> **POTENTIALLY-SAFE:** Enterprise-grade services (e.g. Google Cloud AI, AWS Bedrock, Azure OpenAI) or paid plans that contractually ensure data privacy and prevent model training on your prompts, verify with your information security teams.

---

## Table of Contents
- [Sample Prompts](#sample-prompts)
- [For the Developer](#for-the-developer)
- [Remediate Vulnerability in code](#remediate-vulnerability-in-code)
- [3rd Party Library Remediation](#3rd-party-library-remediation)
- [For the Security Professional](#for-the-security-professional)
- [Data Privacy](#data-privacy)
- [Build](#build)
- [Run](#run)
- [Docker](#docker)
- [Build Docker Image](#build-docker-image)
- [Run with Docker](#run-with-docker)
- [Using Copilot + Petclinic](#using-copilot--petclinic)
- [Install via Link](#install-via-link)
- [Manual Install of MCP Server](#manual-install-of-mcp-server)
- [Using Cline Plugin](#using-cline-plugin)
- [Using oterm](#using-oterm)
- [Proxy Configuration](#proxy-configuration)
- [Java Process](#java-process)
- [Docker](#docker-1)
- [Contrast MCP Server](#contrast-mcp-server)
- [Quick Install](#quick-install)
- [Table of Contents](#table-of-contents)
- [Sample Prompts](#sample-prompts)
- [For the Developer](#for-the-developer)
- [Remediate Vulnerability in code](#remediate-vulnerability-in-code)
- [3rd Party Library Remediation](#3rd-party-library-remediation)
- [Retrieving application based on Tags](#retrieving-application-based-on-tags)
- [Retrieving application based on Metadata](#retrieving-application-based-on-metadata)
- [Retrieving vulnerabilities based on Session Metadata](#retrieving-vulnerabilities-based-on-session-metadata)
- [For the Security Professional](#for-the-security-professional)
- [Data Privacy](#data-privacy)
- [Build](#build)
- [Run](#run)
- [Docker](#docker)
- [Build Docker Image](#build-docker-image)
- [Using Copilot + Petclinic](#using-copilot--petclinic)
- [Install via Link in VScode](#install-via-link-in-vscode)
- [Manual Install of MCP Server](#manual-install-of-mcp-server)
- [Install in Intellij](#install-in-intellij)
- [Using Cline Plugin](#using-cline-plugin)
- [Using Claude Desktop](#using-claude-desktop)
- [Using oterm](#using-oterm)
- [Proxy Configuration](#proxy-configuration)
- [Java Process](#java-process)
- [Docker](#docker-1)
- [Common Issues](#common-issues)
- [Review Log](#review-log)
- [Enable Debug Logging](#enable-debug-logging)
- [Certificate Issues](#certificate-issues)

## Sample Prompts
### For the Developer
Expand Down Expand Up @@ -132,7 +156,7 @@ To build out the vulnerabilites and attack events run
`./testscript.sh`
Select option 25. ( this will exercise the app and perform attacks to populate the vulnerabilities and attack events)
#### Install via Link in VScode
Click following link >>> [![Install in VS Code Docker](https://img.shields.io/badge/VS_Code-docker-0098FF?style=flat-square&logo=githubcopilot&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=contrastmcp&config=%7B%22command%22:%22docker%22,%22args%22:%5B%22run%22,%20%22-e%22,%22CONTRAST_HOST_NAME%22,%20%22-e%22,%22CONTRAST_API_KEY%22,%20%22-e%22,%22CONTRAST_SERVICE_KEY%22,%20%22-e%22,%22CONTRAST_USERNAME%22,%20%22-e%22,%22CONTRAST_ORG_ID%22,%20%20%22-i%22,%20%22--rm%22,%20%22contrast/mcp-contrast:latest%22,%20%22-t%22,%20%22stdio%22%5D,%22env%22:%7B%22CONTRAST_HOST_NAME%22:%22example.contrastsecurity.com%22,%22CONTRAST_API_KEY%22:%22example%22,%22CONTRAST_SERVICE_KEY%22:%22example%22,%22CONTRAST_USERNAME%22:%[email protected]%22,%22CONTRAST_ORG_ID%22:%22example%22%7D%7D) <<<
Click following link >>> [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_contrast--mcp-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=ffffff)](vscode:mcp/install?%7B%22name%22%3A%22contrast-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-e%22%2C%22CONTRAST_HOST_NAME%22%2C%22-e%22%2C%22CONTRAST_API_KEY%22%2C%22-e%22%2C%22CONTRAST_SERVICE_KEY%22%2C%22-e%22%2C%22CONTRAST_USERNAME%22%2C%22-e%22%2C%22CONTRAST_ORG_ID%22%2C%22-i%22%2C%22--rm%22%2C%22contrast%2Fmcp-contrast%3Alatest%22%2C%22-t%22%2C%22stdio%22%5D%2C%22env%22%3A%7B%22CONTRAST_HOST_NAME%22%3A%22%24%7Binput%3Acontrast_host_name%7D%22%2C%22CONTRAST_ORG_ID%22%3A%22%24%7Binput%3Acontrast_org_id%7D%22%2C%22CONTRAST_USERNAME%22%3A%22%24%7Binput%3Acontrast_username%7D%22%2C%22CONTRAST_API_KEY%22%3A%22%24%7Binput%3Acontrast_api_key%7D%22%2C%22CONTRAST_SERVICE_KEY%22%3A%22%24%7Binput%3Acontrast_service_key%7D%22%7D%7D) <<<
Allow the extension to be installed in your VSCode instance.
Select Install Server

Expand Down