generate_saq

Instructions

Implementation Reference

• server.py:516-596 (handler)

  The core handler function for the generate_saq tool. Decorated with @mcp.tool(), it takes organization_name, saq_type, caller, and api_key params. It validates auth, rate limits, looks up the SAQ type from SAQ_TYPES dict, maps applicable PCI requirements from PCI_REQUIREMENTS, and returns a JSON document with SAQ template data including requirement checks, attestation, and disclaimer.

  @mcp.tool()
  def generate_saq(
      organization_name: str,
      saq_type: str = "D",
      caller: str = "",
      api_key: str = "",
  ) -> str:
      """Generate a PCI DSS Self-Assessment Questionnaire template.
  
      Behavior:
          This tool generates structured output without modifying external systems.
          Output is deterministic for identical inputs. No side effects.
          Free tier: 10/day rate limit. Pro tier: unlimited.
          No authentication required for basic usage.
  
      When to use:
          Use this tool when you need to assess, audit, or verify compliance
          requirements. Ideal for gap analysis, readiness checks, and generating
          compliance documentation.
  
      When NOT to use:
          Do not use as a substitute for qualified legal counsel. This tool
          provides technical compliance guidance, not legal advice.
  
      Args:
          organization_name (str): The organization name to analyze or process.
          saq_type (str): The saq type to analyze or process.
          api_key (str): The api key to analyze or process.
  
      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.
      """
      if err := _check_auth(api_key):
          return err
      if err := _rl(caller):
          return err
  
      saq_type_upper = saq_type.upper()
      if saq_type_upper not in SAQ_TYPES:
          return json.dumps({"error": f"Invalid SAQ type. Valid: {list(SAQ_TYPES.keys())}"})
  
      saq = SAQ_TYPES[saq_type_upper]
      applicable_reqs = []
      for req_id in saq["requirements"]:
          req = PCI_REQUIREMENTS[req_id]
          applicable_reqs.append({
              "requirement": req_id,
              "name": req["name"],
              "checks": req["checks"],
              "status": "NOT_ASSESSED",
          })
  
      return json.dumps({
          "document_type": f"PCI DSS SAQ {saq_type_upper}",
          "pci_dss_version": "4.0",
          "organization": organization_name,
          "generated": datetime.now().isoformat(),
          "saq_type": saq_type_upper,
          "saq_description": saq["description"],
          "applicable_requirements": applicable_reqs,
          "total_requirements": len(applicable_reqs),
          "attestation": {
              "merchant_name": organization_name,
              "date": "",
              "signature": "",
              "title": "",
          },
          "disclaimer": "TEMPLATE ONLY. Complete assessment with a Qualified Security Assessor (QSA) for validation.",
      }, indent=2)

• server.py:516-517 (registration)

  Tool registration via @mcp.tool() decorator on the generate_saq function. Uses FastMCP framework to expose the function as an MCP tool named 'generate_saq'.

  @mcp.tool()
  def generate_saq(

• server.py:30-33 (helper)

  Helper function _check_auth used by generate_saq to validate the API key against the MEOK_API_KEY environment variable.

  def _check_auth(api_key: str = "") -> str | None:
      if _MEOK_API_KEY and api_key != _MEOK_API_KEY:
          return "Invalid API key. Get one at https://meok.ai/api-keys"
      return None

• server.py:41-53 (helper)

  Helper function _rl (rate limiter) used by generate_saq to enforce the free tier limit of 10 calls/day per caller.

  def _rl(caller: str = "anonymous", tier: str = "free") -> Optional[str]:
      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 (
              f"Free tier limit ({FREE_DAILY_LIMIT}/day). "
              "Upgrade: https://meok.ai/mcp/pci-dss/pro"
          )
      _usage[caller].append(now)
      return None

• server.py:85-94 (schema)

  SAQ_TYPES dictionary defining all valid SAQ types (A, A-EP, B, B-IP, C, C-VT, D, P2PE) with descriptions and required PCI requirement IDs. Used by generate_saq for validation and data lookup.

  SAQ_TYPES = {
      "A": {"description": "Card-not-present merchants, all cardholder data functions fully outsourced", "requirements": ["2", "6", "8", "9", "12"]},
      "A-EP": {"description": "E-commerce merchants with website that impacts payment security", "requirements": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12"]},
      "B": {"description": "Merchants using imprint machines or standalone dial-out terminals", "requirements": ["3", "4", "7", "9", "12"]},
      "B-IP": {"description": "Merchants using standalone IP-connected PTS POI terminals", "requirements": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12"]},
      "C": {"description": "Merchants with payment application systems connected to Internet", "requirements": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12"]},
      "C-VT": {"description": "Merchants using virtual terminals on isolated computers", "requirements": ["2", "3", "4", "6", "8", "9", "12"]},
      "D": {"description": "All other merchants and all service providers", "requirements": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12"]},
      "P2PE": {"description": "Merchants using validated P2PE solutions", "requirements": ["3", "9", "12"]},
  }