{
  "openapi": "3.1.0",
  "info": {
    "title": "Tendrils MCP Endpoint",
    "version": "1.0.0",
    "description": "JSON-RPC 2.0 MCP endpoint on tendrils.io, proxying the live Jennifer Furniture storefront deployment. 11 public catalog tools (product search, availability, room fit, floorplans, bundles, AR links, checkout handoff). Admin tools return -32601. Versioning: the endpoint is versioned by the MCP protocolVersion in the initialize handshake; breaking changes ship behind a new protocol version, never silently. Rate limit: 60 requests/minute per IP — responses carry RateLimit-* headers and 429 returns Retry-After.",
    "contact": { "name": "Tendrils", "url": "https://tendrils.io", "email": "pranath@tendrils.io" }
  },
  "servers": [{ "url": "https://tendrils.io" }],
  "paths": {
    "/mcp": {
      "post": {
        "operationId": "mcpJsonRpc",
        "summary": "MCP JSON-RPC 2.0 endpoint",
        "description": "Accepts JSON-RPC 2.0. Methods: `initialize` (server info), `tools/list` (public tool schemas), `tools/call` (execute a tool against the live catalog), `resources/list`, `resources/read` (machine-readable docs), `ping`. Content-Type: application/json.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/JsonRpcRequest" },
              "examples": {
                "initialize": { "value": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": { "name": "agent", "version": "1.0" } } } },
                "toolsList": { "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} } },
                "toolsCall": { "value": { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "find_products_by_constraints", "arguments": { "query": "sleeper sofa under $1500", "limit": 4 } } } },
                "resourcesList": { "value": { "jsonrpc": "2.0", "id": 4, "method": "resources/list", "params": {} } }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response envelope",
            "headers": {
              "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per 60s window" },
              "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the window" },
              "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix epoch when the window resets" }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } }
          },
          "400": {
            "description": "Malformed request — JSON parse error (-32700) or invalid JSON-RPC envelope (-32600)",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcErrorResponse" } } }
          },
          "429": {
            "description": "Rate limit exceeded — back off and retry",
            "headers": {
              "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying" }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcErrorResponse" } } }
          }
        }
      },
      "get": {
        "operationId": "mcpInfo",
        "summary": "Endpoint description",
        "responses": {
          "200": {
            "description": "Human/agent-readable description of the endpoint",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointInfo" } } }
          }
        }
      }
    },
    "/.well-known/mcp": {
      "get": {
        "operationId": "mcpServerCard",
        "summary": "MCP server card",
        "responses": {
          "200": {
            "description": "Server card JSON — endpoint, transport, public tool list, provider",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerCard" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "integer", "null"] },
          "method": { "type": "string", "enum": ["initialize", "tools/list", "tools/call", "resources/list", "resources/read", "ping", "notifications/initialized"] },
          "params": { "type": "object" }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "integer", "null"] },
          "result": { "type": "object" },
          "error": { "$ref": "#/components/schemas/RpcError" }
        }
      },
      "JsonRpcErrorResponse": {
        "type": "object",
        "required": ["jsonrpc", "error"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "integer", "null"] },
          "error": { "$ref": "#/components/schemas/RpcError" }
        }
      },
      "RpcError": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": {
            "type": "integer",
            "description": "-32700 parse error, -32600 invalid request, -32601 method/tool not available (also admin-gated), -32602 unknown resource, -32603 upstream unavailable, -32000 rate limited"
          },
          "message": { "type": "string" }
        }
      },
      "EndpointInfo": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" },
          "usage": { "type": "string" },
          "see": { "type": "string", "format": "uri" }
        }
      },
      "ServerCard": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "transport": { "type": "string" },
          "endpoint": { "type": "string", "format": "uri" },
          "tools": { "type": "array", "items": { "type": "string" } },
          "provider": { "type": "object" }
        }
      }
    }
  }
}