Claude または任意の MCP クライアントに、多店舗レストラングループの日次取引データへの直接的な読み取り専用アクセスを提供する MCP サーバー。そして、より重要なのは、誰も記録しないままお金が出ていく数字へのアクセスです。
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.ほとんどのレポートツールは、誰もがすでに尋ねる質問に答えます: 何を売ったか? 売上は簡単な数字です。レジ、ダッシュボード、深夜0時過ぎのWhatsAppグループに載っています。
あるサイトが利益を出すかどうかを決める数字は、割引、無償提供品、キャンセルされたチケット — コントロールブロック — であり、それらが日次レポートに届くことはほとんどありません。3週間かけて1%から4%に上昇するキャンセル率は、特定の夜には何も変わったようには見えません。悪い火曜日、そして静かな木曜日にしか見えません。それが問題であるとわかるのは、ある期間をその前の期間と比較したときだけであり、これこそがこのサーバーの役割です。
ここでの閾値は統計学の教科書からコピーしたものではありません。現場を運営した経験から来ています。
Related MCP server: VeloceMCP
ツール | 答えられること |
| どのサイトが存在し、データがどの期間をカバーしているか |
| 1日のすべて: チャネル別売上、カバー数、平均チケット、コントロールブロック、人件費 |
| 今回の土曜日は実際に悪かったのか、それともただ悪く感じるだけか? |
| 期間の合計、会場別およびグループ全体 |
| 基準値に対して何が動いているか、ユーロ単位で |
すべてのツールは読み取り専用で、そのように注釈が付けられており、response_format: "markdown"（人間向け）または "json"（プログラム向け）を受け付けます。
venue_ops_find_anomalies は、過去7日間をその前の28日間と比較し、2つの異なるものを報告します。なぜなら、それらは異なる意味を持つからです:
ドリフト — 最近の窓全体が動いています。修正されていないシフト表、レジの問題、平和を保つために無償提供を始めたマネージャー。これは高くつくものであり、誰も気づかないものです。
スパイク — 基準値から大きく外れた1日。通常は記録されなかったプロモーション。説明は簡単で、確認する価値があります。
40 EUR未満の検出結果は破棄されます。それらは実際に存在しますが、電話する価値はなく、オオカミ少年の報告は3週目には無視されます。
data/operations.json は 合成 データです。3つの会場、182日分で、scripts/generate_data.py によって固定シードから生成され、結果が再現可能になっています。実際のビジネスではなく、それから特定できる実際のビジネスもありません。
数字は架空のものです。ただし、形状 は違います。曜日による季節性、店内飲食/配達の分割、割引率とキャンセル率、人件費率はすべて、カジュアルダイニングで見られる範囲内に収まっています。
3つの異常値が意図的に埋め込まれており、検出が実際に何かを見つけられるようになっており、誰でもそれが機能することを確認できます:
会場 | 内容 | 時期 |
BCN-01 | キャンセル率が0.9% → 5.2%にドリフトし、その後停止 | 2026年6月15日 – 7月5日 |
MAD-02 | 人件費率が1週間41%に急上昇 | 2026年4月6日 – 12日 |
MAD-01 | 14%の割引が2日間発生 | 2026年5月9日、7月18日 |
これを実際のPOSシステムに向けるには、venue_ops_mcp/data.py のローダーを置き換えてください。ツール層は行のソースを気にしません。
pip install -r requirements.txt
python scripts/generate_data.py以下を claude_desktop_config.json に追加します:
{
"mcpServers": {
"venue-ops": {
"command": "python",
"args": ["-m", "venue_ops_mcp.server"],
"cwd": "/absolute/path/to/venue-ops-mcp"
}
}
}Claude Desktop を再起動します。その後、次のようなことを尋ねてみてください:
どの会場がありますか?
Gran Via は先週の土曜日、その前の土曜日と比べてどうでしたか?
バルセロナの7月5日までの週の問題をチェックしてください。
グループ全体の7月の実績はどうでしたか?
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 は、バルセロナのドリフトが依然として検出され、クリーンなウィンドウでは 何も 検出されないことをアサートします。すべてに反応する検出器は、検出器がないより悪いため、両方の方向がテストされています。
Python 3.10+、MCP Python SDK（MCPServer、stdio トランスポート）、Pydantic v2（入力検証用）。外部サービス、認証情報、ネットワークコールは不要 — サーバーはローカルファイルのみを読み取ります。
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.
