verify_sender

Instructions

Implementation Reference

• server.py:668-668 (registration)

  The @mcp.tool() decorator registers 'verify_sender' as an MCP tool on the FastMCP server named 'Scam Detector'.

  @mcp.tool()

• server.py:669-849 (handler)

  The verify_sender function (handler) checks an email or phone number against known scam patterns. It detects free email providers, suspicious domain patterns, brand impersonation, premium-rate phone numbers, high-risk country codes, etc., and returns a risk score (0-1), verdict, findings, and recommended actions.

  def verify_sender(
      email_or_phone: str,
      api_key: str = "",
  ) -> dict:
      """Check sender patterns against known scam vectors.
  
      Args:
          email_or_phone: The email address or phone number to check.
          api_key: Optional MEOK API key for pro tier.
  
      Behavior:
          This tool is read-only and stateless — it produces analysis output
          without modifying any external systems, databases, or files.
          Safe to call repeatedly with identical inputs (idempotent).
          Free tier: 10/day rate limit. Pro tier: unlimited.
          No authentication required for basic usage.
  
      When to use:
          Use this tool when you need structured analysis or classification
          of inputs against established frameworks or standards.
  
      When NOT to use:
          Not suitable for real-time production decision-making without
          human review of results.
      Behavioral Transparency:
          - Side Effects: This tool is read-only and produces no side effects. It does not modify
            any external state, databases, or files. All output is computed in-memory and returned
            directly to the caller.
          - Authentication: No authentication required for basic usage. Pro/Enterprise tiers
            require a valid MEOK API key passed via the MEOK_API_KEY environment variable.
          - Rate Limits: Free tier: 10 calls/day. Pro tier: unlimited. Rate limit headers are
            included in responses (X-RateLimit-Remaining, X-RateLimit-Reset).
          - Error Handling: Returns structured error objects with 'error' key on failure.
            Never raises unhandled exceptions. Invalid inputs return descriptive validation errors.
          - Idempotency: Fully idempotent — calling with the same inputs always produces the
            same output. Safe to retry on timeout or transient failure.
          - Data Privacy: No input data is stored, logged, or transmitted to external services.
            All processing happens locally within the MCP server process.
      """
      allowed, msg, tier = check_access(api_key)
      if not allowed:
          return {"error": msg, "upgrade_url": "https://meok.ai/pricing"}
      limit_err = _check_rate_limit("verify_sender", tier)
      if limit_err:
          return {"error": "rate_limited", "message": limit_err}
  
      sender = email_or_phone.strip()
      findings = []  # type: List[Dict[str, str]]
      risk_score = 0.0
      sender_type = "unknown"
  
      # Detect if email or phone
      if "@" in sender:
          sender_type = "email"
  
          # Check for free email providers (higher scam risk for official communications)
          free_providers = [
              "gmail.com", "yahoo.com", "hotmail.com", "outlook.com", "aol.com",
              "mail.com", "protonmail.com", "yandex.com", "tutanota.com",
          ]
          domain = sender.split("@")[-1].lower()
  
          if domain in free_providers:
              findings.append({
                  "finding": "Free email provider",
                  "severity": "medium",
                  "detail": "Legitimate organisations typically use corporate domains, not {}".format(domain),
              })
              risk_score += 0.2
  
          # Check for suspicious domain patterns
          suspicious_domain_patterns = [
              (r"[0-9]{3,}", "Numbers in domain", 0.3),
              (r"(.)\1{3,}", "Repeated characters", 0.25),
              (r"-{2,}", "Multiple hyphens", 0.2),
              (r"\.(xyz|top|club|work|click|loan|win|gq|tk|ml|cf|ga)$", "Suspicious TLD", 0.35),
          ]
  
          for pattern, desc, weight in suspicious_domain_patterns:
              if re.search(pattern, domain):
                  findings.append({
                      "finding": desc,
                      "severity": "high" if weight > 0.25 else "medium",
                      "detail": "Domain '{}' matches suspicious pattern".format(domain),
                  })
                  risk_score += weight
  
          # Check for brand impersonation in domain
          brands = ["paypal", "amazon", "apple", "microsoft", "google", "netflix", "facebook", "instagram", "bank"]
          for brand in brands:
              if brand in domain and domain not in ["{}.com".format(brand), "{}.co.uk".format(brand)]:
                  findings.append({
                      "finding": "Possible brand impersonation",
                      "severity": "high",
                      "detail": "Domain contains '{}' but is not the official domain".format(brand),
                  })
                  risk_score += 0.4
                  break
  
          # Check local part for suspicious patterns
          local_part = sender.split("@")[0].lower()
          suspicious_locals = ["noreply", "no-reply", "support", "security", "admin", "help", "info"]
          if local_part in suspicious_locals:
              findings.append({
                  "finding": "Generic sender name",
                  "severity": "low",
                  "detail": "'{}' is commonly used in both legitimate and scam emails".format(local_part),
              })
              risk_score += 0.05
  
      elif re.search(r'\+?\d[\d\s\-]{6,}', sender):
          sender_type = "phone"
  
          # Check for premium rate numbers
          premium_prefixes = ["0900", "0901", "0906", "0907", "900", "976"]
          for prefix in premium_prefixes:
              if sender.replace(" ", "").replace("-", "").startswith(prefix):
                  findings.append({
                      "finding": "Premium rate number",
                      "severity": "high",
                      "detail": "Number starting with {} is a premium rate number -- calling it costs money".format(prefix),
                  })
                  risk_score += 0.5
  
          # Check for international prefixes (common in scams targeting specific countries)
          high_risk_country_codes = ["+233", "+234", "+225", "+228", "+221"]  # Ghana, Nigeria, Ivory Coast, Togo, Senegal
          for code in high_risk_country_codes:
              clean_sender = sender.replace(" ", "").replace("-", "")
              if clean_sender.startswith(code):
                  findings.append({
                      "finding": "High-risk country code",
                      "severity": "medium",
                      "detail": "Country code {} is statistically associated with higher scam rates".format(code),
                  })
                  risk_score += 0.25
  
          # Very short numbers (may be short codes -- some legitimate, some scam)
          digits_only = re.sub(r'[^\d]', '', sender)
          if len(digits_only) <= 5:
              findings.append({
                  "finding": "Short code number",
                  "severity": "low",
                  "detail": "Short codes can be legitimate (bank alerts) or used for scam texts",
              })
              risk_score += 0.1
  
      else:
          findings.append({
              "finding": "Unrecognised format",
              "severity": "low",
              "detail": "Could not determine if input is an email or phone number",
          })
  
      risk_score = min(1.0, risk_score)
  
      if risk_score >= 0.5:
          verdict = "HIGH RISK"
          action = "This sender shows multiple suspicious indicators. Do not engage."
      elif risk_score >= 0.25:
          verdict = "MODERATE RISK"
          action = "Some suspicious patterns detected. Verify through official channels."
      else:
          verdict = "LOW RISK"
          action = "No major red flags, but always verify unsolicited contacts independently."
  
      return {
          "sender": sender,
          "sender_type": sender_type,
          "risk_score": round(risk_score, 2),
          "verdict": verdict,
          "recommended_action": action,
          "findings": findings,
          "verification_tips": [
              "Search the sender address/number online for scam reports",
              "Contact the claimed organisation directly using their official website contact info",
              "Check the organisation's official website for legitimate contact addresses",
              "Report suspicious senders to your email provider or phone carrier",
          ],
          "next_step": "Use quick_check on the full message from this sender",
          "meok_labs": "https://meok.ai",
      }

• server.py:669-672 (schema)

  Input parameters: email_or_phone (str, required) and api_key (str, optional). Returns a dict with keys: sender, sender_type, risk_score, verdict, recommended_action, findings, verification_tips, next_step, meok_labs.

  def verify_sender(
      email_or_phone: str,
      api_key: str = "",
  ) -> dict:

• server.py:45-48 (helper)

  check_access() is called at line 708 to verify API key and determine tier (free/pro). Delegates to _shared_check_access which checks MEOK_API_KEY env var.

  def check_access(api_key=""):
      # type: (str) -> Tuple[bool, str, str]
      """Unified access check -- works with or without shared auth engine."""
      return _shared_check_access(api_key)

• server.py:57-72 (helper)

  _check_rate_limit() is called at line 711 to enforce the free tier daily limit (10 calls/day). Pro tier is unlimited.

  def _check_rate_limit(caller="anonymous", tier="free"):
      # type: (str, str) -> Optional[str]
      """Returns error string if rate-limited, else None."""
      if tier == "pro":
          return None
      now = datetime.now()
      cutoff = now - timedelta(days=1)
      _usage[caller] = [t for t in _usage[caller] if t > cutoff]
      if len(_usage[caller]) >= FREE_DAILY_LIMIT:
          return (
              "Free tier limit reached ({}/day). "
              "Upgrade to MEOK AI Labs Pro for unlimited access at $29/mo: "
              "https://meok.ai/mcp/scam-detector/pro".format(FREE_DAILY_LIMIT)
          )
      _usage[caller].append(now)
      return None