leadintel 0.3.0__py3-none-any.whl

leadintel/storage/db.py

@@ -0,0 +1,189 @@
+"""
+SQLite database storage for LeadIntel.
+
+Persists researched businesses across searches and server sessions.
+Uses standard library sqlite3 without external dependencies.
+Stores the database safely in the user's home directory.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from ..models.business import Business
+
+logger = logging.getLogger(__name__)
+
+DB_DIR = Path.home() / ".local" / "share" / "leadintel"
+DB_PATH = DB_DIR / "leadintel.db"
+DEFAULT_DB_PATH = str(DB_PATH)
+
+
+def _resolve_path(db_path: Optional[str | Path] = None) -> str:
+    """Resolve database path, honoring test overrides or parameters."""
+    if db_path:
+        return str(db_path)
+    if DEFAULT_DB_PATH != str(DB_PATH):
+        return str(DEFAULT_DB_PATH)
+    return str(DB_PATH)
+
+
+def _get_connection(db_path: Optional[str | Path] = None) -> sqlite3.Connection:
+    """Open a SQLite connection and configure row factory."""
+    target_path = _resolve_path(db_path)
+    if target_path != ":memory:":
+        parent = Path(target_path).parent
+        parent.mkdir(parents=True, exist_ok=True)
+
+    conn = sqlite3.connect(target_path)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def init_db(db_path: Optional[str | Path] = None) -> None:
+    """Initialize the SQLite database schema if not already created."""
+    try:
+        DB_DIR.mkdir(parents=True, exist_ok=True)
+        target = _resolve_path(db_path)
+        conn = _get_connection(target)
+        try:
+            with conn:
+                conn.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS businesses (
+                        id TEXT PRIMARY KEY,
+                        model_json TEXT,
+                        updated_at DATETIME
+                    )
+                    """
+                )
+            logger.debug("Database initialized at %s", target)
+        finally:
+            conn.close()
+    except Exception as e:
+        logger.error(f"Failed to initialize SQLite database: {e}")
+
+
+def save_businesses(
+    businesses: list[Business], db_path: Optional[str | Path] = None
+) -> int:
+    """
+    Upsert businesses into the database.
+
+    Stores the serialized business JSON and current UTC timestamp.
+    Returns the count of businesses saved.
+    """
+    if not businesses:
+        return 0
+
+    try:
+        init_db(db_path)
+        target = _resolve_path(db_path)
+        conn = _get_connection(target)
+        count = 0
+        now_iso = datetime.now(timezone.utc).isoformat()
+        try:
+            with conn:
+                for b in businesses:
+                    if not b.id:
+                        continue
+                    model_json = b.model_dump_json()
+                    conn.execute(
+                        """
+                        INSERT INTO businesses (id, model_json, updated_at)
+                        VALUES (?, ?, ?)
+                        ON CONFLICT(id) DO UPDATE SET
+                            model_json = excluded.model_json,
+                            updated_at = excluded.updated_at
+                        """,
+                        (b.id, model_json, now_iso),
+                    )
+                    count += 1
+            logger.debug("Saved %d businesses to database", count)
+            return count
+        finally:
+            conn.close()
+    except Exception as e:
+        logger.error(f"Failed to save businesses to database: {e}")
+        return 0
+
+
+def get_business(business_id: str, db_path: Optional[str | Path] = None) -> Optional[Business]:
+    """
+    Retrieve and deserialize a business from SQLite by ID.
+
+    Returns the Business model if found, None otherwise.
+    """
+    if not business_id:
+        return None
+
+    try:
+        init_db(db_path)
+        target = _resolve_path(db_path)
+        conn = _get_connection(target)
+        try:
+            cursor = conn.cursor()
+            cursor.execute(
+                "SELECT model_json FROM businesses WHERE id = ?",
+                (business_id,),
+            )
+            row = cursor.fetchone()
+            if not row or not row["model_json"]:
+                return None
+            return Business.model_validate_json(row["model_json"])
+        finally:
+            conn.close()
+    except Exception as e:
+        logger.error(f"Error fetching business {business_id}: {e}")
+        return None
+
+
+def get_all_businesses(
+    min_score: Optional[float] = None,
+    limit: int = 50,
+    db_path: Optional[str | Path] = None,
+) -> list[Business]:
+    """
+    Retrieve saved businesses from SQLite, optionally filtered by minimum opportunity score.
+
+    Args:
+        min_score: Optional minimum website_opportunity_score threshold.
+        limit: Maximum number of businesses to return.
+        db_path: Optional database path override (e.g. for testing).
+
+    Returns:
+        List of matching Business objects ordered by updated_at descending.
+    """
+    try:
+        init_db(db_path)
+        target = _resolve_path(db_path)
+        conn = _get_connection(target)
+        results: list[Business] = []
+        try:
+            cursor = conn.cursor()
+            cursor.execute("SELECT model_json FROM businesses ORDER BY updated_at DESC")
+            rows = cursor.fetchall()
+            for row in rows:
+                if not row or not row["model_json"]:
+                    continue
+                try:
+                    biz = Business.model_validate_json(row["model_json"])
+                    if min_score is not None:
+                        opp_score = biz.website_opportunity_score
+                        if opp_score is None or opp_score < min_score:
+                            continue
+                    results.append(biz)
+                    if len(results) >= limit:
+                        break
+                except Exception as exc:
+                    logger.debug("Skipping unparseable business record: %s", exc)
+            return results
+        finally:
+            conn.close()
+    except Exception as e:
+        logger.error(f"Failed to retrieve businesses from database: {e}")
+        return []

leadintel/storage/path_validator.py

@@ -0,0 +1,118 @@
+"""
+Path Traversal and File Security Validator.
+
+Validates destination file paths for exporters (Excel, CSV, JSON):
+- Prevents directory traversal attacks ('..', null bytes).
+- Blocks writes to system root and critical directories (/etc, /bin, /sbin, /usr, /root, /sys, /proc, /System, /Library, Windows System32, etc.).
+- Blocks writes to sensitive user directories (.ssh, .gnupg, .aws, .config, shell rc files).
+- Enforces allowed file extensions (.xlsx, .csv, .json).
+- Canonicalizes and verifies destination paths cross-platform.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from ..services.url_validator import SecurityValidationError
+
+# System and user directories strictly protected from export writes
+BLOCKED_PATH_PREFIXES = (
+    "/etc",
+    "/bin",
+    "/sbin",
+    "/usr",
+    "/root",
+    "/dev",
+    "/sys",
+    "/proc",
+    "/System",
+    "/Library",
+    "/private/etc",
+)
+
+BLOCKED_WINDOWS_PREFIXES = (
+    "c:/windows",
+    "c:/program files",
+    "c:/program files (x86)",
+    "c:/programdata",
+    "d:/windows",
+)
+
+BLOCKED_USER_TARGETS = (
+    ".ssh",
+    ".gnupg",
+    ".aws",
+    ".config",
+    ".bashrc",
+    ".bash_profile",
+    ".zshrc",
+    ".zprofile",
+    ".profile",
+    "id_rsa",
+    "id_ed25519",
+)
+
+
+def validate_safe_export_path(
+    path: str,
+    allowed_extensions: Optional[set[str]] = None,
+) -> str:
+    """
+    Validate and return an absolute path for safe file exports.
+
+    Raises SecurityValidationError or ValueError if path is invalid or attempts traversal.
+    """
+    if not path or not isinstance(path, str):
+        raise ValueError("Export path must be a non-empty string.")
+
+    if "\0" in path:
+        raise SecurityValidationError("Null byte detected in file path.")
+
+    # Check raw path for cross-platform Windows system paths (regardless of host OS)
+    p_norm = path.replace("\\", "/").lower().strip()
+    for win_prefix in BLOCKED_WINDOWS_PREFIXES:
+        if p_norm == win_prefix or p_norm.startswith(win_prefix + "/"):
+            raise SecurityValidationError(
+                f"Export path '{path}' resolves to protected Windows system location '{win_prefix}'."
+            )
+
+    # Prevent UNC network share paths (e.g. \\server\share or //server/share)
+    if p_norm.startswith("//"):
+        raise SecurityValidationError("UNC network paths are not permitted for exports.")
+
+    # Enforce allowed extension if specified
+    if allowed_extensions:
+        _, ext = os.path.splitext(path)
+        ext_clean = ext.lower().lstrip(".")
+        allowed_clean = {e.lower().lstrip(".") for e in allowed_extensions}
+        if ext_clean not in allowed_clean:
+            raise SecurityValidationError(
+                f"Invalid file extension '{ext}'. Allowed extensions: {sorted(allowed_clean)}"
+            )
+
+    abs_path = os.path.abspath(path)
+    real_path = os.path.realpath(abs_path)
+
+    # Check blocked system path prefixes across both real_path and abs_path
+    for prefix in BLOCKED_PATH_PREFIXES:
+        if real_path == prefix or real_path.startswith(prefix + os.sep) or abs_path == prefix or abs_path.startswith(prefix + os.sep):
+            raise SecurityValidationError(
+                f"Export path '{path}' resolves to protected system directory '{prefix}'."
+            )
+
+    # Check sensitive user targets across both real_path and abs_path
+    home = os.path.expanduser("~")
+    for sensitive in BLOCKED_USER_TARGETS:
+        sensitive_full = os.path.join(home, sensitive)
+        if (
+            real_path == sensitive_full
+            or real_path.startswith(sensitive_full + os.sep)
+            or abs_path == sensitive_full
+            or abs_path.startswith(sensitive_full + os.sep)
+        ):
+            raise SecurityValidationError(
+                f"Export path '{path}' resolves to protected user location '{sensitive}'."
+            )
+
+    return abs_path

leadintel/tools/__init__.py

@@ -0,0 +1,38 @@
+"""MCP tools package — registers all tools on the shared MCPServer instance."""
+
+from mcp.server.mcpserver import MCPServer
+
+from . import (
+    analyze_website,
+    check_seo,
+    compare_businesses,
+    export_leads,
+    find_business_website,
+    find_competitors,
+    find_social_profiles,
+    generate_business_insights,
+    generate_business_report,
+    generate_outreach,
+    get_business_details,
+    get_saved_leads,
+    score_lead,
+    search_businesses,
+)
+
+
+def register_all(mcp: MCPServer) -> None:
+    """Register every tool on the provided MCP server."""
+    search_businesses.register(mcp)
+    get_business_details.register(mcp)
+    get_saved_leads.register(mcp)
+    find_business_website.register(mcp)
+    analyze_website.register(mcp)
+    check_seo.register(mcp)
+    find_social_profiles.register(mcp)
+    find_competitors.register(mcp)
+    compare_businesses.register(mcp)
+    score_lead.register(mcp)
+    generate_business_insights.register(mcp)
+    generate_outreach.register(mcp)
+    generate_business_report.register(mcp)
+    export_leads.register(mcp)

leadintel/tools/analyze_website.py

@@ -0,0 +1,57 @@
+"""
+MCP Tool: analyze_website
+
+Comprehensive diagnostic tool for evaluating website availability,
+mobile readiness, HTML structure, contact channels, and broken internal links.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.mcpserver import MCPServer
+
+from ..services.website_analyzer import analyze_target_website
+
+
+def register(mcp: MCPServer) -> None:
+    """Register analyze_website tool on the MCP server."""
+
+    @mcp.tool()
+    async def analyze_website(
+        url: str,
+        check_broken_links: bool = True,
+    ) -> dict[str, Any]:
+        """
+        Analyze a business website for technical readiness, structure, and contacts.
+
+        Performs non-invasive examination of the target website:
+        - HTTP/HTTPS status and SSL verification.
+        - Title, meta description, and mobile viewport configuration.
+        - H1/H2 heading hierarchy and image alt tag presence.
+        - Public email addresses, telephone numbers, and contact forms.
+        - Linked social media profiles.
+        - Sampled check for broken internal links.
+
+        Security & Compliance:
+        - Respects robots.txt directives before scraping.
+        - Protects against SSRF (blocks localhost, private networks, cloud metadata).
+        - Enforces request timeouts and max page size limits.
+        - Does not scrape private or sensitive personal info.
+
+        Args:
+            url: The target website URL (e.g. 'https://example.com').
+            check_broken_links: If True, spot-checks up to 10 internal links for broken status (default: True).
+
+        Returns:
+            Structured diagnostic dictionary.
+        """
+        try:
+            return await analyze_target_website(url=url, check_broken_links=check_broken_links)
+        except Exception as exc:
+            return {
+                "status": "error",
+                "url": url,
+                "available": False,
+                "error": str(exc),
+            }

leadintel/tools/check_seo.py

@@ -0,0 +1,64 @@
+"""
+MCP Tool: check_seo
+
+Custom, free Python SEO audit tool evaluating on-page metadata,
+headings, robots.txt, sitemaps, open graph, and link architecture.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.mcpserver import MCPServer
+
+from ..services.seo_auditor import run_full_seo_audit
+
+
+def register(mcp: MCPServer) -> None:
+    """Register check_seo tool on the MCP server."""
+
+    @mcp.tool()
+    async def check_seo(
+        url: str,
+    ) -> dict[str, Any]:
+        """
+        Run a technical on-page SEO audit on a business website.
+
+        Evaluates fundamental search engine optimization signals:
+        - Missing or duplicate title tags and length bounds.
+        - Missing or suboptimal meta descriptions.
+        - Missing H1 or multiple H1 heading tags.
+        - Missing image alt attributes and overall image alt coverage percentage.
+        - Canonical URL link specification.
+        - Meta robots directives (noindex/nofollow).
+        - Availability of robots.txt and sitemap.xml.
+        - Open Graph tags for social preview readiness.
+        - Internal link count and page weight.
+
+        Output:
+        - SEO score from 0 to 100.
+        - Detailed checklist breakdown.
+        - Specific prioritized issues (errors, warnings, info).
+        - Actionable recommendations.
+
+        Notice:
+        This is an on-page technical SEO diagnostic tool and not an official
+        Google ranking assessment or proprietary PageRank score.
+
+        Args:
+            url: The target website URL (e.g. 'https://example.com').
+
+        Returns:
+            Structured SEO audit report.
+        """
+        try:
+            return await run_full_seo_audit(url=url)
+        except Exception as exc:
+            return {
+                "seo_score": 0,
+                "url": url,
+                "error": str(exc),
+                "disclaimer": "This technical audit requires a reachable, valid website URL.",
+                "issues": [{"level": "error", "message": f"Could not perform audit: {exc}"}],
+                "recommendations": ["Verify website is publicly accessible and URL is correct."],
+            }

leadintel/tools/compare_businesses.py

@@ -0,0 +1,65 @@
+"""
+MCP Tool: compare_businesses
+
+Benchmark a target business against one or more competitors, generating
+a side-by-side comparison matrix, strengths, weaknesses, and digital opportunities.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.mcpserver import MCPServer
+
+from ..services.business_comparison import compare_target_against_competitors
+
+
+def register(mcp: MCPServer) -> None:
+    """Register compare_businesses tool on the MCP server."""
+
+    @mcp.tool()
+    async def compare_businesses(
+        target_business: dict[str, Any],
+        competitor_businesses: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """
+        Compare a target business against a list of competitor businesses.
+
+        Benchmarks organizations across critical digital and operational dimensions:
+        - Website availability & response time
+        - Technical SEO score (0-100)
+        - HTTPS/SSL security configuration
+        - Mobile viewport readiness
+        - Social media footprint (channels active)
+        - Contact accessibility (forms, direct email, direct phone)
+        - Public reviews and ratings where available
+
+        Outputs:
+        - Structured comparison table matrix
+        - High-confidence strengths
+        - Critical digital weaknesses
+        - High-leverage growth opportunities
+        - Executive competitive positioning summary
+
+        Args:
+            target_business: Dict representing target company. Must include 'name', optional 'website', 'category', 'city'.
+            competitor_businesses: List of dicts representing competitor companies to benchmark against.
+
+        Returns:
+            Comprehensive competitive intelligence comparison report.
+        """
+        try:
+            return await compare_target_against_competitors(
+                target_business=target_business,
+                competitors=competitor_businesses,
+            )
+        except Exception as exc:
+            return {
+                "error": str(exc),
+                "target_business": target_business.get("name") if isinstance(target_business, dict) else str(target_business),
+                "comparison_matrix": [],
+                "strengths": [],
+                "weaknesses": [],
+                "opportunities": [],
+                "competitive_positioning_summary": f"Comparison failed: {exc}",
+            }

leadintel/tools/export_leads.py

@@ -0,0 +1,112 @@
+"""MCP tool: export_leads — search + export to CSV, JSON, or Excel."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from datetime import datetime
+from typing import Literal, Optional
+
+from mcp.server.mcpserver import MCPServer
+
+from ..config import settings
+from ..exporters.csv_exporter import export_to_csv
+from ..exporters.excel_exporter import export_to_excel
+from ..providers import build_registry
+from ..storage.path_validator import validate_safe_export_path
+
+OSM_ATTRIBUTION = "Data © OpenStreetMap contributors, ODbL 1.0 — https://www.openstreetmap.org/copyright"
+
+_registry = build_registry(settings)
+
+
+def register(mcp: MCPServer) -> None:
+    """Register export_leads tool on the MCP server."""
+
+    @mcp.tool()
+    async def export_leads(
+        query: str,
+        location: Optional[str] = None,
+        category: Optional[str] = None,
+        limit: int = 50,
+        format: Literal["csv", "json", "excel", "xlsx"] = "csv",
+        output_path: Optional[str] = None,
+    ) -> dict:
+        """
+        Search for businesses and export results to an Excel (.xlsx), CSV, or JSON file.
+
+        Features:
+        - Excel: Creates a multi-sheet workbook with frozen headers, auto-filters, and clean styling.
+        - CSV: Standard tabular spreadsheet export.
+        - JSON: Complete structured lead metadata with timestamps and attribution.
+
+        Args:
+            query: Free-text search term (e.g. 'cafe', 'software').
+            location: City, region, or coordinates.
+            category: Industry or category filter.
+            limit: Max number of leads to export (1-200, default 50).
+            format: 'excel' (or 'xlsx'), 'csv' (default), or 'json'.
+            output_path: Destination file path (optional).
+
+        Returns:
+            Dict containing output_path, row_count, format, and data attribution.
+        """
+        limit = max(1, min(limit, 200))
+
+        businesses, provider_name = await _registry.search(
+            query=query,
+            location=location,
+            category=category,
+            limit=limit,
+        )
+
+        is_osm = provider_name == "openstreetmap"
+        fmt = format.lower()
+        if fmt in ("excel", "xlsx"):
+            ext = "xlsx"
+        elif fmt == "json":
+            ext = "json"
+        else:
+            ext = "csv"
+
+        if not output_path:
+            ts = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
+            fname = f"leadintel_export_{ts}.{ext}"
+            output_path = os.path.join(tempfile.gettempdir(), fname)
+
+        # Execute export
+        if ext == "xlsx":
+            abs_path = export_to_excel(businesses=businesses, output_path=output_path)
+        elif ext == "json":
+            abs_path = _write_json(businesses, output_path, provider_name)
+        else:
+            abs_path = export_to_csv(businesses, output_path=output_path)
+
+        return {
+            "output_path": abs_path,
+            "row_count": len(businesses),
+            "format": ext,
+            "provider": provider_name,
+            "attribution": OSM_ATTRIBUTION if is_osm else None,
+            "note": (
+                f"Exported {len(businesses)} leads to {ext.upper()}. "
+                + (f"Attribution: {OSM_ATTRIBUTION}" if is_osm else "")
+            ).strip(),
+        }
+
+
+def _write_json(businesses, output_path: str, provider_name: str) -> str:
+    safe_path = validate_safe_export_path(output_path, allowed_extensions={"json"})
+    os.makedirs(os.path.dirname(safe_path) or ".", exist_ok=True)
+    payload = {
+        "leadintel_export": True,
+        "provider": provider_name,
+        "attribution": OSM_ATTRIBUTION if provider_name == "openstreetmap" else None,
+        "exported_at": datetime.utcnow().isoformat(),
+        "count": len(businesses),
+        "businesses": [b.model_dump(mode="json") for b in businesses],
+    }
+    with open(safe_path, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2, ensure_ascii=False)
+    return safe_path