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.대부분의 보고 도구는 모두가 이미 묻는 질문에 답합니다: 우리가 무엇을 팔았는가? 매출은 쉬운 숫자입니다. 계산대에, 대시보드에, 자정 10분 후에는 WhatsApp 그룹에 있습니다.
사이트가 수익을 내는지 여부를 결정하는 숫자는 할인, 무상 제공 품목 및 무효 처리된 티켓 — 통제 블록 — 이며, 이는 거의 일일 보고서에 포함되지 않습니다. 3주에 걸쳐 1%에서 4%로 상승하는 무효율은 어느 특정 밤에는 아무것도 아닌 것처럼 보입니다. 그것은 나쁜 화요일처럼 보이다가 조용한 목요일처럼 보입니다. 현재 기간을 이전 기간과 비교할 때만 문제로 보이며, 이것이 이 서버가 하는 일입니다.
여기서 사용된 임계값은 통계 교과서에서 복사된 것이 아닙니다. 실제 매장을 운영한 경험에서 비롯되었습니다.
Related MCP server: VeloceMCP
도구 | 답변 내용 |
| 어떤 사이트가 존재하며 데이터가 어떤 기간을 포함하는지 |
| 하루의 모든 것: 채널별 매출, 커버 수, 평균 티켓, 통제 블록, 인건비 |
| 이번 토요일이 실제로 나빴는지, 아니면 그냥 나쁘게 느껴지는지? |
| 범위별 합계, 매장별 및 그룹 전체 |
| 자체 기준선과 대비하여 움직이는 것이 무엇인지, 유로 단위로 |
모든 도구는 읽기 전용이며, 그렇게 명시되어 있으며, 사람을 위한 response_format: "markdown" 또는 프로그램을 위한 "json"을 받습니다.
venue_ops_find_anomalies는 최근 7일을 그 이전 28일과 비교하여 두 가지 다른 것을 보고합니다. 왜냐하면 그것들은 각각 다른 의미를 가지기 때문입니다:
드리프트 — 전체 최근 기간이 이동했습니다. 고정되지 않은 로테이션, 계산대 문제, 평화를 유지하기 위해 무상 제공을 시작한 관리자. 이것은 비용이 많이 드는 것이며 아무도 알아차리지 못하는 것입니다.
스파이크 — 기준선에서 크게 벗어난 하루. 일반적으로 기록되지 않은 프로모션입니다. 설명하기 쉽고 확인할 가치가 있습니다.
40 EUR 미만의 발견은 삭제됩니다. 실제이지만 전화할 가치가 없으며, 거짓 경보를 울리는 보고서는 3주차가 되면 무시됩니다.
data/operations.json은 합성 데이터입니다. 3개 매장, 182일, scripts/generate_data.py에 의해 고정 시드에서 생성되어 결과를 재현할 수 있습니다. 실제 비즈니스가 아니며 실제 비즈니스를 식별할 수 없습니다.
숫자는 가상이지만, 형태는 그렇지 않습니다. 평일 계절성, 매장 내 식사/배달 비율, 할인 및 무효율, 인건비 비율은 모두 캐주얼 다이닝에서 볼 수 있는 범위 내에 있습니다.
세 가지 이상치가 의도적으로 심어져 있어, 탐지 기능이 실제로 찾을 수 있는 것이 있고 누구나 작동하는지 확인할 수 있습니다:
매장 | 내용 | 시기 |
BCN-01 | 무효율이 0.9%에서 5.2%로 이동한 후 멈춤 | 15 Jun – 5 Jul 2026 |
MAD-02 | 인건비 비율이 1주일 동안 41%로 급등 | 6 – 12 Apr 2026 |
MAD-01 | 14% 할인이 발생한 두 개의 격리된 날 | 9 May, 18 Jul 2026 |
이것을 실제 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.
