validate_spec

Instructions

Implementation Reference

• server.py:322-392 (handler)

  The main handler function for the validate_spec tool. Registered via @mcp.tool() decorator (line 322). It validates an OpenAPI spec JSON string by: (1) checking access/rate limits, (2) parsing JSON, (3) validating presence of 'openapi', 'info.title', 'info.version', 'paths', (4) validating paths start with '/', (5) validating HTTP methods, (6) warning on missing responses. Returns {'valid': bool, 'errors': list, 'warnings': list}.

  @mcp.tool()
  def validate_spec(spec_json: str, api_key: str = "") -> dict:
      """Validate an OpenAPI spec for common issues.
  
      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.
  
      Args:
          spec_json (str): The spec json 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.
      """
      allowed, msg, tier = check_access(api_key)
      if not allowed:
          return {"error": msg, "upgrade_url": "https://meok.ai/pricing"}
  
      if not _check_rate():
          return {"error": "Rate limit exceeded (50/day)"}
      try:
          spec = json.loads(spec_json)
      except json.JSONDecodeError:
          return {"valid": False, "errors": ["Invalid JSON"]}
      errors = []
      warnings = []
      if "openapi" not in spec:
          errors.append("Missing 'openapi' version field")
      if "info" not in spec:
          errors.append("Missing 'info' object")
      else:
          if "title" not in spec["info"]:
              errors.append("Missing 'info.title'")
          if "version" not in spec["info"]:
              errors.append("Missing 'info.version'")
      if "paths" not in spec:
          errors.append("Missing 'paths' object")
      else:
          for path, methods in spec["paths"].items():
              if not path.startswith("/"):
                  errors.append(f"Path '{path}' must start with /")
              for method, definition in methods.items():
                  if method not in ("get", "post", "put", "patch", "delete", "head", "options", "trace"):
                      errors.append(f"Invalid method '{method}' on {path}")
                  if "responses" not in definition:
                      warnings.append(f"{method.upper()} {path} has no responses defined")
      return {"valid": len(errors) == 0, "errors": errors, "warnings": warnings}

• server.py:322-322 (registration)

  The tool is registered with the MCP server using the @mcp.tool() decorator on the validate_spec function.

  @mcp.tool()