check_cardholder_data

Instructions

Implementation Reference

• server.py:218-313 (handler)

  The check_cardholder_data function is an MCP tool decorated with @mcp.tool() that analyzes cardholder data flow for PCI DSS compliance. It checks for violations (CVV/PIN/track data storage, unprotected PAN, unmasked PAN), assesses scope reduction measures (tokenization, encryption, truncation), and returns a JSON compliance report.

  @mcp.tool()
  def check_cardholder_data(
      data_flow_description: str,
      stores_pan: bool = False,
      stores_cvv: bool = False,
      stores_pin: bool = False,
      stores_track_data: bool = False,
      pan_encrypted: bool = False,
      pan_truncated: bool = False,
      tokenization_used: bool = False,
      caller: str = "",
      api_key: str = "",
  ) -> str:
      """Analyze cardholder data flow for PCI DSS compliance.
  
      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 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:
          data_flow_description (str): The data flow description to analyze or process.
          stores_pan (bool): The stores pan to analyze or process.
          stores_cvv (bool): The stores cvv to analyze or process.
          stores_pin (bool): The stores pin to analyze or process.
          stores_track_data (bool): The stores track data to analyze or process.
          pan_encrypted (bool): The pan encrypted to analyze or process.
          pan_truncated (bool): The pan truncated to analyze or process.
          tokenization_used (bool): The tokenization used 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
  
      issues = []
      if stores_cvv:
          issues.append({"violation": "CVV/CVC storage prohibited", "requirement": "3.3.1",
                          "severity": "CRITICAL", "remediation": "Never store CVV/CVC after authorization"})
      if stores_pin:
          issues.append({"violation": "PIN storage prohibited", "requirement": "3.3.1",
                          "severity": "CRITICAL", "remediation": "Never store PIN data after authorization"})
      if stores_track_data:
          issues.append({"violation": "Full track data storage prohibited", "requirement": "3.3.1",
                          "severity": "CRITICAL", "remediation": "Never store full track data after authorization"})
      if stores_pan and not pan_encrypted and not tokenization_used:
          issues.append({"violation": "PAN stored without protection", "requirement": "3.5.1",
                          "severity": "HIGH", "remediation": "Encrypt PAN at rest or use tokenization"})
      if stores_pan and not pan_truncated and not pan_encrypted:
          issues.append({"warning": "PAN displayed without masking", "requirement": "3.4.1",
                          "severity": "MEDIUM", "remediation": "Mask PAN when displayed (show max first 6 / last 4)"})
  
      scope_reduction = []
      if tokenization_used:
          scope_reduction.append("Tokenization reduces PCI scope for stored data")
      if pan_encrypted:
          scope_reduction.append("Encryption at rest meets Requirement 3.5")
      if pan_truncated:
          scope_reduction.append("Truncation removes PAN from scope when properly implemented")
  
      return json.dumps({
          "data_flow": data_flow_description,
          "assessment_date": datetime.now().isoformat(),
          "sensitive_auth_data": {"cvv": stores_cvv, "pin": stores_pin, "track_data": stores_track_data},
          "pan_storage": {"stored": stores_pan, "encrypted": pan_encrypted, "truncated": pan_truncated, "tokenized": tokenization_used},
          "compliance_status": "COMPLIANT" if not issues else "NON_COMPLIANT",
          "issues": issues,
          "scope_reduction_notes": scope_reduction,
      }, indent=2)

• server.py:218-313 (registration)

  The tool is registered via the @mcp.tool() decorator on line 218, which registers it with the FastMCP server instance created on line 99. No separate registration call is needed; the decorator handles it automatically.

  @mcp.tool()
  def check_cardholder_data(
      data_flow_description: str,
      stores_pan: bool = False,
      stores_cvv: bool = False,
      stores_pin: bool = False,
      stores_track_data: bool = False,
      pan_encrypted: bool = False,
      pan_truncated: bool = False,
      tokenization_used: bool = False,
      caller: str = "",
      api_key: str = "",
  ) -> str:
      """Analyze cardholder data flow for PCI DSS compliance.
  
      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 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:
          data_flow_description (str): The data flow description to analyze or process.
          stores_pan (bool): The stores pan to analyze or process.
          stores_cvv (bool): The stores cvv to analyze or process.
          stores_pin (bool): The stores pin to analyze or process.
          stores_track_data (bool): The stores track data to analyze or process.
          pan_encrypted (bool): The pan encrypted to analyze or process.
          pan_truncated (bool): The pan truncated to analyze or process.
          tokenization_used (bool): The tokenization used 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
  
      issues = []
      if stores_cvv:
          issues.append({"violation": "CVV/CVC storage prohibited", "requirement": "3.3.1",
                          "severity": "CRITICAL", "remediation": "Never store CVV/CVC after authorization"})
      if stores_pin:
          issues.append({"violation": "PIN storage prohibited", "requirement": "3.3.1",
                          "severity": "CRITICAL", "remediation": "Never store PIN data after authorization"})
      if stores_track_data:
          issues.append({"violation": "Full track data storage prohibited", "requirement": "3.3.1",
                          "severity": "CRITICAL", "remediation": "Never store full track data after authorization"})
      if stores_pan and not pan_encrypted and not tokenization_used:
          issues.append({"violation": "PAN stored without protection", "requirement": "3.5.1",
                          "severity": "HIGH", "remediation": "Encrypt PAN at rest or use tokenization"})
      if stores_pan and not pan_truncated and not pan_encrypted:
          issues.append({"warning": "PAN displayed without masking", "requirement": "3.4.1",
                          "severity": "MEDIUM", "remediation": "Mask PAN when displayed (show max first 6 / last 4)"})
  
      scope_reduction = []
      if tokenization_used:
          scope_reduction.append("Tokenization reduces PCI scope for stored data")
      if pan_encrypted:
          scope_reduction.append("Encryption at rest meets Requirement 3.5")
      if pan_truncated:
          scope_reduction.append("Truncation removes PAN from scope when properly implemented")
  
      return json.dumps({
          "data_flow": data_flow_description,
          "assessment_date": datetime.now().isoformat(),
          "sensitive_auth_data": {"cvv": stores_cvv, "pin": stores_pin, "track_data": stores_track_data},
          "pan_storage": {"stored": stores_pan, "encrypted": pan_encrypted, "truncated": pan_truncated, "tokenized": tokenization_used},
          "compliance_status": "COMPLIANT" if not issues else "NON_COMPLIANT",
          "issues": issues,
          "scope_reduction_notes": scope_reduction,
      }, indent=2)

• server.py:218-313 (schema)

  Input schema is defined by the function signature (lines 219-230): data_flow_description (str), stores_pan/cvv/pin/track_data (bool), pan_encrypted/truncated (bool), tokenization_used (bool), caller (str), api_key (str). Output is a JSON string with fields data_flow, assessment_date, sensitive_auth_data, pan_storage, compliance_status, issues, scope_reduction_notes.

  @mcp.tool()
  def check_cardholder_data(
      data_flow_description: str,
      stores_pan: bool = False,
      stores_cvv: bool = False,
      stores_pin: bool = False,
      stores_track_data: bool = False,
      pan_encrypted: bool = False,
      pan_truncated: bool = False,
      tokenization_used: bool = False,
      caller: str = "",
      api_key: str = "",
  ) -> str:
      """Analyze cardholder data flow for PCI DSS compliance.
  
      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 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:
          data_flow_description (str): The data flow description to analyze or process.
          stores_pan (bool): The stores pan to analyze or process.
          stores_cvv (bool): The stores cvv to analyze or process.
          stores_pin (bool): The stores pin to analyze or process.
          stores_track_data (bool): The stores track data to analyze or process.
          pan_encrypted (bool): The pan encrypted to analyze or process.
          pan_truncated (bool): The pan truncated to analyze or process.
          tokenization_used (bool): The tokenization used 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
  
      issues = []
      if stores_cvv:
          issues.append({"violation": "CVV/CVC storage prohibited", "requirement": "3.3.1",
                          "severity": "CRITICAL", "remediation": "Never store CVV/CVC after authorization"})
      if stores_pin:
          issues.append({"violation": "PIN storage prohibited", "requirement": "3.3.1",
                          "severity": "CRITICAL", "remediation": "Never store PIN data after authorization"})
      if stores_track_data:
          issues.append({"violation": "Full track data storage prohibited", "requirement": "3.3.1",
                          "severity": "CRITICAL", "remediation": "Never store full track data after authorization"})
      if stores_pan and not pan_encrypted and not tokenization_used:
          issues.append({"violation": "PAN stored without protection", "requirement": "3.5.1",
                          "severity": "HIGH", "remediation": "Encrypt PAN at rest or use tokenization"})
      if stores_pan and not pan_truncated and not pan_encrypted:
          issues.append({"warning": "PAN displayed without masking", "requirement": "3.4.1",
                          "severity": "MEDIUM", "remediation": "Mask PAN when displayed (show max first 6 / last 4)"})
  
      scope_reduction = []
      if tokenization_used:
          scope_reduction.append("Tokenization reduces PCI scope for stored data")
      if pan_encrypted:
          scope_reduction.append("Encryption at rest meets Requirement 3.5")
      if pan_truncated:
          scope_reduction.append("Truncation removes PAN from scope when properly implemented")
  
      return json.dumps({
          "data_flow": data_flow_description,
          "assessment_date": datetime.now().isoformat(),
          "sensitive_auth_data": {"cvv": stores_cvv, "pin": stores_pin, "track_data": stores_track_data},
          "pan_storage": {"stored": stores_pan, "encrypted": pan_encrypted, "truncated": pan_truncated, "tokenized": tokenization_used},
          "compliance_status": "COMPLIANT" if not issues else "NON_COMPLIANT",
          "issues": issues,
          "scope_reduction_notes": scope_reduction,
      }, indent=2)

• server.py:275-278 (helper)

  Helper functions used inside the handler: _check_auth (lines 30-33) validates the API key, and _rl (lines 41-53) enforces free tier rate limiting. Both are called at the top of the handler.

  if err := _check_auth(api_key):
      return err
  if err := _rl(caller):
      return err