PlayFab MCP Server

PlayFab MCP 服务

这是什么？🤔

此服务是一款中间件，可让大模型（例如 Claude 和 VS Code）直接与 PlayFab 服务交互。它充当安全高效的转换器，将 AI 助手与各种 PlayFab 功能连接起来，例如物品搜索、分段查询、玩家档案查找、库存管理和 PlayFab ID 转换。

快速示例

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

它如何工作？🛠️

此服务利用模型上下文协议（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 地址封禁玩家。
• 使用 revoke_all_bans_for_user API 完全解除玩家封禁。

玩家数据管理

• 使用 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）。
• 受支持的 LLM 客户端，例如 Claude Desktop。

设置项目

从 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 配置和 shell 历史记录。运行服务时，请在容器环境中设置 PLAYFAB_TITLE_ID / PLAYFAB_DEV_SECRET_KEY。

使用 Cursor 运行

如需通过 Cursor 使用 PlayFab MCP 服务，请按以下步骤操作：

1. 如果尚未安装，请先安装 Cursor 桌面版。
2. 在空文件夹中打开一个新的 Cursor 实例。
3. 将此代码仓库中的 mcp.json 文件复制到你的文件夹中，并根据你的环境更新相应值。
4. 启动 Cursor；PlayFab MCP Server 应会显示在工具列表中。
5. 例如，尝试输入类似“显示最新的 10 个项目”的提示词，以确认服务能够正确处理你的查询。

将项目详情添加到 Claude Desktop 配置文件

打开 Claude Desktop，然后依次前往“文件” → “设置” → “开发者” → “编辑配置”。接着，将 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"
      }
    }
  }
}

完成这些步骤后，你就成功配置了 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 界面：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：如需报告 Bug 或提出功能请求，请创建 issue
2. 讨论区：如有一般性问题或需要社区支持，请使用 GitHub Discussions
3. 文档：查看 README 和代码注释中的使用示例

创建 issue 之前

请先搜索现有 issue，确认您的问题是否已有人报告。如果找到类似问题，可以通过评论补充信息。

我们支持的内容

• 安装和设置问题
• 提供可复现步骤的 Bug 报告
• 功能请求和建议
• 文档改进

我们不支持的内容

• 一般的 PlayFab API 问题（请参阅 PlayFab 文档）
• 第三方工具或服务相关的问题
• 定制实现请求

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。