quick_scan

Instructions

Implementation Reference

• server.py:279-279 (registration)

  The tool 'quick_scan' is registered as an MCP tool via the @mcp.tool() decorator on line 279.

  @mcp.tool()

• server.py:280-387 (handler)

  The handler function for 'quick_scan'. Takes a description string, checks rate limits, assesses transparency level, detects model type, checks for high-risk keywords, recommends explainability methods, and returns a structured response with transparency assessment.

  def quick_scan(description: str) -> dict:
      """Describe an AI system -> instant transparency and explainability assessment. 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_scan_anonymous")
      if limit_err:
          return {"error": "rate_limited", "message": limit_err}
  
      transparency_level, transparency_score, positive_signals = _assess_transparency_level(description)
      text_lower = description.lower()
  
      # Determine model type
      detected_type = "unknown"
      for mtype in MODEL_TYPES:
          if mtype in text_lower or (mtype == "nlp" and any(w in text_lower for w in ["language", "text", "chat", "llm"])):
              detected_type = mtype
              break
      if detected_type == "unknown" and any(w in text_lower for w in ["image", "vision", "photo", "video"]):
          detected_type = "computer_vision"
      if detected_type == "unknown" and any(w in text_lower for w in ["generat", "create", "synthes"]):
          detected_type = "generative"
      if detected_type == "unknown" and any(w in text_lower for w in ["recommend", "suggest", "personali"]):
          detected_type = "recommendation"
      if detected_type == "unknown" and any(w in text_lower for w in ["predict", "classif", "detect"]):
          detected_type = "classification"
  
      # Determine if high-risk (needs full transparency)
      high_risk_keywords = [
          "hiring", "recruit", "loan", "credit", "insurance", "medical", "diagnosis",
          "judicial", "law enforcement", "biometric", "education", "grading",
      ]
      is_high_risk = bool(_match_keywords(description, high_risk_keywords))
  
      # Recommend explainability methods
      recommended_methods = []  # type: List[str]
      if detected_type in MODEL_TYPES:
          method_keys = MODEL_TYPES[detected_type]["explainability_methods"]
          for mk in method_keys:
              if mk in EXPLAINABILITY_METHODS:
                  recommended_methods.append(EXPLAINABILITY_METHODS[mk]["name"])
  
      # Build top actions
      if transparency_level == "low":
          top_actions = [
              "URGENT: Create model documentation covering purpose, capabilities, and limitations",
              "Implement at least one explainability method ({})".format(
                  recommended_methods[0] if recommended_methods else "SHAP or LIME"
              ),
              "Document known limitations and failure modes for deployers",
          ]
      elif transparency_level == "moderate":
          top_actions = [
              "Strengthen documentation with quantitative performance metrics per group",
              "Add human-readable decision explanations for end users",
              "Conduct a transparency audit against EU AI Act Article 13",
          ]
      else:
          top_actions = [
              "Good transparency baseline -- formalise into EU AI Act Article 13 compliant documentation",
              "Consider generating a model card for public disclosure",
              "Implement ongoing transparency monitoring for model updates",
          ]
  
      return {
          "transparency_level": transparency_level,
          "transparency_score": transparency_score,
          "positive_signals": positive_signals,
          "detected_model_type": detected_type,
          "is_high_risk": is_high_risk,
          "recommended_explainability_methods": recommended_methods if recommended_methods else ["SHAP", "LIME", "Counterfactual Explanations"],
          "top_3_actions": top_actions,
          "eu_ai_act_relevance": (
              "HIGH-RISK: Article 13 transparency obligations are MANDATORY. "
              "Full technical documentation per Annex IV required."
              if is_high_risk
              else "Transparency obligations under Article 50 may apply (user disclosure, content labelling)."
          ),
          "next_step": "Use generate_model_card for structured documentation or transparency_audit for full assessment",
          "meok_labs": "https://meok.ai",
      }

• server.py:280-311 (schema)

  The input schema is defined by type hints: description: str -> dict. No Pydantic models used; validation is via inline type hints and the function docstring.

  def quick_scan(description: str) -> dict:
      """Describe an AI system -> instant transparency and explainability assessment. 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.
      """

• server.py:223-259 (helper)

  Helper function _assess_transparency_level() used by quick_scan to evaluate transparency from the description text.

  def _assess_transparency_level(description):
      # type: (str) -> Tuple[str, float, List[str]]
      """Assess how transparent an AI system appears from its description."""
      text_lower = description.lower()
      score = 0.0
      positive_signals = []  # type: List[str]
      max_score = 12.0
  
      transparency_indicators = [
          ("document", "Documentation mentioned"),
          ("explain", "Explainability considered"),
          ("transparen", "Transparency explicitly addressed"),
          ("human oversight", "Human oversight mentioned"),
          ("audit", "Auditability considered"),
          ("log", "Logging capability mentioned"),
          ("monitor", "Monitoring mentioned"),
          ("bias", "Bias awareness mentioned"),
          ("fairness", "Fairness considered"),
          ("accuracy", "Accuracy metrics mentioned"),
          ("limitation", "Limitations acknowledged"),
          ("user inform", "User information provided"),
      ]
  
      for keyword, signal in transparency_indicators:
          if keyword in text_lower:
              score += 1.0
              positive_signals.append(signal)
  
      normalised = score / max_score
      if normalised >= 0.6:
          level = "high"
      elif normalised >= 0.3:
          level = "moderate"
      else:
          level = "low"
  
      return level, round(normalised, 2), positive_signals

• server.py:216-220 (helper)

  Helper function _match_keywords() used by quick_scan to detect high-risk keywords in the description.

  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]