sec-mcp 0.1.1__tar.gz

sec_mcp-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Luong NGUYEN
+
+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.

sec_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: sec-mcp
+Version: 0.1.1
+Summary: Python toolkit providing security checks for domains, URLs, IPs, and more.
+Author: Luong NGUYEN
+License: MIT
+Project-URL: Homepage, https://github.com/Montimage/sec-mcp
+Project-URL: Repository, https://github.com/Montimage/sec-mcp.git
+Project-URL: Documentation, https://github.com/Montimage/sec-mcp#readme
+Keywords: security,blacklist,mcp,phishing,malware
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: click>=8.1.7
+Requires-Dist: idna>=3.4
+Requires-Dist: mcp[cli]>=0.1.0
+Requires-Dist: schedule>=1.2.0
+Requires-Dist: tqdm>=4.66.0
+Dynamic: license-file
+Dynamic: requires-python
+
+# sec-mcp: Security Checking Toolkit
+
+A Python toolkit providing security checks for domains, URLs, IPs, and more. Integrate easily into any Python application, use via terminal CLI, or run as an MCP server to enrich LLM context with real-time threat insights.
+
+## Features
+
+- Comprehensive security checks for domains, URLs, IP addresses, and more against multiple blacklist feeds
+- On-demand updates from OpenPhish, PhishStats, URLhaus and custom sources
+- High-performance, thread-safe SQLite storage with in-memory caching for fast lookups
+- Python API via `SecMCP` class for easy integration into your applications
+- Intuitive Click-based CLI for interactive single or batch scans
+- Built-in MCP server support for LLM/AI integrations over JSON/STDIO
+
+## Installation
+
+```bash
+pip install sec-mcp
+```
+
+## Usage via CLI
+
+1. Install the package:
+   ```bash
+   pip install sec-mcp
+   ```
+2. Check a single URL/domain/IP:
+   ```bash
+   sec-mcp check https://example.com
+   ```
+3. Batch check from a file:
+   ```bash
+   sec-mcp batch urls.txt
+   ```
+4. View blacklist status:
+   ```bash
+   sec-mcp status
+   ```
+5. Manually trigger an update:
+   ```bash
+   sec-mcp update
+   ```
+
+## Usage via API (Python)
+
+1. Install in your project:
+   ```bash
+   pip install sec-mcp
+   ```
+2. Import and initialize:
+   ```python
+   from sec_mcp import SecMCP
+
+   client = SecMCP()
+   ```
+3. Single check:
+   ```python
+   result = client.check("https://example.com")
+   print(result.to_json())
+   ```
+4. Batch check:
+   ```python
+   urls = ["https://example.com", "https://test.com"]
+   results = client.check_batch(urls)
+   for r in results:
+       print(r.to_json())
+   ```
+5. Get status and update:
+   ```python
+   status = client.get_status()
+   print(status.to_json())
+
+   client.update()
+   ```
+
+## Usage via MCP Client
+
+To run sec-mcp as an MCP server for AI-driven clients (e.g., Claude):
+
+1. Install in editable mode (for development):
+   ```bash
+   pip install -e .
+   ```
+2. Start the MCP server:
+   ```bash
+   sec-mcp-server
+   ```
+3. Configure your MCP client (e.g., Claude) to point at the command:
+   ```json
+   {
+     "mcpServers": {
+       "sec-mcp": {
+         "command": ".venv/bin/python3",
+         "args": ["-m", "sec_mcp.start_server"]
+       }
+     }
+   }
+   ```
+
+Clients will then use the built-in `check_blacklist` tool over JSON/STDIO for real-time security checks.
+
+## Configuration
+
+The client can be configured via `config.json`:
+
+- `blacklist_sources`: URLs for blacklist feeds
+- `update_time`: Daily update schedule (default: "00:00")
+- `cache_size`: In-memory cache size (default: 10000)
+- `log_level`: Logging verbosity (default: "INFO")
+
+## Configuring sec-mcp with Claude (MCP Client)
+
+To use your MCP Server for security checking (sec-mcp) with an MCP client such as Claude, add it to your Claude configuration as follows:
+
+```json
+{
+  "mcpServers": {
+    "sec-mcp": {
+      "command": ".venv/bin/python3",
+      "args": ["-m", "sec_mcp.start_server"]
+    }
+  }
+}
+```
+
+- Ensure you have installed all dependencies in your virtual environment (`.venv`).
+- The `command` should point to your Python executable inside `.venv` for best isolation.
+- The `args` array should launch your MCP server using the provided script.
+- You can add other MCP servers in the same configuration if needed.
+
+This setup allows Claude (or any compatible MCP client) to connect to your sec-mcp server and use its `check_blacklist` tool for real-time security checks on URLs, domains, or IP addresses.
+
+For more details and advanced configuration, see the [Model Context Protocol examples](https://modelcontextprotocol.io/examples).
+
+## Development
+
+Clone the repository and install in development mode:
+
+```bash
+git clone <repository-url>
+cd sec-mcp
+pip install -e .
+```
+
+## License
+
+MIT

sec_mcp-0.1.1/README.md

@@ -0,0 +1,146 @@
+# sec-mcp: Security Checking Toolkit
+
+A Python toolkit providing security checks for domains, URLs, IPs, and more. Integrate easily into any Python application, use via terminal CLI, or run as an MCP server to enrich LLM context with real-time threat insights.
+
+## Features
+
+- Comprehensive security checks for domains, URLs, IP addresses, and more against multiple blacklist feeds
+- On-demand updates from OpenPhish, PhishStats, URLhaus and custom sources
+- High-performance, thread-safe SQLite storage with in-memory caching for fast lookups
+- Python API via `SecMCP` class for easy integration into your applications
+- Intuitive Click-based CLI for interactive single or batch scans
+- Built-in MCP server support for LLM/AI integrations over JSON/STDIO
+
+## Installation
+
+```bash
+pip install sec-mcp
+```
+
+## Usage via CLI
+
+1. Install the package:
+   ```bash
+   pip install sec-mcp
+   ```
+2. Check a single URL/domain/IP:
+   ```bash
+   sec-mcp check https://example.com
+   ```
+3. Batch check from a file:
+   ```bash
+   sec-mcp batch urls.txt
+   ```
+4. View blacklist status:
+   ```bash
+   sec-mcp status
+   ```
+5. Manually trigger an update:
+   ```bash
+   sec-mcp update
+   ```
+
+## Usage via API (Python)
+
+1. Install in your project:
+   ```bash
+   pip install sec-mcp
+   ```
+2. Import and initialize:
+   ```python
+   from sec_mcp import SecMCP
+
+   client = SecMCP()
+   ```
+3. Single check:
+   ```python
+   result = client.check("https://example.com")
+   print(result.to_json())
+   ```
+4. Batch check:
+   ```python
+   urls = ["https://example.com", "https://test.com"]
+   results = client.check_batch(urls)
+   for r in results:
+       print(r.to_json())
+   ```
+5. Get status and update:
+   ```python
+   status = client.get_status()
+   print(status.to_json())
+
+   client.update()
+   ```
+
+## Usage via MCP Client
+
+To run sec-mcp as an MCP server for AI-driven clients (e.g., Claude):
+
+1. Install in editable mode (for development):
+   ```bash
+   pip install -e .
+   ```
+2. Start the MCP server:
+   ```bash
+   sec-mcp-server
+   ```
+3. Configure your MCP client (e.g., Claude) to point at the command:
+   ```json
+   {
+     "mcpServers": {
+       "sec-mcp": {
+         "command": ".venv/bin/python3",
+         "args": ["-m", "sec_mcp.start_server"]
+       }
+     }
+   }
+   ```
+
+Clients will then use the built-in `check_blacklist` tool over JSON/STDIO for real-time security checks.
+
+## Configuration
+
+The client can be configured via `config.json`:
+
+- `blacklist_sources`: URLs for blacklist feeds
+- `update_time`: Daily update schedule (default: "00:00")
+- `cache_size`: In-memory cache size (default: 10000)
+- `log_level`: Logging verbosity (default: "INFO")
+
+## Configuring sec-mcp with Claude (MCP Client)
+
+To use your MCP Server for security checking (sec-mcp) with an MCP client such as Claude, add it to your Claude configuration as follows:
+
+```json
+{
+  "mcpServers": {
+    "sec-mcp": {
+      "command": ".venv/bin/python3",
+      "args": ["-m", "sec_mcp.start_server"]
+    }
+  }
+}
+```
+
+- Ensure you have installed all dependencies in your virtual environment (`.venv`).
+- The `command` should point to your Python executable inside `.venv` for best isolation.
+- The `args` array should launch your MCP server using the provided script.
+- You can add other MCP servers in the same configuration if needed.
+
+This setup allows Claude (or any compatible MCP client) to connect to your sec-mcp server and use its `check_blacklist` tool for real-time security checks on URLs, domains, or IP addresses.
+
+For more details and advanced configuration, see the [Model Context Protocol examples](https://modelcontextprotocol.io/examples).
+
+## Development
+
+Clone the repository and install in development mode:
+
+```bash
+git clone <repository-url>
+cd sec-mcp
+pip install -e .
+```
+
+## License
+
+MIT

sec_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sec-mcp"
+version = "0.1.1"
+description = "Python toolkit providing security checks for domains, URLs, IPs, and more."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [ { name = "Luong NGUYEN" } ]
+dependencies = [
+  "requests>=2.31.0",
+  "httpx>=0.25.0",
+  "click>=8.1.7",
+  "idna>=3.4",
+  "mcp[cli]>=0.1.0",
+  "schedule>=1.2.0",
+  "tqdm>=4.66.0",
+]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Security",
+]
+keywords = ["security", "blacklist", "mcp", "phishing", "malware"]
+
+[project.urls]
+Homepage      = "https://github.com/Montimage/sec-mcp"
+Repository    = "https://github.com/Montimage/sec-mcp.git"
+Documentation = "https://github.com/Montimage/sec-mcp#readme"
+
+[project.scripts]
+sec-mcp = "sec_mcp.cli:cli"
+sec-mcp-server = "sec_mcp.start_server:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["sec_mcp*"]

sec_mcp-0.1.1/sec_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""
+MCP Client - A Python library and CLI for checking domains, URLs, and IPs against blacklists.
+"""
+
+from .sec_mcp import SecMCP, CheckResult, StatusInfo
+from .cli import cli
+from .utility import validate_input, setup_logging
+
+__version__ = "0.1.1"
+__all__ = ['SecMCP', 'CheckResult', 'StatusInfo', 'cli', 'validate_input', 'setup_logging']

sec_mcp-0.1.1/sec_mcp/cli.py

@@ -0,0 +1,84 @@
+import click
+from .sec_mcp import SecMCP
+
+# Global SecMCP instance for CLI
+core = SecMCP()
+
+@click.group()
+@click.version_option(version="0.1.1", message="%(version)s (MCP Client)")
+def cli():
+    """MCP Client CLI for checking domains, URLs, and IPs against blacklists.
+
+    Examples:
+      mcp check https://example.com
+      mcp batch urls.txt --json
+      mcp status
+    """
+    pass
+
+@cli.command(help="Check a single domain, URL, or IP against the blacklist.\n\nExample: mcp check https://example.com --json")
+@click.argument('value')
+@click.option('--json', is_flag=True, help='Output in JSON format')
+def check(value: str, json: bool):
+    result = core.check(value)
+    if json:
+        click.echo(result.to_json())
+    else:
+        if result.blacklisted:
+            click.secho(f"Status: Blacklisted", fg="red")
+        else:
+            click.secho(f"Status: Safe", fg="green")
+        click.echo(f"Explanation: {result.explanation}")
+
+@cli.command(help="Check multiple inputs from a file against the blacklist.\n\nExample: mcp batch urls.txt --json")
+@click.argument('file', type=click.Path(exists=True))
+@click.option('--json', is_flag=True, help='Output in JSON format')
+def batch(file: str, json: bool):
+    with open(file) as f:
+        values = [line.strip() for line in f if line.strip()]
+    results = core.check_batch(values)
+    if json:
+        import json as _json
+        click.echo(_json.dumps([r.to_json() for r in results], indent=2))
+    else:
+        for value, result in zip(values, results):
+            click.secho(f"{value}:", bold=True)
+            if result.blacklisted:
+                click.secho(f"  Status: Blacklisted", fg="red")
+            else:
+                click.secho(f"  Status: Safe", fg="green")
+            click.echo(f"  Explanation: {result.explanation}")
+
+@cli.command(help="Show blacklist status (entry count, last update, sources).\n\nExample: mcp status --json")
+@click.option('--json', is_flag=True, help='Output in JSON format')
+def status(json):
+    status = core.get_status()
+    if json:
+        import json as _json
+        click.echo(_json.dumps(status.to_json(), indent=2))
+    else:
+        click.secho(f"Total entries: {status.entry_count}", bold=True)
+        click.echo(f"Last update: {status.last_update}")
+        click.echo("Active sources:")
+        for source in status.sources:
+            click.echo(f"  - {source}")
+        click.echo(f"Server status: {status.server_status}")
+
+@cli.command(help="Update blacklist feeds immediately.")
+@click.option('--json', is_flag=True, help='Output minimal JSON confirmation')
+def update(json):
+    """Force an immediate update of all blacklists."""
+    core.update()
+    if json:
+        import json as _json
+        click.echo(_json.dumps({"updated": True}))
+    else:
+        click.echo("Blacklist update triggered.")
+
+@cli.command(help="Sample random blacklist entries for testing.")
+@click.option('-n', '--count', default=10, help='Number of entries to sample')
+def sample(count: int):
+    """Output a random sample of blacklist values for quick tests."""
+    entries = core.sample(count)
+    for value in entries:
+        click.echo(value)

sec_mcp-0.1.1/sec_mcp/config.json

@@ -0,0 +1,11 @@
+{
+    "blacklist_sources": {
+        "OpenPhish": "https://openphish.com/feed.txt",
+        "PhishStats": "https://phishstats.info/phish_score.csv",
+        "URLhaus": "https://urlhaus.abuse.ch/downloads/text/"
+    },
+    "update_time": "00:00",
+    "cache_size": 10000,
+    "log_level": "INFO",
+    "db_path": "mcp.db"
+}

sec_mcp-0.1.1/sec_mcp/mcp_server.py

@@ -0,0 +1,42 @@
+from mcp.server.fastmcp import FastMCP
+import anyio
+# import SecMCP for server logic
+from .sec_mcp import SecMCP
+from .utility import validate_input
+
+# Initialize FastMCP server
+mcp = FastMCP("mcp-blacklist")
+
+# Global SecMCP instance for MCP server
+core = SecMCP()
+
+@mcp.tool(description="Calculate sum of two numbers. Returns JSON: {sum: number}.")
+async def sum_numbers(a: float, b: float):
+    """Sum two numbers."""
+    return {"sum": a + b}
+
+@mcp.tool(name="check", description="Check if a domain, URL, or IP address is in the blacklist. Returns JSON: {is_safe: bool, explain: str}.")
+async def check_blacklist(value: str):
+    """Check a single value against the blacklist."""
+    if not validate_input(value):
+        return {"is_safe": False, "explain": "Invalid input format. Must be a valid domain, URL, or IP address."}
+    result = core.check(value)
+    return {"is_safe": not result.blacklisted, "explain": result.explanation}
+
+@mcp.tool(description="Get status of the blacklist. Returns JSON: {entry_count: int, last_update: str, sources: List[str], server_status: str}.")
+async def get_blacklist_status():
+    """Return current blacklist status."""
+    status = core.get_status()
+    return {
+        "entry_count": status.entry_count,
+        "last_update": status.last_update,
+        "sources": status.sources,
+        "server_status": status.server_status
+    }
+
+@mcp.tool(description="Force immediate update of all blacklists. Returns JSON: {updated: bool}.")
+async def update_blacklists():
+    """Trigger an immediate blacklist refresh."""
+    # Offload to thread to avoid nested event loops
+    await anyio.to_thread.run_sync(core.update)
+    return {"updated": True}

sec_mcp-0.1.1/sec_mcp/sec_mcp.py

@@ -0,0 +1,70 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import List, Optional
+from .storage import Storage
+from .update_blacklist import BlacklistUpdater
+
+@dataclass
+class CheckResult:
+    blacklisted: bool
+    explanation: str
+
+    def to_json(self):
+        return {
+            "is_safe": not self.blacklisted,
+            "explain": self.explanation
+        }
+
+@dataclass
+class StatusInfo:
+    entry_count: int
+    last_update: datetime
+    sources: List[str]
+    server_status: str
+
+    def to_json(self):
+        return {
+            "entry_count": self.entry_count,
+            "last_update": self.last_update.isoformat(),
+            "sources": self.sources,
+            "server_status": self.server_status
+        }
+
+class SecMCP:
+    def __init__(self):
+        self.storage = Storage()
+        self.updater = BlacklistUpdater(self.storage)
+
+    def check(self, value: str) -> CheckResult:
+        """Check a single value against the blacklist."""
+        if self.storage.is_blacklisted(value):
+            source = self.storage.get_blacklist_source(value)
+            return CheckResult(
+                blacklisted=True,
+                explanation=f"Blacklisted by {source}"
+            )
+        return CheckResult(
+            blacklisted=False,
+            explanation="Not blacklisted"
+        )
+
+    def check_batch(self, values: List[str]) -> List[CheckResult]:
+        """Check multiple values against the blacklist."""
+        return [self.check(value) for value in values]
+
+    def get_status(self) -> StatusInfo:
+        """Get current status of the blacklist service."""
+        return StatusInfo(
+            entry_count=self.storage.count_entries(),
+            last_update=self.storage.get_last_update(),
+            sources=self.storage.get_active_sources(),
+            server_status="Running (STDIO)"
+        )
+
+    def update(self) -> None:
+        """Force an immediate update of all blacklists."""
+        self.updater.force_update()
+
+    def sample(self, count: int = 10) -> List[str]:
+        """Return a random sample of blacklist entries for testing."""
+        return self.storage.sample_entries(count)