PlayFab Data Gateway for MCP (Model Context Protocol)

Core Purpose 🤔

This service acts as an intermediary abstraction layer, enabling sophisticated artificial intelligence agents (such as those powering Claude or integrated environments like VS Code) to dynamically interface with the PlayFab suite of game services. It securely marshals requests pertaining to user records, segmented player groupings, item schema retrieval, and transactional inventory operations.

Operational Sample

User Query: "Provide a list of the ten most recently indexed catalog entries."
AI Agent Response: *executes the PlayFab search_items endpoint and renders findings as structured text.*

Mechanism of Action 🛠️

The gateway utilizes the Model Context Protocol (MCP) specification to standardize the communication interface between diverse AI inference engines and the PlayFab ecosystem. While MCP is engineered for broad model compatibility, its current deployment remains within a developer preview capacity.

To initiate operations, follow these fundamental steps:

1. Initialize your development workspace.
2. Provision your specific PlayFab credentials within your chosen LLM client's configuration profile.
3. Commence conversational interaction with your backend data streams.

Capabilities Matrix 📊

Item Catalog and Search Operations

• Catalog searching via the search_items API call.
• Economy v2 Artifact Lifecycle:
• Item draft creation utilizing create_draft_item.
• Modification of existing drafts via update_draft_item.
• Permanent deletion from the catalog using delete_item.
• Promotion of drafts to live status via publish_draft_item.
• Retrieval of specific item metadata using get_item.

Player Record Management

• Fetching granular segment composition details.
• Identifying player entities belonging to defined segments.
• Translating a generic PlayFab Identifier into a Title Player Account Identifier using get_title_player_account_id_from_playfab_id.
• Obtaining comprehensive details of a user account via get_user_account_info.

Stock Management (Inventory)

• Data Retrieval Functions:
• Enumerating current player holdings via get_inventory_items.
• Discovering available inventory collection namespaces using get_inventory_collection_ids.
• Insertion/Removal Procedures:
• Augmenting user inventory using add_inventory_items.
• Erasing inventory entries via delete_inventory_items.
• Decrementing stock quantities with subtract_inventory_items.
• State Modification:
• Adjusting metadata or properties of existing inventory entries through update_inventory_items.

Economy v2 Administrative Tasks

• Executing complex, atomic sequences of inventory changes via execute_inventory_operations.
• Note: Within Economy v2 paradigm, virtual currencies are internally represented and managed as distinct inventory assets.

User Account Administration

• Imposing restrictions (bans) on users based on unique identifiers, network addresses (IP), or hardware identifiers (MAC) via ban_users.
• Complete lifting of all existing prohibitions for a user using revoke_all_bans_for_user.

Persistent Player Data Handling

• Retrieving player-specific custom attributes using get_user_data.
• Persisting updates to player custom attributes via update_user_data.

Global Title Configuration

• Writing overarching, environment-wide configuration data via set_title_data.
• Reading the global configuration via get_title_data.
• Writing internal, server-only configuration variables via set_title_internal_data.
• Reading the private internal configuration data via get_title_internal_data.

Rapid Deployment Guide 🚀

Installation via Smithery

For automated deployment integrated directly into Claude Desktop using Smithery:

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

Prerequisites

• Runtime environment: Node.js version 18 or superior.
• Essential Credentials: An active PlayFab account is required to source your Title ID and Developer Secret Key from the Game Manager console.
• Client Compatibility: A suitable LLM environment, such as Claude Desktop.

Project Initialization

Acquire your PlayFab Title ID and Developer Secret Key from the PlayFab Game Manager interface. Subsequently, establish a .env file in the project's root directory containing these parameters (substitute placeholders with your actual secrets):

PLAYFAB_TITLE_ID=YOUR_TITLE_ID_HERE
PLAYFAB_DEV_SECRET_KEY=YOUR_SECRET_KEY_HERE

Setup & Launch Sequence

1. Dependency Acquisition

Execute the following command in the project's primary directory to fetch all required node modules:

bash npm install

1. Project Compilation

Translate the TypeScript source code into executable JavaScript by running:

bash npm run build

1. Service Startup

Initiate the gateway server execution via:

bash npm start

1. Verification Output

Successful initialization will yield a confirmation message transmitted to the console:

text PlayFab Server running on stdio

Development Workflow Configuration

Code Quality Enforcement

• ESLint: Configuration adheres to TypeScript standards using recommended rule sets for stylistic uniformity.
• Prettier: Configured for automated source code styling adherence.
• TypeScript: Strict compilation mode is enforced to maximize type safety.
• Jest: The designated testing harness for running TypeScript-based unit and integration tests.

Available Execution Scripts

Command	Function
npm run build	Compiles source assets
npm run watch	Enables file watching for continuous compilation
npm run typecheck	Validates TypeScript type correctness
npm run lint	Executes static code analysis via ESLint
npm run lint:fix	Attempts automated ESLint error correction
npm run format	Applies Prettier formatting rules
npm run format:check	Verifies current file formatting compliance
npm test	Executes the complete test suite
npm run test:watch	Runs tests interactively with file monitoring
npm run test:coverage	Generates a detailed report of test coverage

TypeScript Compilation Strictness

This project mandates strict compilation settings in tsconfig.json, specifically ensuring: - Null and Undefined values are explicitly handled (strictNullChecks). - Inference of the any type is prohibited (noImplicitAny). - Function parameter and return types must be explicitly declared or strictly inferred (strictFunctionTypes). - Overall activation of the strictest rule set (alwaysStrict).

Testing Protocols

Tests reside in directories named __tests__ or in files suffixed with .test.ts. Adherence to the test suite via npm test is mandatory prior to merging code changes.

Integrating with Cursor IDE

To leverage this PlayFab gateway within the Cursor environment, perform the subsequent actions:

1. Install the Cursor Desktop application if you have not yet done so.
2. Launch a fresh Cursor instance within an empty directory.
3. Copy the provided configuration file (.cursor/mcp.json) from this repository into your new directory, adjusting any necessary environment variables.
4. Upon launching Cursor, the PlayFab Data Gateway service will become visible in the tools listing. Test functionality with a query such as, "Check the latest 10 items."

Configuring Claude Desktop Integration

Access Claude Desktop's settings panel (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 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"
      }
    }
  }
}

Completing these steps successfully connects your LLM interface directly to the PlayFab backend services.

Development Standards & Release Cycle

Commit Style Guideline

This repository enforces the Conventional Commits specification to facilitate automated changelog generation and semantic versioning.

Format Template

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

<detailed body explaining motivation/changes>

<footer>

Type Definitions

• feat: Introduces a new capability (signals a MINOR version increment).
• fix: Corrects a functional defect (signals a PATCH version increment).
• docs: Changes confined solely to documentation.
• style: Formatting adjustments that do not alter code logic.
• refactor: Code restructuring that adds no new features or fixes bugs.
• perf: Optimizations leading to performance gains.
• test: Additions or modifications to the test suite.
• chore: Maintenance tasks related to tooling or build processes.

Version Bumping Logic

• MAJOR Bumps: Triggered by the presence of a BREAKING CHANGE note in the footer, or an exclamation mark (!) immediately following the type/scope.
• Example: feat!: deprecate legacy authentication endpoint
• MINOR Bumps: Triggered when the commit type is feat.
• PATCH Bumps: Triggered when the commit type is fix.

Release Pipeline

Phase 1: Version Update & Changelog Generation

# Analyze history, update CHANGELOG.md, and bump version numerically:
npm version patch  # or minor/major based on analysis

Phase 2: Repository Synchronization

# Commit version bump and push main branch updates
git push origin main

# Push the newly created version tag
git push origin --tags

Phase 3: Automated Publishing

Pushing a tag matching the v* pattern initiates the release-and-publish.yml CI/CD workflow, which automatically:

• Generates a GitHub Release artifact with descriptive release notes.
• Publishes the compiled package to the npm registry.
• Attaches necessary binaries/assets to the release.

Repository Configuration Requirements

For the automated process to function correctly, specific secrets must be configured in the repository settings:

1. NPM_TOKEN: Required for authentication during npm package publication.
2. DEPENDABOT_PAT: A Personal Access Token (scoped for repo and workflow permissions) needed for Dependabot to submit PRs that the CI can merge automatically.
3. Configure this via Settings → Secrets and variables → Actions.
4. Branch Protection Rules: The main branch must enforce checks:
5. Require successful status checks before merging, specifically ensuring that the build jobs (build (18.x), build (20.x), build (22.x)) pass.

Tooling Quick Reference

Script	Description
npm start	Initiates the MCP server listener
npm run build	Generates distributable JavaScript from TypeScript
npm run watch	Runs compilation in continuous development mode
npm run typecheck	Runs isolated TypeScript type verification
npm run lint	Executes static code stylistic and correctness checks
npm run lint:fix	Attempts automated correction of ESLint violations
npm run format	Standardizes file formatting across the project
npm run format:check	Reports on files that do not meet formatting standards
npm test	Executes the full suite of unit and integration tests
npm run test:watch	Runs tests interactively, restarting on file changes
npm run test:coverage	Produces a metric report detailing test coverage levels

Security Posture

Security is paramount. If you identify any vulnerability within this codebase, adhere strictly to the following confidential reporting protocol:

Vulnerability Disclosure Procedure

1. Public Disclosure Prohibition: Absolutely do not create a public GitHub Issue for security flaws.
2. Private Reporting Channel: Report all security-sensitive findings exclusively through GitHub's private vulnerability reporting mechanism:
3. Navigate to the repository's Security tab.
4. Select the option labeled Report a vulnerability.
5. Furnish a comprehensive breakdown of the discovered weakness.

Required Disclosure Elements

• A detailed narrative describing the nature of the flaw.
• Precise, sequential instructions to reliably reproduce the vulnerability.
• An assessment of the potential negative impact.
• Any proposed mitigation strategies (optional contribution).

Our Service Commitment

• We commit to acknowledging your submission within two business days (48 hours).
• You will receive periodic status updates regarding remediation efforts.
• We will attribute credit for the discovery (unless explicit anonymity is requested).

Operational Security Guidelines

Users integrating this gateway must adhere to these best practices:

1. Credential Isolation: Sensitive configuration data (secrets, keys) must always be managed via environment variables, never hardcoded in source control.
2. Dependency Hygiene: Regularly audit dependencies using npm audit and maintain an up-to-date package set.
3. Principle of Least Privilege: Ensure the credentials used by this service possess only the minimum necessary permissions to execute required functions.
4. Key Rotation: Implement a regular schedule for refreshing the PlayFab Developer Secret Keys.

Assistance and Community

Channels for Support

Should you encounter operational difficulties or require clarification on utilizing the PlayFab MCP Gateway, the preferred support vectors are:

1. Bug Reports & Feature Requests: Log all defects and enhancement proposals via a formal GitHub Issue.
2. General Inquiries: For non-critical questions and community interaction, utilize GitHub Discussions.
3. Reference Material: Consult the extensive documentation within this README and inline code comments for usage examples.

Pre-Submission Checklist

Before filing a new issue, please execute a thorough search of existing issues to confirm the problem hasn't already been documented or resolved. If related, feel free to contribute supplementary details to the existing thread.

Scope of Supported Topics

• Troubleshooting installation and initial configuration hurdles.
• Reporting reproducible software defects.
• Submitting enhancement ideas or functional requests.
• Suggesting improvements to the documentation.

Out of Scope Support

• Inquiries regarding general PlayFab API usage (consult the official PlayFab Documentation).
• Issues arising from external, third-party tooling or services.
• Requests for custom feature implementation outside the primary scope.

Licensing

This project is distributed under the permissive MIT License; refer to the LICENSE file for complete terms and conditions.

WIKIPEDIA CONTEXT MAPPING: Business management tools encompass the methodologies, applications, and computational aids utilized by organizations to maintain market relevance, enhance operational efficiency, and adapt to dynamic commercial landscapes. These systems span departmental needs—from strategic foresight and process automation to data governance and decision support structures. Modern business software has transitioned from rudimentary MIS to comprehensive ERP and cloud-based suites, driven by cost reduction imperatives and the necessity of precise customer need fulfillment. Effective adoption hinges not merely on acquiring the newest technology, but on the careful tailoring and integration of the chosen tools to meet specific organizational mandates.