Vulnerability-Scanner-MCP-Server by surendra-bishnoi29 - MCP Server

Vulnerability Scanner MCP Server

A Model Context Protocol (MCP) server that provides on-demand vulnerability scanning capabilities for software projects. This server automatically detects project ecosystems, runs security checks, and generates comprehensive reports in HTML or PDF format.

Features

🔍 Automated Vulnerability Scanning: Detects and analyzes security vulnerabilities in your projects
🎯 Ecosystem Detection: Automatically identifies project types (Node.js, Python, etc.)
📊 Multiple Report Formats: Generate reports in HTML or PDF format
🎨 Professional Reports: Lighthouse-style HTML reports with visual metrics
🔌 MCP Compatible: Works with any MCP-compatible client (Claude Desktop, etc.)
⚡ Fast & Efficient: Optimized for quick scanning and reporting
🛡️ Secure: Input validation and error handling built-in

Installation

Prerequisites

Node.js 18+
npm or yarn

Setup

Clone or download the project

git clone <repository-url>
cd vulnerability-scanner-mcp

Install dependencies
```
npm install
```
Build the server
```
npm run build
```

Usage

As an MCP Server

With Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "vulnerability-scanner": {
      "command": "node",
      "args": ["/path/to/vulnerability-scanner-mcp/dist/server.js"],
      "env": {}
    }
  }
}

With MCP Inspector (for testing)

Install MCP Inspector:
```
npx @modelcontextprotocol/inspector
```
Configure connection:
- Transport Type: STDIO
- Command: node
- Arguments: /path/to/vulnerability-scanner-mcp/dist/server.js

Available Tools

`runFullScanAndGenerateReport`

Performs a complete vulnerability scan on a project directory.

Parameters:

projectPath (optional): Absolute path to project directory. Defaults to current working directory.
reportFormat (optional): Report format - "html" or "pdf". If omitted, returns JSON summary only.

Examples:

// Basic scan (JSON summary only)
{
  "name": "runFullScanAndGenerateReport",
  "arguments": {}
}

// Scan with HTML report
{
  "name": "runFullScanAndGenerateReport", 
  "arguments": {
    "reportFormat": "html"
  }
}

// Scan specific directory with PDF report
{
  "name": "runFullScanAndGenerateReport",
  "arguments": {
    "projectPath": "/path/to/project",
    "reportFormat": "pdf"
  }
}

Response Format:

{
  "content": [{
    "type": "text",
    "text": "{\"summary\":\"Scan complete. Found 19 vulnerabilities across 2 ecosystem(s).\",\"reportFilePath\":\"/tmp/security-report-123.html\",\"scanResults\":[...]}"
  }]
}

Development

Scripts

# Build the project
npm run build

# Start the server
npm start

# Development mode with auto-rebuild
npm run dev

# Run tests
npm test

# Run error handling tests
npm run test:errors

# Run all tests
npm run test:all

Project Structure

vulnerability-scanner-mcp/
├── src/
│   └── server.ts              # Main MCP server implementation
├── dist/                      # Built JavaScript files
├── test-mcp-server.js         # Comprehensive test suite
├── test-error-cases.js        # Error handling tests
├── manual-vulnerability-scan.js # Manual testing script
├── TESTING_GUIDE.md           # Detailed testing instructions
├── TEST_RESULTS.md            # Test results and validation
├── package.json               # Dependencies and scripts
├── tsconfig.json              # TypeScript configuration
└── tsup.config.ts             # Build configuration

Testing

The project includes comprehensive testing:

Automated Tests: Run npm test for full test suite
Manual Testing: Use MCP Inspector for interactive testing
Error Handling: Dedicated error case testing
Integration Testing: Real MCP protocol compliance testing

See for detailed testing instructions.

Report Formats

HTML Reports

Professional Lighthouse-style reports featuring:

📊 Visual vulnerability metrics with circular progress indicators
🎨 Color-coded severity levels (Critical, High, Moderate, Low)
📈 Summary statistics and risk scoring
🤖 AI-powered security analysis
📱 Responsive design for all devices

PDF Reports

Clean, printable reports with:

📄 Executive summary
📋 Detailed vulnerability listings
🏷️ Severity classifications
📊 Statistical overview

Architecture

Core Components

MCP Server: Handles protocol communication and tool registration
Vulnerability Engine: Performs actual security scanning (via core-engine)
Report Generator: Creates HTML and PDF reports
Input Validation: Zod-based parameter validation

Dependencies

@modelcontextprotocol/sdk: MCP protocol implementation
zod: Runtime type validation
pdfkit: PDF generation
core-engine: Vulnerability scanning engine

Security

✅ Input validation with Zod schemas
✅ Enum validation for report formats
✅ Path sanitization for project directories
✅ Error handling without information leakage
✅ No code injection vulnerabilities

Error Handling

The server provides robust error handling:

Invalid Parameters: Proper validation error messages
Missing Dependencies: Clear dependency error reporting
File System Errors: Graceful handling of permission issues
Timeout Handling: Prevents hanging operations

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass: npm run test:all
Submit a pull request

Troubleshooting

Common Issues

Server won't start:

Ensure Node.js 18+ is installed
Run npm run build first
Check for port conflicts

Tool not found in MCP client:

Verify server path in MCP configuration
Check server logs for initialization errors
Ensure proper MCP protocol version

Scan failures:

Verify project directory exists and is readable
Check for required ecosystem files (package.json, requirements.txt, etc.)
Review server logs for detailed error messages

Debug Mode

Enable debug logging:

DEBUG=* npm start

License

ISC License

Support

For issues and questions:

Check the for testing procedures
Review for expected behavior
Enable debug logging for detailed error information
Create an issue with reproduction steps

Status: ✅ Production Ready - All tests passing, MCP protocol compliant