PlayFab Integration Gateway

Overview 🤔

This server acts as a crucial intermediary, bridging the gap between large language models (like those powering Claude or development environments like VS Code) and the comprehensive suite of PlayFab game backend services. It functions as a secure and optimized translator, enabling natural language commands to trigger complex PlayFab operations, including searching the item catalog, querying player segments, retrieving profile details, managing virtual inventories, and converting PlayFab identifiers.

Illustrative Scenario

text User Input: "Fetch the ten most recent additions to the item registry." AI Agent Output: Invokes the PlayFab search_items endpoint and formats the resulting data for readability.

Operational Mechanics 🛠️

This system utilizes the Model Context Protocol (MCP) specification to create a standardized communication channel between the AI inference engine and the required PlayFab APIs. While MCP is architected for broad compatibility across various AI frameworks, its current deployment is accessible in a developer preview state.

Getting Started Sequence:

1. Initialize your development workspace.
2. Inject your specific project credentials into your LLM client's configuration files.
3. Commence intuitive interaction with your PlayFab data assets!

Capabilities Matrix 📊

Catalog & Item Search

• Execute targeted item lookups via the search_items API.
• Economy v2 Catalog Administration:
• Provision new items in draft status using create_draft_item.
• Modify existing draft item attributes via update_draft_item.
• Retire items from the catalog using delete_item.
• Promote draft items to live status with publish_draft_item.
• Retrieve granular details for any item using get_item.

Player & Segment Intelligence

• Fetch detailed membership data for defined player segments.
• Analyze player profiles filtered by specific segment criteria.
• Translate a generic PlayFab ID into a Title Player Account ID using get_title_player_account_id_from_playfab_id.
• Obtain exhaustive user account metadata via get_user_account_info.

Virtual Goods & Inventory Handling

• Data Retrieval:
• Query the current contents of a player's inventory using get_inventory_items.
• Fetch available inventory collection identifiers through get_inventory_collection_ids.
• Mutation Operations (Addition/Removal):
• Inject new items into inventory via add_inventory_items.
• Purge items from inventory using delete_inventory_items.
• Reduce the quantity of specific items via subtract_inventory_items.
• Attribute Adjustments:
• Modify metadata or configuration associated with inventory entries using update_inventory_items.

Economy v2 Backend Management

• Perform complex, atomic sequences of inventory modifications via execute_inventory_operations.
• Note: Within the Economy v2 paradigm, virtual currencies are treated fundamentally as inventory assets.

User Account Moderation

• Enforce punitive actions (bans) against players based on ID, network address (IP), or device identifier (MAC) using ban_users.
• Lift all active restrictions for a user with revoke_all_bans_for_user.

Persistent Player Data Access

• Read custom, player-specific key-value data using get_user_data.
• Persist updates to player custom data via update_user_data.

Global Title Configuration Control

• Establish or overwrite system-wide title settings using set_title_data.
• Retrieve current system-wide title configuration via get_title_data.
• Set backend-only, non-public internal configurations with set_title_internal_data.
• Fetch internal configuration values using get_title_internal_data.

Initial Deployment Guide 🚀

Automated Installation via Smithery

To set up the PlayFab Integration Gateway for automatic execution within Claude Desktop using Smithery:

bash npx -y @smithery/cli install @akiojin/playfab-mcp-server --client claude

Prerequisites

• A runtime environment supporting Node.js version 18 or newer.
• An active PlayFab developer account (you must secure your Title ID and Developer Secret Key from the PlayFab Game Manager console).
• A compatible LLM host application (e.g., Claude Desktop).

Project Configuration Steps

1. Secure your PlayFab Title ID and Developer Secret Key from the Game Manager.
2. In the project's root directory, generate a .env file containing these secrets:

bash PLAYFAB_TITLE_ID=YOUR_TITLE_ID_HERE PLAYFAB_DEV_SECRET_KEY=YOUR_SECRET_KEY_HERE

Deployment and Activation

1. Dependency Acquisition

Execute this command in the project root to fetch necessary libraries:

bash npm install

1. Source Compilation

Transform the TypeScript source code into executable JavaScript:

bash npm run build

1. Server Initialization

Launch the gateway service:

bash npm start

1. Verification Message

Successful launch confirmation will display:

text PlayFab Server running on stdio

Development Tooling Configuration

Quality Assurance Frameworks

• ESLint: Enforcing code style uniformity using recommended TypeScript rules.
• Prettier: Automated code formatting adhering to project standards.
• TypeScript: Strict compilation mode enabled for maximal type integrity.
• Jest: Testing harness integrated for TypeScript projects.

Utility Scripts Reference

bash

Compile source code

npm run build

Enable file-watching for rapid development

npm run watch

Validate TypeScript definitions only

npm run typecheck

Execute static code analysis (Lint)

npm run lint

Automatically correct linting violations

npm run lint:fix

Apply standard code formatting

npm run format

Verify current code formatting status

npm run format:check

Execute the full test suite

npm test

Run tests continuously upon file changes

npm run test:watch

Generate detailed test coverage metrics

npm run test:coverage

TypeScript Strictness Profile

This project mandates TypeScript's strictest settings, which guarantees: - Nullability is explicitly handled. - Implicit any types are forbidden. - Function signatures require full type specification. - Overall, the compiler operates in its most rigorous mode.

Testing Protocol

Tests are implemented using Jest and reside in directories named __tests__ or files ending in .test.ts. Comprehensive testing prior to code commits is mandatory to maintain quality standards.

Integration with Cursor IDE

To integrate this PlayFab gateway with the Cursor IDE:

1. Ensure Cursor Desktop is installed.
2. Launch Cursor in a fresh, empty workspace directory.
3. Copy the repository's mcp.json configuration file into your workspace folder, ensuring environmental placeholders are correctly substituted.
4. Launch Cursor; the PlayFab tool should appear in the available tools list.
5. Test functionality with a prompt like, "What items are available for purchase?"

Configuring Claude Desktop Client

Adjust the Claude Desktop configuration by navigating to File → Settings → Developer → Edit Config. Substitute the existing content of your claude_desktop_config file with the following structure, populating the environment variables with your actual credentials:

{ "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" } } } }

Following these procedures establishes a seamless operational link between your chosen LLM environment and the PlayFab backend services.

Collaboration Guidelines

Commit Standardization

This project enforces adherence to the Conventional Commits specification to streamline automated release management.

Message Structure

text ():