PlayFab MCP Server

PlayFab MCP サーバー

これは何ですか？ 🤔

このサーバーは、Claude や VS Code などの大規模言語モデルが PlayFab サービスと直接やり取りできるようにするミドルウェアです。安全かつ効率的な翻訳役として、AI アシスタントと、アイテム検索、セグメント照会、プレイヤープロフィールの検索、インベントリ管理、PlayFab ID の変換など、さまざまな PlayFab 機能を接続します。

簡単な例

You: "Show me the latest 10 items."
Claude: *calls the PlayFab search_items API and returns the results in plain text*

どのように動作しますか？ 🛠️

このサーバーは Model Context Protocol（MCP）を活用し、AI モデルと PlayFab サービスの間に汎用インターフェースを確立します。MCP はあらゆる AI モデルをサポートするように設計されていますが、現在は開発者プレビューとして提供されています。

次の手順で始めましょう。

1. プロジェクトをセットアップします。
2. LLM クライアントの設定にプロジェクトの詳細を追加します。
3. PlayFab データとの自然なやり取りを始めましょう！

何ができますか？ 📊

カタログと検索

• PlayFab の search_items API を使ってアイテムを検索します。
• カタログ管理（Economy v2）：
  • create_draft_item API を使って新しいドラフトアイテムを作成します。
  • update_draft_item API を使って既存のドラフトアイテムを更新します。
  • delete_item API を使ってカタログからアイテムを削除します。
  • publish_draft_item API を使ってドラフトアイテムを公開し、利用可能にします。
  • get_item API を使ってアイテムの詳細情報を取得します。

プレイヤー管理

• セグメントの詳細情報を取得します。
• 指定したセグメント内のプレイヤープロフィールを照会します。
• get_title_player_account_id_from_playfab_id API を使って、PlayFab ID を Title Player Account ID に変換します。
• get_user_account_info API を使ってユーザーアカウントの詳細情報を取得します。

インベントリ管理

• 取得操作：
  • get_inventory_items API を使って現在のインベントリアイテムを取得します。
  • get_inventory_collection_ids API を使ってインベントリコレクション ID を取得します。
• 追加／削除操作：
  • add_inventory_items API を使ってインベントリにアイテムを追加します。
  • delete_inventory_items API を使ってインベントリからアイテムを削除します。
  • subtract_inventory_items API を使って指定した数量を減らします。
• 変更操作：
  • update_inventory_items API を使ってアイテムのプロパティを更新します。

Economy v2 の管理

• execute_inventory_operations API を使ってインベントリ操作を一括実行します。
• 注：Economy v2 では、仮想通貨はインベントリアイテムとして管理されます。

ユーザーアカウントの管理

• ban_users API を使って、ID、IP、または MAC アドレスでプレイヤーを BAN します。
• revoke_all_bans_for_user API を使って、プレイヤーのすべての BAN を解除します。

プレイヤーデータ管理

• get_user_data API を使ってプレイヤーのカスタムデータを取得します。
• update_user_data API を使ってプレイヤーのカスタムデータを更新します。

タイトル設定の管理

• set_title_data API を使ってグローバルタイトルデータを設定します。
• get_title_data API を使ってタイトルデータを取得します。
• set_title_internal_data API を使ってサーバー専用の内部データを設定します。
• get_title_internal_data API を使って内部データを取得します。

クイックスタート 🚀

前提条件

• Node.js 18 以上。
• 有効な PlayFab アカウント（PlayFab Game Manager から Title ID と Developer Secret Key を取得してください）。
• Claude Desktop など、サポートされている LLM クライアント。

プロジェクトのセットアップ

PlayFab Game Manager から PlayFab Title ID と Developer Secret Key を取得し、プロジェクトのルートに .env ファイルを作成して、次の内容を記述します（プレースホルダーを実際の認証情報に置き換えてください）。

PLAYFAB_TITLE_ID=
PLAYFAB_DEV_SECRET_KEY=

インストールとセットアップ

1. 依存関係のインストール

   プロジェクトのルートで次のコマンドを実行し、必要な依存関係をすべてインストールします。

   npm install
   

2. プロジェクトのビルド

   次を実行してプロジェクトをコンパイルします。

   npm run build
   

3. サーバーの起動

   次を実行してサーバーを起動します。

   npm start
   

4. 確認メッセージ

   起動すると、次のメッセージが表示されます。

   PlayFab Server running on stdio
   

開発環境のセットアップ

コード品質ツール

• ESLint：コードの一貫性を保つための推奨ルールを備えた、TypeScript 用の設定
• Prettier：プロジェクト固有の設定による自動コードフォーマット
• TypeScript：型安全性を高めるため、厳格モードを有効化
• Jest：TypeScript 用に設定されたテストフレームワーク

利用可能なスクリプト

# Build the project
npm run build

# Development mode with file watching
npm run watch

# TypeScript type checking
npm run typecheck

# Run ESLint
npm run lint

# Run ESLint and fix issues
npm run lint:fix

# Format code with Prettier
npm run format

# Check code formatting
npm run format:check

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

TypeScript の設定

このプロジェクトでは TypeScript の厳格モードを有効にしており、以下を保証します。

• 厳密な null チェック
• 暗黙的な any 型の禁止
• 厳密な関数型
• 常に厳格モードを使用

テスト

テストには Jest を使用し、__tests__ ディレクトリまたは .test.ts 拡張子のファイルに配置します。コード品質を確保するため、変更をコミットする前にテストを実行してください。

仕様駆動開発（Spec Kit、JP）

• CLI をインストール：uv tool install specify-cli --from git+https://github.com/akiojin/spec-kit.git
• 仕様／計画／タスクを作成：./.specify/scripts/bash/create-new-feature.sh "feature summary"（デフォルトではブランチを作成しません。必要な場合は --branch を指定してください）
• アセット：.specify/templates/*、.specify/scripts/bash/*、specs/ 配下の仕様
• Claude/Codex のスラッシュコマンド：/speckit.constitution、/speckit.specify、/speckit.plan、/speckit.tasks、/speckit.implement

Docker 開発環境

このリポジトリには、軽量な開発コンテナー（Node 22、ツール類、GitHub CLI）が付属しています。

# Build image
docker compose build

# Open a shell inside the container
docker compose run --rm playfab-mcp-server bash

# Inside the container
npm ci
npm run build
npm start

ボリュームには、ワークスペース（.）、Codex/Claude の設定、シェルの履歴が保持されます。サーバーの実行時は、コンテナー環境で PLAYFAB_TITLE_ID / PLAYFAB_DEV_SECRET_KEY を設定してください。

Cursor での実行

Cursor で PlayFab MCP サーバーを使用するには、次の手順に従ってください。

1. まだインストールしていない場合は、Cursor Desktop をインストールします。
2. 空のフォルダーで Cursor の新しいインスタンスを開きます。
3. このリポジトリの mcp.json ファイルをフォルダーにコピーし、環境に合わせて値を更新します。
4. Cursor を起動すると、ツール一覧に PlayFab MCP Server が表示されます。
5. たとえば、「最新の 10 個のアイテムを表示して」のようなプロンプトを試し、サーバーがクエリを正しく処理することを確認します。

Claude Desktop の設定ファイルにプロジェクトの詳細を追加する

Claude Desktop を開き、「File」→「Settings」→「Developer」→「Edit Config」の順に移動します。次に、claude_desktop_config ファイルの内容を以下のスニペットに置き換えます。

{
  "mcpServers": {
    "playfab": {
      "command": "npx",
      "args": [
        "-y",
        "@akiojin/playfab-mcp-server"
      ],
      "env": {
        "PLAYFAB_TITLE_ID": "Your PlayFab Title ID",
        "PLAYFAB_DEV_SECRET_KEY": "Your PlayFab Developer Secret Key"
      }
    }
  }
}

これらの手順により、LLM クライアントで使用できるよう PlayFab MCP サーバーが正常に設定され、PlayFab のサービスとシームレスにやり取りできるようになります。

Spec Kit を使用した仕様駆動開発

このリポジトリでは、akiojin/gwt で使用されている Spec Kit の SDD/TDD ワークフローに従います。

• 要件：Python 3.11+ と uv
• CLI をインストール：uv tool install specify-cli --from git+https://github.com/akiojin/spec-kit.git
• アセット：.specify/templates 配下のテンプレート、.specify/scripts/bash 配下のスクリプト、specs/ に配置される仕様
• 新しい仕様／計画を作成：./.specify/scripts/bash/create-new-feature.sh "feature summary"（ブランチも作成する場合は --branch を追加）
• 生成されるファイルには spec.md、plan.md、tasks.md が含まれます。コードと合わせてレビューし、コミットしてください。
• Claude/Codex のスラッシュコマンド（利用可能な場合）：/speckit.constitution、/speckit.specify、/speckit.plan、/speckit.tasks、/speckit.implement

コントリビューション

コミットメッセージの規約

このプロジェクトでは、自動バージョン管理とリリースに Conventional Commits を採用しています。

コミットメッセージの形式

<type>(<scope>): <subject>

<body>

<footer>

種類

• feat：新機能（MINOR バージョンの更新を実行）
• fix：バグ修正（PATCH バージョンの更新を実行）
• docs：ドキュメントのみの変更
• style：コードの意味に影響しない変更
• refactor：バグ修正にも機能追加にも該当しないコード変更
• perf：パフォーマンスを改善するコード変更
• test：不足しているテストの追加、または既存テストの修正
• chore：ビルドプロセスまたは補助ツールの変更

バージョン更新ルール

• MAJOR バージョン：コミットメッセージのフッターに BREAKING CHANGE が含まれる場合、またはタイプ／スコープの後に ! が付いている場合
  • 例：feat!: remove deprecated API endpoints
  • 例：feat: new API\n\nBREAKING CHANGE: removed old endpoints
• MINOR バージョン：コミットタイプが feat の場合
  • 例：feat: add new PlayFab API integration
• PATCH バージョン：コミットタイプが fix の場合
  • 例：fix: correct error handling in API calls

リリースプロセス（develop → main、release-please）

1. リリース PR の準備：prepare-release.yml ワークフローを実行して、develop から main への PR を作成します
   • Actions UI：Prepare Release → ref に develop を指定して実行
   • CLI：gh workflow run prepare-release.yml --ref develop
   • develop からの PR がすでにある場合は再利用されます。develop から作成された PR は、ワークフローによって自動マージできます。
2. リリースの自動化：main が更新されると、release.yml が release-please（manifest）を実行して、バージョンを更新し、CHANGELOG.md を更新して、GitHub Release／タグを作成します。
3. 公開：タグ v* のプッシュによって publish.yml が実行され、テスト、ビルド、型チェック、npm publish --access public が行われます。

必須シークレット：

• PERSONAL_ACCESS_TOKEN（任意。指定された場合は prepare-release／release で使用され、指定されていない場合は GITHUB_TOKEN にフォールバックします）
• NPM_TOKEN（publish.yml 用）

ブランチ保護：main の保護を維持し、リリース PR はマージ前に必須チェックを通過する必要があります。

スクリプト一覧

スクリプト	説明
npm start	MCP サーバーを起動します
npm run build	TypeScript を JavaScript にビルドします
npm run watch	開発用にウォッチモードでビルドします
npm run typecheck	TypeScript の型チェックを実行します
npm run lint	ESLint のチェックを実行します
npm run lint:fix	ESLint の問題を自動的に修正します
npm run format	Prettier でコードをフォーマットします
npm run format:check	コードのフォーマットをチェックします
npm test	すべてのテストを実行します
npm run test:watch	ウォッチモードでテストを実行します
npm run test:coverage	テストカバレッジレポートを生成します

セキュリティ

セキュリティを重視しています。このプロジェクトでセキュリティ脆弱性を発見した場合は、以下の手順に従ってください。

セキュリティ脆弱性の報告

1. セキュリティ脆弱性について、公開の GitHub issue は作成しないでください
2. 代わりに、GitHub の非公開の脆弱性報告機能からセキュリティ上の問題を報告してください。
   • このリポジトリの Security タブを開きます
   • Report a vulnerability をクリックします
   • 脆弱性の詳細を入力します

ご報告いただきたい情報

• 脆弱性の説明
• 問題を再現する手順
• 想定される影響
• 修正案（任意）

当方の取り組み

• ご報告を受領してから48時間以内に、受領確認をご連絡します
• 対応状況を定期的にお知らせします
• 匿名を希望されない限り、発見者としてクレジットを記載します

セキュリティのベストプラクティス

このサーバーを使用する際は、以下を守ってください。

1. 認証情報をコミットしないでください：機密データには必ず環境変数を使用してください
2. 依存関係を最新の状態に保ってください：定期的に npm audit を実行し、パッケージを更新してください
3. 最小権限を使用してください：必要最小限の権限のみを付与してください
4. キーを定期的にローテーションしてください：PlayFab Developer Secret Keys を定期的に変更してください

サポート

ヘルプを得る

PlayFab MCP Server の使用中に問題が発生した場合や、ご質問がある場合は、以下の方法でサポートを受けられます。

1. GitHub Issues：バグ報告や機能リクエストについては、issue を作成してください
2. Discussions：一般的な質問やコミュニティサポートには、GitHub Discussionsをご利用ください
3. ドキュメント：使用例については、README とコードコメントをご確認ください

issue を作成する前に

既存の issue を検索して、同じ問題がすでに報告されていないか確認してください。類似の issue が見つかった場合は、コメントで追加情報を記載できます。

サポート対象

• インストールおよびセットアップに関する質問
• 再現手順を記載したバグ報告
• 機能のリクエストおよび提案
• ドキュメントの改善

サポート対象外

• PlayFab API に関する一般的な質問（PlayFab Documentationをご覧ください）
• サードパーティ製のツールやサービスに関する問題
• カスタム実装の依頼

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細はLICENSEファイルをご覧ください。