Metadata-Version: 2.5
Name: cybersafe-mcp
Version: 0.3.0
Summary: An open-source, plain-language cybersecurity MCP server with hybrid AI/ML scam detection for everyday users (especially 40+).
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=2.0.0
Requires-Dist: starlette>=0.40.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: ml
Requires-Dist: torch>=2.2.0; extra == 'ml'
Requires-Dist: transformers>=4.45.0; extra == 'ml'
Description-Content-Type: text/markdown

# CyberSafe MCP (v0.3 — Hybrid AI/ML Edition)

An open-source, plain-language **Model Context Protocol (MCP)** server built in Python to help everyday users—especially people **40+**—stay safe on phones, laptops, and AI tools.

Built with the official [Python MCP SDK v2](https://py.sdk.modelcontextprotocol.io/) (`mcp>=2.0.0`).

## What's Inside v0.3

### Hybrid AI/ML + Regional Rules Scam Detection
- `analyze_scam_message(message, channel, region)` now runs a **Hybrid Engine**:
  1. **Explainable Regional Packs** (`global`, `india`, `us_uk`) in `src/cybersafe_mcp/scam_packs/*.json` for clear, zero-jargon red flags (Digital Arrest, UPI QR fraud, KYC traps, IRS/HMRC scams, AI voice-cloning).
  2. **Local HuggingFace AI Model** (optional `ml` extra) that catches subtle or paraphrased scams with no exact keywords—running 100% locally in memory with zero user data sent to third-party AI APIs.
  - Default model: [`mrm8488/bert-tiny-finetuned-sms-spam-detection`](https://huggingface.co/mrm8488/bert-tiny-finetuned-sms-spam-detection) (~17.6 MB, fast on CPU).
  - Multilingual alternative: set `CYBERSAFE_ML_MODEL=Horizon-Labs/phishing-scam-detector-base` ([model card](https://huggingface.co/Horizon-Labs/phishing-scam-detector-base)).

### Other Security Tools
- `check_url_safety(url)` — Local phishing heuristics + optional live [URLhaus API](https://urlhaus.abuse.ch/api/) lookups (never visits the link).
- `check_email_breach(email)` — Live breach check via the free, no-key [XposedOrNot API](https://xposedornot.com/api_doc).
- `get_latest_alerts(limit, consumer_only, keyword)` — Live consumer-filtered alerts from the [CISA KEV Catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog).
- `check_password_hygiene(password_sample)` — Pure local offline password-strength evaluator.
- `get_daily_cyber_tip(category)` — One 60-second daily tip (`phone`, `laptop`, `ai`, `general`).

## Quick Start

### Lightweight Mode (Rules Only — Fastest Install)
```bash
uv sync --extra dev
uv run pytest
uv run mcp dev src/cybersafe_mcp/server.py
```

### Full Hybrid AI/ML Mode (Rules + Local HuggingFace Model)
```bash
uv sync --extra dev --extra ml
uv run pytest
uv run mcp dev src/cybersafe_mcp/server.py
```
On the first call to `analyze_scam_message`, the ~17.6 MB BERT-Tiny model downloads once into your local HuggingFace cache and runs completely offline after that.

To swap models without changing code:
```bash
# macOS / Linux
CYBERSAFE_ML_MODEL=Horizon-Labs/phishing-scam-detector-base uv run mcp dev src/cybersafe_mcp/server.py

# Windows PowerShell
$env:CYBERSAFE_ML_MODEL="Horizon-Labs/phishing-scam-detector-base"
uv run mcp dev src/cybersafe_mcp/server.py
```

## Remote Deployment (Streamable HTTP)
```bash
uv run cybersafe-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```
Health endpoint: `GET /health` (also reports whether the AI/ML engine is enabled and which model is configured).


<!-- mcp-name: io.github.<kshitij9896>/cybersafe-mcp -->
