generate_full_spec

Instructions

Implementation Reference

• server.py:182-182 (registration)

  Tool registration via @mcp.tool() decorator

  @mcp.tool()

• server.py:182-252 (handler)

  Handler function that generates a complete OpenAPI 3.0 spec from title, description, version, and a JSON array of endpoint definitions. Parses endpoints, builds path/method entries, and returns the full spec object.

  @mcp.tool()
  def generate_full_spec(
      title: str, description: str, version: str = "1.0.0", endpoints_json: str = "[]"
  , api_key: str = "") -> dict:
      """Generate a complete OpenAPI 3.0 spec. Pass endpoints_json as a JSON array of {path, method, summary} objects.
  
      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 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:
          title (str): The title to analyze or process.
          description (str): The description to analyze or process.
          version (str): The version to analyze or process.
          endpoints_json (str): The endpoints 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:
          endpoints = json.loads(endpoints_json)
      except json.JSONDecodeError:
          return {"error": "Invalid JSON for endpoints_json"}
      paths: dict = {}
      for ep in endpoints:
          p = ep.get("path", "/")
          m = ep.get("method", "get").lower()
          s = ep.get("summary", "")
          if p not in paths:
              paths[p] = {}
          paths[p][m] = {
              "summary": s,
              "operationId": p.strip("/").replace("/", "_") + f"_{m}",
              "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}},
          }
      spec = {
          "openapi": "3.0.3",
          "info": {"title": title, "description": description, "version": version},
          "paths": paths,
          "components": {"schemas": {}},
      }
      return {"spec": spec}

• server.py:23-29 (helper)

  Rate limiting helper used by generate_full_spec to enforce 50 calls/day limit

  def _check_rate() -> bool:
      now = time.time()
      _calls[:] = [t for t in _calls if now - t < 86400]
      if len(_calls) >= DAILY_LIMIT:
          return False
      _calls.append(now)
      return True

• auth_middleware.py:103-135 (helper)

  Authentication and access control helper imported from auth_middleware; called by generate_full_spec to check API key and tier limits

  def check_access(api_key: str = "", framework: str = None) -> Tuple[bool, str, Tier]:
      """
      Main access control function. Returns (allowed, message, tier).
      Call at the start of every tool.
      """
      tier = get_tier_from_api_key(api_key)
      limits = TIER_LIMITS[tier]
      
      # Rate limit check
      usage = _load_json(USAGE_FILE)
      today = time.strftime("%Y-%m-%d")
      key_hash = hashlib.sha256((api_key or "anon").encode()).hexdigest()[:12]
      day_key = f"{key_hash}:{today}"
      
      current = usage.get(day_key, 0)
      max_calls = limits["calls_per_day"]
      
      if max_calls != -1 and current >= max_calls:
          return (
              False,
              f"Rate limit reached ({max_calls}/day on {tier.value} tier). "
              f"Upgrade at https://meok.ai/pricing",
              tier,
          )
      
      # Record usage
      usage[day_key] = current + 1
      # Clean old entries (keep last 7 days)
      cutoff = time.strftime("%Y-%m-%d", time.localtime(time.time() - 7 * 86400))
      usage = {k: v for k, v in usage.items() if k.split(":")[1] >= cutoff}
      _save_json(USAGE_FILE, usage)
      
      return True, "OK", tier