campaign-mcp (動作確認用)

CAMPAIGN_SCHEMA.md で設計したキャンペーン応募フレームワークの、動作確認用MCPサーバー。 GitHub公開前に、Claude Desktop / MCP Inspector から直接ツールを叩いてロジックを検証する目的。

セットアップ

npm install

# D1データベースを作成(初回のみ)
npx wrangler d1 create campaign-db
# 出力されたdatabase_idをwrangler.jsoncの REPLACE_WITH_YOUR_D1_DATABASE_ID に貼り付ける

# マイグレーション適用(ローカル)
npm run db:migrate:local

# OAuth用のKV namespaceを作成(初回のみ)
npx wrangler kv namespace create OAUTH_KV
# 出力されたidをwrangler.jsoncの REPLACE_WITH_YOUR_KV_NAMESPACE_ID に貼り付ける

GitHub OAuth Appの作成(認証に必要)

1. https://github.com/settings/developers → 「New OAuth App」
   • Homepage URL: 適当でよい(例: http://localhost:8787)
   • Authorization callback URL: http://localhost:8787/callback (本番デプロイ後は本番URLの /callback に変更)
2. 発行された Client ID / Client Secret を控える
3. ローカル開発用に .dev.vars.example を .dev.vars にコピーし、値を埋める(.dev.vars はgit管理外)

cp .dev.vars.example .dev.vars
# GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET / COOKIE_ENCRYPTION_KEY を編集

COOKIE_ENCRYPTION_KEY はランダムな文字列でよい(例: openssl rand -hex 32)。

4. wrangler.jsonc の ALLOWED_GITHUB_USERNAMES に、ツールを呼べるGitHubユーザー名をカンマ区切りで設定する(ここに無いアカウントはGitHub認証は通っても実ツールを呼べない)

本番デプロイ時は .dev.vars の代わりにsecretとして登録する:

npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY

ローカル起動

npm run dev

動作確認手順

1. npm run devでローカルにMCPサーバーを起動(デフォルトで http://localhost:8787/mcp)
2. MCP Inspector を起動し、http://localhost:8787/mcp に接続。「Streamable HTTP」を選び、初回接続時にブラウザでGitHub認証・同意画面が挟まる
3. 以下の順でツールを試す:
   • create_campaign でテスト用キャンペーンを作成
   • submit_entry を複数回叩き、同じ店舗・購入日・レシート番号で送ると duplicate になることを確認
   • manualReceiptNumber を空欄にして送ると「仮受理」になることを確認(NULL同士は重複とみなされないため、何度でも仮受理される — これは想定通りの挙動)
   • list_entries で応募一覧を確認
   • run_draw で抽選を実行し、draw_logs にシードが記録されることを確認

本番公開前にやること(このMCPサーバーはまだ最小構成)

• OCR照合(非同期)は未実装。現状は手入力値のみで判定している
• レート制限(総当たり対策)は未実装
• campaign_stores(fixed_list時の店舗マスタ)を参照したバリデーションは未実装