quick_check

Instructions

Implementation Reference

• server.py:314-391 (handler)

  Main handler for the quick_check tool. Accepts a message string, checks rate limits, calculates scam score via _calculate_scam_score, classifies risk level (critical/high/moderate/low/minimal), and returns a structured response with scam_probability, risk_level, verdict, recommended_action, tactics_detected, pattern_details, and next_step.

  def quick_check(message: str) -> dict:
      """Paste any message (email, text, DM) -> instant scam probability score. No API key required.
  
      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.
      """
      limit_err = _check_rate_limit("quick_check_anonymous")
      if limit_err:
          return {"error": "rate_limited", "message": limit_err}
  
      scam_score, matched_patterns = _calculate_scam_score(message)
  
      # Classify risk level
      if scam_score >= 0.75:
          risk_level = "critical"
          verdict = "VERY LIKELY A SCAM"
          action = "Do NOT respond, click links, or provide any personal information. Block and report."
      elif scam_score >= 0.5:
          risk_level = "high"
          verdict = "LIKELY A SCAM"
          action = "Exercise extreme caution. Verify independently through official channels before taking any action."
      elif scam_score >= 0.3:
          risk_level = "moderate"
          verdict = "SUSPICIOUS"
          action = "Proceed with caution. Verify the sender and any claims through official channels."
      elif scam_score >= 0.15:
          risk_level = "low"
          verdict = "SLIGHTLY SUSPICIOUS"
          action = "Likely legitimate but contains some common scam indicators. Verify if unsure."
      else:
          risk_level = "minimal"
          verdict = "APPEARS LEGITIMATE"
          action = "No significant scam indicators detected. Standard caution applies."
  
      # Extract tactics used
      tactics_used = [p["pattern"] for p in matched_patterns]
  
      return {
          "scam_probability": round(scam_score, 2),
          "risk_level": risk_level,
          "verdict": verdict,
          "recommended_action": action,
          "tactics_detected": tactics_used,
          "pattern_details": matched_patterns[:5],
          "message_length": len(message),
          "next_step": (
              "Use detect_social_engineering for deeper manipulation analysis"
              if scam_score >= 0.3
              else "Use report_scam if you believe this is a scam"
          ),
          "meok_labs": "https://meok.ai",
      }

• server.py:249-293 (helper)

  Helper function that calculates overall scam probability score (0-1) by iterating over SCAM_PATTERNS, matching keywords via _match_keywords, and applying additional heuristics (ALL CAPS, excessive punctuation, currency signs, grammar red flags).

  def _calculate_scam_score(text):
      # type: (str) -> Tuple[float, List[Dict[str, object]]]
      """Calculate overall scam probability score. Returns (score 0-1, matched_patterns)."""
      total_weight = 0.0
      matches = []  # type: List[Dict[str, object]]
  
      for ptype, pinfo in SCAM_PATTERNS.items():
          matched = _match_keywords(text, pinfo["indicators"])
          if matched:
              total_weight += pinfo["weight"] * min(len(matched) / 3.0, 1.5)
              matches.append({
                  "pattern": pinfo["name"],
                  "weight": pinfo["weight"],
                  "matched_indicators": matched[:5],
                  "description": pinfo["description"],
              })
  
      # Additional heuristics
      text_lower = text.lower()
  
      # ALL CAPS sections
      caps_words = re.findall(r'\b[A-Z]{4,}\b', text)
      if len(caps_words) > 2:
          total_weight += 0.1
  
      # Excessive exclamation/question marks
      if text.count("!") > 3 or text.count("?") > 5:
          total_weight += 0.1
  
      # Multiple dollar/pound/euro signs
      currency_count = len(re.findall(r'[$\u00a3\u20ac]', text))
      if currency_count > 2:
          total_weight += 0.1
  
      # Grammar/spelling red flags (common in scams)
      grammar_flags = [
          "kindly", "dear sir", "dear madam", "dear friend", "dear customer",
          "do the needful", "revert back", "prepone",
      ]
      if _match_keywords(text, grammar_flags):
          total_weight += 0.15
  
      # Normalize to 0-1
      score = min(1.0, total_weight / 1.5)
      return score, matches

• server.py:242-246 (helper)

  Helper function that performs case-insensitive keyword matching, returning a list of matched keywords found in the input text.

  def _match_keywords(text, keywords):
      # type: (str, List[str]) -> List[str]
      """Return matched keywords found in text (case-insensitive)."""
      text_lower = text.lower()
      return [kw for kw in keywords if kw.lower() in text_lower]

• server.py:311-312 (registration)

  Registration of quick_check as an MCP tool via the @mcp.tool() decorator on FastMCP server instance at line 299.

  # Tool: quick_check -- ZERO config, no API key, instant result
  # ---------------------------------------------------------------------------

• server.py:57-72 (helper)

  Rate limit checker used by quick_check. Enforces a free tier limit of 10 calls/day, returning an error string if exceeded.

  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