{
  "schema_version": "cellaria_mcp_catalog_v1",
  "updated_at": "2026-07-14",
  "protocol": {
    "transport": "stdio",
    "jsonrpc": "2.0",
    "preferred_version": "2025-11-25",
    "supported_versions": [
      "2025-11-25",
      "2025-06-18",
      "2025-03-26",
      "2024-11-05"
    ]
  },
  "server": {
    "name": "cellaria-commercial",
    "title": "Cellaria Commercial Intelligence",
    "version": "1.0.0-demo",
    "instructions": "Cellaria exposes synthetic, local demo intelligence only. Keep every conclusion aggregated, show coverage and caveats, and never reveal restaurant identity, exact restaurant sales, exact margin, exact stock, total market share, absolute rankings, or guaranteed sales forecasts. N>=5 is the minimum publication rule. The report tool creates a non-persistent draft and requires human review before any commercial submission. Local demo calls are not billed."
  },
  "demo_access": {
    "key_id": "static_demo_pages",
    "credential": null,
    "mode": "synthetic_local_demo",
    "billable": false,
    "note": "static_demo_pages is a public demo identifier, not a credential and never a valid X-API-Key value.",
    "public_api_paths": [
      "/v1/health",
      "/v1/ready",
      "/v1/openapi.json",
      "/v1/billing/plans",
      "/data/cellaria_mcp_tools.json"
    ],
    "authenticated_api_paths": [
      "/v1/market/ask",
      "/v1/market/compare",
      "/v1/market/report-packages",
      "/v1/market/report-requests",
      "/v1/market/usage"
    ]
  },
  "guardrails": {
    "minimum_restaurant_count": 5,
    "default_output": "aggregated_or_indexed",
    "restaurant_identity": "hidden_without_explicit_permission",
    "blocked_claims": [
      "restaurant_identity_or_contact_data",
      "exact_restaurant_sales",
      "exact_restaurant_margin_or_cost",
      "exact_restaurant_stock",
      "total_market_share",
      "absolute_market_ranking",
      "guaranteed_sales_forecast"
    ],
    "required_disclosures": [
      "demo_or_live_data_status",
      "coverage_or_sample_status",
      "confidence_or_caveat",
      "metered_unit",
      "human_review_for_commercial_submission"
    ],
    "commercial_disclaimer": "Las salidas son señales agregadas y orientativas. Presencia no equivale a ventas, PVP no equivale a margen y la muestra no representa necesariamente todo el mercado."
  },
  "metering": {
    "local_demo": {
      "ledger": "disabled",
      "billable": false,
      "key_id": "static_demo_pages"
    },
    "production": {
      "ledger": "api_usage_events",
      "usage_endpoint": "/v1/market/usage",
      "quota_note": "La cuota y la facturación dependen del contrato y del plan asignado a la API key.",
      "units": {
        "market_answer": "Una respuesta comercial preparada.",
        "wine_comparison": "Una comparación agregada de dos o tres vinos.",
        "product_catalog_read": "Una lectura del catálogo comercial.",
        "report_request_draft": "Un borrador de solicitud; el alta autenticada se mide por separado."
      }
    }
  },
  "tools": [
    {
      "name": "cellaria_ask",
      "title": "Ask Cellaria",
      "description": "Responde una pregunta comercial sobre vino con señales demo agregadas, evidencia, cobertura, caveats y una siguiente acción segura. Rechaza solicitudes de identidad o métricas sensibles exactas.",
      "inputSchema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "question": {
            "type": "string",
            "minLength": 8,
            "maxLength": 500,
            "description": "Pregunta de negocio sobre presencia, PVP, comparables, catálogo, stock agregado u oportunidad."
          },
          "buyer_type": {
            "type": "string",
            "enum": [
              "winery",
              "distributor",
              "importer",
              "analyst"
            ],
            "default": "winery"
          },
          "region": {
            "type": "string",
            "minLength": 2,
            "maxLength": 80,
            "default": "Madrid"
          },
          "period": {
            "type": "string",
            "enum": [
              "30d",
              "90d",
              "180d",
              "365d"
            ],
            "default": "90d"
          },
          "subject": {
            "type": "string",
            "minLength": 2,
            "maxLength": 120,
            "description": "Vino, bodega, DO o categoría a priorizar."
          }
        },
        "required": [
          "question"
        ]
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": false
      },
      "execution": {
        "taskSupport": "forbidden"
      },
      "commercial": {
        "api_endpoint": "POST /v1/market/ask",
        "access": "contracted",
        "required_scope": "market:read",
        "metered_unit": "market_answer",
        "demo_billable": false
      },
      "examples": [
        {
          "question": "¿Qué PVP defiende El Anejón en Madrid?",
          "buyer_type": "winery",
          "region": "Madrid",
          "period": "90d"
        }
      ]
    },
    {
      "name": "cellaria_compare_wines",
      "title": "Compare wines",
      "description": "Compara de dos a tres referencias demo con el mismo marco agregado de presencia observada, PVP, oportunidad y cobertura. No produce rankings absolutos ni identifica restaurantes.",
      "inputSchema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "wines": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "minItems": 2,
            "maxItems": 3,
            "uniqueItems": true,
            "description": "Nombres o IDs de dos o tres referencias del catálogo demo."
          },
          "region": {
            "type": "string",
            "minLength": 2,
            "maxLength": 80,
            "default": "Madrid"
          },
          "include_comparables": {
            "type": "boolean",
            "default": true
          }
        },
        "required": [
          "wines"
        ]
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": false
      },
      "execution": {
        "taskSupport": "forbidden"
      },
      "commercial": {
        "api_endpoint": "GET /v1/market/compare",
        "access": "contracted",
        "required_scope": "market:read",
        "metered_unit": "wine_comparison",
        "demo_billable": false
      },
      "examples": [
        {
          "wines": [
            "El Anejón",
            "Alion",
            "Flor de Pingus"
          ],
          "region": "Madrid"
        }
      ]
    },
    {
      "name": "cellaria_list_products",
      "title": "List Cellaria products",
      "description": "Lista informes, índices y productos comerciales disponibles en el catálogo demo, ordenados por encaje con el buyer indicado.",
      "inputSchema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "buyer_type": {
            "type": "string",
            "enum": [
              "winery",
              "distributor",
              "importer",
              "analyst"
            ]
          },
          "category": {
            "type": "string",
            "minLength": 2,
            "maxLength": 80
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 5
          }
        }
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": false
      },
      "execution": {
        "taskSupport": "forbidden"
      },
      "commercial": {
        "api_endpoint": "GET /v1/market/report-packages",
        "access": "contracted",
        "required_scope": "market:read",
        "metered_unit": "product_catalog_read",
        "demo_billable": false
      },
      "examples": [
        {
          "buyer_type": "distributor",
          "limit": 3
        }
      ]
    },
    {
      "name": "cellaria_generate_report_request",
      "title": "Draft a report request",
      "description": "Genera un borrador local y no persistente de solicitud de informe, con payload API, revisión de privacidad y siguiente paso. No envía, compra ni contrata nada.",
      "inputSchema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "title": {
            "type": "string",
            "minLength": 5,
            "maxLength": 180
          },
          "question": {
            "type": "string",
            "minLength": 8,
            "maxLength": 500
          },
          "requested_scope": {
            "type": "string",
            "enum": [
              "pricing_benchmark_report",
              "commercial_route_report",
              "wine_fit_report",
              "stock_rotation_report",
              "market_briefing_report",
              "custom_market_report"
            ]
          },
          "buyer_type": {
            "type": "string",
            "enum": [
              "winery",
              "distributor",
              "importer",
              "analyst"
            ],
            "default": "winery"
          },
          "region": {
            "type": "string",
            "minLength": 2,
            "maxLength": 80,
            "default": "Madrid"
          },
          "subject": {
            "type": "string",
            "minLength": 2,
            "maxLength": 120
          },
          "period": {
            "type": "string",
            "enum": [
              "30d",
              "90d",
              "180d",
              "365d"
            ],
            "default": "90d"
          },
          "priority": {
            "type": "string",
            "enum": [
              "low",
              "normal",
              "high"
            ],
            "default": "normal"
          }
        },
        "required": [
          "title",
          "question"
        ]
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": false
      },
      "execution": {
        "taskSupport": "forbidden"
      },
      "commercial": {
        "api_endpoint": "POST /v1/market/report-requests",
        "access": "contracted_human_review",
        "required_scope": "market:read",
        "metered_unit": "report_request_draft",
        "demo_billable": false
      },
      "examples": [
        {
          "title": "Benchmark de PVP de El Anejón en Madrid",
          "question": "¿Qué banda de PVP observada defiende El Anejón en Madrid?",
          "requested_scope": "pricing_benchmark_report",
          "buyer_type": "winery",
          "region": "Madrid",
          "subject": "El Anejón",
          "period": "90d",
          "priority": "normal"
        }
      ]
    }
  ]
}