venue-ops-mcp

一个MCP服务器，让Claude或任何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.

为什么存在

大多数报表工具回答的是每个人都会问的问题：我们卖了什么？销售额是简单的数字。它们出现在收银机上、仪表盘上、午夜过后的WhatsApp群里。

决定一个门店是否盈利的数字是折扣、免单项目和作废订单——控制模块——而这些几乎从未出现在日报中。作废率在三周内从1%滑落到4%，在任何一个晚上看起来都不算什么。它看起来像是一个糟糕的星期二，然后是一个冷清的星期四。只有当你将一个时间段与前一个时间段进行比较时，它才看起来像是一个问题，而这正是这个服务器所做的。

这里的阈值并非来自统计学教科书。它们来自于实际运营门店的经验。

工具

每个工具都是只读的，并已标注为只读，接受 response_format: "markdown"（供人阅读）或 "json"（供程序使用）。

两种异常形态

venue_ops_find_anomalies 将最近7天与前28天进行比较，并报告两种不同情况，因为它们含义不同：

• 漂移 —— 整个近期窗口已经移动。未固定的轮班表、收银机问题、为了息事宁人而开始免单的经理。这是代价高昂的那种，也是没人注意到的那种。

• 峰值 —— 某一天远高于基线。通常是没人记录的促销活动。解释起来很简单，值得确认。

低于40欧元的发现会被忽略。它们是真实的，但不值得打一个电话，而一个总是报假警的报告在第三周就会被忽视。

数据

data/operations.json 是合成的。三个门店，182天，由 scripts/generate_data.py 使用固定种子生成，以确保结果可重现。这不是真实的业务，也无法从中识别出任何真实业务。

数字是虚构的；但形态不是。工作日的季节性、堂食/外卖比例、折扣和作废率以及人工成本百分比都处于休闲餐饮常见的范围内。

故意植入了三个异常，以便检测功能有真实的东西可找，并且任何人都可以检查其是否有效：

要将其指向真实的销售点系统，请替换 venue_ops_mcp/data.py 中的数据加载器。工具层不关心数据行来自哪里。

安装

pip install -r requirements.txt
python scripts/generate_data.py

与Claude Desktop一起使用

将其添加到 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日那一周的问题。

• 集团在七月份的表现如何？

验证

python scripts/smoke_test.py    # every tool, and the planted anomalies
python scripts/stdio_check.py   # the MCP handshake a real client performs

smoke_test.py 断言巴塞罗那的漂移仍然被检测到，并且一个干净的窗口没有产生任何发现。一个对所有事情都触发的检测器比没有检测器更糟糕，因此两个方向都经过了测试。

构建工具

Python 3.10+，MCP Python SDK（MCPServer，stdio传输），Pydantic v2用于输入验证。无外部服务，无凭证，无网络调用——服务器仅读取本地文件。

许可证

MIT。