iflow-mcp_haroldfinchift-vuln-nist-mcp-server 1.1.0__py3-none-any.whl

iflow_mcp_haroldfinchift_vuln_nist_mcp_server-1.1.0.dist-info/METADATA

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_haroldfinchift-vuln-nist-mcp-server
+Version: 1.1.0
+Summary: A Model Context Protocol (MCP) server for querying NIST National Vulnerability Database (NVD) API endpoints
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: httpx>=0.24.0
+Dynamic: license-file
+
+# vuln-nist-mcp-server
+
+A Model Context Protocol (MCP) server for querying NIST National Vulnerability Database (NVD) API endpoints.
+
+## Purpose
+
+This MCP server exposes tools to query the NVD/CVE REST API and return formatted text results suitable for LLM consumption via the MCP protocol. It includes automatic query chunking for large date ranges and parallel processing for improved performance.
+
+Base API docs: https://nvd.nist.gov/developers/vulnerabilities
+
+## Features
+
+### Available Tools
+
+- **`get_temporal_context`** - Get current date and temporal context for time-relative queries
+  - Essential for queries like "this year", "last year", "6 months ago"
+  - Provides current date mappings and examples for date parameter construction
+  - **USAGE**: Call this tool FIRST when user asks time-relative questions
+
+- **`search_cves`** - Search CVE descriptions by keyword with flexible date filtering
+  - Parameters: `keyword`, `resultsPerPage` (default: 20), `startIndex` (default: 0), `last_days` (`recent_days` has been deprecated), `start_date`, `end_date`
+  - **New in v1.1.0**: Support for absolute date ranges with `start_date` and `end_date` parameters
+  - **Date filtering priority**: `start_date`/`end_date` → `last_days` → default 30 days
+  - Auto-chunks queries > 120 days into parallel requests
+  - Results sorted by publication date (newest first)
+
+- **`get_cve_by_id`** - Retrieve detailed information for a specific CVE
+  - Parameters: `cve_id`
+  - Returns: CVE details, references, tags, and publication dates
+
+- **`cves_by_cpe`** - List CVEs associated with a Common Platform Enumeration (CPE)
+  - Parameters: `cpe_name` (full CPE 2.3 format required), `is_vulnerable` (optional)
+  - Validates CPE format before querying
+
+- **`kevs_between`** - Find CVEs added to CISA KEV catalog within a date range
+  - Parameters: `kevStartDate`, `kevEndDate`, `resultsPerPage` (default: 20), `startIndex` (default: 0)
+  - Auto-chunks queries > 90 days into parallel requests
+  - Results sorted by publication date (newest first)
+
+- **`cve_change_history`** - Retrieve change history for CVEs
+  - Parameters: `cve_id` OR (`changeStartDate` + `changeEndDate`), `resultsPerPage` (default: 20), `startIndex` (default: 0)
+  - Auto-chunks date range queries > 120 days into parallel requests
+  - Results sorted by change creation date (newest first)
+
+### Key Features
+
+- **Temporal Awareness**: New `get_temporal_context` tool for accurate time-relative queries
+- **Flexible Date Filtering**: Support for both relative (`last_days`) and absolute (`start_date`/`end_date`) date ranges
+- **Improved Result Ordering**: All results sorted chronologically (newest first) for better relevance
+- **Parallel Processing**: Large date ranges are automatically split into chunks and processed concurrently
+- **Input Validation**: CPE format validation, date parsing, parameter sanitization
+- **Emoji Indicators**: Clear visual feedback (✅ success, ❌ error, ⚠️ warning, 🔍 search, 🔥 KEV, 🌐 CPE, 🕘 history, 📅 temporal)
+- **Comprehensive Logging**: Detailed stderr logging for debugging
+- **Error Handling**: Graceful handling of API errors, timeouts, and malformed responses
+
+## Prerequisites
+
+- Docker (recommended) or Python 3.11+
+- Network access to NVD endpoints (`services.nvd.nist.gov`)
+- MCP-compatible client (e.g., Claude Desktop)
+
+## Quick Start
+
+### Using Docker (Recommended)
+
+```bash
+# Clone and build
+git clone https://github.com/HaroldFinchIFT/vuln-nist-mcp-server
+cd vuln-nist-mcp-server
+docker build -t vuln-nist-mcp-server .
+
+# Run
+docker run --rm -it vuln-nist-mcp-server
+```
+
+## Configuration
+
+Environment variables:
+
+- `NVD_BASE_URL`: Base URL for NVD API (default: `https://services.nvd.nist.gov/rest/json`)
+- `NVD_VERSION`: API version (default: `/2.0`)
+- `NVD_API_TIMEOUT`: Request timeout in seconds (default: `10`)
+
+## Usage Examples
+
+### With Claude Desktop or MCP Client
+
+**Get temporal context for time-relative queries:**
+```
+Tool: get_temporal_context
+Params: {}
+```
+
+**Search recent CVEs (relative time):**
+```
+Tool: search_cves
+Params: {
+  "keyword": "Microsoft Exchange",
+  "resultsPerPage": 10,
+  "last_days": 7
+}
+```
+
+**Search CVEs with absolute date range:**
+```
+Tool: search_cves
+Params: {
+  "keyword": "buffer overflow",
+  "start_date": "2024-01-01T00:00:00",
+  "end_date": "2024-03-31T23:59:59"
+}
+```
+
+**Search CVEs for "this year" (use get_temporal_context first):**
+```
+# First, get temporal context
+Tool: get_temporal_context
+
+# Then use the provided date mappings
+Tool: search_cves
+Params: {
+  "keyword": "remote code execution",
+  "start_date": "2025-01-01T00:00:00",
+  "end_date": "2025-09-17T12:00:00"
+}
+```
+
+**Get CVE details:**
+```
+Tool: get_cve_by_id
+Params: {"cve_id": "CVE-2024-21413"}
+```
+
+**Check CPE vulnerabilities:**
+```
+Tool: cves_by_cpe
+Params: {
+  "cpe_name": "cpe:2.3:a:microsoft:exchange_server:2019:*:*:*:*:*:*:*",
+  "is_vulnerable": "true"
+}
+```
+
+**Find recent KEV additions:**
+```
+Tool: kevs_between
+Params: {
+  "kevStartDate": "2024-01-01T00:00:00.000Z",
+  "kevEndDate": "2024-03-31T23:59:59.000Z"
+}
+```
+
+## Performance Notes
+
+- Queries with date ranges > 90-120 days are automatically chunked for better performance
+- Parallel processing reduces total query time for large date ranges
+- Results are automatically sorted by publication date (newest first) across all chunks
+
+## Development
+
+### File Structure
+
+```
+vuln-nist-mcp-server/
+├── Dockerfile
+├── glama.json
+├── LICENSE
+├── nvd_logo.png
+├── README.md
+├── requirements.txt
+├── SECURITY.md 
+└── vuln_nist_mcp_server.py
+```
+
+## Security Considerations
+
+- No API key required (public NVD endpoints)
+- Container runs as non-root user (`mcpuser`)
+- Input validation prevents injection attacks
+- No persistent storage of sensitive data
+- Network capabilities added only when required via Docker flags
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test locally
+5. Submit a pull request
+
+## License
+
+MIT - see LICENSE file for details
+
+## Changelog
+
+### v1.1.0
+- **NEW**: Added `get_temporal_context` tool for temporal awareness and time-relative queries
+- **ENHANCED**: `search_cves` now supports absolute date ranges with `start_date` and `end_date` parameters
+- **ENHANCED**: Improved date filtering logic with priority: absolute dates → relative days → default 30 days
+- **ENHANCED**: All tools now return results sorted chronologically (newest first) for better relevance
+- **IMPROVED**: Better error handling for ISO-8601 date parsing
+- **DEPRECATED**: `recent_days` parameter in `search_cves` (use `last_days` instead)
+- **UPDATED**: Logo and visual improvements
+
+### v1.0.0
+- Initial release
+- Support for all major NVD API endpoints
+- Automatic query chunking and parallel processing
+- CPE format validation
+- Comprehensive error handling

iflow_mcp_haroldfinchift_vuln_nist_mcp_server-1.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+vuln_nist_mcp_server.py,sha256=D1sYCDReat88GN83Uf8QHv_adPt_R9mOHMvzOZx7pis,21497
+iflow_mcp_haroldfinchift_vuln_nist_mcp_server-1.1.0.dist-info/licenses/LICENSE,sha256=6ZzG5LeGiA5YwdZjNbAhTbQqL4xUNIZaY-dWlhHIqrQ,1066
+iflow_mcp_haroldfinchift_vuln_nist_mcp_server-1.1.0.dist-info/METADATA,sha256=ugsBAmFJm5GZP9Dcqy5Vrm1BdPhTR3052BQzuKJXob4,7256
+iflow_mcp_haroldfinchift_vuln_nist_mcp_server-1.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+iflow_mcp_haroldfinchift_vuln_nist_mcp_server-1.1.0.dist-info/entry_points.txt,sha256=m-JsAcfutWM4aUWeOlgnEQjaOw6dm3MROdkedUzGJHE,67
+iflow_mcp_haroldfinchift_vuln_nist_mcp_server-1.1.0.dist-info/top_level.txt,sha256=86AVq6DXmtpI5_84wR-watmQTlHxsBfeu10slaYBWJE,21
+iflow_mcp_haroldfinchift_vuln_nist_mcp_server-1.1.0.dist-info/RECORD,,

iflow_mcp_haroldfinchift_vuln_nist_mcp_server-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

iflow_mcp_haroldfinchift_vuln_nist_mcp_server-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vuln-nist-mcp-server = vuln_nist_mcp_server:main

iflow_mcp_haroldfinchift_vuln_nist_mcp_server-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nick Clyde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

iflow_mcp_haroldfinchift_vuln_nist_mcp_server-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vuln_nist_mcp_server

vuln_nist_mcp_server.py

@@ -0,0 +1,573 @@
+"""vuln-nist-mcp-server MCP server"""
+import asyncio
+import os
+import sys
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import cast
+import re
+
+import httpx
+import traceback
+
+from mcp.server.fastmcp import FastMCP
+
+__version__ = "1.0.0"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    stream=sys.stderr,
+)
+logger = logging.getLogger("vuln-nist-mcp-server")
+
+mcp = FastMCP("vuln-nist-mcp-server")
+
+# Configuration
+NVD_BASE = os.environ.get("NVD_BASE_URL", "https://services.nvd.nist.gov/rest/json")
+NVD_VERSION = os.environ.get("NVD_VERSION", "/2.0")
+API_TIMEOUT = int(os.environ.get("NVD_API_TIMEOUT", "10"))
+
+# Utility helpers
+def _safe_str(s):
+    """Return safe stripped string"""
+    try:
+        return "" if s is None else str(s).strip()
+    except Exception:
+        return ""
+
+def _int_or_default(s, default=20):
+    """Convert string to int or default"""
+    try:
+        return int(str(s).strip()) if str(s).strip() != "" else default
+    except Exception:
+        return default
+
+def _short_desc_from_vuln(v):
+    """Return a short description for a vuln object"""
+    try:
+        cve = v.get("cve", {})
+        descs = cve.get("descriptions", []) or []
+        for d in descs:
+            if d.get("lang") == "en" and d.get("value"):
+                txt = d.get("value")
+                return txt if len(txt) <= 240 else txt[:237] + "..."
+        if descs:
+            txt = descs[0].get("value", "")
+            return txt if len(txt) <= 240 else txt[:237] + "..."
+    except Exception:
+        pass
+    return "(no description)"
+
+def _format_vuln_entry(v):
+    """Format a single vulnerability entry for output"""
+    try:
+        cve = v.get("cve", {})
+        cve_id = cve.get("id", "UNKNOWN")
+        published = _safe_str(cve.get("published"))
+        desc = _short_desc_from_vuln(v)
+        return f"- {cve_id} | published: {published} | {desc}"
+    except Exception:
+        return "- (malformed entry)"
+
+# === MCP TOOLS ===
+
+@mcp.tool()
+async def get_temporal_context() -> str:
+    """
+    Get current date and temporal context when it needed.
+
+    **USAGE**: Call this tool FIRST when user asks for time-relative question like "this year", "last year", "6 months ago", etc.
+
+    Returns current date context and examples for constructing specific date parameters.
+    """
+    now = datetime.now(timezone.utc)
+    current_year = now.year
+    current_date = now.strftime("%Y-%m-%dT%H:%M:%S")
+
+    this_year_start = f"{current_year}-01-01T00:00:00"
+    last_year_start = f"{current_year - 1}-01-01T00:00:00"
+    last_year_end = f"{current_year - 1}-12-31T23:59:59"
+    six_months_ago = (now - timedelta(days=180)).strftime("%Y-%m-%dT00:00:00")
+    three_months_ago = (now - timedelta(days=90)).strftime("%Y-%m-%dT00:00:00")
+
+    return f"""📅 **CURRENT TEMPORAL CONTEXT**
+        
+        🗓️ **Current date**: {now.strftime('%Y-%m-%d %H:%M:%S UTC')}
+        📊 **Current year**: {current_year}
+        
+        🎯 **COMMON TIME PERIOD MAPPINGS**:
+        
+        ▪️ **"This year"**: 
+           start_date="{this_year_start}", end_date="{current_date}"
+        
+        ▪️ **"Last year"**: 
+           start_date="{last_year_start}", end_date="{last_year_end}"
+        
+        ▪️ **"Last 6 months"**: 
+           start_date="{six_months_ago}", end_date="{current_date}"
+        
+        ▪️ **"Last 3 months"**: 
+           start_date="{three_months_ago}", end_date="{current_date}"
+        
+        ▪️ **"2 years ago ({current_year - 2})"**: 
+           start_date="{current_year - 2}-01-01T00:00:00", end_date="{current_year - 2}-12-31T23:59:59"
+        
+        ▪️ **"Q1 this year"**: 
+           start_date="{current_year}-01-01T00:00:00", end_date="{current_year}-03-31T23:59:59"
+        
+        ▪️ **"Q1 last year"**: 
+           start_date="{current_year - 1}-01-01T00:00:00", end_date="{current_year - 1}-03-31T23:59:59"
+        
+        💡 **Usage**: Copy the appropriate value above and use them directly in the other tools call when it is needed.
+        """
+
+@mcp.tool()
+async def search_cves(
+        keyword: str = "",
+        resultsPerPage: int = 20,
+        startIndex: int = 0,
+        recent_days: int | None = None, #deprecated
+        last_days: int | None = None,
+        start_date: str = "",
+        end_date: str = "",
+) -> str:
+    """
+    Search CVEs by keyword in description, with flexible time filtering.
+
+    **IMPORTANT**: For time-relative queries (this year, last year, etc.), call get_temporal_context() FIRST to get current date information.
+
+    **Date filtering logic (in priority order):**
+    - If start_date and end_date are provided → use them directly
+    - Else if last_days is provided → calculate start_date = now - last_days
+    - Else fallback to last 30 days
+
+    **Technical notes:**
+    - If the time period > 120 days, queries are split into 120-day chunks
+    - start_date, end_date: Use ISO 8601 format: "YYYY-MM-DDTHH:MM:SS"
+    - recent_days parameter is deprecated, use last_days instead.
+    """
+
+    last_days = last_days if last_days is not None else recent_days
+
+    keyword = _safe_str(keyword)
+    now = datetime.now(timezone.utc)
+
+    if end_date and end_date.strip():
+        try:
+            end_date = datetime.fromisoformat(end_date.replace("Z", "+00:00"))
+        except ValueError:
+            return "❌ Error: end_date must be valid ISO-8601 format"
+    else:
+        end_date = now
+
+    if start_date and start_date.strip():
+        try:
+            start_date = datetime.fromisoformat(start_date.replace("Z", "+00:00"))
+        except ValueError:
+            return "❌ Error: start_date must be valid ISO-8601 format"
+    else:
+        if last_days is not None:
+            start_date = end_date - timedelta(days=last_days)
+        else:
+            start_date = end_date - timedelta(days=30)
+
+    url = f"{NVD_BASE}/cves{NVD_VERSION}"
+
+    async def fetch_chunk(chunk_start: datetime, chunk_end: datetime):
+        pubStartDate = chunk_start.strftime("%Y-%m-%dT%H:%M:%S.000")
+        pubEndDate = chunk_end.strftime("%Y-%m-%dT%H:%M:%S.000")
+
+        query = (
+            f"?keywordSearch={keyword}"
+            f"&resultsPerPage={resultsPerPage}"
+            f"&startIndex={startIndex}"
+            f"&pubStartDate={pubStartDate}"
+            f"&pubEndDate={pubEndDate}"
+        )
+        full_url = url + query
+        logger.info(f"search_cves chunk: full_url={full_url}")
+
+        async with httpx.AsyncClient(timeout=API_TIMEOUT) as client:
+            resp = await client.get(full_url)
+            resp.raise_for_status()
+            return resp.json()
+
+    try:
+        # Generate chunks (max 120 days each)
+        chunk_size = timedelta(days=120)
+        chunks = []
+        chunk_start = start_date
+        while chunk_start < end_date:
+            chunk_end = min(chunk_start + chunk_size, end_date)
+            chunks.append((chunk_start, chunk_end))
+            chunk_start = chunk_end
+
+        tasks = [fetch_chunk(cs, ce) for cs, ce in chunks]
+        responses = await asyncio.gather(*tasks, return_exceptions=True)
+
+        total = 0
+        results: list[dict] = []
+
+        for resp in responses:
+            if isinstance(resp, Exception):
+                logger.error(f"Chunk failed: {resp}")
+                continue
+
+            data = cast(dict, resp)
+            total += data.get("totalResults", 0)
+            results.extend(data.get("vulnerabilities", []) or [])
+
+        results.sort(
+            key=lambda v: v.get("cve", {}).get("published", ""),
+            reverse=True
+        )
+
+        lines = [f"🔍 Search results for \"{keyword}\" - total matches: {total}"]
+        if not results:
+            lines.append("⚠️ No vulnerabilities returned for the given params.")
+        else:
+            for v in results:
+                lines.append(_format_vuln_entry(v))
+
+        lines.append(
+            f"📄 Aggregated across {len(chunks)} chunk(s) "
+            f"(parallelized), period={start_date.date()} → {end_date.date()}, "
+            f"resultsPerPage={resultsPerPage}"
+        )
+        return "\n".join(lines)
+
+    except httpx.HTTPStatusError as e:
+        logger.error(f"HTTP error in search_cves: {e.response.status_code} - {e.response.text}")
+        return f"❌ API Error: {e.response.status_code}"
+    except Exception as e:
+        logger.error("Exception in search_cves: " + str(e))
+        logger.debug(traceback.format_exc())
+        return f"❌ Error: {str(e)}"
+
+@mcp.tool()
+async def get_cve_by_id(cve_id: str = "") -> str:
+    """Retrieve a CVE by its CVE-ID"""
+    cve_id = _safe_str(cve_id)
+    if not cve_id:
+        return "❌ Error: cve_id parameter is required"
+    url = f"{NVD_BASE}/cves{NVD_VERSION}"
+    params = {"cveId": cve_id}
+    logger.info(f"get_cve_by_id: cveId={cve_id}")
+    try:
+        async with httpx.AsyncClient(timeout=API_TIMEOUT) as client:
+            resp = await client.get(url, params=params)
+            resp.raise_for_status()
+            data = resp.json()
+        vulns = data.get("vulnerabilities", []) or []
+        if not vulns:
+            return f"⚠️ No CVE found for {cve_id}"
+        v = vulns[0]
+        cve = v.get("cve", {})
+        desc = _short_desc_from_vuln(v)
+        published = _safe_str(cve.get("published"))
+        lastmod = _safe_str(cve.get("lastModified"))
+        tags = cve.get("cveTags", []) or []
+        tag_names = ", ".join([t.get("tag", "") for t in tags]) if tags else "none"
+        out = [
+            f"✅ CVE: {cve_id}",
+            f"- Published: {published}",
+            f"- Last Modified: {lastmod}",
+            f"- Tags: {tag_names}",
+            f"- Description: {desc}",
+        ]
+        refs = v.get("references", []) or []
+        if refs:
+            out.append(f"- References ({len(refs)}):")
+            for r in refs[:5]:
+                rtype = r.get("type", "ref")
+                urlr = r.get("url", "")
+                out.append(f"  - [{rtype}] {urlr}")
+            if len(refs) > 5:
+                out.append(f"  - ... and {len(refs)-5} more")
+        return "\n".join(out)
+    except httpx.HTTPStatusError as e:
+        logger.error(f"HTTP error in get_cve_by_id: {e.response.status_code}")
+        return f"❌ API Error: {e.response.status_code}"
+    except Exception as e:
+        logger.error("Exception in get_cve_by_id: " + str(e))
+        logger.debug(traceback.format_exc())
+        return f"❌ Error: {str(e)}"
+
+CPE_REGEX = re.compile(
+    r"^cpe:(?P<version>2\.3):"
+    r"(?P<part>[aho]):"
+    r"(?P<vendor>[^:]*):"
+    r"(?P<product>[^:]*):"
+    r"(?P<version_field>[^:]*):"
+    r"(?P<update>[^:]*):"
+    r"(?P<edition>[^:]*):"
+    r"(?P<language>[^:]*):"
+    r"(?P<sw_edition>[^:]*):"
+    r"(?P<target_sw>[^:]*):"
+    r"(?P<target_hw>[^:]*):"
+    r"(?P<other>[^:]*)$"
+)
+
+@mcp.tool()
+async def cves_by_cpe(cpe_name: str = "", is_vulnerable: str = "") -> str:
+    """List CVEs associated with a specific CPE"""
+    cpe_name = _safe_str(cpe_name)
+    if not cpe_name:
+        return "❌ Error: cpe_name parameter is required"
+
+    if not CPE_REGEX.match(cpe_name):
+        return ("❌ Error: cpe_name must be provided in full CPE 2.3 format, e.g. "
+                "cpe:2.3:a:vendor:product:version:update:edition:language:"
+                "sw_edition:target_sw:target_hw:other - eventually use the wildcard *, e.g.: cpe:2.3:a:ntp:ntp:4.2.8:p3:*:*:*:*:*:*")
+
+    url = f"{NVD_BASE}/cves{NVD_VERSION}"
+    params = {"cpeName": cpe_name}
+    if _safe_str(is_vulnerable).lower() in ("1", "true", "yes"):
+        params["isVulnerable"] = ""
+    logger.info(f"cves_by_cpe: cpeName={cpe_name} isVulnerable={_safe_str(is_vulnerable)}")
+    try:
+        async with httpx.AsyncClient(timeout=API_TIMEOUT) as client:
+            resp = await client.get(url, params=params)
+            resp.raise_for_status()
+            data = resp.json()
+        total = data.get("totalResults", 0)
+        vulns = data.get("vulnerabilities", []) or []
+        lines = [f"🌐 CVEs for CPE \"{cpe_name}\" - total matches: {total}"]
+        if not vulns:
+            lines.append("⚠️ No vulnerabilities returned for the given CPE.")
+        else:
+            for v in vulns[:50]:
+                lines.append(_format_vuln_entry(v))
+            if total > len(vulns):
+                lines.append(f"📄 Partial list: returned {len(vulns)} of {total}")
+        return "\n".join(lines)
+    except httpx.HTTPStatusError as e:
+        logger.error(f"HTTP error in cves_by_cpe: {e.response.status_code}")
+        return f"❌ API Error: {e.response.status_code}"
+    except Exception as e:
+        logger.error("Exception in cves_by_cpe: " + str(e))
+        logger.debug(traceback.format_exc())
+        return f"❌ Error: {str(e)}"
+
+@mcp.tool()
+async def kevs_between(
+    kevStartDate: str = "",
+    kevEndDate: str = "",
+    resultsPerPage: str = "20",
+    startIndex: str = "0"
+) -> str:
+    """
+    List CVEs added to CISA KEV catalog in a date window.
+    If the requested window exceeds 90 days, the query is automatically
+    split into multiple chunks (max 90 days each) and results are aggregated.
+    """
+    kevStartDate = _safe_str(kevStartDate)
+    kevEndDate = _safe_str(kevEndDate)
+    if not kevStartDate or not kevEndDate:
+        return "❌ Error: kevStartDate and kevEndDate parameters are required and must be ISO-8601"
+
+    rpp = _int_or_default(resultsPerPage, 20)
+    sidx = _int_or_default(startIndex, 0)
+
+    try:
+        dt_start = datetime.fromisoformat(kevStartDate.replace("Z", "+00:00"))
+        dt_end = datetime.fromisoformat(kevEndDate.replace("Z", "+00:00"))
+
+        if dt_end <= dt_start:
+            return "❌ Error: kevEndDate must be after kevStartDate"
+
+        chunk_size = timedelta(days=90)
+        chunks = []
+        chunk_start = dt_start
+        while chunk_start < dt_end:
+            chunk_end = min(chunk_start + chunk_size, dt_end)
+            chunks.append((chunk_start, chunk_end))
+            chunk_start = chunk_end
+
+        async def fetch_chunk(cs, ce):
+            params = {
+                "hasKev": "",
+                "kevStartDate": cs.strftime("%Y-%m-%dT%H:%M:%S.000"),
+                "kevEndDate": ce.strftime("%Y-%m-%dT%H:%M:%S.000"),
+                "resultsPerPage": str(rpp),
+                "startIndex": str(sidx),
+            }
+            url = f"{NVD_BASE}/cves{NVD_VERSION}"
+            logger.info(f"kevs_between chunk: {params['kevStartDate']} -> {params['kevEndDate']}")
+            async with httpx.AsyncClient(timeout=API_TIMEOUT) as client:
+                resp = await client.get(url, params=params)
+                resp.raise_for_status()
+                return resp.json()
+
+        tasks = [fetch_chunk(cs, ce) for cs, ce in chunks]
+        responses = await asyncio.gather(*tasks, return_exceptions=True)
+
+        total = 0
+        vulns: list[dict] = []
+
+        for resp in responses:
+            if isinstance(resp, Exception):
+                logger.error(f"KEV chunk failed: {resp}")
+                continue
+
+            data = cast(dict, resp)
+            total += data.get("totalResults", 0)
+            vulns.extend(data.get("vulnerabilities", []) or [])
+
+        vulns.sort(
+            key=lambda v: v.get("cve", {}).get("published", ""),
+            reverse=True
+        )
+
+        lines = [
+            f"🔥 KEV CVEs added between {kevStartDate} and {kevEndDate} - total matches (aggregated): {total}"
+        ]
+        if not vulns:
+            lines.append("⚠️ No KEV CVEs returned for the given window.")
+        else:
+            for v in vulns:
+                lines.append(_format_vuln_entry(v))
+        lines.append(f"📄 Aggregated across {len(chunks)} chunk(s), resultsPerPage={rpp} startIndex={sidx}")
+
+        return "\n".join(lines)
+
+    except ValueError:
+        return "❌ Error: kevStartDate and kevEndDate must be valid ISO-8601 timestamps"
+    except httpx.HTTPStatusError as e:
+        logger.error(f"HTTP error in kevs_between: {e.response.status_code}")
+        return f"❌ API Error: {e.response.status_code}"
+    except Exception as e:
+        logger.error("Exception in kevs_between: " + str(e))
+        logger.debug(traceback.format_exc())
+        return f"❌ Error: {str(e)}"
+
+@mcp.tool()
+async def cve_change_history(
+    cve_id: str = "",
+    changeStartDate: str = "",
+    changeEndDate: str = "",
+    resultsPerPage: str = "20",
+    startIndex: str = "0"
+) -> str:
+    """
+    Retrieve change history for a CVE or a time window.
+    If no cve_id is provided and the date range exceeds 120 days,
+    the query is split into multiple chunks (max 120 days each) and results aggregated.
+    """
+    cve_id = _safe_str(cve_id)
+    rpp = _int_or_default(resultsPerPage, 20)
+    sidx = _int_or_default(startIndex, 0)
+    url = f"{NVD_BASE}/cvehistory{NVD_VERSION}"
+
+    try:
+        chunks = []
+
+        if cve_id:
+            params = {"cveId": cve_id, "resultsPerPage": str(rpp), "startIndex": str(sidx)}
+            logger.info(f"cve_change_history: cveId={cve_id}")
+            async with httpx.AsyncClient(timeout=API_TIMEOUT) as client:
+                resp = await client.get(url, params=params)
+                resp.raise_for_status()
+                data = resp.json()
+            changes = data.get("cveChanges", []) or []
+            total = data.get("totalResults", 0)
+        else:
+            changeStartDate = _safe_str(changeStartDate)
+            changeEndDate = _safe_str(changeEndDate)
+            if not changeStartDate or not changeEndDate:
+                return "❌ Error: either cve_id or both changeStartDate and changeEndDate are required"
+
+            dt_start = datetime.fromisoformat(changeStartDate.replace("Z", "+00:00"))
+            dt_end = datetime.fromisoformat(changeEndDate.replace("Z", "+00:00"))
+
+            if dt_end <= dt_start:
+                return "❌ Error: changeEndDate must be after changeStartDate"
+
+            chunk_size = timedelta(days=120)
+            chunks = []
+            chunk_start = dt_start
+            while chunk_start < dt_end:
+                chunk_end = min(chunk_start + chunk_size, dt_end)
+                chunks.append((chunk_start, chunk_end))
+                chunk_start = chunk_end
+
+            async def fetch_chunk(cs, ce):
+                params = {
+                    "changeStartDate": cs.strftime("%Y-%m-%dT%H:%M:%S.000"),
+                    "changeEndDate": ce.strftime("%Y-%m-%dT%H:%M:%S.000"),
+                    "resultsPerPage": str(rpp),
+                    "startIndex": str(sidx)
+                }
+                logger.info(f"cve_change_history chunk: {params['changeStartDate']} -> {params['changeEndDate']}")
+                async with httpx.AsyncClient(timeout=API_TIMEOUT) as client:
+                    resp = await client.get(url, params=params)
+                    resp.raise_for_status()
+                    return resp.json()
+
+            tasks = [fetch_chunk(cs, ce) for cs, ce in chunks]
+            responses = await asyncio.gather(*tasks, return_exceptions=True)
+
+            total = 0
+            changes: list[dict] = []
+
+            for resp in responses:
+                if isinstance(resp, Exception):
+                    logger.error(f"CVE change chunk failed: {resp}")
+                    continue
+
+                data = cast(dict, resp)
+                total += data.get("totalResults", 0)
+                changes.extend(data.get("cveChanges", []) or [])
+
+        changes.sort(
+            key=lambda v: v.get("change", {}).get("created", ""),
+            reverse=True
+        )
+
+        lines = [f"🕘 CVE Change History - total events: {total}"]
+        if not changes:
+            lines.append("⚠️ No change events returned for the given query.")
+        else:
+            for ch in changes[:50]:
+                try:
+                    change = ch.get("change", {})
+                    cid = change.get("cveId", "UNKNOWN")
+                    event = change.get("eventName", "EVENT")
+                    created = change.get("created", "")
+                    lines.append(f"- {cid} | event: {event} | at: {created}")
+                except Exception:
+                    lines.append("- (malformed change event)")
+            if total > len(changes):
+                lines.append(f"📄 Partial list: returned {len(changes)} of {total}")
+        if not cve_id and len(chunks) > 1:
+            lines.append(f"📄 Aggregated across {len(chunks)} chunk(s), resultsPerPage={rpp} startIndex={sidx}")
+
+        return "\n".join(lines)
+
+    except ValueError:
+        return "❌ Error: changeStartDate and changeEndDate must be valid ISO-8601 timestamps"
+    except httpx.HTTPStatusError as e:
+        logger.error(f"HTTP error in cve_change_history: {e.response.status_code}")
+        return f"❌ API Error: {e.response.status_code}"
+    except Exception as e:
+        logger.error("Exception in cve_change_history: " + str(e))
+        logger.debug(traceback.format_exc())
+        return f"❌ Error: {str(e)}"
+
+# === SERVER STARTUP ===
+
+def main():
+    """Main entry point"""
+    logger.info(f"Starting NIST Vulnerability MCP server v{__version__}...")
+    try:
+        mcp.run(transport="stdio")
+    except KeyboardInterrupt:
+        logger.info("Server stopped by user")
+        sys.exit(0)
+    except Exception as e:
+        logger.error(f"Server error: {e}", exc_info=True)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()