Appearance
パチスロカウンター — 記事執筆時の履歴取得契約
有料記事などの考察を書くとき、カウンターアプリ（Supabase）に保存した稼働履歴を Cursor MCP paid-article-tools から読むための契約。
配置方針は slot-kouryaku-counter/docs/01-architecture.md。画面仕様は 02-screen-design.md。
本契約は slot-kouryaku リポジトリ側で実装する（MCP Tool 追加）。カウンターアプリ本体のテーブルが先に存在する。
概要
- 呼び出し元: Cursor の
paid-article-tools（既存の差枚・イベント取得と同じ経路） - 認証: Supabase サービスロール（MCP プロセスの環境変数のみ。ブラウザ・WP テーマ・クライアント JS には埋め込まない）
- WordPress DB・会員 API は使わない
Tool 名（案）
fetch_slot_counter_history
既存 Tool 一覧の正本は docs/usage/mcp-paid-article-tools.md。本 Tool 追加時に同ドキュメントへ行を足す。
入力（リクエスト）
| param | 必須 | 型・制約 | 説明 |
|---|---|---|---|
play_date | はい | YYYY-MM-DD | 稼働日 |
template_name | 任意 | 非空文字列 | テンプレート表示名（例: 戦国乙女5）。省略時は当該日の全テンプレート |
template_id | 任意 | UUID | テンプレート ID。template_name より優先 |
hall_name | 任意 | 非空文字列 | ホール名で絞り込み |
user_id | 条件付き必須 | UUID | 対象ユーザー。省略時は SLOT_COUNTER_DEFAULT_USER_ID を使う。どちらも無い場合はエラー（後述） |
サービスロールは RLS をバイパスするため、クエリは常に単一 user_id で絞り込む。全ユーザー横断の取得は禁止する。
出力（レスポンス）
成功時
| field | 型 | 説明 |
|---|---|---|
success | boolean | 常に true |
play_date | string | 要求した日付 |
sessions | array | 下記 SessionDto[] |
SessionDto
| field | 型 | 説明 |
|---|---|---|
session_id | string | UUID |
template_id | string | UUID |
template_name | string | 表示名 |
hall_name | string | null | |
machine_number | number | null | 台番号 |
header | object | 差枚・有利区間差枚など任意ヘッダー |
session_start | object | 開始時投資・持ち玉 |
summary | object | 総消化G・平均・最大ハマり・差枚など（サーバーまたは MCP で算出してよい） |
rows | array | HistoryRowDto[] |
HistoryRowDto
| field | 型 | 説明 |
|---|---|---|
row_id | string | UUID |
sort_order | number | 並び |
values | object | テンプレート欄キー → 値 |
apply_to_counter | boolean | カウンター反映フラグ |
display | object | 任意。表向けに畳み込み済み備考など、執筆に使いやすい整形 |
失敗・エラー条件
| 条件 | 挙動 | メッセージ方針 |
|---|---|---|
| 環境変数未設定（URL / サービスキー） | success: false | Supabase 接続設定不足を明示 |
user_id 省略かつ SLOT_COUNTER_DEFAULT_USER_ID 未設定 | success: false | ユーザー未指定。全件取得は禁止 |
play_date 不正 | success: false | 日付形式エラー |
| Supabase エラー | success: false | 詳細はログ。ユーザー向けは要約 |
| 0 件 | success: true, sessions: [] | 空配列（執筆側で「データなし」と扱う） |
環境変数（MCP）
| 変数（案） | 必須 | 説明 |
|---|---|---|
SLOT_COUNTER_SUPABASE_URL | はい | プロジェクト URL |
SLOT_COUNTER_SUPABASE_SERVICE_KEY | はい | サービスロールキー |
SLOT_COUNTER_DEFAULT_USER_ID | 条件付き必須 | 単一運用時の既定ユーザー。引数 user_id 省略時に必須 |
.cursor/mcp.json の env に載せ、gitignore 対象のままにする（mcp.json.example にはプレースホルダのみ）。
セキュリティ
- サービスロールは RLS をバイパスする。そのため MCP は 必ず
user_id（引数またはSLOT_COUNTER_DEFAULT_USER_ID）で行を絞り込む。未設定での全件取得は禁止する。 - サービスロールキーは MCP ホストの環境変数のみ。リポジトリにコミットしない。
- 取得結果を記事に書くときは、個人が特定されない形（ホール名・台番の扱い）を執筆者が判断する。アプリ PP の「考察記事への利用」と整合させる。
- WP 管理画面や公開 REST から同一キーで呼ばない。
依存
- カウンターアプリの Supabase スキーマ（
templates/sessions/history_rows）が存在すること - 本リポジトリで
fetch_slot_counter_historyを MCP +（必要なら）薄いクライアントに追加すること
関連ドキュメント更新（実装 Issue 時）
- docs/usage/mcp-paid-article-tools.md の Tool 表
.cursor/skills/paid-article-conversational-draft/SKILL.mdの Tool 表.cursor/mcp.json.exampleの env プレースホルダ