Metadata-Version: 2.4
Name: iflow-mcp_firetix_mcp-simple-tool
Version: 0.1.0
Summary: A simple MCP server exposing a website fetching tool
Author: Anthropic, PBC.
Maintainer-email: David Soria Parra <davidsp@anthropic.com>, Justin Spahr-Summers <justin@anthropic.com>
License: MIT
License-File: LICENSE
Keywords: automation,fetch,llm,mcp,web
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.10
Requires-Dist: anyio>=4.5
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27
Requires-Dist: mcp
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: h11>=0.16.0; extra == 'dev'
Requires-Dist: pyright>=1.1.378; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.5; extra == 'dev'
Requires-Dist: pytest>=8.3.3; extra == 'dev'
Requires-Dist: ruff>=0.6.9; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="logo.png" alt="Vibe tester Logo" width="270"/>
</p>


# MCP Vulnerability Checker Server

A modular Model Context Protocol (MCP) server providing comprehensive security vulnerability intelligence tools including CVE lookup, EPSS scoring, CVSS calculation, exploit detection, and Python package vulnerability checking.


## Demo

<p align="center">
  <img src="demo.gif" alt="demo"/>
</p>

## 🔗 Using the Hosted Server

The vulnerability intelligence MCP server is already hosted and ready to use! Simply configure your MCP client to connect to it.

### Claude Desktop Configuration

Add this configuration to your Claude Desktop settings file (`~/.config/claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "vulnerability-intelligence": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "FETCH_URL": "https://vulnerability-intelligence-mcp-server-edb8b15494e8.herokuapp.com/sse"
      }
    }
  }
}
```

### Cursor IDE Configuration

Add this configuration to your Cursor MCP settings file (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "vulnerability-intelligence": {
      "url": "https://vulnerability-intelligence-mcp-server-edb8b15494e8.herokuapp.com/sse"
    }
  }
}
```

Alternatively, in Cursor IDE:
1. Open Cursor Settings → Features → MCP Servers
2. Click "Add New Server"
3. Select "Server-Sent Events (SSE)" as the type
4. Enter URL: `https://vulnerability-intelligence-mcp-server-edb8b15494e8.herokuapp.com/sse`
5. Give it a name: `vulnerability-intelligence`

### Test the Connection

Once configured, try these example queries in Claude or Cursor:

- **CVE Lookup**: "Look up CVE-2021-44228" (Log4Shell vulnerability)
- **EPSS Score**: "Get EPSS score for CVE-2021-44228"
- **Package Check**: "Check the 'requests' Python package for vulnerabilities"
- **Exploit Check**: "Check for exploits for CVE-2021-44228"
- **CVSS Calculator**: "Calculate CVSS score for vector CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"

## 🛡️ Available Security Tools

### 🔍 CVE Vulnerability Lookup (`cve_lookup`)
- **Purpose**: Fetches detailed vulnerability information from the National Vulnerability Database (NVD)
- **Data Source**: NIST National Vulnerability Database API 2.0
- **Usage**: `cve_lookup cve_id="CVE-2021-44228"`
- **Features**:
  - CVSS scores (v2.0, v3.0, v3.1) with severity ratings
  - Comprehensive vulnerability descriptions
  - References, advisories, and remediation links
  - CWE (Common Weakness Enumeration) mappings
  - Publication and modification timeline
  - Affected product configurations

### 📊 EPSS Score Lookup (`get_epss_score`)
- **Purpose**: Get Exploit Prediction Scoring System (EPSS) scores for CVEs
- **Data Source**: FIRST EPSS API
- **Usage**: `get_epss_score cve_id="CVE-2021-44228"`
- **Features**:
  - Probability of exploitation within 30 days
  - AI-powered risk prioritization
  - Real-time threat intelligence integration
  - Percentile rankings for relative risk assessment

### 🧮 CVSS Score Calculator (`calculate_cvss_score`)
- **Purpose**: Calculate CVSS base scores from vector strings
- **Data Source**: CVSS v3.0/v3.1 specification
- **Usage**: `calculate_cvss_score vector="CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"`
- **Features**:
  - Support for CVSS v3.0 and v3.1
  - Detailed metric breakdown
  - Severity level mapping (Critical, High, Medium, Low)
  - Vector string validation and parsing

### 🔎 Vulnerability Search (`search_vulnerabilities`)
- **Purpose**: Search vulnerability databases with advanced filtering
- **Data Source**: Multiple vulnerability databases (NVD, CVE)
- **Usage**: `search_vulnerabilities keywords="apache" severity="HIGH" date_range="1y"`
- **Features**:
  - Keyword-based search across vulnerability descriptions
  - Severity filtering (CRITICAL, HIGH, MEDIUM, LOW)
  - Date range filtering (30d, 90d, 1y, 2y, or custom)
  - Advanced query capabilities for threat research

### 🎯 Exploit Availability Check (`get_exploit_availability`)
- **Purpose**: Check for public exploits and proof-of-concepts (PoCs)
- **Data Source**: ExploitDB, Metasploit, GitHub, security advisories
- **Usage**: `get_exploit_availability cve_id="CVE-2021-44228"`
- **Features**:
  - Multi-source exploit detection
  - Active exploitation indicators
  - PoC code availability assessment
  - Threat intelligence aggregation

### ⏰ Vulnerability Timeline (`get_vulnerability_timeline`)
- **Purpose**: Get comprehensive timeline and patch status information
- **Data Source**: NVD, vendor advisories, security bulletins
- **Usage**: `get_vulnerability_timeline cve_id="CVE-2021-44228"`
- **Features**:
  - Publication and disclosure timeline
  - Patch availability status
  - Vendor advisory tracking
  - Remediation guidance timeline

### 🎯 VEX Status Check (`get_vex_status`)
- **Purpose**: Check Vulnerability Exploitability eXchange (VEX) status for specific products
- **Data Source**: Vendor VEX statements and product security advisories
- **Usage**: `get_vex_status cve_id="CVE-2021-44228" product="Apache HTTP Server"`
- **Features**:
  - Product-specific impact assessment
  - Vendor-provided exploitability statements
  - False positive filtering
  - Supply chain impact analysis

### 📦 Python Package Vulnerability Check (`package_vulnerability_check`)
- **Purpose**: Checks Python packages for known security vulnerabilities
- **Data Source**: OSV (Open Source Vulnerabilities) Database + PyPI
- **Usage**: `package_vulnerability_check package_name="requests" version="2.25.1"`
- **Features**:
  - Comprehensive vulnerability scanning for PyPI packages
  - Version-specific or all-versions checking
  - Detailed vulnerability reports with severity scores
  - Affected version ranges and fix information
  - Integration with CVE, GHSA, and PYSEC databases
  - Package metadata from PyPI

## 🏗️ Modular Architecture

The server is built with a clean, modular architecture:

```
mcp_simple_tool/
├── server.py                    # Main MCP server orchestration
└── tools/                       # Individual tool modules
    ├── cve_lookup.py            # CVE vulnerability lookup
    ├── epss_lookup.py           # EPSS score lookup
    ├── cvss_calculator.py       # CVSS score calculator
    ├── vulnerability_search.py  # Advanced vulnerability search
    ├── exploit_availability.py  # Exploit and PoC detection
    ├── vulnerability_timeline.py # Timeline and patch status
    ├── vex_status.py            # VEX status checking
    └── package_vulnerability.py # Python package security check

tests/                           # Comprehensive test suite
├── run_tests.py                 # Automated test runner
└── test_*.py                    # Individual tool tests
```

## 🔧 Alternative Setup Methods

### Docker Setup (Recommended for Local Development)

1. Initial setup:
```bash
# Clone the repository
git clone https://github.com/firetix/vulnerability-intelligence-mcp-server
cd vulnerability-intelligence-mcp-server

# Create environment file
cp .env.example .env
```

2. Build and run using Docker Compose:
```bash
# Build and start the server
docker compose up --build -d

# View logs
docker compose logs -f

# Check server status
docker compose ps

# Stop the server
docker compose down
```

3. The server will be available at: http://localhost:8000/sse

4. Connect to Cursor IDE:
   - Open Cursor Settings → Features
   - Add new MCP server
   - Type: Select "sse"
   - URL: Enter `http://localhost:8000/sse`

### Local Development Setup

1. Install the uv package manager:
```bash
# Install uv on macOS
brew install uv
# Or install via pip (any OS)
pip install uv
```

2. Install dependencies and run:
```bash
# Install the package with development dependencies
uv pip install -e ".[dev]"

# Using stdio transport (default)
uv run mcp-simple-tool

# Using SSE transport on custom port
uv run mcp-simple-tool --transport sse --port 8000

# Run the comprehensive test suite
python tests/run_tests.py
```

3. For Cursor IDE integration (stdio mode):
   - Copy the absolute path to `cursor-run-mcp-server.sh`
   - Open Cursor Settings → Features → MCP Servers
   - Add new server with "stdio" type and the script path

## 🧪 Testing the Tools

Run the comprehensive test suite:

```bash
# Run all tests
python tests/run_tests.py

# Run individual tool tests
python tests/test_cve_lookup.py
python tests/test_package_vulnerability.py  
python tests/test_modular_server.py
```

### Example Test Outputs

**CVE Lookup Test:**
```bash
🔍 **CVE Vulnerability Report: CVE-2021-44228**

📅 **Timeline:**
   • Published: 2021-12-10T10:15:09.143
   • Last Modified: 2023-11-07T04:10:58.217

⚠️ **CVSS Scores:**
   • CVSS 3.1: 10.0 (CRITICAL)
```

**Package Vulnerability Test:**
```bash
🚨 **Python Package Security Report: requests**

⚠️ **Found 11 known vulnerabilities**

📦 **Package Information:**
   • Latest Version: 2.32.3
   • Summary: Python HTTP for Humans.
```

## 🌍 Environment Variables

Available environment variables (can be set in `.env`):

- `MCP_SERVER_PORT` (default: 8000) - Port to run the server on
- `MCP_SERVER_HOST` (default: 0.0.0.0) - Host to bind the server to
- `DEBUG` (default: false) - Enable debug mode
- `MCP_USER_AGENT` - Custom User-Agent for HTTP requests

## 🚀 Deploy Your Own Instance

If you want to deploy your own instance of the vulnerability intelligence server, you can use Heroku for quick deployment:

### Quick Deploy to Heroku

1. Click "Deploy to Heroku" button

   [![Deploy to Heroku](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/firetix/vulnerability-intelligence-mcp-server)

2. After deployment, your instance will be available at:
   - `https://<your-app-name>.herokuapp.com/sse`

3. Configure your MCP client to use your deployed instance:
   - For Claude Desktop: Update the `FETCH_URL` in your configuration
   - For Cursor IDE: Update the URL in your MCP settings

4. Test your deployment with the same example queries:
   - **CVE Lookup**: "Look up CVE-2021-44228"
   - **EPSS Score**: "Get EPSS score for CVE-2021-44228"
   - **Package Check**: "Check the 'requests' Python package for vulnerabilities"
   - **Exploit Check**: "Check for exploits for CVE-2021-44228"

## 📊 Data Sources & APIs

- **CVE Data**: [NIST National Vulnerability Database](https://nvd.nist.gov/) (NVD API 2.0)
- **EPSS Scores**: [FIRST EPSS API](https://www.first.org/epss/) (Exploit Prediction Scoring System)
- **CVSS Calculations**: CVSS v3.0/v3.1 specification compliance
- **Vulnerability Search**: Multiple CVE and vulnerability databases
- **Exploit Intelligence**: ExploitDB, Metasploit, GitHub security advisories
- **Package Vulnerabilities**: [OSV (Open Source Vulnerabilities)](https://osv.dev/)
- **Package Metadata**: [PyPI (Python Package Index)](https://pypi.org/)
- **VEX Data**: Vendor VEX statements and product security advisories

## 🤝 Security Use Cases

This MCP server is designed for security engineers, developers, and teams who need:

### Vulnerability Research & Intelligence
- Quick CVE lookups with comprehensive details
- CVSS and EPSS scoring for accurate risk assessment
- Advanced vulnerability search across multiple databases
- Exploit availability and threat intelligence gathering
- Timeline analysis for understanding vulnerability lifecycle

### Risk Assessment & Prioritization
- EPSS-based exploitation probability scoring
- CVSS vector calculation and validation
- VEX status checking for product-specific impact
- Multi-factor risk analysis combining multiple data sources

### Dependency Management
- Python package security auditing
- Version-specific vulnerability checking
- Supply chain security assessment
- Open source component risk evaluation

### Security Operations & Incident Response
- Rapid vulnerability triage and classification
- Exploit availability assessment for threat modeling
- Security advisory research and correlation
- Timeline-based patch management planning

## 🔄 Extending the Server

The modular architecture makes it easy to add new security tools:

1. Create a new module in `mcp_simple_tool/tools/`
2. Export the function in `tools/__init__.py`
3. Register the tool in `server.py`
4. Add tests in `tests/`

See [README_MODULAR.md](README_MODULAR.md) for detailed extension guide.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

