Un servidor MCP que le da a Claude o a cualquier cliente MCP acceso directo y de solo lectura a las cifras de operación diaria de un grupo de restaurantes con múltiples locales y, más concretamente, a los números por donde se va el dinero sin que nadie lo anote.
You: is anything leaking this week?
Claude: Eixample (BCN-01) — voided tickets have drifted from 1.55% of gross
to 4.60% over the last seven days, against a 28-day baseline. That is
799.16 EUR over the window. It is not a spike on one shift; it is a slope
across the whole week, which is the shape a till problem makes.La mayoría de las herramientas de informes responden a la pregunta que todo el mundo ya se hace: ¿qué vendimos? Las ventas son el número fácil. Están en el TPV, en el panel de control, en el grupo de WhatsApp a las doce y diez de la noche.
Los números que deciden si un local es rentable son descuentos, artículos compensados y tickets anulados — el bloque de control — y casi nunca llegan a un informe diario. Una tasa de anulación que pasa del 1% al 4% en tres semanas no parece nada en una noche cualquiera. Parece un mal martes, luego un jueves tranquilo. Solo parece un problema cuando comparas una ventana con la ventana anterior, que es lo que hace este servidor.
Los umbrales aquí no están copiados de un libro de texto de estadística. Vienen de haber gestionado locales.
Related MCP server: VeloceMCP
Herramienta | Qué responde |
| Qué locales existen y qué período cubren los datos |
| Todo sobre un día: ventas por canal, cubiertos, ticket medio, bloque de control, personal |
| ¿Este sábado fue realmente malo o solo lo parece? |
| Totales para un rango, por local y para el grupo |
| Qué se está moviendo contra su propia línea base, en euros |
Cada herramienta es de solo lectura, está anotada como tal y acepta response_format: "markdown" para una persona o "json" para un programa.
venue_ops_find_anomalies compara los últimos 7 días con los 28 anteriores e informa de dos cosas diferentes, porque significan cosas diferentes:
Deriva — toda la ventana reciente se ha movido. Una rotación sin arreglar, un problema en el TPV, un gerente que ha empezado a compensar para mantener la paz. Esta es la cara y la que nadie detecta.
Pico — un día muy fuera de la línea base. Normalmente una promoción que nadie registró. Barato de explicar, vale la pena confirmarlo.
Los hallazgos por debajo de 40 EUR se descartan. Son reales y no merecen una llamada telefónica, y un informe que da falsas alarmas se ignora a la tercera semana.
data/operations.json es sintético. Tres locales, 182 días, generado por scripts/generate_data.py a partir de una semilla fija para que los resultados sean reproducibles. No es un negocio real y ningún negocio real es identificable a partir de él.
Los números son inventados; la forma no lo es. La estacionalidad semanal, la división entre cena en local y a domicilio, las tasas de descuento y anulación y el porcentaje de personal se encuentran dentro de los rangos que se ven en la restauración informal.
Se han plantado tres anomalías a propósito, para que la detección tenga algo real que encontrar y para que cualquiera pueda comprobar que funciona:
Local | Qué | Cuándo |
BCN-01 | La tasa de anulación deriva del 0,9% al 5,2% y se detiene | 15 jun – 5 jul 2026 |
MAD-02 | El porcentaje de personal se dispara al 41% durante una semana | 6 – 12 abr 2026 |
MAD-01 | Dos días aislados de descuento al 14% | 9 may, 18 jul 2026 |
Para apuntar esto a un sistema de punto de venta real, reemplaza el cargador en venue_ops_mcp/data.py. La capa de herramientas no se preocupa de dónde vienen las filas.
pip install -r requirements.txt
python scripts/generate_data.pyAñade esto a claude_desktop_config.json:
{
"mcpServers": {
"venue-ops": {
"command": "python",
"args": ["-m", "venue_ops_mcp.server"],
"cwd": "/absolute/path/to/venue-ops-mcp"
}
}
}Reinicia Claude Desktop. Luego pregúntale cosas como:
¿Qué locales tenemos?
¿Cómo le fue a Gran Vía el sábado pasado en comparación con los sábados anteriores?
Revisa Barcelona en busca de problemas en la semana que termina el 5 de julio.
¿Qué hizo el grupo en julio?
python scripts/smoke_test.py # every tool, and the planted anomalies
python scripts/stdio_check.py # the MCP handshake a real client performssmoke_test.py afirma que la deriva de Barcelona sigue siendo detectada y que una ventana limpia no produce ningún hallazgo. Un detector que salta con todo es peor que ningún detector, así que se prueban ambas direcciones.
Python 3.10+, el SDK de MCP para Python (MCPServer, transporte stdio), Pydantic v2 para la validación de entrada. Sin servicios externos, sin credenciales, sin llamadas de red — el servidor solo lee un archivo local.
MIT.
Compare a day against the same weekday in previous weeks.
This is the only fair comparison in hospitality. Measuring a Monday against the Sunday before it makes every Monday look like a collapse and every Friday like a triumph; comparing like weekday with like weekday is what tells you whether something actually changed.
Args: params (CompareWeekdayInput): Validated parameters containing: - venue_id (str): Venue identifier - day (str): The day being judged, YYYY-MM-DD - weeks (int): How many previous same-weekdays to average, 1-12 (default 4) - response_format (ResponseFormat): 'markdown' or 'json'
Returns: str: The day, the same-weekday average, and the variance between them.
JSON schema:
{
"venue_id": str,
"day": {...}, # same shape as venue_ops_get_day
"comparison_days": [str], # dates averaged
"averages": {"net_sales": float, "covers": float,
"average_ticket": float, "labour_pct": float,
"discount_rate": float, "void_rate": float},
"variance": {...} # same keys, as fractions of 1
}Examples: - Use when: "Was last Saturday actually bad, or does it just feel bad?" - Don't use when: You want a whole month's totals (use venue_ops_period_summary).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds context about the comparison methodology, output shape, and variance meaning, going beyond the annotations. It doesn't cover auth/rate limits, but those are less critical for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with summary, rationale, Args, Returns, and Examples sections. The rationale is slightly verbose but earns its place by explaining the tool's unique value. It's not excessively long for the information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of annotations and output schema, the description covers purpose, usage, parameters, and return format well. It includes examples and a JSON schema snippet. Minor gaps like edge cases with insufficient weeks are not addressed, but overall it's comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for all parameters (venue_id, day, weeks, response_format), so schema coverage is high. The description's Args section repeats and lightly rephrases the schema, adding minimal new meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Compare a day against the same weekday in previous weeks' with a specific verb and resource, and explains why this is the only fair comparison in hospitality. It clearly distinguishes from sibling tools like venue_ops_period_summary and venue_ops_get_day.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Don't use when' scenarios, and names an alternative tool (venue_ops_period_summary) for a different use case. This gives the agent clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Flag discounts, comps, voids or labour moving against their own baseline.
Compares the last 7 days against the 28 before them and reports two shapes. A drift is a sustained rise across the whole recent window, which is what a till problem or an unfixed rota looks like. A spike is one day far outside the baseline, usually a promotion nobody logged. Findings below 40 EUR are dropped: they are real but not worth a phone call.
Args: params (AnomalyInput): Validated parameters containing: - venue_id (Optional[str]): One venue, or omit to scan all - end (Optional[str]): Last day of the window, defaults to the dataset end - response_format (ResponseFormat): 'markdown' or 'json'
Returns: str: Findings sorted by money at stake, largest first.
JSON schema:
{
"window_end": str,
"findings": [
{
"type": "drift" | "spike",
"metric": str, # discount_rate | comp_rate | void_rate | labour_pct
"label": str, # human wording, e.g. "voided tickets"
"venue_id": str,
"baseline_rate": float, # fraction of 1
"euros_at_stake": float,
# drift only: window, baseline_window, recent_rate, relative_increase
# spike only: date, weekday, day_rate, z_score
}
]
}Examples: - Use when: "Is anything leaking this week?" - Use when: "Check Barcelona for problems ending 5 July." - Don't use when: You want the day's trading figures (use venue_ops_get_day).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is clear. The description adds valuable behavioral detail: the comparison windows (7 vs 28 days), the two shapes (drift vs spike), and the €40 threshold for dropping findings. These go beyond annotations. Minor deduction for not explicitly stating the tool is idempotent in behavior, though annotations cover it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with logical sections: overview, algorithm details, args, returns, examples. Each sentence adds value. Minor deduction: the overview paragraph could be slightly more concise (e.g., 'Compares the last 7 days...' could be merged with the earlier sentence).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully complete for a read-only analytical tool with a single required parameter (params). The output schema is fully documented, annotations cover safety, and the description explains the algorithm, thresholds, and use cases. The complexity is moderate, and every aspect is addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the JSON schema provides no descriptions for the top-level parameters. However, the description includes a comprehensive 'Args' section with valid types, defaults, and behavior for each parameter (venue_id, end, response_format). This fully compensates for the schema gap. The output schema is also clearly documented in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Flag', 'Compares') and resources ('discounts, comps, voids or labour'), clearly distinguishing this from siblings like venue_ops_get_day (daily trading figures) and venue_ops_period_summary. The domain of anomaly detection is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Don't use when' examples, directly referencing a sibling tool (venue_ops_get_day) for contrasting use cases. This gives clear guidance on when to invoke this tool vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full trading figures for one venue on one day.
Gives sales split by channel, covers, average ticket, the control block (discounts, comps, voids) and labour cost, with every rate expressed against gross so the percentages are comparable across venues.
Args: params (DayInput): Validated parameters containing: - venue_id (str): Venue identifier, e.g. 'MAD-01' - day (str): Trading day, YYYY-MM-DD - response_format (ResponseFormat): 'markdown' or 'json'
Returns: str: The day's figures.
JSON keys include: net_sales, dine_in_sales, delivery_sales, covers,
transactions, average_ticket, spend_per_cover, discounts, comps, voids,
control_total, gross_sales, discount_rate, comp_rate, void_rate,
labour_cost, labour_hours, labour_pct (float rates are fractions of 1).
Error response: "Error: <message>" naming the valid venues or dates.Examples: - Use when: "How did Gran Via do on 14 August?" - Don't use when: You want to know whether that day was normal (use venue_ops_compare_weekday).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the exact output format (markdown or json), listing all JSON keys, and describing the error response format. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (Args, Returns, Examples). Every sentence is informative and earns its place. The main purpose is stated in the first sentence, and the total length is proportional to the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (single venue, single day), and the description covers input parameter details, output structure (with key names), error handling, and usage examples. It also differentiates from a sibling tool. Given the output schema exists and the tool has good annotations, the description is fully sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an 'Args' section that describes venue_id, day, and response_format with examples. The input schema also has descriptions for each parameter, so the tool description adds context like 'Use venue_ops_list_venues to see them all' and the example date format. The return keys are also listed, which helps the agent understand parameter impact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Return the full trading figures for one venue on one day,' which is a specific verb+resource combination. It lists the exact data breakdown (sales by channel, covers, average ticket, etc.) and explicitly distinguishes from sibling venue_ops_compare_weekday in the 'Don't use when' example.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Examples' section provides a clear use case ('How did Gran Via do on 14 August?') and a non-use case with an explicit alternative tool ('use venue_ops_compare_weekday'). This gives the agent precise when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every venue in the dataset and the period the data covers.
Call this first when you do not know which venue ids exist. It is cheap and it tells you the date range every other tool will accept.
Args: params (ListVenuesInput): Validated parameters containing: - response_format (ResponseFormat): 'markdown' or 'json'
Returns: str: Venue list and covered period.
JSON schema:
{
"currency": str, # e.g. "EUR"
"period": {"start": str, "end": str},
"venues": [
{"venue_id": str, "name": str, "city": str, "seats": int}
]
}Examples: - Use when: "Which sites do we have data for?" - Don't use when: You already have a venue id and want figures (use venue_ops_get_day).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety profile is clear. The description adds value by explaining the tool reveals the date range accepted by other tools, which is behavioral context beyond annotations. However, it does not detail what happens on failure or edge cases (e.g., empty dataset).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise and well-structured. Description front-loads the core purpose, follows with usage guidance, then succinctly documents parameters and output schema via Args/Returns/JSON schema. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single parameter, a clear output schema, and rich annotations, the description is complete. It covers purpose, usage context, parameter details, and expected output structure. No gaps remain for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% but there is only 1 parameter (response_format) which is well described in the schema (markdown vs json). The description adds an example of usage context but does not significantly improve schema understanding. Baseline 3 is appropriate as schema already handles this simple parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every venue and the period data covers. It differentiates from siblings by explaining when to call this first (when venue ids are unknown) and directs to venue_ops_get_day for known venue ids.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to call this first when venue ids are unknown, notes it is cheap, and clarifies the date range context. Provides concrete when-to-use and when-not-to-use examples, including which sibling tool to use instead (venue_ops_get_day).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Total up a date range, for one venue or for the whole group.
Args: params (PeriodInput): Validated parameters containing: - start (str): First day, YYYY-MM-DD - end (str): Last day inclusive, YYYY-MM-DD - venue_id (Optional[str]): One venue, or omit for all venues plus a total - response_format (ResponseFormat): 'markdown' or 'json'
Returns: str: Totals and derived rates for the range.
JSON schema:
{
"period": {"start": str, "end": str},
"venues": {venue_id: {...aggregated figures...}},
"group_total": {...} # present only when venue_id was omitted
}Examples: - Use when: "What did the group do in July?" - Use when: "Give me Chamberi's numbers for the last two weeks." - Don't use when: You want a single day (use venue_ops_get_day).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by specifying that the group_total is present only when venue_id is omitted, and that the response format can be markdown or json. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Args, Returns, JSON schema, Examples) and is appropriately sized. Every sentence adds value, and the examples are concise and illustrative. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, one nested object, output schema provided), the description is complete. It covers input semantics, output structure, usage examples, and exclusions. The output schema is present, so the description doesn't need to explain return values in detail, but it still provides a high-level summary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does by listing each parameter (start, end, venue_id, response_format) with brief semantics and the JSON schema for the return value. While it doesn't detail every field in the aggregated figures, it provides enough for an agent to understand the inputs and expected output structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool aggregates a date range for one venue or the whole group, with specific verbs ('Total up') and resource ('date range, for one venue or for the whole group'). It distinguishes from sibling tools by explicitly noting when not to use it (single day, use venue_ops_get_day).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage examples ('Use when: What did the group do in July?') and a clear exclusion ('Don't use when: You want a single day (use venue_ops_get_day)'). This directly guides the agent on when to select this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0venue_ops_compare_weekdayvenue_ops_find_anomaliesvenue_ops_get_dayvenue_ops_list_venuesvenue_ops_period_summaryScored across 5 tools
Each tool has a clearly distinct purpose: listing venues, retrieving a single day, comparing to same weekday averages, aggregating a range, and detecting anomalies. There is no overlap or ambiguity between them, and cross-references in examples reinforce which tool to use for which question.
All five tools follow the exact same verb_noun pattern with the venue_ops_ prefix, using snake_case (find_anomalies, list_venues, get_day, compare_weekday, period_summary). The naming is perfectly predictable and consistent.
With 5 tools, the server is well-scoped for a venue operations analytics domain. Each tool earns its place and covers a distinct query pattern without being too thin or unnecessarily heavy.
The tool surface covers the core analytics needs: discovery (list), point-in-time snapshot (get day), fair comparison (compare weekday), aggregation (period summary), and proactive insight (find anomalies). No obvious gaps within the stated purpose of venue analytics.
Read-only tools for finding where a small business leaks deals, time, and cash.
Read-only access to your VortexIQ store data: audits, KPIs, alerts, Brand DNA, reports, Ask VIQ.
Query financial statements, KPIs, ratios, cash forecasts and budgets from your general ledger
Read-only access to your Drivara fleet — jobs, drivers, vehicles, fuel, profit & analytics.
