venue-ops-mcp

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%に上昇するキャンセル率は、特定の夜には何も変わったようには見えません。悪い火曜日、そして静かな木曜日にしか見えません。それが問題であるとわかるのは、ある期間をその前の期間と比較したときだけであり、これこそがこのサーバーの役割です。

ここでの閾値は統計学の教科書からコピーしたものではありません。現場を運営した経験から来ています。

ツール

すべてのツールは読み取り専用で、そのように注釈が付けられており、response_format: "markdown"（人間向け）または "json"（プログラム向け）を受け付けます。

異常値の2つの形状

venue_ops_find_anomalies は、過去7日間をその前の28日間と比較し、2つの異なるものを報告します。なぜなら、それらは異なる意味を持つからです:

• ドリフト — 最近の窓全体が動いています。修正されていないシフト表、レジの問題、平和を保つために無償提供を始めたマネージャー。これは高くつくものであり、誰も気づかないものです。

• スパイク — 基準値から大きく外れた1日。通常は記録されなかったプロモーション。説明は簡単で、確認する価値があります。

40 EUR未満の検出結果は破棄されます。それらは実際に存在しますが、電話する価値はなく、オオカミ少年の報告は3週目には無視されます。

データ

data/operations.json は 合成 データです。3つの会場、182日分で、scripts/generate_data.py によって固定シードから生成され、結果が再現可能になっています。実際のビジネスではなく、それから特定できる実際のビジネスもありません。

数字は架空のものです。ただし、形状 は違います。曜日による季節性、店内飲食/配達の分割、割引率とキャンセル率、人件費率はすべて、カジュアルダイニングで見られる範囲内に収まっています。

3つの異常値が意図的に埋め込まれており、検出が実際に何かを見つけられるようになっており、誰でもそれが機能することを確認できます:

これを実際のPOSシステムに向けるには、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日までの週の問題をチェックしてください。

• グループ全体の7月の実績はどうでしたか?

検証

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.