{
  "openapi": "3.1.0",
  "info": {
    "title": "ZGTS Derma Roller API",
    "version": "1.0.0",
    "description": "MCP-compatible API for ZGTS derma roller needle size recommendations, guide search, product info, and usage protocols. Powered by JSON-RPC 2.0 over HTTP (MCP Streamable HTTP transport). Register at https://smithery.ai/servers/ravi8585/zgts-derma-roller",
    "contact": {
      "name": "Color Papers India Pvt Ltd",
      "url": "https://zgts.in/docs",
      "email": "info@zgts.in"
    },
    "license": {
      "name": "MIT"
    },
    "termsOfService": "https://zgts.in/terms",
    "x-mcp-server": {
      "name": "zgts-derma-roller",
      "version": "1.0.0",
      "transport": "streamable-http",
      "endpoint": "https://zgts.in/api/mcp",
      "registry": "https://smithery.ai/servers/ravi8585/zgts-derma-roller",
      "authentication": "none",
      "capabilities": { "tools": true, "resources": true, "prompts": true }
    },
    "x-rateLimit": {
      "policy": "unlimited",
      "limit": null,
      "remaining": null,
      "reset": null,
      "description": "No rate limits — fully open public API. All requests are served without throttling or quota.",
      "headers": {
        "X-RateLimit-Limit": "unlimited",
        "X-RateLimit-Remaining": "unlimited",
        "X-RateLimit-Reset": "0",
        "X-RateLimit-Policy": "no-rate-limit",
        "Retry-After": "0"
      },
      "retryGuidance": "All endpoints are idempotent and read-only. Safe to retry immediately on any error. No backoff required.",
      "timeoutRecommendation": "30s",
      "statusPage": "https://zgts.in/status"
    }
  },
  "servers": [
    {
      "url": "https://zgts.in",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/mcp": {
      "post": {
        "summary": "MCP JSON-RPC endpoint (Streamable HTTP)",
        "description": "Model Context Protocol server endpoint. Accepts JSON-RPC 2.0 requests. Supports: initialize, tools/list, tools/call, resources/list, resources/read. No authentication required.",
        "operationId": "mcp_jsonrpc",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "examples": {
                "initialize": {
                  "summary": "Initialize MCP session",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "initialize",
                    "params": {
                      "protocolVersion": "2024-11-05",
                      "clientInfo": { "name": "claude-code", "version": "1.0.0" },
                      "capabilities": {}
                    }
                  }
                },
                "tools_list": {
                  "summary": "List available tools",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 2,
                    "method": "tools/list"
                  }
                },
                "search_guides": {
                  "summary": "Search derma roller guides",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 3,
                    "method": "tools/call",
                    "params": {
                      "name": "search_guides",
                      "arguments": {
                        "query": "acne scars"
                      }
                    }
                  }
                },
                "needle_recommendation": {
                  "summary": "Get needle size recommendation",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 4,
                    "method": "tools/call",
                    "params": {
                      "name": "get_needle_recommendation",
                      "arguments": {
                        "concern": "hair loss",
                        "experience_level": "beginner"
                      }
                    }
                  }
                },
                "get_product_info": {
                  "summary": "Get product information",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 5,
                    "method": "tools/call",
                    "params": {
                      "name": "get_product_info",
                      "arguments": {
                        "variant": "540"
                      }
                    }
                  }
                },
                "get_usage_guide": {
                  "summary": "Get usage protocol",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 6,
                    "method": "tools/call",
                    "params": {
                      "name": "get_usage_guide",
                      "arguments": {
                        "needle_size": "0.5",
                        "concern": "acne scars"
                      }
                    }
                  }
                },
                "resources_list": {
                  "summary": "List available resources",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 7,
                    "method": "resources/list"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful JSON-RPC response",
            "headers": {
              "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "description": "CORS — value: *" },
              "Cross-Origin-Resource-Policy": { "schema": { "type": "string" }, "description": "CORP — value: cross-origin" },
              "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Rate limit — value: unlimited" },
              "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Remaining — value: unlimited" },
              "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "Reset timestamp — value: 0 (no limit)" },
              "X-RateLimit-Policy": { "schema": { "type": "string" }, "description": "Policy — value: no-rate-limit" },
              "Retry-After": { "schema": { "type": "string" }, "description": "Retry delay — value: 0 (no delay)" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                },
                "examples": {
                  "initialize_response": {
                    "summary": "Initialize response",
                    "value": {
                      "jsonrpc": "2.0",
                      "id": 1,
                      "result": {
                        "protocolVersion": "2024-11-05",
                        "serverInfo": {
                          "name": "zgts-derma-roller",
                          "version": "1.0.0"
                        },
                        "capabilities": {
                          "tools": { "listChanged": false },
                          "resources": { "listChanged": false }
                        }
                      }
                    }
                  },
                  "tools_list_response": {
                    "summary": "Tools list response",
                    "value": {
                      "jsonrpc": "2.0",
                      "id": 2,
                      "result": {
                        "tools": [
                          {
                            "name": "search_guides",
                            "description": "Search ZGTS derma roller guides by topic or skin concern",
                            "inputSchema": {
                              "type": "object",
                              "properties": {
                                "query": { "type": "string", "description": "Topic to search (e.g. 'acne scars', 'hair growth')" }
                              },
                              "required": ["query"]
                            }
                          },
                          {
                            "name": "get_needle_recommendation",
                            "description": "Get personalised needle size recommendation based on concern and experience level",
                            "inputSchema": {
                              "type": "object",
                              "properties": {
                                "concern": { "type": "string" },
                                "experience_level": { "type": "string", "enum": ["beginner", "intermediate", "advanced"] }
                              },
                              "required": ["concern"]
                            }
                          },
                          {
                            "name": "get_product_info",
                            "description": "Get ZGTS product specs, pricing, and purchase links",
                            "inputSchema": {
                              "type": "object",
                              "properties": {
                                "variant": { "type": "string", "enum": ["192", "540", "all"] }
                              }
                            }
                          },
                          {
                            "name": "get_usage_guide",
                            "description": "Get step-by-step rolling instructions and aftercare protocol",
                            "inputSchema": {
                              "type": "object",
                              "properties": {
                                "needle_size": { "type": "string" },
                                "concern": { "type": "string" }
                              }
                            }
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request — malformed JSON or invalid JSON-RPC request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcError"
                },
                "example": {
                  "jsonrpc": "2.0",
                  "id": null,
                  "error": {
                    "code": -32700,
                    "message": "Parse error"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcError"
                },
                "example": {
                  "jsonrpc": "2.0",
                  "id": 1,
                  "error": {
                    "code": -32603,
                    "message": "Internal error"
                  }
                }
              }
            }
          }
        },
        "tags": ["MCP"]
      },
      "options": {
        "summary": "CORS preflight for MCP endpoint",
        "operationId": "mcp_options",
        "responses": {
          "204": {
            "description": "CORS preflight accepted",
            "headers": {
              "Access-Control-Allow-Origin": { "schema": { "type": "string" } },
              "Access-Control-Allow-Methods": { "schema": { "type": "string" } },
              "Access-Control-Allow-Headers": { "schema": { "type": "string" } }
            }
          }
        },
        "tags": ["MCP"]
      }
    },
    "/ask": {
      "post": {
        "summary": "NLWeb natural language query endpoint",
        "description": "Accepts a natural language question and returns a structured answer about derma rollers. Compatible with NLWeb 1.0 schema.",
        "operationId": "nlweb_ask",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NlwebRequest"
              },
              "example": {
                "q": "What needle size should I use for hair growth?"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "NLWeb answer response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NlwebResponse"
                },
                "example": {
                  "_meta": {
                    "response_type": "answer",
                    "version": "1.0",
                    "source": "zgts.in"
                  },
                  "query": "What needle size should I use for hair growth?",
                  "answer": "For hair growth, use a 0.5mm derma roller for beginners or 1.0mm for intermediate users. Roll over the scalp 2-3 times per week.",
                  "items": [
                    {
                      "@type": "Article",
                      "name": "Derma Roller for Hair Growth Guide",
                      "url": "https://zgts.in/guides/derma-roller-for-hair"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request — missing required parameter",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": { "error": "Missing required parameter: q" }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": { "error": "Internal server error" }
              }
            }
          }
        },
        "tags": ["NLWeb"]
      }
    },
    "/.well-known/mcp": {
      "get": {
        "summary": "MCP server discovery manifest",
        "description": "Returns MCP server discovery information including server URL, transport type, capabilities, and available tools.",
        "operationId": "mcp_discovery",
        "responses": {
          "200": {
            "description": "MCP server manifest",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/McpServerInfo" }
              }
            }
          }
        },
        "tags": ["Discovery"]
      }
    },
    "/status": {
      "get": {
        "summary": "API status and health check",
        "description": "Returns operational status, uptime, and rate limit policy for all ZGTS API endpoints.",
        "operationId": "get_status",
        "responses": {
          "200": {
            "description": "API status information",
            "headers": {
              "X-RateLimit-Limit": { "schema": { "type": "string" }, "description": "Rate limit — value: unlimited" },
              "X-RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Remaining requests — value: unlimited" },
              "X-RateLimit-Policy": { "schema": { "type": "string" }, "description": "Rate limit policy — value: no-rate-limit" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "operational" },
                    "service": { "type": "string" },
                    "version": { "type": "string" },
                    "timestamp": { "type": "string", "format": "date-time" },
                    "uptime": { "type": "string" },
                    "rateLimit": {
                      "type": "object",
                      "properties": {
                        "policy": { "type": "string", "example": "unlimited" },
                        "description": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "tags": ["Status"]
      }
    }
  },
  "components": {
    "schemas": {
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": ["2.0"],
            "description": "JSON-RPC version — must be '2.0'"
          },
          "id": {
            "type": "integer",
            "description": "Request identifier — must be unique per session"
          },
          "method": {
            "type": "string",
            "enum": ["initialize", "tools/list", "tools/call", "resources/list", "resources/read"],
            "description": "MCP method name"
          },
          "params": {
            "type": "object",
            "description": "Method parameters — structure depends on method"
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc", "id"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": "integer" },
          "result": {
            "type": "object",
            "description": "Successful result — present when no error"
          },
          "error": {
            "$ref": "#/components/schemas/JsonRpcErrorObject"
          }
        }
      },
      "JsonRpcError": {
        "type": "object",
        "required": ["jsonrpc", "error"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["integer", "null"] },
          "error": { "$ref": "#/components/schemas/JsonRpcErrorObject" }
        }
      },
      "JsonRpcErrorObject": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": {
            "type": "integer",
            "description": "Error code: -32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error"
          },
          "message": { "type": "string" },
          "data": { "type": "object" }
        }
      },
      "McpServerInfo": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "example": "zgts-derma-roller" },
          "description": { "type": "string" },
          "version": { "type": "string", "example": "1.0.0" },
          "serverUrl": { "type": "string", "format": "uri", "example": "https://zgts.in/api/mcp" },
          "transport": { "type": "string", "example": "streamable-http" },
          "authentication": { "type": "string", "example": "none" },
          "homepage": { "type": "string", "format": "uri" },
          "capabilities": {
            "type": "object",
            "properties": {
              "tools": { "type": "boolean" },
              "resources": { "type": "boolean" }
            }
          },
          "tools": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      },
      "NlwebRequest": {
        "type": "object",
        "required": ["q"],
        "properties": {
          "q": {
            "type": "string",
            "description": "Natural language question about derma rollers",
            "example": "What needle size for hair growth?"
          }
        }
      },
      "NlwebResponse": {
        "type": "object",
        "properties": {
          "_meta": {
            "type": "object",
            "properties": {
              "response_type": { "type": "string" },
              "version": { "type": "string" },
              "source": { "type": "string" }
            }
          },
          "query": { "type": "string" },
          "answer": { "type": "string" },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "@type": { "type": "string" },
                "name": { "type": "string" },
                "url": { "type": "string", "format": "uri" }
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string", "description": "Human-readable error description" }
        }
      }
    },
    "securitySchemes": {}
  },
  "security": [],
  "tags": [
    { "name": "MCP", "description": "Model Context Protocol (JSON-RPC 2.0 over HTTP)" },
    { "name": "NLWeb", "description": "Natural Language Web query interface" },
    { "name": "Discovery", "description": "MCP server discovery endpoints" }
  ]
}