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.

이것이 존재하는 이유

대부분의 보고 도구는 모두가 이미 묻는 질문에 답합니다: 우리가 무엇을 팔았는가? 매출은 쉬운 숫자입니다. 계산대에, 대시보드에, 자정 10분 후에는 WhatsApp 그룹에 있습니다.

사이트가 수익을 내는지 여부를 결정하는 숫자는 할인, 무상 제공 품목 및 무효 처리된 티켓 — 통제 블록 — 이며, 이는 거의 일일 보고서에 포함되지 않습니다. 3주에 걸쳐 1%에서 4%로 상승하는 무효율은 어느 특정 밤에는 아무것도 아닌 것처럼 보입니다. 그것은 나쁜 화요일처럼 보이다가 조용한 목요일처럼 보입니다. 현재 기간을 이전 기간과 비교할 때만 문제로 보이며, 이것이 이 서버가 하는 일입니다.

여기서 사용된 임계값은 통계 교과서에서 복사된 것이 아닙니다. 실제 매장을 운영한 경험에서 비롯되었습니다.

도구

모든 도구는 읽기 전용이며, 그렇게 명시되어 있으며, 사람을 위한 response_format: "markdown" 또는 프로그램을 위한 "json"을 받습니다.

이상치의 두 가지 형태

venue_ops_find_anomalies는 최근 7일을 그 이전 28일과 비교하여 두 가지 다른 것을 보고합니다. 왜냐하면 그것들은 각각 다른 의미를 가지기 때문입니다:

• 드리프트 — 전체 최근 기간이 이동했습니다. 고정되지 않은 로테이션, 계산대 문제, 평화를 유지하기 위해 무상 제공을 시작한 관리자. 이것은 비용이 많이 드는 것이며 아무도 알아차리지 못하는 것입니다.

• 스파이크 — 기준선에서 크게 벗어난 하루. 일반적으로 기록되지 않은 프로모션입니다. 설명하기 쉽고 확인할 가치가 있습니다.

40 EUR 미만의 발견은 삭제됩니다. 실제이지만 전화할 가치가 없으며, 거짓 경보를 울리는 보고서는 3주차가 되면 무시됩니다.

데이터

data/operations.json은 합성 데이터입니다. 3개 매장, 182일, scripts/generate_data.py에 의해 고정 시드에서 생성되어 결과를 재현할 수 있습니다. 실제 비즈니스가 아니며 실제 비즈니스를 식별할 수 없습니다.

숫자는 가상이지만, 형태는 그렇지 않습니다. 평일 계절성, 매장 내 식사/배달 비율, 할인 및 무효율, 인건비 비율은 모두 캐주얼 다이닝에서 볼 수 있는 범위 내에 있습니다.

세 가지 이상치가 의도적으로 심어져 있어, 탐지 기능이 실제로 찾을 수 있는 것이 있고 누구나 작동하는지 확인할 수 있습니다:

이것을 실제 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.