generate_endpoint

Instructions

Implementation Reference

• server.py:33-118 (handler)

  The main handler function for the 'generate_endpoint' MCP tool. It is decorated with @mcp.tool() (line 32), accepts path, method, summary, request_body, response_description, and api_key parameters, performs access check and rate limiting, constructs an OpenAPI endpoint definition dictionary with operationId, responses, optional requestBody (from comma-separated fields), and path parameters extracted via regex, and returns a dict with path, method, and definition.

  def generate_endpoint(
      path: str, method: str, summary: str, request_body: Optional[str] = None, response_description: str = "Successful response"
  , api_key: str = "") -> dict:
      """Generate an OpenAPI endpoint definition from a description.
  
      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:
          path (str): The path to analyze or process.
          method (str): The method to analyze or process.
          summary (str): The summary to analyze or process.
          request_body (Optional[str]): The request body to analyze or process.
          response_description (str): The response description 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)"}
      method = method.lower()
      if method not in ("get", "post", "put", "patch", "delete", "head", "options"):
          return {"error": f"Invalid HTTP method: {method}"}
      endpoint: dict = {
          "summary": summary,
          "operationId": path.strip("/").replace("/", "_").replace("{", "").replace("}", "") + f"_{method}",
          "responses": {
              "200": {
                  "description": response_description,
                  "content": {"application/json": {"schema": {"type": "object"}}},
              },
              "400": {"description": "Bad request"},
              "500": {"description": "Internal server error"},
          },
      }
      if request_body and method in ("post", "put", "patch"):
          fields = [f.strip() for f in request_body.split(",")]
          properties = {}
          for field in fields:
              parts = field.split(":")
              fname = parts[0].strip()
              ftype = parts[1].strip() if len(parts) > 1 else "string"
              properties[fname] = {"type": ftype}
          endpoint["requestBody"] = {
              "required": True,
              "content": {
                  "application/json": {
                      "schema": {"type": "object", "properties": properties, "required": list(properties.keys())},
                  }
              },
          }
      params = []
      import re
      for match in re.finditer(r"\{(\w+)\}", path):
          params.append({"name": match.group(1), "in": "path", "required": True, "schema": {"type": "string"}})
      if params:
          endpoint["parameters"] = params
      return {"path": path, "method": method, "definition": endpoint}

• server.py:32-33 (registration)

  The tool is registered with MCP via the @mcp.tool() decorator on line 32, which registers 'generate_endpoint' as a callable tool on the FastMCP instance.

  @mcp.tool()
  def generate_endpoint(