add_auth_to_spec

Instructions

Implementation Reference

• server.py:319-319 (registration)

  The @mcp.tool() decorator immediately above line 256 registers 'add_auth_to_spec' as an MCP tool named 'add_auth_to_spec'.

  return {"spec": spec}

• server.py:256-319 (handler)

  Main handler for add_auth_to_spec tool. Parses spec_json as JSON, validates auth_type against supported schemes (bearer, api_key, basic, oauth2), injects securitySchemes and security into the OpenAPI spec, and returns the augmented spec.

  def add_auth_to_spec(spec_json: str, auth_type: str = "bearer", api_key: str = "") -> dict:
      """Add authentication scheme to an OpenAPI spec. auth_type: bearer, api_key, basic, oauth2.
  
      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.
          auth_type (str): The auth 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.
      """
      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 {"error": "Invalid JSON for spec"}
      schemes = {
          "bearer": {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"},
          "api_key": {"type": "apiKey", "in": "header", "name": "X-API-Key"},
          "basic": {"type": "http", "scheme": "basic"},
          "oauth2": {
              "type": "oauth2",
              "flows": {"authorizationCode": {"authorizationUrl": "https://example.com/oauth/authorize", "tokenUrl": "https://example.com/oauth/token", "scopes": {"read": "Read access", "write": "Write access"}}},
          },
      }
      if auth_type not in schemes:
          return {"error": f"Unknown auth type: {auth_type}. Use: bearer, api_key, basic, oauth2"}
      if "components" not in spec:
          spec["components"] = {}
      spec["components"]["securitySchemes"] = {auth_type: schemes[auth_type]}
      spec["security"] = [{auth_type: []}]
      return {"spec": spec}